v2.0.0-pre2

SomnoTrace v2.0.0-pre2 Release Notes

Highlights & What's New Since v1.4.2

SomnoTrace v2.0.0-pre2 marks a major milestone for the firmware, transitioning the project into the v2.0 architecture. This release brings a completely modularized EDF export engine, bulletproof storage coordination between uploads and session recording, zero-leak BLE sync, full civil calendar/DST accuracy, and verified transactional consistency on SD card exports.

---

1. Modular EDF Subsystem (v2.0 Architectural Foundation)

• Decoupled Engine: Decomposed the monolithic export generator into clean, single-responsibility modules:
  • edf_header: Fixed 256-byte EDF headers, patient/recording IDs, and metadata sidecars.
  • edf_waveform: High-rate breath waveforms (BRP.edf), per-breath stats (PLD.edf), and oximetry (SA2.edf).
  • edf_annotations: Event annotations (EVE.edf) and Cheyne-Stokes logging (CSL.edf).
  • edf_summary: Multi-record daily summary (STR.edf) from ResMed protobuf spools and settings snapshots.
  • edf_data_dict: Master signal dictionary defining physical and digital boundaries for 134 channels.
• Native ResMed SD Parity: Generated exports match native AirSense 11 SD card layouts and binary formats 1:1, ensuring out-of-the-box compatibility with OSCAR, SleepHQ, and clinical analysis software.

2. Resilient Storage & Export Coordination (No More Dropped Exports)

• Deferred Export Recovery: When therapy stops while a background cloud or SMB upload holds the storage lock, SomnoTrace no longer drops the export. It queues a deferred export marker and automatically exports the day as soon as the storage lock becomes available.
• Granular Storage Leases: The upload scheduler now acquires storage locks on a per-day basis rather than locking the SD card for the entire upload session, preventing export starvation during long cloud syncs or SleepHQ polling.
• Smart Upload Reconciliation: Upload passes now reconcile newly added or rebuilt sessions instead of forgetting the whole day, eliminating duplicate session uploads to SleepHQ.

3. BLE Protocol Hardening & Memory Leak Elimination

• Spool Fragment Leak Fix: Fixed an issue where transient timeouts during BLE summary spool downloads over weak radio links leaked accumulated memory buffers (~90 KB per failed attempt).
• Race-Free Teardown: The spool fragment collector is now detached before releasing memory, preventing late-arriving BLE notifications from corrupting freed state during disconnects.

4. Full Daylight Saving (DST) & Calendar Accuracy

• Civil Calendar Math Across DST Transitions: Replaced naive 24-hour UTC arithmetic with proper civil calendar transitions. Morning sessions during 23-hour spring-forward transitions now reliably map to the correct therapy day instead of landing in yesterday's folder.
• Standardized Noon-Day Derivation: Unified noon-day cutoffs across session logging, oximetry correlation, upload indexing, and portal management via a centralized as11_time module.

5. Cheyne-Stokes Respiration (CSR) Event Support

• Dedicated CSL.edf Layer: Added full support for ResMed CSL.edf annotation exports. CsrStart and CsrEnd events are captured, timestamped with backdate offsets, and deduplicated, allowing OSCAR and SleepHQ to accurately display Cheyne-Stokes breathing episodes.

6. SD Card Data Integrity & Checksum Reliability

• Transactional Sidecar Checksums: Identification.crc and CurrentSettings.crc generation is now strictly gated on the successful write of their respective .json files. If a JSON write fails, any existing stale .crc is actively unlinked, guaranteeing that downstream tools never encounter corrupt or mismatched checksums.

7. Automated Property-Based Test Suite

• Host-Executable Test Harness: Added an automated property test suite with 37 property tests and 8 state-machine scenarios covering fixed-point scaling, rounding, clamping, sentinels, and boundary dates without requiring physical hardware.

---

Credits & Acknowledgements

A huge thank you to everyone involved in making this milestone release possible through code contributions, rigorous protocol analysis, and real-world testing:

Code Contributions

• @Plantucha:
  • Pull Request #187: Implemented the deferred export queue on storage lease contention (SD_LEASE_EXPORT), non-blocking lease probing, and smart day reconciliation to prevent duplicate uploads to SleepHQ.
  • Pull Request #196: Fixed the BLE spool fragment memory leak on collection timeouts (~90 KB accumulation under weak signal) and implemented race-free collector detachment during teardown.

Technical Analysis, Bug Reports & Architectural Review

• @Plantucha:
  • Issue #200: Discovered and proved the 23-hour spring-forward DST boundary defect in noon-day derivation across multiple timezones.
  • Issue #190: Identified Cheyne-Stokes Respiration (CSR) event labeling requirements in CSL.edf, driving the backdate timing and deduplication implementation.
  • Issue #198: Uncovered the sidecar .crc failure path where checksums could be written despite .json write failures.
  • Issue #199: Conducted comprehensive dimensional analysis on STR.edf summary metric scaling across all 53 signals.
  • Issue #186 & Discussion #191: Detailed review and verification of the EDF modularization and STR data dictionary parity.

Testing & Community Feedback

• @cwm12345 and @moldbuster for upstream storage and UI pull requests (#171, #172, #173, #178, #179).
• @irfanguder, @Asad-Foresite, and community testers for continuous real-world session verification, SleepHQ sync testing, and hardware log captures across diverse AirSense 11 and O2 Ring setups.