Bluetooth Interface Documentation¶

Service Overview¶

The scooter exposes several Bluetooth LE services for control and monitoring. All services use the base UUID: xxxx-6e67-5d0d-aab9-ad9126b66f91

Device Information¶

• Device Name: "unu Scooter"
• Company ID: 0xE50A
• Advertising: 1 second interval, 3 minute duration
• Connection Interval: 20-75ms
• Security: MITM enabled, LESC enabled, display-only pairing (6-digit PIN), bonding supported

What a client can do without bonding¶

Reads and writes require an encrypted, MITM-protected link on every characteristic except two: 9a59a021 (Reset Reason) and 9a59a022 (Reset Count), which are open. Everything else, including both control characteristics, is protected. There is no unbonded path to scooter:state unlock or to any power command.

An unbonded client can still:

• see the advertisement: device name and manufacturer data (company 0xE50A, payload = the first two bytes of the BLE MAC, so an app can tell scooters apart before connecting)
• connect and discover the full GATT structure: every service, characteristic and its properties
• read the two reset counters above

Advertising modes¶

Advertising follows the vehicle state, and it filters connections rather than changing the advertisement. The payload is byte-identical in both modes.

ready-to-drive is whitelist-only rather than off, so a bonded phone can reconnect mid-ride while unknown phones are ignored. Consequence when testing: a locked scooter advertises and is visible to a scanner, but will not accept a connection from an unbonded client. Unlock it (parked) to pair a new one.

The mode can be overridden at runtime:

redis-cli lpush scooter:bluetooth advertising-restart-no-whitelisting
redis-cli lpush scooter:bluetooth advertising-start-with-whitelisting
redis-cli lpush scooter:bluetooth advertising-stop

The override does not survive the next change of advertising-mode class (parked and anything else), a disconnect, or a bond change, each of which recomputes the mode from the vehicle state. A transition between two whitelist-only states leaves it in place.

Internal UUID ranges (not GATT)¶

Some UUIDs in this range address messages on the internal MDB to nRF52 link rather than characteristics. They are not part of the GATT table: no client can discover, read or subscribe to them, and they are listed here only so they are not mistaken for a service that failed to appear.

Control Service (9a590000)¶

Primary control interface for scooter functions

hard-reboot is only accepted during normal operation (stand-by, suspend, parked, ready-to-drive). It's rejected during active hibernation entry or if a hard reboot is already in progress.

Status Service (9a590020)¶

Provides scooter state information

The set above is the full set BLE clients ever observe. When the scooter is in the internal hop-on state, the firmware cloaks the characteristic as "stand-by" so mobile apps with no concept of hop-on still see a locked scooter and offer their unlock affordance. hop-on-learning is collapsed to "parked" upstream (in bluetooth-service) and never reaches the firmware as a distinct value. See Vehicle States. | 9a590022 | Seatbox State | - "open"
- "closed"
- "unknown" | | 9a590023 | Handlebar Lock | - "locked"
- "unlocked" |

Battery Service (9a590040)¶

Auxiliary battery monitoring

Connectivity Battery Service (9a590060)¶

CBB status monitoring

Power State Service (9a5900a0)¶

System power state monitoring

(cf. State Diagram)

Main Battery Service (9a5900e0)¶

Primary battery monitoring

Power Mux Service (9a590100)¶

Extended Commands Service (9a590400)¶

Unified extensible command/response channel for phone app interaction

Supported commands:

Error responses follow the pattern <prefix>:error:<details>. See Generic settings for the complete contract.

Generic settings¶

get:<key> and set:<key>:<value> use the schema published by settings-service in settings:schema. Reads and writes reject unknown keys; writes also reject read-only keys and schema-invalid values. A value begins after the first colon, so a value may itself contain colons. get:list and get:list:<prefix> return get:count:<n> followed by exactly n get:<key> notifications.

All extended commands, including generic settings, require the encrypted MITM-protected bonded connection described above. The protocol has no per-phone authorization: any bonded phone with extended-command access can read schema-declared setting values and change any writable schema setting. Treat bonding as the authorization boundary.

OTA Transfer Service (9a590500)¶

Firmware bundle transfer from the phone to the scooter (MDB and DBC updates over BLE). Windowed, resumable, integrity-checked; the nRF forwards these characteristics verbatim to bluetooth-service. See BLE OTA Firmware Transfer for the full protocol.

Scooter Info Service (9a59a040)¶

System-level telemetry and configuration

System Info Service (9a59a000)¶

RESETREAS (Reset Reason Register)¶

Reset reason register. Cumulative unless cleared. Fields are cleared by writing '1'. If no reset sources are flagged, indicates reset from on-chip reset generator (power-on-reset or brownout reset).

Register layout has:

• Low bits (0-3): Basic reset sources
• High bits (16-20): System OFF wake-up sources