Web API#

The camera answers HTTP on port 5000. Any CineMate CLI command line can be sent over HTTP instead. Replies are plain text, so a microcontroller needs no JSON parser.

curl -d "rec" http://cinepi.local:5000/api/v1/cmd

Address#

Send a command#

One endpoint: /api/v1/cmd. Send the command line exactly as you would type it in the CLI.

curl -d "set iso 800" http://cinepi.local:5000/api/v1/cmd
curl -d "set fps 48" http://cinepi.local:5000/api/v1/cmd

Replies#

Add ?json=1 for {"ok":true,"cmd":"set iso 800","message":""} instead.

Read a value#

GET /api/v1/get/is_recording   →   1

Returns the raw value as text. This is the endpoint for a tally light. Unknown keys return 404 and err unknown key. Key names are the Redis keys.

Many values at once#

Use ?keys= on memory-constrained devices; a full snapshot is all 88 keys, a couple of kilobytes of JSON. Unknown keys in ?keys= are skipped silently rather than erroring, so one firmware build works across CineMate versions.

/commands and /hello#

GET /api/v1/commands returns every command the camera accepts, as JSON [{"name":"set iso","arg":"int"}, ...], or one name per line with ?fmt=text. It is built live from the running command table.

GET /api/v1/hello returns cinemate 3.4.0 api=1 sensor=imx585 cams=1 rec=0. A configured token guards it, like every other /api/v1/ route.

Keep a device in sync#

Use the UDP broadcast unless you have a reason not to. One plain-text line goes to port 8888, at both the wlan0 subnet broadcast address and 255.255.255.255, at 5 Hz plus immediately on change (coalesced to at most 10 Hz):

is_recording=1 iso=800 fps=24.0 shutter_angle_actual=180.0 recording_time_tod=01:02:03:04 space_left=412 drop_frame_count=0 is_mounted=1

The keys are the Redis keys, unabbreviated, truncated at 500 bytes. That line is the default set; pick your own in settings.jsonc.

Server-sent events#

GET /api/v1/events returns text/event-stream: one data: key=value per changed key, with a : ping heartbeat every 15 seconds. One thread is held per open connection, so SSE is capped (max_sse_clients, default 4). Beyond the cap the server returns 503 and err too many clients.

Settings#

The stock settings.jsonc already carries a full system.web_api block under system, with exactly the values below — edit it there. The same values are also hard-coded in src/module/web_api_settings.py, and they apply if you delete the block or fill it in only partly, so every field is optional.

"system": {
  "web_api": {
    "enabled": true,
    "token": "",
    "allow_destructive": false,
    "max_commands_per_sec": 20,
    "max_sse_clients": 4,
    "broadcast": {
      "enabled": true,
      "port": 8888,
      "hz": 5,
      "keys": ["is_recording", "iso", "fps", "shutter_angle_actual",
               "recording_time_tod", "space_left", "drop_frame_count", "is_mounted"]
    }
  }
}

Other control paths#

The CLI, serial, the Web API and the Web GUI funnel into one dispatcher. GPIO buttons, rotary encoders and the I²C quad encoder are wired up differently: settings.jsonc names a controller method ({"method": "set_zoom"}), called directly rather than as a command line, so a command name is not a valid value there.

Next step: Building control units — wiring and firmware for a physical controller.