Commands and Responses¶
This section provides descriptions of every command and response in the Control Point characteristic of the ANURA Vibration Sensing Service.
List of Opcodes¶
A list of all opcodes is detailed in the table below. See the respective sub-section for details on each opcode.
Value |
Opcode |
Description |
|---|---|---|
1 |
Indicates the response code for a command. |
|
2 |
Controls transmission of snippet reports. |
|
3 |
Controls transmission of aggregated data reports. |
|
4 |
Controls transmission of health reports. |
|
5 |
Requests the version information of the sensor. |
|
6 |
Response of the Get Version command. |
|
7 |
Sends configuration settings to the sensor. |
|
8 |
Response of the Write Settings command. |
|
9 |
Requests the current settings from the sensor. |
|
10 |
Applies previously written settings to the sensor. |
|
11 |
Response of the Apply Settings command. |
|
12 |
Tests the data throughput of the Report characteristic. |
|
13 |
Controls transmission of capture reports. |
|
16 |
Deactivates the sensor. |
|
17 |
Triggers a measurement on the sensor. |
|
18 |
Requests firmware information from the sensor. |
|
19 |
Response of the Get Firmware Info command. |
|
20 |
Cancel active report requests. |
|
100 |
Prepares the sensor for a firmware upgrade. |
|
101 |
Applies the firmware upgrade to the sensor. |
|
102 |
Confirms the completion of the firmware upgrade. |
|
103 |
Reboots the sensor. |
List of Response Codes¶
The table below lists the response codes used with the Response opcode to indicate the outcome of commands.
Value |
Response Code |
Description |
|---|---|---|
1 |
Ok |
Command executed successfully. |
2 |
Error |
General error occurred. |
3 |
Opcode Unsupported |
Opcode is not supported. |
4 |
Busy |
Device is busy and cannot process the command. |
5 |
Bad Argument |
Invalid argument provided. |
6 |
Control Point Busy |
Control Point is busy. |
7 |
Unexpected |
Unexpected error occurred. |
Response (Opcode 1)¶
The Response opcode indicates the response code for a command, signaling either success or an error.
The Response opcode is used for generic succes and error responses when there is no need for a command-specific response. Any command can return this opcode to indicate an error, even if the command specifies a different response message for successful execution.
A message with the Response opcode has a byte layout detailed in the table below.
Byte Position |
Field |
Description |
|---|---|---|
0 |
Opcode |
Fixed value indicating a Response message. |
1 |
Command Opcode |
The opcode of the command being responded to. |
2 |
Response Code |
Code indicating success or type of error. |
Report Snippets (Opcode 2)¶
The Report Snippets command is used to control the transmission of snippet reports.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Count |
uint / null |
Number of reports to send.
|
1 |
Auto Resume |
bool |
Resume transmissions from the report buffer.
The auto-resume feature functions correctly only if reports are consistently requested with auto-resume enabled. When auto-resume is not enabled, tracking of the last sent report is disabled. |
Report Aggregates (Opcode 3)¶
The Report Aggregates command is used to control the transmission of aggregated data reports.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Count |
uint / null |
Number of reports to send.
|
1 |
Auto Resume |
bool |
Resume transmissions from the report buffer.
The auto-resume feature functions correctly only if reports are consistently requested with auto-resume enabled. When auto-resume is not enabled, tracking of the last sent report is disabled. |
Report Health (Opcode 4)¶
The Report Health command is used to control the transmission of health reports.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Count |
uint / null |
Number of reports to send.
A non-zero count, including |
Get Version (Opcode 5)¶
The Get Version command requests the version information of the sensor.
This command does not accept any parameters.
If successful, a Get Version Response is returned.
Get Version Response (Opcode 6)¶
The Get Version Response provides the version information of the sensor.
The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Version |
tstr |
The version of the sensor firmware as dot-separated parts, e.g., ‘23.1.3.9.0’. |
1 |
Build Version |
tstr |
The build version of the sensor firmware, as an opaque string. |
Write Settings (Opcode 7)¶
The Write Settings command updates the sensor settings with the provided values. After writing, settings are pending and must be applied using the Apply Settings command. Multiple Write Settings commands may be sent to modify pending settings before applying them with Apply Settings.
This command accepts a CBOR-encoded map of settings as parameters. Any unrecognized or malformed settings will be ignored and counted as unhandled, which will be reflected in the response.
Key |
Field |
Type |
Description |
|---|---|---|---|
N/A |
N/A |
N/A |
This command accepts a map of settings to be updated. |
On success, a Write Settings Response is returned.
Write Settings Response (Opcode 8)¶
The Write Settings Response indicates if any settings in the Write Settings command were ignored.
The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Num Unhandled |
int |
The number of setting keys that were skipped by the sensor. Sensors ignore any unrecognized or malformed settings, increasing the count of unhandled settings. |
Report Settings (Opcode 9)¶
The Report Settings command requests the current settings from the sensor. Unlike other Report commands (such as Report Snippets), it does not support subscribing to updates. Instead, it should be viewed as a single request/response transaction.
This command does not accept any parameters.
On success, the command is acknowledged by a Response containing the Ok response code via the Control Point. However, the requested settings are sent asynchronously via the Report characteristic.
Apply Settings (Opcode 10)¶
The Apply Settings command applies previously written settings to the sensor.
This command does not accept any parameters.
On success, an Apply Settings Response is returned.
Apply Settings Response (Opcode 11)¶
The Apply Settings Response indicates the result of the Apply Settings command.
The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Will Reboot |
bool |
Indicates whether the sensor will reboot as a result of applying the settings.
|
Test Throughput (Opcode 12)¶
The Test Throughput command initiates a data throughput test of the Report characteristic. This test takes precedence over all other reporting tasks, meaning no other data will be delivered on the Report characteristic while the test is running.
Executing this command causes the sensor to send one uninterrupted report, which is extended with new segments for the duration of the test. It is up to the client to estimate the throughput based on the elapsed time and the amount of data transmitted.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Duration |
uint |
The duration of the throughput test in milliseconds. |
Report Captures (Opcode 13)¶
The Report Captures command is used to control the transmission of capture reports.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Count |
uint / null |
Number of reports to send.
|
1 |
Auto Resume |
bool |
Resume transmissions from the report buffer.
The auto-resume feature functions correctly only if reports are consistently requested with auto-resume enabled. When auto-resume is not enabled, tracking of the last sent report is disabled. |
Deactivate (Opcode 16)¶
The Deactivate command deactivates the sensor.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Key |
uint |
Must be set to the magic value |
Trigger Measurement (Opcode 17)¶
The Trigger Measurement command initiates measurements on the sensor, prompting a sensor that would otherwise remain in standby (e.g., due to lack of motion) to sample its accelerometer and perform analyses.
The normal sensor logic rules governing generation of snippets and other reports are still in effect. Therefore, this command does not guarantee that reports will be generated and sent.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Duration |
uint |
The duration of the trigger in milliseconds, limited to a maximum of 1 minute. This can be extended indefinitely by issuing the Trigger Measurement command again before the previous duration elapses. |
Get Firmware Info (Opcode 18)¶
The Get Firmware Info command requests firmware information from the sensor.
This command does not accept any parameters.
On success, an Get Firmware Info Response is returned.
Get Firmware Info Response (Opcode 19)¶
The Get Firmware Info Response provides firmware information from the sensor.
The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
App Version |
uint |
The version of the application co-processor firmware. Represented as a 32-bit unsigned integer, composed of four 8-bit segments correspondomg to parts of the version number. |
1 |
App Build Version |
tstr |
The build version of the application co-processor firmware, as an opaque string. |
2 |
App Status |
uint |
The status bitfield of the application co-processor firmware. Bit definitions:
- |
3 |
Net Version |
uint |
The version of the radio co-processor firmware. Represented as a 32-bit unsigned integer, composed of four 8-bit segments correspondomg to parts of the version number. |
4 |
Net Build Version |
tstr |
The build version of the radio co-processor firmware, as an opaque string. |
Reset Report (Opcode 20)¶
The Reset Report command cancels all active report requests.
This command does not accept any parameters.
Prepare Upgrade (Opcode 100)¶
The Prepare Upgrade command prepares the sensor to receive a firmware upload.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Image Index |
uint |
The index of the firmware image to be uploaded. |
1 |
Image Size |
uint |
The size of the firmware image in bytes that will be uploaded to the sensor. |
Apply Upgrade (Opcode 101)¶
The Apply Upgrade command applies the firmware upgrade to the sensor. The device reboots as part of the process to apply an upgrade.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Permanent |
uint |
Apply permanently without a confirmation step. Requires the magic value |
Confirm Upgrade (Opcode 102)¶
The Confirm Upgrade command confirms the firmware upgrade on the sensor.
The command parameters are provided as a CBOR-encoded map, with fields detailed in the table below.
Key |
Field |
Type |
Description |
|---|---|---|---|
0 |
Image Index |
uint |
The index of the firmware image to be confirmed. |
Reboot (Opcode 103)¶
The Reboot command reboots the device.
This command does not accept any parameters.