CalmOS Home Automation Python Developer

Python Developer – Smart Home State Machine (FastAPI / asyncio)

We are building CalmOS, a local-first smart home system on FastAPI (Python). We need a developer to implement the state machine — the brain that coordinates all subsystems simultaneously.

CalmOS thinks in states, not devices. Each state defines what lighting, audio, climate, ventilation, sockets, blinds, and security do at the same time. The codebase is running and documented. Full access provided. Testable locally, no on-site hardware needed.

---
9 STATES:
Sleeping · Waking Up · Cooking · Working · Guests · Away · Holiday · Night · Emergency
---

KEY BEHAVIORS PER STATE:
Sleeping: all lights off, infrasound sleep-masking audio (bedroom only), climate 16-18°C silent mode, CO₂ monitored continuously, all sockets off (except fridge/server), security armed. Only activates when ALL residents are in bedroom.

Waking Up: circadian light fade-in (warm → daylight, 20-30 min), infrasound fades out, light follows resident room by room, blinds open slowly, sockets activate as resident enters each room.

Away: setback climate, security elevated. Geofencing at 500m radius triggers preparation sequence (heat, light, ventilate, aroma) before resident arrives.

Holiday: occupancy simulation (random lights + subtle audio), frost protection 6°C minimum, anti-mold minimum ventilation, holiday alarm level (maximum sensitivity). Geofencing triggers full home-coming on return.

Night: includes Night Walk sub-mode — camera detects movement 22:00–06:00 → floor lights only (warm white ≤ 2000K, 15s after passing), all other systems unchanged.
---
AUTOMATIC ROUTINES (run independent of active state):

| Trigger | Action |
|------------------------------|-----------------------------------------------|
| CO₂ > 1000 ppm | Increase ventilation, open zone flap |
| Bathroom humidity > threshold | Ventilation spike |
| Wind > threshold | Outdoor blinds retract |
| No person > X min | Heating setback, lights off, security up |
| Geofencing 500m | Climate, light, ventilation, aroma ready |
---
PREDICTIVE ACTIONS (state machine receives and executes these):

| Situation | Action | Lead Time |
|-------------------------|---------------------------------|-----------|
| Sun hits facade | Blinds down, pre-cool | 2h |
| Resident approaching | Warm, lit, ventilated | 20 min |
| Night < 5°C | Heating up, frost protection | 3-4h |
| Electricity price rising | Charge battery first | Before |
---
EXISTING ENDPOINTS (already in CalmOS, state machine calls these):
Lighting: Art-Net UDP 6454 · Audio: Snapcast JSON-RPC · Sockets/Switches: Shelly HTTP RPC · Ventilation: POST /api/lueftung · Sensors: ESPHome native API (CO₂, temp, humidity)
---
REQUIREMENTS:
- All 9 states switchable via POST /api/state/{mode}
- Transitions smooth throughout — fades, not hard switches
- YAML/JSON config per state (template provided by us)
- Scheduler: configurable time-based triggers per state
- Manual override at any time, return to previous state after timeout
- Multi-person logic: sleeping state only when ALL residents in bedroom
- Placeholder endpoints for: climate API (pending), geofencing input (pending)
---
ACCEPTANCE CRITERIA:
- All 9 states switch correctly via API
- Sleeping → Waking Up: circadian fade, infrasound out, light follows resident
- Away → Home: system ready before resident arrives (geofencing)
- Holiday: occupancy simulation active, frost protection holds
- Night walk: floor lights only, sleep mode uninterrupted
- Routines trigger correctly independent of active state
- No hard switches anywhere — all transitions smooth
- Multi-person condition respected for sleeping state
---
OPEN ITEMS (placeholders needed, not blocking):
- Climate API integration (pending, 22.05.)
- Geofencing webhook (after app, mock endpoint for testing)
- State YAML configs provided by us before start