MQTT Messaging

Meridian VMS uses MQTT for real-time communication between the management server and recording servers. MQTT enables instant push of configuration changes to recorders without requiring service restarts.

Architecture

Management Server                    Recording Servers
      │                                     │
      │  Publish: config commands           │
      ├────────────────────────────────────>│
      │                                     │
      │  Subscribe: heartbeat/status        │
      │<────────────────────────────────────┤
      │                                     │
      └──────────── MQTT Broker ────────────┘
                   (port 1883)

The MQTT broker runs on the management server host. Recording servers connect to the broker on startup and maintain a persistent connection throughout their lifecycle.

Configuration Commands

The management server publishes configuration commands when changes need to be applied to a specific recording server in real time. Each recording server subscribes to its own command channel on startup.

Supported commands:

Command	Payload	Effect
add_camera	Camera configuration	Recorder begins ingesting and recording the new camera
remove_camera	Camera identifier	Recorder gracefully stops recording and releases the camera stream
update_camera	Updated camera configuration	Recorder restarts the affected camera pipeline with new settings
update_detection_config	Detection configuration	Recorder updates AI detection parameters without restarting the video pipeline

Heartbeat and Status

Recording servers publish periodic heartbeat messages to confirm they are alive and report per-camera status. The management server subscribes to heartbeat channels to update the online/offline state displayed in the web interface.

Heartbeat interval

Recording servers send a heartbeat every 30 seconds. If no heartbeat is received within 90 seconds, the management server marks the recording server as offline.

Configuration

MQTT broker connectivity is configured during installation. The management server connects to the broker on startup and recording servers are configured with the broker address as part of their setup process.

Broker Security

Production security

For production deployments, consider enabling MQTT authentication and TLS encryption on the broker to secure communication between servers.

Benefits Over Polling

• Instant propagation — Camera additions, removals, and setting changes take effect within seconds
• No restart required — The recorder daemon applies changes on the fly without stopping active recording pipelines
• Reduced load — Eliminates periodic polling requests from every recording server
• Scalable — MQTT handles hundreds of connected recorders efficiently with minimal overhead

Troubleshooting

If configuration changes are not being applied to a recording server:

1. Verify the MQTT broker is running: sudo systemctl status mosquitto
2. Check the recorder daemon logs for MQTT connection errors: sudo journalctl -u meridian-recorder -f
3. Confirm the MQTT broker address is correctly configured on the recording server
4. Test broker connectivity from the recorder host