Fields, enums and error codes
Every field a device sends, every enum it uses, the server-side defaults to match, the full error code table with retry semantics, and a glossary.
7 min read
The device record
| Field | Values | Notes |
|---|---|---|
| mac_address | AA:BB:CC:DD:EE:FF | Unique. The identity |
| property_id | int | Required |
| team_id / table_id | int | Exactly one, per your placement model |
| user_id | int | Optional. Who carries it |
| communication_mode | ai · udp · websocket | Defaults to websocket with a table_id, else ai |
| language | en · ur · ar · multi | multi is code-switching |
| status | ACTIVE · INACTIVE · BLOCKED | BLOCKED means answer 403 everywhere |
| is_online | bool | Event-driven on; swept off after 60 s of silence |
| health_status | HEALTHY · DEGRADED · CRITICAL | Computed from telemetry |
| firmware_version / ota_version / hardware_version | string | From heartbeat; freeze into incidents |
| ip_address | string | IPv4 or IPv6 |
Heartbeat telemetry
All optional. Older firmware that sends none still works, so treat every field as nullable in your schema.
| Field | Unit |
|---|---|
| firmware_version, ota_version, hardware_version | string |
| cpu_usage_percent, memory_usage_percent | 0–100 |
| temperature_celsius | °C |
| uptime_seconds | seconds |
| wifi_rssi | dBm, negative |
| free_storage_bytes | bytes |
| battery_percent | 0–100 |
Full-duplex telemetry worth collecting
| Field | Why you want it |
|---|---|
| playback_buffer_high_water_ms | Decides whether server-side pacing is needed |
| playback_underruns | Audible gaps in the agent's speech |
| playback_overruns | Buffer too small for the burst |
| ws_reconnects | Network quality at that site |
| mic_mute_violations | Frames sent while the speaker was active — should always be 0 |
| rssi | Correlates with everything above |
Enums
| Enum | Values |
|---|---|
| Incident types | CRASH · HARDWARE_ERROR · NETWORK_ERROR · LOW_BATTERY · LOW_STORAGE · HIGH_TEMP · OTA_FAIL · UNEXPECTED_REBOOT · OFFLINE · UNKNOWN, plus firmware-defined WS_CONNECT_FAIL · AUDIO_UNDERRUN · TLS_FAIL |
| Severities | CRITICAL · HIGH · MEDIUM · LOW |
| Command types | REBOOT · TRIGGER_OTA · CHANGE_MODE · FACTORY_RESET · MUTE · UNMUTE · COLLECT_LOGS · PING |
| Command lifecycle | PENDING → SENT → ACKNOWLEDGED → COMPLETED | FAILED, plus EXPIRED |
| OTA progress | DOWNLOADING · INSTALLING · SUCCESS · FAILED · ROLLED_BACK |
| OTA release types | STABLE · BETA · CRITICAL_PATCH |
| Property types | HOTEL · RESTAURANT · SECURITY |
| Communication modes | ai · udp · websocket |
| Languages | en · ur · ar · multi |
Defaults to match
These are the values a factory-flashed device and the reference server agree on. If you change one on your side, you are changing a contract — check the device is provisioned to match.
| Setting | Default |
|---|---|
| UDP ingest port | 12345 |
| Sample rate / channels | 16 000 Hz / 1 |
| UDP payload format | udp-v1 |
| Voice gate: min RMS / attack / silence close | 700 / 3 chunks / 3000 ms |
| Pre-roll buffer / flush | 2.0 s / 1.0 s |
| Offline threshold / sweep interval | 60 s / 60 s |
| UDP presence stamp throttle | 180 s |
| Print claim timeout | 90 s |
| Print stale threshold | 60 s |
| Default printer port | 9100 |
| Mic-mute tail (tail_ms) | 300 ms |
| WebSocket ping / pong deadline | 20 s / 10 s |
| Command expiry | 24 h |
Error codes
Full-duplex handshake — the socket closes after the message
| Code | Permanent? | Device action |
|---|---|---|
| unknown_device | Yes | Stop. Fault indicator. No retry |
| unknown_property | Yes | Stop. Provisioning fault |
| protocol_unsupported | Yes | Stop. Needs an update |
| menu_unavailable | No | Retry with backoff |
| busy | No | Retry with backoff |
HTTP
| Status | Meaning | Device action |
|---|---|---|
| 200 / 201 | Success | Continue |
| 204 | Nothing waiting (print queue, notifications) | Normal. Poll again |
| 400 | Malformed request | Stop. Fix the firmware; do not retry |
| 403 | Device blocked, or wrong tenant | Stop. Terminal |
| 404 | MAC, order or command not found | Stop. Provisioning fault |
| 422 | Schema validation failed | Stop. Fix the payload |
| 429 | Rate or stream limit | Back off; honour Retry-After |
| 499 | Client disconnected mid-upload | The device's side dropped. Investigate |
| 500 | Server error | Retry with backoff |
| 503 | Capacity reached | Back off; honour Retry-After |
Glossary
| Term | Meaning |
|---|---|
| Property | One physical site: a restaurant, hotel, warehouse |
| Placement | How a device is attached to a site: a team, or a table |
| Mode | ai, udp or websocket — which protocol this unit speaks |
| Sealing | Deciding where one spoken utterance ends and the next begins |
| Pre-roll | Audio buffered before the voice gate opened, so the first syllable survives |
| Voice gate | An RMS gate that stops silence reaching the recogniser |
| Claim | A device reserving a print job so no other device prints it |
| Draft transcript | A mid-utterance snapshot, persisted so a crash loses nothing. Not final |
| Incident | A device-reported fault, stamped with the firmware version at the time |
| udp-v1 | The push-to-talk wire protocol |
| device_session | A random value regenerated on every boot; distinguishes a reboot from a reconnect |
Something wrong or missing on this page? Tell us.