HMS-CPAP
A small, local-only CPAP data viewer. Reads your machine's SD card, shows you your nights in a web dashboard, and (optionally) publishes them to Home Assistant.
Not a medical device
HMS-CPAP is a hobbyist data viewer. It is not a medical device, is not cleared
by any regulator, and cannot diagnose anything or tell you whether your
therapy is working. Never change your therapy settings based on this
software. Talk to the clinician who manages your therapy. The numbers can be
wrong: the parsers read undocumented, reverse-engineered formats.
Read DISCLAIMER.md before using this. By using it you accept
the Terms of Use. Not affiliated with ResMed, Philips, Löwenstein,
Sefam, BMC, React Health, SleepHQ, or anyone else named here. See NOTICE.
What it is
A C++ service with a built-in Angular web UI. It pulls the files your CPAP
writes to its SD card (over WiFi via an ezShare or Toshiba FlashAir card, or
from a folder),
parses them itself, stores the results in a database, and shows you the data.
It is a fully local-first experience.
Supported machines
| Manufacturer | Models | Live sessions |
|---|
| ResMed | AirSense 10, AirSense 11 | Yes, charts update every 65s during therapy |
| Lowenstein | Prisma Line (20A, 20C, 25S, 25ST), Prisma Smart (Max, Plus, Soft) | No, files are written after each session |
| Sefam | S.Box AUTO (1263R), SleepBox AUTO (1200R) | No, the card is read after the night |
| BMC / React Health | Luna | No, the card is read after the night |
On a Sefam card you get the recorded signals, breath-by-breath respiratory
mechanics, and apneas. You do not get an AHI. The machine records apneas but
does not mark hypopneas in a form anyone outside Sefam can read, so HMS-CPAP
shows an apnea-only index and labels it as one. It will read lower than the AHI
a ResMed reports for the same night. That is a different measurement, not a
better night.
On a Luna card you get pressure, leak, respiratory rate and I:E ratio per minute, and the apneas the
machine marks itself (obstructive and clear airway). On a bi-level Luna, IPAP,
EPAP and pressure support are reported too. There is no flow waveform yet: its
scale on the card is not known, and a number in the wrong unit is worse than
none. A Luna is read from a local folder or the upload page, not over WiFi.
Features
- Dashboard with the key numbers per night, 30-day trends, pressure gauges, and a per-night CpapDash Index (usage + AHI + leak in one number)
- Session detail with 13 zoomable signal charts, event markers, and live view while you sleep (ResMed)
- Events explorer: every respiratory event across all nights, filterable by date, type, and duration
- PDF reports for a date range, made for handing to your doctor
- Pulse oximetry: Wellue O2Ring SpO2/HR overlay with ODI, imported by CSV upload
- AirSense 11 over Bluetooth (off by default): for a machine whose SD slot cannot power a WiFi card, the bridge reads the machine's own daily summary over its Bluetooth and the nights show up without a card
- Manual upload page: drag in a CPAP
.zip or O2Ring .csv from any browser, no shared network needed
- Home Assistant: 47+ sensors via MQTT auto-discovery, or install it as an add-on and run it inside HA
- Equipment & supply reminders: track mask, filters, tubing per profile; days-left sensors and due/overdue events for automations
- SleepHQ export (off by default): forward each finished night to SleepHQ
- ResMed myAir comparison (off by default, read-only): put ResMed's own nightly score next to CpapDash's
- LLM night summaries (off by default): plain-language write-ups via Ollama or any OpenAI-compatible endpoint
- ML insights (off by default): AHI prediction, compliance forecast, mask-fit risk, anomaly detection
- Any database: SQLite (default, zero setup), PostgreSQL, or MySQL/MariaDB
- Runs on Windows, macOS, Linux, Raspberry Pi, Docker, or as a Home Assistant add-on
Install
Pick one. Every path ends at the same four-screen setup wizard in your browser:
where to store data, where the data comes from, which optional extras to turn
on, and whether to start at boot.
Home Assistant add-on (easiest if you run HA)
Settings -> Apps -> three dots -> Repositories, add:
https://github.com/hms-homelab/hms-cpap-ha-addon
Install CpapDash, start it, and the wizard opens through Ingress. No port to
open, no second password; the MQTT broker's credentials are picked up
automatically.
Windows
Download HmsCpapInstaller-Setup.exe from
Releases and run it. No
admin rights needed. A tray icon gives you Open Dashboard, Sync Now, and Start
at Login.
macOS
Download hms-cpap-macos-arm64.zip from
Releases, unzip, run:
./hms_cpap
Your browser opens on http://localhost:8893/setup.
Raspberry Pi and Linux (Docker)
The image on GHCR is built for arm64 and amd64, so it runs as-is on a
64-bit Pi 3/4/5 or any x86 Linux box. Nothing to compile.
docker run -d --name hms-cpap -p 8893:8893 \
-v cpap_config:/config -v cpap_data:/data \
ghcr.io/hms-homelab/hms-cpap:latest
Open http://localhost:8893/setup. Config lives in the cpap_config volume and
data in cpap_data; neither is touched by image updates.
If you'd rather have PostgreSQL and an MQTT broker alongside it, clone the repo
and run docker compose up -d instead; it brings up all three and waits for
the database before starting CpapDash.
A Pi that already runs Home Assistant can skip Docker entirely and use the
add-on above.
Linux (build from source)
git clone https://github.com/hms-homelab/hms-cpap.git
cd hms-cpap
./build_and_deploy.sh --deploy # builds frontend + backend, runs tests, installs the systemd unit
Or without the script: mkdir build && cd build && cmake .. && make -j$(nproc) && ./hms_cpap.
Getting the data off the machine
ResMed AirSense 11 with REF 39517 on the label underneath: its SD slot
can't power a WiFi SD card reliably, so don't use an ez Share or a Toshiba
FlashAir in it. Read it over its own Bluetooth instead (see
AirSense 11 over Bluetooth), or
use a local folder or the upload page.
- ezShare WiFi SD (recommended): the card sits in the CPAP's SD slot and
serves files over WiFi. It makes its own network, so you need a bridge such as
hms-mm (Mule & Miner) to put it on
your LAN. The wizard can scan for one. To set a bridge up, the
hms-mm web flasher flashes both of its
boards from Chrome and takes your WiFi details on the same page -- nothing to
install. Works with a ResMed card and a Sefam S.Box card. For a Sefam card,
set an archive folder: the card is copied there, all of it on the first run
and then its last two nights.
- Toshiba FlashAir WiFi SD: the card sits in the CPAP's SD slot and joins
your home WiFi itself, so no bridge is needed. Set it to join your network
(
APPMODE=5 in its SD_WLAN/CONFIG) and pick FlashAir in the wizard; it is
found as http://flashair.local, or give its address. ResMed cards. Tested
on a FlashAir W-02 in an AirSense 10, read live through a full night.
- Local folder: point the wizard at the SD card root (the folder that holds
both
STR.edf and DATALOG/), on a USB reader, NAS share, or any mount. For
a Luna, point it at the card root and pick "BMC / React Health Luna".
- Upload page: zip the card and drop it in the browser. A ResMed, Sefam,
Löwenstein or Luna card is recognised by its files, and every night not yet
stored is imported.
Everything else (config keys, CLI flags, MQTT sensor list, myAir setup,
architecture, development, cross-compiling) is in
docs/REFERENCE.md.
How it is built
The architecture/ folder maps the code:
- architecture/db.md: every table on SQLite, MySQL
and PostgreSQL, how they are keyed and related, who writes and reads each
one, and the time rules every date follows.
- architecture/layers.md: the layers of the app
(entities, the database layer, services, the web query layer, controllers,
the frontend) and how a web request and a collection burst travel through
them.
Disclaimers
- Not a medical device. It does not diagnose anything and it is not a
monitoring or alarm system. Never adjust your therapy based on this software.
DISCLAIMER.md
- The data can be wrong. Parsers are reverse-engineered from undocumented
formats and collection can fail silently. Cross-check with your clinician or
the manufacturer's own tools.
- No authentication. The web UI has no login. Keep it on your LAN; do not
expose it to the internet.
- Privacy. There is no telemetry and nothing phones home. The only outbound integrations are
SleepHQ, CpapDash sync, myAir, and LLM summaries, all off by default and each
one you enable yourself. PRIVACY.md
- Independence. Not affiliated with or endorsed by ResMed, Philips,
Lowenstein Medical, Sefam, BMC, React Health, SleepHQ, or any other company named here. Trademarks
belong to their owners. No OSCAR source was copied or derived from; it was
consulted only to understand file formats. NOTICE
- License. MIT. Use it, modify it, sell it; keep the notice.
LICENSE · TERMS.md
Contributing & support
Fork, branch, add tests, make sure ./tests/run_tests passes, open a PR. See
docs/CONTRIBUTING.md.
If this project is useful to you, consider
buying me a coffee or starring the repo.
