API Reference

This document describes all CBOR-RPC methods and data types in the ANURA Transceiver API.

For CBOR-RPC protocol fundamentals, message formats, and well-known methods, see CBOR-RPC.

Utility Methods

method ping

Simple no-operation request for connection health checks and keepalive.

Parameters:

None

Returns:

null

method reboot

Reboot the transceiver.

The transceiver reboots immediately after responding. The connection will be lost.

Parameters:

None

Returns:

null

Node Management

method set_assigned_nodes

Assign sensor nodes to the transceiver for automatic connection management.

The transceiver will automatically scan for, connect to, and maintain connections with the assigned nodes. Only assigned nodes can be used for AVSS communication via the proxy methods.

Note

This method replaces the entire list of assigned nodes. To modify the list, send the complete new list including both existing and new nodes.

Parameters:

  • 0 : nodes (array of assigned_node) – Array of node objects to assign

Errors:

  • API_ERR_ARGUMENT_DECODE if trying to assign more nodes than the transceiver supports

Returns:

null

method get_assigned_nodes

Retrieve the list of currently assigned nodes.

Note

The element order of the returned list may differ from what was sent in set_assigned_nodes.

Parameters:

None

Returns:

Array of assigned nodes

Return type:

get_assigned_nodes_result

Result type:

struct get_assigned_nodes_result

Result structure for get_assigned_nodes.

Fields:

  • 0 : nodes (array of assigned_node) – Array of assigned node objects

method get_connected_nodes

Retrieve the list of currently connected nodes.

Returns only the nodes that are currently connected and ready for AVSS communication. A node must be both assigned and connected for AVSS proxy methods to succeed.

Parameters:

None

Returns:

Array of connected nodes

Return type:

get_connected_nodes_result

Result type:

struct get_connected_nodes_result

Result structure for get_connected_nodes.

Fields:

  • 0 : nodes (array of connected_node) – Array of assigned node objects

method scan_nodes

Start scanning for nearby Bluetooth Low Energy nodes.

After calling this method, the transceiver emits scan_nodes_received notifications as nodes are discovered. Scanning continues for a maximum of 30 seconds or until scan_nodes_stop is called

This method is useful for discovering available nodes before assigning them.

Parameters:

None

Returns:

null

method scan_nodes_stop

Stop the node scanning process.

Parameters:

None

Returns:

null

AVSS Proxy Methods

method avss_request

Send an AVSS Control Point request to a sensor node.

The node must be assigned and connected for this method to succeed. The transceiver forwards the raw AVSS request to the node over BLE and returns the node’s response.

Important

Only one avss_request call can be outstanding per node at a time. Attempting another request to the same node before the previous call completes will fail with OPERATION_FAILED. Each request involves BLE round-trips and typically takes hundreds of milliseconds to complete.

Refer to the AVSS Commands and Responses documentation for details on AVSS Control Point message formats.

Parameters:

  • 0 : address (bluetooth_addr_le) – Address of the target node

  • 1 : data (bstr) – Raw AVSS Control Point request bytes (opcode + payload)

Errors:

  • API_ERR_NODE_UNAVAILABLE if the target node is not connected or service discovery has not completed

  • API_ERR_OPERATION_FAILED if the transceiver is currently serving another AVSS request to the same node, or if the operation failed for another reason

Returns:

Response from the node

Return type:

avss_request_result

Result type:

struct avss_request_result

Result structure for avss_request.

Fields:

  • 0 : response (bstr) – Raw AVSS Control Point response bytes

method avss_program_write

Write data to a sensor node’s AVSS Program characteristic.

This method writes to the AVSS Program characteristic using BLE “write without response”. It is used during node firmware upgrades.

The node must be assigned and connected for this method to succeed.

Parameters:

  • 0 : address (bluetooth_addr_le) – Address of the target node

  • 1 : data (bstr) – Data to write to Program characteristic

Errors:

  • API_ERR_NODE_UNAVAILABLE if the target node is not connected or service discovery has not completed

  • API_ERR_OPERATION_FAILED if the operation failed

Returns:

null

Device Information

method get_device_info

Retrieve hardware information about the transceiver.

Returns static device identification information. Not all fields may be applicable to all transceiver models.

Parameters:

None

Returns:

Device information

Return type:

get_device_info_result

Result type:

struct get_device_info_result

Result structure for get_device_info.

Fields:

  • 0 : board (str) – Board identifier

  • 1 : hw_rev (uint) – Hardware revision number

  • 2 : device_id (bstr) – Unique device identifier

  • 3 : app_version (str) – Application version string

  • 4 : app_build_version (str) – Application build version string

  • 5 : serial_number (str) – Device serial number

  • 6 : hostname (str) – Network hostname

  • 7 : mac_address (bstr) – Ethernet MAC address (6 bytes)

  • 8 : ip_addresses (array of ip addresses) – List of addresses assigned to the transceiver’s network interface using the tagged format specified in RFC9164.

method get_device_status

Retrieve current operational status of the transceiver.

Returns dynamic status information about the transceiver’s current state.

Parameters:

None

Returns:

Device status

Return type:

get_device_status_result

Result type:

struct get_device_status_result

Result structure for get_device_status.

Fields:

  • 0 : uptime (uint) – Uptime in seconds

  • 1 : reboot_count (uint) – Number of reboots since manufacturing

  • 2 : reset_cause (uint) – Reason code for last reset

method get_firmware_info

Retrieve firmware version information from the transceiver.

This method provides detailed version information for both the application processor and network processor firmwares.

Parameters:

None

Returns:

Firmware information

Return type:

get_firmware_info_result

Result type:

struct get_firmware_info_result

Result structure for get_firmware_info.

Fields:

  • 0 : dfu_status (uint) – Device Firmware Update status code. Indicates the state of any pending firmware update.

  • 1 : app_version (uint) – The version of the application processor firmware. Represented as a 32-bit unsigned integer, composed of four 8-bit segments corresponding to parts of the version number.

  • 2 : app_build_version (str) – The build version of the application processor firmware, as an opaque string.

  • 3 : net_version (uint) – The version of the network processor firmware. Represented as a 32-bit unsigned integer, composed of four 8-bit segments corresponding to parts of the version number.

  • 4 : net_build_version (str) – The build version of the network processor firmware, as an opaque string.

Time Synchronization

method get_time

Retrieve the transceiver’s current system time.

Parameters:

None

Returns:

Current time

Return type:

get_time_result

Result type:

struct get_time_result

Result structure for get_time.

Fields:

  • 0 : time (int64) – Unix time in nanoseconds

method set_time

Set the transceiver’s system time.

The time value is Unix time in nanoseconds (nanoseconds since 1970-01-01 00:00:00 UTC). This is used for PTP-based time synchronization with sensor nodes.

Parameters:

  • 0 : time (int64) – Unix time in nanoseconds

Returns:

null

method get_ptp_status

Retrieve Precision Time Protocol (PTP) status.

Returns information about the transceiver’s PTP synchronization state.

Parameters:

None

Returns:

PTP status

Return type:

get_ptp_status_result

Result type:

struct get_ptp_status_result

Result structure for get_ptp_status.

Fields:

  • 0 : port_state (str) – PTP port state

  • 1 : offset (int) – Clock offset in nanoseconds

  • 2 : delay (int) – Path delay in nanoseconds

  • 3 : offset_histogram (array of int) – Histogram of recent offset measurements

Device Firmware Update

method dfu_prepare

Prepare for a firmware update.

This method must be called before dfu_write to prepare the transceiver for receiving firmware data. It resets the write cursor to the beginning.

Parameters:

  • 0 : size (uint) – Total size of firmware image in bytes

Returns:

null

method dfu_write

Write a chunk of firmware data.

Write firmware data at the specified offset. The client should send the entire firmware image in sequential chunks until all bytes have been transferred.

Parameters:

  • 0 : offset (uint) – Byte offset within firmware image

  • 1 : data (bstr) – Firmware data chunk

Returns:

null

method dfu_apply

Apply the uploaded firmware image.

After this method completes, the transceiver will reboot into the new firmware.

Warning

Always use permanent=0 and verify firmware with dfu_confirm after reboot. Setting permanent=0x5045524D bypasses the confirmation safety mechanism and may brick the device if the firmware fails to boot.

Parameters:

  • 0 : permanent (uint) – 0x5045524D for permanent, 0 for temporary

Returns:

null

method dfu_confirm

Confirm that the new firmware is working correctly.

If a temporary update was applied, this method makes it permanent. If not called, the transceiver will revert to the previous firmware on next reboot.

Parameters:

None

Returns:

null

Data Types

This section documents common data types that are used across multiple API methods. These types are shared and reusable. They appear in various method signatures and notifications throughout the API.

For method-specific result types that are only used in a single context, see the inline type definitions within each method’s documentation.

struct api_error

API error response returned when a method call fails.

Fields:

  • 0 : code (uint) – Error code indicating the type of failure. See error codes below.

  • ? 1 : internal_code (uint) – Optional: Internal troubleshooting code. Not suitable for external use or API stability guarantees.

  • ? 2 : message (str) – Optional: Human-readable error description. Reserved for future use.

Error Codes:

API_ERR_RESERVED = 0

Reserved.

API_ERR_ARGUMENT_DECODE = 1

Decoding the argument failed.

API_ERR_VALUE_RANGE = 2

An argument value was out of range.

API_ERR_INVALID_STATE = 3

Internal state prohibits the requested operation.

API_ERR_OPERATION_FAILED = 4

The requested operation was attempted, but failed.

API_ERR_OUT_OF_ORDER= 5

Operation attempted out of the required order.

API_ERR_OUT_OF_BOUNDS = 6

Operation would exceed bounds.

API_ERR_NODE_UNAVAILABLE = 7

Node is not connected or not fully initialized.

API_ERR_RESPONSE_ENCODE = 8

Failed to encode the response.

record bluetooth_addr_le

A Bluetooth Low Energy address, represented as a CBOR array with two elements.

Elements:

  • 0 : type (uint) – Address type: 0 = public, 1 = random

  • 1 : address (bstr) – Bluetooth address bytes (most significant byte first, 6 bytes)

Example:

Address AA:BB:CC:DD:EE:FF with public address type:

[0, h'AABBCCDDEEFF']
struct assigned_node

Represents a node assigned to the transceiver for automatic connection management.

Fields:
struct connected_node

Represents a node currently connected to the transceiver.

Fields:

  • 0 : address (bluetooth_addr_le) – Bluetooth address of the node

  • 1 : rssi (int) – Received Signal Strength Indicator in dBm