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 :doc:`cbor-rpc`. Utility Methods --------------- .. cborrpc:method:: ping Simple no-operation request for connection health checks and keepalive. :Parameters: None :Returns: ``null`` .. cborrpc:method:: reboot Reboot the transceiver. The transceiver reboots immediately after responding. The connection will be lost. :Parameters: None :Returns: ``null`` Node Management --------------- .. cborrpc: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 :cborrpc:struct:`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`` .. cborrpc: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 :cborrpc:meth:`set_assigned_nodes`. :Parameters: None :Returns: Array of assigned nodes :Return type: :cborrpc:struct:`get_assigned_nodes_result` **Result type:** .. cborrpc:struct:: get_assigned_nodes_result Result structure for get_assigned_nodes. :Fields: * ``0`` : **nodes** (array of :cborrpc:struct:`assigned_node`) -- Array of assigned node objects .. cborrpc: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: :cborrpc:struct:`get_connected_nodes_result` **Result type:** .. cborrpc:struct:: get_connected_nodes_result Result structure for :cborrpc:struct:`get_connected_nodes`. :Fields: * ``0`` : **nodes** (array of :cborrpc:struct:`connected_node`) -- Array of assigned node objects .. cborrpc: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 :cborrpc:meth:`scan_nodes_stop` is called This method is useful for discovering available nodes before assigning them. :Parameters: None :Returns: ``null`` .. cborrpc:method:: scan_nodes_stop Stop the node scanning process. :Parameters: None :Returns: ``null`` AVSS Proxy Methods ------------------ .. cborrpc: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 :doc:`AVSS Commands and Responses <../avss/commands-and-responses>` documentation for details on AVSS Control Point message formats. :Parameters: * ``0`` : **address** (:cborrpc:record:`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: :cborrpc:struct:`avss_request_result` **Result type:** .. cborrpc:struct:: avss_request_result Result structure for :cborrpc:meth:`avss_request`. :Fields: * ``0`` : **response** (*bstr*) -- Raw AVSS Control Point response bytes .. cborrpc: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** (:cborrpc:record:`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 ------------------ .. cborrpc: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: :cborrpc:struct:`get_device_info_result` **Result type:** .. cborrpc:struct:: get_device_info_result Result structure for :cborrpc:meth:`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. .. cborrpc: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: :cborrpc:struct:`get_device_status_result` **Result type:** .. cborrpc:struct:: get_device_status_result Result structure for :cborrpc:meth:`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 .. cborrpc: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: :cborrpc:struct:`get_firmware_info_result` **Result type:** .. cborrpc:struct:: get_firmware_info_result Result structure for :cborrpc:meth:`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 -------------------- .. cborrpc:method:: get_time Retrieve the transceiver's current system time. :Parameters: None :Returns: Current time :Return type: :cborrpc:struct:`get_time_result` **Result type:** .. cborrpc:struct:: get_time_result Result structure for :cborrpc:meth:`get_time`. :Fields: * ``0`` : **time** (*int64*) -- Unix time in nanoseconds .. cborrpc: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`` .. cborrpc: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: :cborrpc:struct:`get_ptp_status_result` **Result type:** .. cborrpc:struct:: get_ptp_status_result Result structure for :cborrpc:meth:`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 ----------------------- .. cborrpc:method:: dfu_prepare Prepare for a firmware update. This method must be called before :cborrpc:meth:`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`` .. cborrpc: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`` .. cborrpc: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 :cborrpc:meth:`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`` .. cborrpc: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. .. cborrpc: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. .. cborrpc: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'] .. cborrpc:struct:: assigned_node Represents a node assigned to the transceiver for automatic connection management. :Fields: * ``0`` : **address** (:cborrpc:record:`bluetooth_addr_le`) -- Bluetooth address of the node .. cborrpc:struct:: connected_node Represents a node currently connected to the transceiver. :Fields: * ``0`` : **address** (:cborrpc:record:`bluetooth_addr_le`) -- Bluetooth address of the node * ``1`` : **rssi** (*int*) -- Received Signal Strength Indicator in dBm