Scooter Firmware Bring-Up

The scooter only ever talks to the MQTT broker. It has no HTTP client and never learns whether the backend accepted a frame. Everything after the broker belongs to the backend team, but knowing the path tells you where to look when something goes missing.

• No application-level receipt for telemetry. MQTT QoS 1 PUBACK means the broker has it, nothing more. Rejected frames are stored server-side with the raw bytes and a reason.
• A command succeeds only when your ACK arrives. The backend never treats "published to MQTT" as done. No matching ACK within 15 s means TIMEOUT.
• The wire contract lives in one place: packages/protocol/src/. The server and the simulator both import it, so when this guide and that code disagree, the code wins. Tell the backend team.

Every scooter has its own credential. A shared fleet key is forbidden: one extracted key would let anyone impersonate every scooter and receive every scooter's commands. The backend team provisions each unit and gives you four values.

• Store the credential in EEPROM or flash, per unit. Never compile one into a shared image.
• Never print the password on a debug UART. A lost password means reprovisioning, not recovery.
• Two units with the same client id will repeatedly kick each other off the broker. Only one session per client id can exist at a time.

mosquitto_sub -h mqtt.xzcode.me -p 8883 -V mqttv311 \
  --cafile isrg-root-x1.pem \
  -i scooter-1 -u scooter-1 -P '<password>' \
  -t 'sc/1/cmd' -q 1 -d

Trusting the server

The broker presents a Let's Encrypt certificate for mqtt.xzcode.me. Let's Encrypt replaces it about every 60–90 days, so load the ISRG Root X1 CA into the modem (and ISRG Root X2, so a change of key type doesn't strand units). Never pin the leaf certificate. A pinned leaf bricks the whole fleet's connectivity on the next renewal.

Certificate validation needs the time. After a cold boot, get network time from the modem (NITZ, or AT+CCLK? on 3GPP modules) before opening TLS. The same clock stamps telemetry, which the backend rejects if it's more than 5 minutes off.

The CONNECT packet

Register a Last Will so the broker announces the scooter offline if the link dies without a clean disconnect:

On every successful CONNACK, in this order

1. Publish 0x01 to sc/1/status, QoS 1, retained.
2. Subscribe to sc/1/cmd at QoS 1. Clean session drops subscriptions, so this happens every time.
3. Publish a BOOT event if this is the first connect since power-up.
4. Replay any buffered readings with bit 7 set (stage 07).
5. Resume live telemetry on the normal interval.

If the connect fails, back off with jitter: for example 2 s, 4 s, 8 s … capped at 5 minutes, plus a random 0–30%. A fleet that reconnects in lockstep after a cell outage floods the broker all at once.

docker exec <emqx-container> emqx ctl clients show scooter-1

Every frame is a fixed-size binary record: a version byte 0x01, the fields, then a CRC over everything before it. Multi-byte fields are little endian, the AVR's native order, so a memcpy of a uint32_t is already correct. The CRC goes out low byte first too.

CRC-16/CCITT-FALSE

Poly 0x1021, init 0xFFFF, no reflection, no final XOR. Check value: CRC of the ASCII string "123456789" is 0x29B1. Test this before anything else; a wrong CRC is the most common bring-up failure.

/* Bit-wise: no table, fits comfortably on an ATmega328. */
uint16_t crc16_ccitt_false(const uint8_t *data, uint8_t len) {
    uint16_t crc = 0xFFFF;
    while (len--) {
        crc ^= (uint16_t)(*data++) << 8;
        for (uint8_t i = 0; i < 8; i++)
            crc = (crc & 0x8000) ? (crc << 1) ^ 0x1021 : (crc << 1);
    }
    return crc;
}

/* Sealing a 20-byte telemetry frame: CRC over bytes 0..17, stored LE. */
uint16_t crc = crc16_ccitt_false(frame, 18);
frame[18] = crc & 0xFF;
frame[19] = crc >> 8;

Telemetry · 20 bytes · sc/{id}/tel

The bottom row is the golden vector from packages/protocol/test/telemetry.spec.ts: msg_id 4660, latitude 30.0444, longitude 31.2357, battery 87 %, speed 23 km/h, status 0x1A, CRC 0x469D. Its timestamp decodes to a 1970 date, so use it to test byte layout only. Sent live, it would be rejected as CLOCK_SKEW.

status_bits · byte 17

01 34 12 04 03 02 01 60 69 E8 11 88 30 9E 12 57 17 1A 9D 46

Telemetry is also the heartbeat. There's no separate keepalive frame, so publish every interval even when nothing has changed. Publish at QoS 1, not retained, with bit 7 clear.

What the backend does with each frame

Checks run in this order. A reject is refused and stored with the raw bytes. A tag is accepted but flagged.

msg_id rules

• Increment by one per frame, wrapping at 65 535. At 10 s, a wrap takes about 7.5 days, far outside the 600 s dedup window.
• Don't reset it on reconnect. Rapid reconnects would reuse ids inside the window, and real readings would be discarded as duplicates.
• Don't restart it from 0 after a reboot either. A unit that reboots and reconnects within 10 minutes hits the same trap. Save the counter to EEPROM every few hundred frames and skip ahead on boot, or seed it randomly.
• A QoS 1 retransmission reuses the same bytes and the same msg_id. That's correct.

Commands arrive on sc/{id}/cmd as 12-byte frames. The backend matches your ACK to the command by command_id alone, so mirror it exactly.

Command · 12 bytes · received on sc/{id}/cmd

Example: UNLOCK (0x02), command_id 42, issued at 1789313734, CRC 0x0491.

ACK · 10 bytes · publish to sc/{id}/ack

The ACK for the command above, result SUCCESS. The same ACK with result ALREADY_DONE is 01 02 2A 00 00 00 02 00 66 C3.

Device rules for commands

• Keep the last ~8 executed command_ids in RAM (32 bytes). If a command's id is already there, don't actuate again; answer ALREADY_DONE. Retries always reuse the original id, so this is what prevents a double unlock.
• Don't send an ACK you can't back up. Silence becomes a clean TIMEOUT the operator can retry; a false SUCCESS leaves a rider standing at a locked scooter.
• An ACK that arrives after the 15 s timeout is ignored. It doesn't bring the command back.
• The backend never sends two in-flight commands of the same opcode to one scooter, so you won't see overlapping UNLOCKs.
• Handle the frame as it arrives: check length, version and CRC first. A command failing those gets no ACK.

curl -X POST https://api.xzcode.me/api/v1/scooters/1/commands \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"opcode":"PING"}'
# → 202 {"command_id": 42, "state": "PENDING", ...}

curl -H "Authorization: Bearer $TOKEN" https://api.xzcode.me/api/v1/commands/42
# → "state": "ACKED", "result_name": "SUCCESS"   within about a second

Event · 8 bytes · sc/{id}/evt

Any other type is rejected as UNKNOWN_EVENT_TYPE, not ignored.

Status · 1 byte · sc/{id}/status

Just 0x01 (online) or 0x00 (offline), with no version byte and no CRC. Publish 0x01 retained after every connect. The broker publishes the retained 0x00 for you through the Last Will when the link drops. Before a deliberate power-down, publish 0x00 retained yourself, then send DISCONNECT. A clean disconnect doesn't trigger the Will.

This is the behaviour that matters most. While the link is down, keep sampling and store the readings. When the link returns, replay them with bit 7 set. Bit 7 means one thing: this reading is not current.

• Replayed frames take new msg_ids from the normal sequence. Don't reuse the ids the readings would have had.
• Keep each reading's original timestamp. The backend accepts buffered frames up to 7 days old, but still rejects any stamped more than 5 minutes in the future.
• Replay oldest first, then go back to live frames. If storage fills, drop the oldest readings, not the newest.
• Pace a long replay (for example 5–10 frames per second). The broker has no trouble with it, but the modem's send buffer may.

Before blaming firmware, confirm the backend is healthy by running the simulator with a scooter id that isn't your hardware. If the simulated scooter works and yours doesn't, the difference is in the device.

npm run sim -- --count 1 --start-id 2 --interval 10          # known-good peer on the live broker
npm run sim -- --count 1 --start-id 2 --ack-mode silent      # forces the 15 s TIMEOUT path
npm run sim -- --count 1 --start-id 2 --buffered-burst       # outage + bit 7 replay

# every command it receives is printed:
[sim] scooter 2 <- cmd #42 UNLOCK
[sim] scooter 2 -> ack #42 SUCCESS (locked=false)

For a full reference implementation of connect, status, subscribe, telemetry, ACK and replay, read apps/simulator/src/virtual-scooter.ts.