robot2zabbix-backend

Python service that subscribes to MQTT telemetry topics and forwards mapped metrics to Zabbix through zabbix_sender.

It also exposes a built-in navigation API for the browser client and a Zabbix-backed floorplan endpoint that can be embedded into a Zabbix 7.4 dashboard through a URL or iframe widget.

When the browser client runs on a different machine, set api.host: 0.0.0.0 in the backend config so the REST and WebSocket endpoints are reachable over the network.

Spool

When spool.enabled is set, every incoming MQTT message is persisted as NDJSON for downstream machine processing.

• Valid messages are appended under spool/valid/YYYY/MM/DD/HH/<event_kind>.ndjson
• Invalid messages are appended under spool/invalid/YYYY/MM/DD/HH/<bucket>.ndjson

Each valid record contains status, received_at, topic, and event. Invalid records contain status, received_at, topic, raw_payload, and parse_error.

Navigation API

When api.enabled is set, the backend keeps an in-memory object state store keyed by MQTT agent_id and exposes:

• GET /api/v1/objects
• GET /api/v1/objects/locations
• GET /api/v1/floorplan
• GET /api/v1/objects/{object_id}
• GET /api/v1/stream/locations

Object metadata (name, object_type) comes from api.objects in the YAML config. Status values are derived from heartbeat freshness and location freshness using offline_timeout_ms and stale_timeout_ms.

The API sends permissive CORS headers so a browser-based client can consume it from a separate static folder.

Zabbix Floorplan

GET /api/v1/floorplan is intended for the warehouse floorplan viewer embedded in Zabbix 7.4. It reads the current robot state and recent coordinate history from Zabbix items through the Zabbix JSON-RPC API and returns one snapshot that already contains:

• current robot positions
• derived status
• current BSSID and RSSI
• recent tail points for every robot

To enable this mode, configure the zabbix section with:

• api_url: full JSON-RPC endpoint, for example http://zabbix.example/api_jsonrpc.php
• api_token: Zabbix API token with read access to hosts, items, and history
• history_window_sec: how far back to read item history for tails
• tail_limit: maximum returned tail points per robot

Required item keys per robot host:

• wifi.location.x
• wifi.location.y
• wifi.state.bssid
• wifi.signal.rssi_dbm

Optional item key:

• robot.status

If robot.status is absent, the backend derives online / stale / offline from item freshness using api.stale_timeout_ms and api.offline_timeout_ms.

Web Client

A lightweight static navigation client lives in client/:

• client/index.html
• client/styles.css
• client/app.js

It first tries GET /api/v1/floorplan and, when that endpoint is configured, uses Zabbix as the source of truth for robot positions and tails. If the floorplan endpoint is unavailable, the client falls back to the older navigation API and WebSocket stream.

The viewer renders the local warehouse floorplan with robot markers, status colors, BSSID / RSSI labels, and tails with per-segment color changes when the robot switches access points.

Open client/index.html directly in a browser or serve the client/ folder with any static file server. You can override the API base URL with the api query parameter, for example:

client/index.html?api=http://127.0.0.1:8080

For Zabbix 7.4, publish the client/ folder on an HTTP server reachable by the Zabbix frontend and add it to the dashboard with a URL or iframe-style widget. Use the backend base URL in the api query string so the viewer can call /api/v1/floorplan.

Run

python -m robot2zabbix_backend --config config/r2z-backend.yaml

Tests

pytest -q