Lightweight C++ microservice for ResMed CPAP data collection with Home Assistant integration.

Automatically extracts sleep therapy data from your ResMed AirSense 10/11 CPAP machine, parses EDF files using OSCAR algorithms, and publishes 47+ metrics to Home Assistant via MQTT discovery. Supports three data sources: ez Share WiFi SD (HTTP polling), FYSETC SD WiFi Pro (MQTT push with realtime therapy data), or local filesystem.

• 3 Data Sources - ezShare WiFi SD (polling), FYSETC SD WiFi Pro (MQTT push), or local files
• 47+ Metrics - AHI, leak rate, pressure, usage hours, events, STR daily summary, LLM AI summary
• Home Assistant Auto-Discovery - Instant MQTT integration with 47 sensor entities
• PostgreSQL Storage - Historical data for ML analysis and long-term trends
• Session Grouping - Intelligently combines BRP/PLD/SAD/EVE/CSL files into therapy sessions
• Realtime Therapy Data - FYSETC mode streams BRP data every 60s during therapy
• LLM Session Summary - Optional AI-generated therapy analysis via Ollama
• Ultra-Lightweight - 6.5 MB native binary
• 155 Unit Tests - Comprehensive coverage across all services

• Quick Start
• Data Sources
• Configuration
• Deployment
• Home Assistant Integration
• Architecture
• Development
• FAQ
• Contributing

# 1. Clone and build
git clone https://github.com/hms-homelab/hms-cpap.git
cd hms-cpap
mkdir build && cd build
cmake .. && make -j$(nproc)

# 2. Configure
cp ../.env.example ../.env
nano ../.env  # Set MQTT, DB, and source settings

# 3. Run (choose your data source)
CPAP_SOURCE=ezshare ./hms_cpap   # ezShare WiFi SD polling
CPAP_SOURCE=fysetc  ./hms_cpap   # FYSETC SD WiFi Pro MQTT push
CPAP_SOURCE=local   ./hms_cpap   # Local filesystem

How it works: HTTP polling every 65s via WiFi bridge on Raspberry Pi.

Hardware: ezShare WiFi SD card + Raspberry Pi with dual WiFi (wlan0=home, wlan1=ezShare AP).

Pros: Simple, no hardware mods. Cons: 2-4 min session detection latency, requires dedicated Pi WiFi interface.

How it works: ESP32-based PCB sits between CPAP and SD card on the SPI bus. Passively monitors CS line via hardware pulse counter, performs surgical bus steals (<10ms) during therapy, pushes EDF data via MQTT.

Hardware: FYSETC SD WiFi Pro board installed inside CPAP machine.

Pros: 65s end-to-end latency, realtime BRP streaming during therapy, zero network disruption, BRP-validated therapy detection. Cons: Requires hardware installation inside CPAP.

Firmware: hms-cpap-fysetc -- ESP-IDF project, builds with idf.py build.

See docs/FYSETC_RECEIVER.md for the full protocol, MQTT topics, and FSM state diagram.

How it works: Reads EDF files from a local directory (e.g. mounted SD card or NAS).

Use case: Offline analysis, backfill, or reparse of archived data.

All configuration via environment variables (12-factor app). See .env.example for complete reference.

# ez Share WiFi SD card base URL
EZSHARE_BASE_URL=http://192.168.4.1

# MQTT broker (required for Home Assistant)
MQTT_BROKER=localhost
MQTT_PORT=1883
MQTT_USER=mqtt_user
MQTT_PASSWORD=your_mqtt_password

# Device identification
CPAP_DEVICE_ID=resmed_airsense10
CPAP_DEVICE_NAME="ResMed AirSense 10"

# Collection interval (seconds)
BURST_INTERVAL=120  # Default: 2 minutes

# PostgreSQL (for historical storage)
DB_HOST=localhost
DB_NAME=cpap_data
DB_USER=cpap_user
DB_PASSWORD=your_db_password

# Health check port
HEALTH_CHECK_PORT=8893

# Build
mkdir build && cd build && cmake .. && make -j$(nproc)

# Install
sudo cp hms_cpap /usr/local/bin/
sudo cp ../.env /etc/hms-cpap/.env  # Edit with your settings

# Service file: /etc/systemd/system/hms-cpap.service

[Unit]
Description=HMS-CPAP Data Collection Service
After=network.target postgresql.service emqx.service

[Service]
Type=simple
EnvironmentFile=/etc/hms-cpap/.env
ExecStart=/usr/local/bin/hms_cpap
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable hms-cpap
sudo systemctl start hms-cpap

./build_arm.sh          # Cross-compile for ARM
./deploy_to_pi.sh       # Build + deploy + restart in one step

See docs/CROSS_COMPILATION.md for sysroot setup.

Docker image available for CI and containerized deployments:

docker run -d --env-file .env -p 8893:8893 ghcr.io/hms-homelab/hms-cpap:latest

HMS-CPAP uses MQTT Discovery for automatic Home Assistant integration.

configuration.yaml:

mqtt:
  broker: localhost  # Your MQTT broker
  username: mqtt_user
  password: your_mqtt_password
  discovery: true  # Enable discovery

Sensors will auto-appear as a device:

Device: ResMed AirSense 10

Sensors (34 total):

• sensor.cpap_ahi - Apnea-Hypopnea Index
• sensor.cpap_leak_rate - Leak rate (L/min)
• sensor.cpap_pressure_current - Current pressure (cmH2O)
• sensor.cpap_usage_hours - Total usage hours
• sensor.cpap_session_start - Last session start time
• sensor.cpap_central_apneas - Central apnea events
• sensor.cpap_obstructive_apneas - Obstructive apnea events
• ... and 27 more metrics

Example Lovelace card:

type: entities
title: CPAP Therapy
entities:
  - entity: sensor.cpap_ahi
    name: AHI (events/hour)
  - entity: sensor.cpap_leak_rate
    name: Leak Rate
  - entity: sensor.cpap_usage_hours
    name: Usage Tonight
  - entity: sensor.cpap_pressure_current
    name: Current Pressure

📖 Full Guide: See docs/HOME_ASSISTANT.md for dashboard examples and automations

┌─────────────────┐
│  ResMed CPAP    │
│  AirSense 10    │
└────────┬────────┘
         │ SD Card (SPI bus)
         │
    ┌────┴────────────────┐
    │                     │
    ▼                     ▼
┌──────────┐    ┌──────────────────┐
│ ezShare  │    │ FYSETC SD WiFi   │
│ WiFi SD  │    │ Pro (ESP32)      │
│          │    │ - CS line PCNT   │
│ HTTP     │    │ - <10ms steals   │
│ polling  │    │ - MQTT push      │
└────┬─────┘    └────────┬─────────┘
     │ HTTP               │ MQTT
     ▼                    ▼
┌──────────────────────────────────┐
│          HMS-CPAP Service        │
│  BurstCollector | FysetcReceiver │
│  EDFParser + SessionDiscovery    │
│  DataPublisher + LLM Summary     │
└──────────┬──────────┬────────────┘
           │          │
    ┌──────┘          └──────┐
    ▼                        ▼
┌──────────┐       ┌──────────────┐
│PostgreSQL│       │ MQTT (EMQX)  │
│(history) │       │ 47 sensors   │
└──────────┘       └──────┬───────┘
                          │
                          ▼
                  ┌───────────────┐
                  │Home Assistant │
                  └───────────────┘

ezShare mode: Poll HTTP every 65s -> download EDF deltas -> detect session stop (files unchanged across 2 cycles) -> parse -> publish

FYSETC mode: Receive BRP chunks in realtime during therapy -> post-therapy: manifest + STR from FYSETC -> diff & fetch missing files -> parse -> publish + LLM summary

Multiple checkpoint files per session are grouped by SESSION_GAP_MINUTES (default 60).

• C++17 compiler (GCC 9+, Clang 10+)
• CMake 3.16+
• libcurl, libpq, libssl

Native x86 Build:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

# Run tests
make test

# Run with verbose output
./hms_cpap

ARM Cross-Compilation (for Pi Zero 2 W):

# One-time setup: Install ARM toolchain
sudo apt-get install -y g++-arm-linux-gnueabihf sshpass

# Sync Pi libraries to sysroot (one-time, ~220MB)
mkdir -p sysroot/usr sysroot/lib/arm-linux-gnueabihf
rsync -avz aamat@192.168.2.73:/usr/include ./sysroot/usr/
rsync -avz aamat@192.168.2.73:/usr/lib ./sysroot/usr/
rsync -avz aamat@192.168.2.73:/lib/arm-linux-gnueabihf ./sysroot/lib/

# Build for ARM (40 seconds vs 5 minutes on Pi!)
./build_arm.sh

# Deploy to Pi and restart service
./deploy_to_pi.sh

📖 Full documentation: See docs/CROSS_COMPILATION.md for detailed setup, troubleshooting, and architecture details.

hms-cpap/
├── src/
│   ├── main.cpp                    # Entry point (ezshare/fysetc/local modes)
│   ├── clients/
│   │   └── EzShareClient.cpp       # WiFi SD HTTP client
│   ├── parsers/
│   │   └── EDFParser.cpp           # EDF file parsing (OSCAR algorithms)
│   ├── services/
│   │   ├── BurstCollectorService.cpp     # ezShare/local polling mode
│   │   ├── FysetcReceiverService.cpp     # FYSETC MQTT push mode
│   │   ├── SessionDiscoveryService.cpp   # Session grouping
│   │   └── DataPublisherService.cpp      # MQTT + DB publishing
│   ├── database/
│   │   └── DatabaseService.cpp     # PostgreSQL interface
│   └── mqtt/
│       └── DiscoveryPublisher.cpp  # HA MQTT auto-discovery
├── include/                        # Header files (mirrors src/)
├── tests/                          # 155 unit tests (GTest + GMock)
├── docs/                           # FYSETC_RECEIVER, RESMED_WRITE_TIMING, etc.
├── cmake/                          # ARM cross-compilation toolchain
├── scripts/                        # Utility scripts
└── CMakeLists.txt

cd build && make -j$(nproc)
./tests/run_tests

155 tests across 14 test suites:

• EDF parsing (BRP, EVE, SAD, STR)
• Session discovery and grouping
• MQTT publishing and discovery
• Database operations
• FysetcReceiver (sync, chunk, manifest, base64)
• Configuration, models, integration

Most solutions require cloud services, proprietary apps, or manual SD card removal. HMS-CPAP provides:

• 100% local, no cloud
• Automatic collection via WiFi
• Open-source algorithms (OSCAR)
• Home Assistant integration
• ML-ready PostgreSQL storage

Currently optimized for ResMed AirSense 10/11 (EDF format). Other ResMed models may work. Philips/Respironics use different formats and would need parser modifications.

All data stays local:

• No cloud services
• No external API calls
• Your network only
• PostgreSQL encryption optional
• MQTT can use TLS

Yes! HMS-CPAP uses OSCAR algorithms for parsing. You can:

• Import HMS-CPAP archives into OSCAR
• Run both simultaneously
• Cross-validate metrics

Yes, if you value:

• Stable WiFi (no network switching)
• Reliable collection (always connected)
• WAF (Wife Acceptance Factor - no disruptions)

Direct connection works fine if:

• Single user, dedicated device
• Manual collection acceptable
• Don't mind WiFi switching

📖 Complete List: See docs/METRICS.md

Contributions welcome! Please:

1. Fork repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure tests pass (make test)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open Pull Request

• C++17 standard
• Google C++ Style Guide
• Include unit tests
• Document public APIs

This project is licensed under the MIT License - see LICENSE file.

• OSCAR algorithms - GPL-3.0 (EDF parsing logic)
• libcurl - MIT-style license
• PostgreSQL libpq - PostgreSQL License
• Paho MQTT - EPL 2.0

• OSCAR Project - EDF parsing algorithms
• ResMed - CPAP hardware
• ez Share - WiFi SD card
• Home Assistant - Smart home platform
• CPAP community on Reddit

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Reddit: r/CPAP, r/homeassistant

Made with ❤️ for better sleep and open health data

If this project is useful to you, consider buying me a coffee!