Test and live mode

Test keys (cym_test_…) are served by a simulator with the same response shapes as a real device. Every response says meta.livemode: false, so simulated data can never be mistaken for a reading. Test mode is free and needs no hardware, so you can build and run CI against it.

Each test project starts with simulated rooms such as room_bedroom. Test mode covers every capability on this site, including skeletons and telling people from pets, so you can build against any of them before a device is installed.

To work offline, cymatics mock start runs the same simulator on your machine with built-in test keys.

A scenario is a scripted timeline: someone sleeps, sits up, leaves the bed, falls, recovers. Start one with POST /v1/scenario-runs and you get a run with its own virtual rooms and devices. Pause it, resume it, or advance a paused run by a duration, and read its rooms, results and events like any others. A fixed seed replays the same content every time.

The simulator ships with 14 presets:

• continuous_care_night
• quiet_night
• bed_exit
• fall_in_en_suite
• busy_meeting_room
• device_offline
• person_and_pet
• exercise_and_skeleton
• vitals_while_moving
• quality_and_revision
• multi_device_tracking
• recovery_week
• footfall_and_visits
• raw_radar_sample

$ echo '{"scenario_id":"bed_exit","seed":42}' | cymatics scenarios run --input -
$ echo '{"action":"pause"}' | cymatics scenario-runs control RUN_ID --input -
$ echo '{"action":"advance","duration_ms":6000}' \
    | cymatics scenario-runs control RUN_ID --input -
$ cymatics events list --room ROOM_ID --json

You can also send a custom timeline instead of a scenario_id. Scenario operations are test only: create scenario run, get scenario run, control scenario run. Live keys calling them get 403 mode_mismatch.

Live keys (cym_live_…) read from a paired Cymo. You can only create one after pairing a device in the dashboard. Live usage is billed per live hour: one hour of streaming from one Cymo.

Live keys call the same endpoints and get the same shapes, with meta.livemode: true. What a live project measures depends on the Cymos paired to it: List capabilities reports live_available for each capability, and List models lists the models your live project can use.

An operation with no live data for the project, for example because no paired Cymo covers it, returns 503 live_unavailable rather than made-up data. Once a project has a monthly live-hour cap and reaches it, live requests get 429 quota_exceeded until the cap is raised.

Use the test and live switch in the dashboard breadcrumb. Your code does not change: swap the key and the API answers in that key's mode. A flag can't turn a test key into a live one, and a live key never reads simulated data.