Somnoscope — literally a "sleep microscope." A local sleep tracker that fuses wearable, climate, and ML data — no cloud, no vendor lock-in, and no claim to be a finished product you can't audit yourself.
Status: Phase 1 — infrastructure foundation. Not production-ready yet.
Commercial sleep trackers give you a "sleep score" and a few colored bars, but:
- Raw data stays locked inside proprietary clouds.
- Scoring algorithms are not inspectable.
- Sensor fusion with room climate (CO₂, temperature, humidity) simply doesn't happen — even though that's often the actual reason for restless nights.
Somnoscope is an attempt to solve all three problems on a Raspberry Pi or any ordinary Linux host. The system should still deliver useful analysis when only a single wearable is connected — IoT sensors and the LLM coach are optional plug-and-play modules.
| Feature | Status | Module |
|---|---|---|
| Config-driven modularity | ✅ Phase 1 | core/ |
| BLE wearable adapter | ⏳ Phase 2 | adapters/ |
| MQTT climate-sensor integration | ⏳ Phase 3 | iot/ |
| SciPy preprocessing + EDF export | ⏳ Phase 4 | ml_pipeline/ |
| YASA sleep-stage scoring | ⏳ Phase 4 | ml_pipeline/ |
| InfluxDB persistence | ⏳ Phase 5 | database/ |
| Local LLM coach (Ollama) | ⏳ Phase 6 | llm_coach/ |
[ BLE wearable ]──┐
├──► [ adapters/ ] ──► [ ml_pipeline/ ] ──► [ database/ ] ──► [ Grafana ]
[ ESP32 climate ]─┤ │ │ │
(via MQTT) │ │ │ │
└──► [ iot/ ] └──► [ llm_coach/ ] ────┘
Everything runs locally on a single host. Modules communicate through asyncio
queues and a central config loader.
⚠️ Current functionality is limited to bootstrapping — see the roadmap below.
git clone https://github.com/numan7272/Somnoscope.git
cd Somnoscope
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\Activate.ps1 # Windows PowerShell
pip install -r requirements.txt
python main.pymain.py reads config.yaml, writes logs to logs/somnoscope.log, and prints
which modules are currently active to the terminal.
config.yaml controls every module. Excerpt:
wearable:
enabled: true
device_type: "fitbit_ble"
mac_address: "AA:BB:CC:DD:EE:FF"
climate_sensors:
enabled: false # module is skipped when false
llm_coach:
enabled: falseAny optional module can be toggled on or off at any time without breaking the rest of the system (graceful degradation).
- Python 3.10+ (
asyncio) bleakfor BLEpaho-mqttfor IoT sensorsscipy,mne,yasafor signal processing and sleep scoringinfluxdb-clientfor persistence- Optional:
ollama/llama-cpp-pythonfor the local LLM coach
- Phase 1 — config loader, logger, bootstrap
- Phase 2 — BLE wearable adapter (Fitbit as the first reference)
- Phase 3 — MQTT subscriber for ESP32 climate data
- Phase 4 — preprocessing + YASA scoring
- Phase 5 — InfluxDB writer + Grafana dashboards
- Phase 6 — local LLM coach via RAG
Bugs and ideas go through GitHub Issues. The full workflow is documented in CONTRIBUTING.md (currently in German — English translation coming soon). Short version:
- Open an issue first — even for small bugs, with reproduction steps and expected behavior.
- One branch per issue — format:
fix/issue-<nr>-shortnameorfeat/issue-<nr>-shortname. - Document root cause and chosen solution in the issue.
- Close the issue only when the PR is merged — not when it's opened.
MIT — see LICENSE.
Somnoscope processes health data. Even though everything runs locally: if you expose the system beyond your own network (e.g., by putting Grafana on the public internet), you are responsible for authentication, TLS, and GDPR/HIPAA compliance yourself. The defaults are deliberately "localhost only."