Hardware and firmware contract
What ships on every QuickComm device: the fixed audio contract, the capabilities on the board, what the firmware does and deliberately does not do, and what you can change without a reflash.
10 min read
On this page
You are buying a piece of hardware that is deliberately, aggressively stupid. The device is a microphone, a speaker, a button and a MAC address. It holds no menu, no order, no task list, no user list and no conversation state. It does not know what business it is in.
That is the whole reason this integration is possible. Because the device holds no business logic, the same flashed firmware serves a restaurant, a guard force, a hotel, a warehouse or a clinic. What changes is the server it talks to and the logic that server runs.
One firmware, three modes
There is one hardware family and one firmware image. A device's behaviour is selected by a single field, communication_mode, set at provisioning time and stored server-side on the device record.
| Mode | communication_mode | Transport | Conversation shape | Typical unit |
|---|---|---|---|---|
| A — Push-to-talk streaming | udp | Custom UDP udp-v1, 16 kHz PCM, uplink only | Human to human, machine listens | Earpiece, Bridge Node |
| B — Request/response walkie | ai | HTTPS POST /voice, framed PCM, plus a downlink poll | Speak, get an answer back | Earpiece, Bridge Node |
| C — Full-duplex agent | websocket | WebSocket over TLS, PCM both ways | Two-way conversation with an AI agent | Table Top |
- The mode is not baked into the flash. It is a value on the server, handed to the device at provisioning and changeable afterwards, including remotely by a CHANGE_MODE command. A unit shipped as a warehouse walkie can become a counter terminal without a reflash.
- The modes are not exclusive per fleet. One site can run udp badges for staff and a websocket terminal for customers at the same time, against the same backend and the same data model.
- A device with a table_id defaults to websocket; every other device defaults to ai. That is enforced in the provisioning schema, not in the firmware.
What is genuinely fixed
These are identical in all three modes and across all three form factors. Treat them as the hardware contract — everything else is configuration or server-side logic.
| Fixed | Value |
|---|---|
| Audio encoding | Signed 16-bit little-endian PCM (s16le) |
| Sample rate | 16 000 Hz, mono |
| Identity | The unit's MAC address, uppercase colon-separated |
| Provisioning channel | SoftAP captive portal at 192.168.4.1, seeded by QR |
| Fleet plane | Heartbeat, telemetry, incidents, commands, OTA over HTTPS |
| Interruption | The physical button. There is no acoustic barge-in |
What is on every unit
The three form factors differ in power, mounting and audio interface. The compute, radio and audio platform underneath is the same, which is why one firmware image and one integration cover all of them.
| Subsystem | What you get |
|---|---|
| Wi-Fi | 802.11 b/g/n, 2.4 GHz, integrated antenna |
| Bluetooth | Bluetooth 5.2 (BLE) |
| Microphone | Digital MEMS |
| Audio codec | 24-bit ADC/DAC |
| Capture format | 16 kHz PCM, mono, push-to-talk framed |
| Pre-roll buffer | Yes — the first syllable of a transmission is never clipped |
| Edge processing | On-device voice activity detection and wake handling |
| Flash | 8 MB, with an A/B partition layout for rollback-safe updates |
| Firmware updates | Over-the-air, staged, with per-device rollout control |
| Remote management | Remote commands, health telemetry, offline detection |
| Status | RGB LED indicator; Table Top and Bridge Node also carry a status display |
Which product speaks which mode
| Product | Default mode | Also supports | Why |
|---|---|---|---|
| Earpiece | A — udp | B — ai | Worn through a shift, keyed by hand. Push-to-talk streaming is the cheapest mode to run and the kindest to a shared access point. Switch it to ai when the wearer needs an answer spoken back. |
| Bridge Node | A — udp | B — ai | Sits inline on an existing radio's audio path, so it inherits that fleet's push-to-talk discipline. The host device's own audio stays live. |
| Table Top | C — websocket | A — udp, B — ai | Mains-capable and room-facing, so it can hold a full-duplex conversation and drive the print bridge. Placed on a table, it defaults to websocket automatically. |
What the firmware holds
Provisioning is the only moment a device learns who it is. Everything it retains across a power cycle is in this table — there is nothing else in non-volatile storage that affects how it behaves.
| Key | Example | Notes |
|---|---|---|
| mac_address | AA:BB:CC:DD:EE:FF | The burned-in MAC, or a server-assigned one |
| property_id | 4 | No default. No guess. The device refuses to run without it |
| organization_id | 2 | Carried for convenience |
| team_id or table_id | 7 | Whichever the property type requires |
| user_id | 19 | Optional — who is carrying it |
| comm_mode | udp | Selects the transport |
| server host and port | api.yourcompany.com:443 | Or a private address when you run the backend |
| ssid / password | — | Wi-Fi credentials |
What the firmware does
- 1Boots. If provisioning is absent or incomplete, it refuses to run and shows a fault. It never guesses a tenant.
- 2Joins Wi-Fi, then starts an independent 30-second heartbeat that runs for the life of the session, in every mode, including while audio is flowing.
- 3Opens the transport its comm_mode selects and speaks the wire protocol for that mode.
- 4Captures 16 kHz mono PCM while the button is held, with a pre-roll buffer so the leading syllable survives.
- 5Mutes the microphone whenever its own speaker is producing sound, plus a short tail afterwards.
- 6Polls for remote commands when the heartbeat response says there are any, acknowledges them, executes, and reports the result.
- 7Checks for firmware updates on boot and hourly, verifies the SHA-256 checksum before flashing, and reports progress and rollbacks honestly.
- 8Files an incident when it faults, stamped by the server with the firmware version at the moment of the fault.
What the firmware deliberately does not do
- It does not decide what a sentence means. Intent, routing and severity are server-side.
- It does not hold a menu, a task list, a user directory or any conversation state.
- It does not render receipts. It receives rendered ESC/POS bytes and a LAN address, which is why a receipt layout change never needs a reflash.
- It does not authenticate a person. Attribution to a staff member is a user_id set at provisioning or per request.
- It does not resample audio. If your deployment needs a rate correction, that happens server-side where it can be done properly.
What you can change without touching firmware
| Change | How |
|---|---|
| Which backend the device talks to | Provisioning payload: mode=local with your host and port |
| Which transport it speaks | communication_mode on the device record, or a CHANGE_MODE command in the field |
| Recognition language | language on the device record: en, ur, ar or multi |
| What a spoken sentence means | Server-side intent taxonomy and prompt |
| What gets created and who it routes to | Server-side task and order logic |
| What the device says back or prints | The mode B notification queue, the mode C agent, the print bridge |
| Mic-mute tail length | tail_ms, delivered in the mode C handshake |
| Firmware version | Staged OTA from your server, with rollback |
Something wrong or missing on this page? Tell us.