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. .. _opcode_table: .. list-table:: AVSS Control Point Opcodes :widths: 10 30 60 :header-rows: 1 * - Value - Opcode - Description * - 1 - :ref:`Response ` - Indicates the response code for a command. * - 2 - :ref:`Report Snippets ` - Controls transmission of snippet reports. * - 3 - :ref:`Report Aggregates ` - Controls transmission of aggregated data reports. * - 4 - :ref:`Report Health ` - Controls transmission of health reports. * - 5 - :ref:`Get Version ` - Requests the version information of the sensor. * - 6 - :ref:`Get Version Response ` - Response of the Get Version command. * - 7 - :ref:`Write Settings ` - Sends configuration settings to the sensor. * - 8 - :ref:`Write Settings Response ` - Response of the Write Settings command. * - 9 - :ref:`Report Settings ` - Requests the current settings from the sensor. * - 10 - :ref:`Apply Settings ` - Applies previously written settings to the sensor. * - 11 - :ref:`Apply Settings Response ` - Response of the Apply Settings command. * - 12 - :ref:`Test Throughput ` - Tests the data throughput of the Report characteristic. * - 13 - :ref:`Report Captures ` - Controls transmission of capture reports. * - 16 - :ref:`Deactivate ` - Deactivates the sensor. * - 17 - :ref:`Trigger Measurement ` - Triggers a measurement on the sensor. * - 18 - :ref:`Get Firmware Info ` - Requests firmware information from the sensor. * - 19 - :ref:`Get Firmware Info Response ` - Response of the Get Firmware Info command. * - 20 - :ref:`Reset Report ` - Cancel active report requests. * - 100 - :ref:`Prepare Upgrade ` - Prepares the sensor for a firmware upgrade. * - 101 - :ref:`Apply Upgrade ` - Applies the firmware upgrade to the sensor. * - 102 - :ref:`Confirm Upgrade ` - Confirms the completion of the firmware upgrade. * - 103 - :ref:`Reboot ` - Reboots the sensor. List of Response Codes ---------------------- The table below lists the response codes used with the :ref:`Response ` opcode to indicate the outcome of commands. .. list-table:: AVSS Control Point Response Codes :widths: 10 30 60 :header-rows: 1 * - 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: 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. .. list-table:: Byte Layout of the Response Opcode :widths: 20 20 60 :header-rows: 1 * - 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: 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. .. list-table:: Report Snippets Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Count - uint / null - Number of reports to send. - ``null``: No limit, allowing for continual reporting until stopped. - ``0``: Stops the transmission of reports. - Integer: Send the specified number of reports, then stop. * - 1 - Auto Resume - bool - Resume transmissions from the report buffer. - ``true``: Attempt to resume report transmissions from the last sent report. If not feasible, start with the oldest report available in the buffer. - ``false``: Do not send any old reports from the buffer. Start with the next report that becomes available after reports have been requested. 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: 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. .. list-table:: Report Aggregates Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Count - uint / null - Number of reports to send. - ``null``: No limit, allowing for continual reporting until stopped. - ``0``: Stops the transmission of reports. - Integer: Send the specified number of reports, then stop. * - 1 - Auto Resume - bool - Resume transmissions from the report buffer. - ``true``: Attempt to resume report transmissions from the last sent report. If not feasible, start with the oldest report available in the buffer. - ``false``: Do not send any old reports from the buffer. Start with the next report that becomes available after reports have been requested. 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: 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. .. list-table:: Report Health Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Count - uint / null - Number of reports to send. - ``null``: No limit, allowing for continual reporting until stopped. - ``0``: Stops the transmission of reports. - Integer: Send the specified number of reports, then stop. A non-zero count, including ``null``, triggers an immediate health check and resets the periodic health check interval. .. _get_version_opcode: 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 :ref:`Get Version Response ` is returned. .. _get_version_response_opcode: 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. .. list-table:: Get Version Response Parameters :widths: 10 15 15 60 :header-rows: 1 * - 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: 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 :ref:`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. .. list-table:: Write Settings Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - N/A - N/A - N/A - This command accepts a map of settings to be updated. On success, a :ref:`Write Settings Response ` is returned. .. _write_settings_response_opcode: Write Settings Response (Opcode 8) ------------------------------------------ The Write Settings Response indicates if any settings in the :ref:`Write Settings ` command were ignored. The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below. .. list-table:: Write Settings Response Parameters :widths: 10 15 15 60 :header-rows: 1 * - 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: 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 :ref:`Response ` containing the Ok response code via the Control Point. However, the requested settings are sent asynchronously via the Report characteristic. .. _apply_settings_opcode: 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 :ref:`Apply Settings Response ` is returned. .. _apply_settings_response_opcode: Apply Settings Response (Opcode 11) -------------------------------------------- The Apply Settings Response indicates the result of the :ref:`Apply Settings ` command. The response parameters are provided as a CBOR-encoded map, with fields detailed in the table below. .. list-table:: Apply Settings Response Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Will Reboot - bool - Indicates whether the sensor will reboot as a result of applying the settings. - ``true``: The sensor will reboot. - ``false``: The sensor will not reboot. .. _test_throughput_opcode: 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. .. list-table:: Test Throughput Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Duration - uint - The duration of the throughput test in milliseconds. .. _report_captures_opcode: 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. .. list-table:: Report Captures Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Count - uint / null - Number of reports to send. - ``null``: No limit, allowing for continual reporting until stopped. - ``0``: Stops the transmission of reports. - Integer: Send the specified number of reports, then stop. * - 1 - Auto Resume - bool - Resume transmissions from the report buffer. - ``true``: Attempt to resume report transmissions from the last sent report. If not feasible, start with the oldest report available in the buffer. - ``false``: Do not send any old reports from the buffer. Start with the next report that becomes available after reports have been requested. 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: 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. .. list-table:: Deactivate Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Key - uint - Must be set to the magic value ``0xFEEDF00D``. .. _trigger_measurement_opcode: 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. .. list-table:: Trigger Measurement Parameters :widths: 10 15 15 60 :header-rows: 1 * - 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: 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 :ref:`Get Firmware Info Response ` is returned. .. _get_firmware_info_response_opcode: 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. .. list-table:: Get Firmware Info Response Parameters :widths: 10 15 15 60 :header-rows: 1 * - 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: - ``0``: Firmware image is confirmed. * - 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: Reset Report (Opcode 20) --------------------------------- The Reset Report command cancels all active report requests. This command does not accept any parameters. .. _prepare_upgrade_opcode: 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. .. list-table:: Prepare Upgrade Parameters :widths: 10 15 15 60 :header-rows: 1 * - 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: 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. .. list-table:: Apply Upgrade Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Permanent - uint - Apply permanently without a confirmation step. Requires the magic value ``0x21118B00`` to take effect. .. _confirm_upgrade_opcode: 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. .. list-table:: Confirm Upgrade Parameters :widths: 10 15 15 60 :header-rows: 1 * - Key - Field - Type - Description * - 0 - Image Index - uint - The index of the firmware image to be confirmed. .. _reboot_opcode: Reboot (Opcode 103) ---------------------------- The Reboot command reboots the device. This command does not accept any parameters.