Use the device's configured embedded broker or external broker. The device MQTT client must be running and connected to that broker. Embedded credentials/ACLs are synchronized from eligible device users; external brokers must enforce the same per-user topic ownership. Configure broker listeners, TLS/trust and client settings through the device management interface.

The embedded internal listener uses 127.0.0.1:1883. This loopback listener is not a LAN endpoint. Use the configured external listener (TLS port 8883 by default) for remote clients.

The embedded broker uses the device’s HTTPS certificate and private key by default and follows renewal of device-managed HTTPS material. An uploaded custom MQTT server certificate is preserved until you explicitly reset it to the HTTPS certificate. Connect using a hostname or IP in the certificate’s Subject Alternative Name (SAN), and configure clients with the appropriate trusted issuer chain. /media/data/mqtt/ca.crt can contain a certificate rather than a complete issuing-CA chain; do not assume that exporting this file alone establishes normal CA-chain trust. Keep hostname and certificate verification enabled. See Certificates and TLS for provisioning.

Enable the MQTT module in Settings → Modules and configure its MQTT section on that same page. An active mqtt license is required to run the service and execute commands; configuration can still be read and saved while inactive. Choose the embedded or external broker, credentials, topic prefix and device ID, save, then start the device client. Embedded mode manages the local broker as part of startup. Confirm that the client reports connected. Configure application users and their API permissions before connecting an integration client.

Omit / when configured with include_device_id=false. Subscribe to replies before publishing. Always publish requests non-retained. All 67 operations accept a versioned request through execute_v1; only the eight commands below also have direct-topic handlers. Each is one operation with two transport forms, not two command names.

Replace the illustrative expiry with device-compatible Unix milliseconds strictly in the future and at most 60 seconds ahead. Calculate expiry from the current time when sending each new request; keep client and device clocks synchronized. Give every intentional action a unique request ID. Request IDs are 1–64 bytes; requests are limited to 4096 bytes. Required fields are version, request_id, command, expires_at_ms; params defaults to {} where allowed. Unknown fields/types/commands are rejected. User identity comes from the ACL-protected topic, never a payload owner field.

Responses contain version, request_id, command, timestamp_ms, phase, success, data, and error fields when applicable. Phases are rejected, failed, accepted, applied, and completed. applied normally confirms API configuration readback; accepted reports asynchronous intent, not physical completion. GPIO direct output additionally confirms driver readback. Read-only queries use completed.

Structured mutating requests use duplicate protection scoped to the topic user. Identical ID, command, parameters and expiry replay the cached result while the request remains valid; conflicting mutation IDs are rejected. Entries expire at expires_at_ms, with a five-minute monotonic upper bound, so the normal retry window is at most 60 seconds. get_state and status always read fresh state and do not use the cache. Replies are non-retained QoS 1 and limited to 16 KiB. Asynchronous actions report progress through state queries rather than later correlated completion callbacks.

Use the certificate controls in Settings → Modules → MQTT. Server identity, trust for incoming client certificates and trust for an external broker are separate settings. Certificate uploads and removals automatically reload or restart the affected connection; a separate reload button is not required. After a change, reconnect integration clients and check the device connection status. A successful upload reports installation, not a completed TLS handshake.

Uploads check PEM readability and certificate/key matching. They do not establish that an external client trusts the chain or that the configured hostname matches its SAN. Use a correctly issued chain for normal CA validation, or an explicitly supported certificate-pinning configuration. The device skips TLS for broker hosts literally named localhost or 127.0.0.1, including external mode; use a certificate-matching named endpoint when TLS is required.

For automation, send authenticated POST /api/mqtt/certificates?kind= with multipart/form-data and NetworkSettings_rw permission. The whole request body is limited to 256 KiB. PEM fields are certificate, key, ca, and optional passphrase. Transfer private keys only over HTTPS.

Success returns HTTP 200 with {"ok":true}; installation/validation errors return HTTP 400 with {"ok":false,"error":"…"}. Missing permission returns 403 and oversized uploads return 413. Inspect mqtt_certificates for certificate source, identity and CA-bundle details.

Read mqtt_config, write configuration with NetworkSettings_rw, and inspect mqtt_config_validation_result before starting. Include mode (embedded or external) in configuration writes. Saved configuration lives in /media/data/config/mqtt.json. The management HTTP endpoints are GET /api/mqtt/config, POST /api/mqtt/config and GET /api/mqtt/status.

Use mqtt_action with an action value of start_client, stop_client, restart_client, restart_broker, reload_acl or reload_certificates. The HTTP POST /api/mqtt/actions interface accepts the four restart/reload actions, not start/stop. Starting applies saved configuration; observe client/broker state after asynchronous transitions. Module activation, including activation during application startup, starts MQTT from saved settings. The exposed startup.auto_start field is not used to gate this activation path; do not rely on it to keep an active module stopped after reboot.

connection.session_persistent defaults to false (clean session); existing saved values are preserved. Enabling it lets the broker retain subscriptions and queue eligible messages during disconnection. Queued direct commands have no expiry and can execute after reconnection. Prefer expiring execute_v1 requests for controls. This setting is distinct from the application result cache and from durable broker storage. The outgoing in-memory queue is bounded by connection.publish_queue_limit and drops its oldest item when full.

For an external broker, the application derives the caller from the topic username; it cannot inspect the publishing client’s authenticated broker identity. Configure broker ACLs so each client can publish only its own command topics and read only its own private responses. Only the device service identity may publish responses/capabilities. TLS alone does not enforce these ownership rules.

These names are also valid inside an execute_v1 envelope. New clients should use the envelope for client-chosen IDs, expiry and duplicate protection.

RPM values must be nonnegative signed-32-bit integers. This is a representation bound, not a hardware-certified speed range. The existing API motor behavior remains in effect. Direct deliveries get generated IDs and have no duplicate protection. status replies on the user's response topic and, for direct requests, preserves a limited shared events/status snapshot. It is distinct from get_state, which reads selected raw API fields.

Breaking change: the following 23 names no longer execute, on either direct topics or execute_v1. They return COMMAND_REPLACED with a replacement description and are absent from capability discovery. Publish replacement requests through execute_v1; do not merely rename the old direct topic. Replies then arrive on the execute_v1 response topic and use the result envelope's data object.

Former camera_settings keys: exposure, brightness, contrast, whiteBalance, noiseSuppression, sharpness, saturation.

Former stream keys: resolution, fps, streamingResolution, streamingFps, streamingBitrate, freeze.

For system, former response labels description and performance become raw state keys systemDescription and systemPerformance in data. There is no separate grouped-query handler or duplicated top-level result data.

The optional video_start.mode input was also removed. Use video_start, timelapse_start, or slowmotion_start, each with {}. Even mode:"normal" is rejected; empty parameters give one explicit command per recording mode. slowmo is not a separate alias.

video_stop, timelapse_stop, and slowmotion_stop remain distinct: the latter two require the matching active mode, while video_stop is generic. Opposite on/off actions and different head/sensor targets remain separate because they request different state changes. Shared status-event topics remain available; removing grouped query commands does not remove those event topics.

Head 0 and head 1 commands address the numbered camera, light or disc independently. select_head0/1 selects the active view; headN_sensorM selects that head’s sensor. Layout commands select single view, the named picture-in-picture corner, or side-by-side. Automatic exposure, white balance and noise suppression toggle the corresponding image setting; auto-rotate and disc controls address the named head. Stream/record time/date commands toggle those overlays. Audio commands toggle recording or backup audio, subject to configured audio input. visual_backup_on/off sets backup intent for the configured backup storage.

These names use empty {} parameters. Three also appear in the direct-topic table above and are counted once. All others require execute_v1.

Head/sensor/focus/layout availability is checked. Shared API recording services enforce camera/storage and resource restrictions. timelapse_stop and slowmotion_stop require the matching active mode. MQTT video_stop remains a generic stop for legacy compatibility.

set_parameter requires exactly params.name and params.value. Only these names are exposed:

For example:

Recording/backup setting restrictions from the API still apply. A rejected setter or readback mismatch returns failed. Zoom and autofocus return accepted because hardware motion is asynchronous. These controls do not introduce new guarantees beyond the API's hardware behavior.

For overlays and pre-roll, omitted fields retain their previous values. Unknown fields, empty objects and string-encoded objects are rejected. The result's data.value contains the full accepted object; numeric integer/float representation differences do not cause false failures. prerollSettings describes configuration; read prerollStatus to check active buffering, duration and capacity. Special recording modes can suspend buffering even when configured enabled.

Filename components accept ASCII letters, digits, hyphen, underscore and dot. Empty strings clear the component and restore normal API naming behavior. Spaces, non-ASCII text, directory separators, NUL, . and .. are rejected before invoking the API, so names are not silently sanitized or truncated. Naming changes affect subsequent captures/files, not names of existing recordings. The 17/55-byte limits match the current API setter's inclusive substring limits.

Bitrate caps use the existing API's 10–100 Mbit/s bounds. The target bitrate's 100 Mbit/s ceiling is an command contract limit; it is not a claim that all codecs or modes can achieve it. Existing recording resolution/FPS changes may recompute the recording cap. Query accepted settings after such changes.

configure_backup invokes only the following three API setters with storage-policy permission; it cannot change storage credentials or select a storage device.

The 8760-hour ceiling is a deliberate command limit, not a storage-capacity guarantee. The API may reduce the requested hours to fit available storage. A successful retention result includes requested, value, configured_hours and adjusted. For example, requested:24, value:12, adjusted:true means the API selected 12 hours. The exposed write key is backupNumberOfSavedHours; backupNumberOfSavedHoursSet is read-only and reports effective configuration.

These settings use existing backup behavior, including capacity notifications, stopping/reducing retention at capacity, and automatic cleanup of eligible backup media. Changes apply as individual operations, not as an atomic multi-setting transaction. Read the policy settings and remaining capacity after configuring them.

Projects: humandetect, spandetekt, motiondetect. Starting AI requires an active license, connected camera, available processing resources and a selected installed model where the project requires one. motiondetect does not use a selectable model. Stop remains possible when the license is inactive. Stop AI and wait for process exit before changing project/confidence; an active project's model cannot be changed.

Runtime settings accept displayMode (all, or relevant for spandetekt), showTool, profile, autoTag, deletable, window (0.3–60), integer triggerTime/gap/cooldown (0–3600), classes, and ampel. Profiles must be advertised by the selected model. Class maps allow at most 16 entries; class keys have at most 64 bytes. Numeric class/traffic-light thresholds are 0–10000; positive warn must not exceed positive crit. ampel requires window and classes. These are transport bounds and count-based thresholds, not necessarily confidence probabilities.

Omitted top-level settings are preserved. Supplied nested class/traffic-light objects replace those nested values. Null reset, arbitrary runtime keys, model upload/delete and producer ingestion are not exposed. AI start/stop results report accepted; use kiControl, kiProjects, and processAmpel for actual process/decision state. Stored runtime settings still require producer support. These services are shared with OPC but execute with the MQTT caller's permissions.

All three require StreamSettings_rw and enabled/licensed GPIO. Command and returned single-binding pin numbers are 1–4; raw binding arrays from get_state retain API indexes 0–3. Input/output state objects use pin1…pin4 string levels "0"/"1".

The supported MQTT input actions remain light0, light1 and recording. The wider API gpioActions/gpioSources catalogs may contain additional entries; use this protocol’s command tables to determine accepted values. For example, freeze is not an accepted input-binding action.

For supported input actions, HIGH selects on/start and LOW selects off/stop. The current level is applied once after binding creation and GPIO initialization, then after subsequent level changes, following a 300 ms settling interval. A failed action or a later UI change is not continuously retried at the same level; another input transition is required. Duplicate pin/action combinations are rejected; input bindings are capped at 32 total and eight per MQTT user. One output binding occupies each pin. MQTT can replace its own output binding, but cannot replace or delete another user’s or an OPC/API-owned binding. Driver readback does not verify external wiring; binding creation confirms stored configuration.

MQTT binding ownership is server-assigned deviceRole:"mqtt_user" plus createdByUser:, persisted across restart. Input actions recheck GPIO and target-action permissions; output evaluations recheck GPIO and source-read permissions. Deleting a user removes that user’s MQTT input and output bindings, so recreating the same username does not inherit them. Permission revocation prevents further authorized actions/evaluations but does not automatically reset an output. Removing a binding leaves its last output level unchanged. No missing owner falls back to admin for MQTT bindings; naming a user opc-pubsub does not grant the OPC role.

Bindings keep running independently of broker connectivity while their owner's permissions allow it. The existing privileged API/OPC output-binding administration can still replace or remove output bindings. Output source inversion can make a missing/inactive source HIGH. Backup activity is requested intent; reconstruction state does not start reconstruction. Direct output levels are not persisted across reboot. General network tasks, arbitrary state writes, pulses and schedules remain outside this command interface.

Device availability uses separate /camera/status/online and /camera/status/lwt topics. Connection publishes retained online:true on the online topic; the Last Will publishes online:false on the LWT topic after unexpected disconnection. Do not treat a retained online message alone as proof of a current connection, or the Last Will timestamp as the exact disconnection time. Grouped state events under /events/# are retained QoS 1 snapshots. The /events/status/picture event (payload field picture_taken) is non-retained; old retained photo events are cleared when the device connects. Private request results are non-retained.

get_state includes kiControl, kiModels, kiRuntimeSettings, kiProjects, processAmpel, processGraph, reconstruction3dActive, gpioInput, gpioOutput, gpioInputBindings, gpioOutputBindings, gpioSources, and gpioActions, alongside the operational allowlist. Each read is permission-checked. Producer inputs kiSample/kiEvent remain unexposed.

The private automation_state topic publishes version, timestamp_ms, a state object and omitted_keys. It includes readable values from kiControl, kiProjects, processAmpel, gpioInput, and gpioOutput; it is sent on connect and on changes, coalesced to at most four snapshots per second. It uses non-retained QoS 1 and rechecks each user's read permissions on every send. Large fields are omitted to preserve result-size bounds; query individual fields instead. Existing shared event topics are not expanded to broadcast private AI/GPIO state. Snapshots are not correlated completion events.

get_state requires params.keys, an array of 1–16 allowed strings. Duplicate keys are returned once. Reads return current API state, not a hardware-synchronous snapshot. Every requested key requires read permission. MQTT also supports systemDescription and systemPerformance. The shared readable keys are:

cameraSwitch, cam0Exists, cam1Exists, cam0SelectedSensor, cam1SelectedSensor, headIsSlowMoCompatible, light0, light1, light0Brightness, light1Brightness, light0Dim, light1Dim, dictRotation0, dictRotation1, RPM0, RPM1, exposure, whiteBalance, noiseSuppression, brightness, expo, gain, contrast, sharpness, saturation, redGain, blueGain, pip, autoRotate0, autoRotate1, freeze, zoomState, focusView, focusCam0Sensor0, focusCam0Sensor1, focusCam1Sensor0, focusCam1Sensor1, takePicture, record, recordingMode, recordTime, recordingFilename, fotoFilename, backupActive, backupFilename, backupRemainingCapacitySeconds, fotoResolution, resolution, fps, streamingResolution, streamingFps, pictureQuality, streamingQuality, recordingQuality, slowmoQuality, streamingFormat, recordingFormat, timelapseInputFps, timelapseOutputFps, highSpeedMode, streamingWithTimeStamp, streamingWithDateStamp, recordingWithTimeStamp, recordingWithDateStamp, recordingAudioActive, backupAudioActive, streamingIsBusy, streamingBitrate, streamingMaxBitrate, recordingMaxBitrate, streamingTimestampSetting, recordingTimestampSetting, prerollSettings, prerollStatus, changeVideoName, changeImageName, changePostName, changeBackupPostName, alignmentStream0, alignmentStream1, backupUseCompleteSpace, backupNumberOfSavedHours, backupNumberOfSavedHoursSet, backupOnReachingRecordingTimeCapacityAction, kiControl, kiModels, kiRuntimeSettings, kiProjects, processAmpel, processGraph, reconstruction3dActive, gpioInput, gpioOutput, gpioInputBindings, gpioOutputBindings, gpioSources, gpioActions, fpgaTemp, oct0, oct1, psi0, psi1, swVersion, fmVersion.

The broker authenticates the client and enforces topic ownership; the application separately checks the corresponding API permission for each command. Users must only publish to their own cmd/users//+ topics and subscribe to their own response/users//#. External broker administrators must enforce this separation, including protection against publishing forged responses. The device’s internal client needs access to incoming user commands and outgoing replies/telemetry.

Subscribe to your retained per-user capabilities topic for permitted commands, resolved reply paths, typed settings and envelope limits. Capabilities refresh on connection and permission changes; deleting a user clears its retained capabilities. execute_v1 describes the dispatcher and is not an extra permitted operation. Availability still depends on connected heads, storage, licenses and configuration. Every write and requested state key is permission-checked, including cached retries. Values requiring read permission are omitted when the caller lacks it.

The mutation cache holds at most 64 entries per user and 1024 globally. When either limit is reached, new structured mutations return QUEUE_FULL until entries expire; read-only queries do not consume slots. Cache state survives broker reconnects in the same application process, but not application restart. Retry a missing mutation reply with the identical envelope, including expiry, only while that expiry is valid. After expiry, query current state before deciding whether a new action is needed. Direct commands have neither expiry nor duplicate protection. The receive channel holds 100 events; overflow and requests over 4096 bytes can be dropped without a correlated reply. Receive-queue drops increment mqtt_status_update.statistics.commands_dropped. A broker delivery acknowledgement does not confirm execution.

For capture, compare takePicture and fotoFilename with their previous values. For recording, observe record, recordingMode, recordingFilename and recordTime. For AI, observe kiControl, kiProjects and processAmpel. A filename alone does not establish that writing has finished. Other clients can change the same state.

Install the Python paho-mqtt client in your integration environment. Set MQTT_HOST, MQTT_USER, MQTT_PASSWORD, MQTT_CA, and MQTT_BASE for your configuration. This example uses TLS, subscribes before publishing, and makes a read-only state request. The example requires Paho MQTT 2.x.