-
Notifications
You must be signed in to change notification settings - Fork 19
Communication protocol
The following specifications use these abbreviations for data type/width:
| type | definition |
|---|---|
| (u)char | (un)signed 8bit |
| (u)short | (un)signed 16bit |
| (u)long | (un)signed 32bit |
| float | 32bit float |
(Data is little-endian. Brackets indicate an array)
Within the broadcast packet, the badge advertises with the name "BADGE" or "HDBDG", and includes useful status information in the manufacturer-specific data field.
Earlier revisions of the badge firmware (before scan implementation, release 1.1) sent the following structure as the manufacturer data field, little-endian:
| Item | Type | Description |
|---|---|---|
| Field length | uchar | length of following data in bytes: 9 |
| Advertising data type | uchar | manufacturer-specific data: 0xFF |
| Company identifier | ushort | arbitrarily 0xFF00 |
| Battery voltage | float | value is battery voltage |
| Sync status | uchar | value 1 if badge has received date/time from server, 0 otherwise |
| Collector status | uchar | value 1 if badge is collecting microphone data, 0 otherwise |
Later firmware revisions (release 1.2 and later) condensed the existing data, and included additional information, as follows (also little-endian):
| Item | Type | Description |
|---|---|---|
| Field length | uchar | length of following data in bytes: 14 |
| Advertising data type | uchar | manufacturer-specific data: 0xFF |
| Company identifier | ushort | arbitrarily 0xFF00 |
| Battery level | uchar | unsigned; scaled so that voltage = 1V + 0.01V*batteryLevel |
| Status flags | uchar | bit 0 is sync status, bit 1 is collector status, bit 2 is scanner status |
| Badge ID number | ushort | configurable ID number, set by default to the CRC16-CCITT-FALSE of the badge MAC address |
| Badge group number | uchar | configurable group identifier, default 0 |
| Badge MAC address | uchar[6] | useful for central devices that do not make peripheral addresses accessible |
The badges use the NRF UART Service (a custom service to emulate a UART interface) to transfer data to a central device. The central device sends a command along with relevant parameters, and the badge responds appropriately.
Earlier firmware revisions support the following commands:
- Status request: get badge information (battery level, sync status, etc), and sync badge time
- Start recording: start collecting microphone readings
- Stop recording: stop collecting microphone readings
- Request microphone data: get microphone data since specified time
- Identify: light an LED for a specified amount of time
| Command | Server sends | Badge responds |
|---|---|---|
| Status request | 's' (uchar) timestamp (ulong) milliseconds (ushort) |
clock status (uchar) data status (uchar) collector status (uchar) timestamp1 (ulong) ms1 (ushort) battery voltage (float) |
| Start recording | '1' (uchar) timestamp (ulong) milliseconds (ushort) timeout2 (ushort) |
timestamp1 (ulong) ms1 (ushort) |
| Stop recording | '0' (uchar) | none |
| Request mic data | 'r' (uchar) timestamp (ulong) milliseconds (ushort) |
chunks of data (see below) |
| Identify | 'i' (uchar) timeout3 (ushort) |
none (lights LED) |
| 1The badge responds with its previous internal time (0 if unsynced) before syncing itself with the timestamp received from the server. | ||
| 2The badge will stop collecting microphone data a specified number of minutes after it last received a command from the server. 0 for no timeout. | ||
| 3Number of seconds to light LED. 0 to turn off LED. |
The badge sends the server chunks of microphone data consisting of a header packet:
- timestamp (ulong)
- ms (ushort)
- battery voltage (float)
- sample period in ms (ushort)
- number of samples in chunk (uchar)
followed by an array of data samples (uchar), in packets of up to 20bytes.
The last chunk of data is followed by a null header (comprised of zeroes) to mark the end of transmission.
Later firmware revisions include additional commands related to scanning functionality, and slightly modify the status command response.
- Status request: get badge information (battery level, sync status, etc), and sync badge time
- Start recording: start collecting microphone readings
- Stop recording: stop collecting microphone readings
- Start recording: start performing scans
- Stop recording: stop performing scans
- Request microphone data: get microphone data since specified time
- Request scan data: get scan data since specified time
- Identify: light an LED for a specified amount of time
| Command | Server sends | Badge responds |
|---|---|---|
| Status request [Badge assignment]5 |
's' (uchar) timestamp (ulong) milliseconds (ushort) [ID (ushort)]5 [group # (uchar)]5 |
clock status (uchar) scanner status (uchar) collector status (uchar) timestamp1 (ulong) ms1 (ushort) battery voltage (float) |
| Start recording | '1' (uchar) timestamp (ulong) milliseconds (ushort) timeout2 (ushort) |
timestamp1 (ulong) ms1 (ushort) |
| Stop recording | '0' (uchar) | none |
| Start scanning | 'p' (uchar) timestamp (ulong) milliseconds (ushort) timeout2 (ushort) window4 (ushort) interval4 (ushort) duration4 (ushort) period4 (ushort) |
timestamp1 (ulong) ms1 (ushort) |
| Stop scanning | 'q' (uchar) | none |
| Request mic data | 'r' (uchar) timestamp (ulong) milliseconds (ushort) |
chunks of mic data (see below) |
| Request scan data | 'b' (uchar) timestamp (ulong) |
scan results (see below) |
| Identify | 'i' (uchar) timeout3 (ushort) |
none (lights LED) |
| 1The badge responds with its previous internal time (0 if unsynced) before syncing itself with the timestamp received from the server. | ||
| 2The badge will stop collecting microphone/scan data a specified number of minutes after it last received a command from the server. 0 for no timeout. | ||
| 3Number of seconds to light LED. 0 to turn off LED. | ||
| 4Scan timing parameters. 0 for default. "Window" and "Interval" set the duty cycle of the radio during a scan: the radio is active for [window] milliseconds every [interval] milliseconds. "Duration" sets the duration of a scan in seconds (known as "timeout" in the Nordic API) and "Period" sets how often the badge performs a scan, in seconds. | ||
| 5Optional parameters. A status request sent with these optional parameters will change the badge's broadcast ID and group number, stored in non-volatile memory. Sending the ID to 0xFFFF or the group number to 0xFF will reset the respective parameters to defaults (default ID: CRC16 of the badge MAC address; default group: 0) |
The badge sends the server chunks of microphone data consisting of a header packet:
- timestamp (ulong)
- ms (ushort)
- battery voltage (float)
- sample period in ms (ushort)
- number of samples in chunk (uchar)
followed by an array of data samples (uchar), in packets of up to 20bytes.
The badge sends the server scan results each consisting of a header packet:
- timestamp (ulong)
- battery voltage (float)
- number of devices seen in scan (uchar)
followed by an array of device data, in packets of up to 20bytes. Each device is reported with the following data:
- ID (ushort)
- average RSSI (char)
- number of times seen (char)
The last chunks of mic/scan data are followed by a corresponding null header (comprised of zeroes) to mark the end of transmission.