adar-api

ADAR API Python Package

A Python package for communicating with the ADAR 3D Ultrasonic Sensor via Constrained Application Protocol (CoAP).

Overview

This package serves two main purposes:

1. Easy-to-use Python API: Provides a simple interface for receiving 3D point cloud data from ADAR sensors, for conversion to other ecosystems like ROS or Foxglove.

2. Reference Implementation: Documents the CoAP resources and binary data formats to enable porting to other languages (C, C++, etc.)

Table of Contents

• Installation
• Network Requirements
• Quick Start
  • Point Cloud Publisher
  • ROS Integration
  • ADAR API
• API Reference - For Python developers
  • Error Handling
  • Usage Examples
• CoAP Resources and Data Formats - For protocol reference

Installation

Compatibility: ADAR API 2.0 supports both v0 and v1 endpoints. The package automatically detects the endpoint version supported by the device. Features requiring authentication (login, state control, reboot) are only available on v1 endpoints.

Prerequisites: Python 3.11+ must be installed.

Quick Installation

Install the ADAR API package from PyPI:

pip install adar-api

Recommended: Using a Virtual Environment

For better dependency management, it's recommended to use a virtual environment:

1. Create a virtual environment:

   python -m venv .venv
   

2. Activate the virtual environment:

   Linux/macOS:

   source .venv/bin/activate
   

   Windows (cmd):

   .venv\Scripts\activate
   

   Windows (PowerShell):

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   .venv\Scripts\Activate.ps1
   

3. Install the package:

   pip install adar-api
   

Note: You need to activate the virtual environment each time you want to use the pointcloud-publisher command or the ADAR API in a new terminal session. To deactivate the virtual environment, simply type deactivate.

Network Requirements

• Protocol: CoAP over UDP (port 5683)
• Network: IPv4 connectivity to sensor
• Firewall: Ensure UDP port 5683 is accessible

Quick Start

Point cloud Publisher

The easiest way to visualize the ADAR point cloud is to use the built-in pointcloud-publisher:

pointcloud-publisher <ADAR_IP_ADDRESS>

Example for an ADAR with factory-default IP address:

pointcloud-publisher 10.20.30.40

Advanced Usage

Specify a custom Foxglove server host: This can be useful if you want to publish the pointcloud to a different computer than the one running the pointcloud-publisher script.

pointcloud-publisher <ADAR_IP_ADDRESS> --foxglove-host <HOST_IP>

Example for broadcasting to a specific foxglove host: This will publish the pointcloud from an ADAR with IP address 10.20.30.40 to a foxglove host running on IP address 127.0.0.2

pointcloud-publisher 10.20.30.40 --foxglove-host 127.0.0.2

Example for zone visualization: This will publish the active zone presets as markers in Foxglove. The zones are read from an ADAR configuration file and automatically switch based on the device's active zone.

pointcloud-publisher 10.20.30.40 --config-path path/to/config.adar

Command Line Options:

• ipaddr (required): IP address of the ADAR device
• --foxglove-host (optional): Host IP address for the Foxglove server (default: 127.0.0.1)
• --config-path (optional): Path to the ADAR device configuration file for zone visualization (default: None)

Visualization with Foxglove Studio

1. Start the pointcloud publisher (as shown above)
2. Open Foxglove Studio
3. Connect to the Foxglove server:
   • Go to "Open connection"
   • Select "Foxglove WebSocket"
   • Enter ws://127.0.0.1:8765 (or your custom host)
4. Import layout for ADAR:
   • In the top right pane, select the layout drop-down and click "Import from file..."
   • Select the foxglove_layout_ADAR.json file.
   • The point cloud should now appear in a 3D view and a 2D top-down view.

ROS Integration

For ROS (Robot Operating System) integration, see the ROS example documentation for detailed setup instructions, including Docker configuration and usage examples.

ADAR API

For custom integrations, use the Python API directly:

import asyncio
from adar_api import Adar, CoapPointCloud
from aiocoap import Context


async def main():
    # Create CoAP context
    ctx = await Context.create_client_context()

    # Connect to ADAR sensor
    adar = Adar(ctx, ip_address="10.20.30.40")

    # Get device information
    device_info = await adar.get_device_info()
    print(f"Device: {device_info.device_name}")
    print(f"Firmware: {device_info.firmware_version}")
    print(f"Serial: {device_info.device_identification.serial_number}")
    print(f"Hardware: {device_info.device_identification.hardware_version}")

    # Get single point cloud frame
    point_cloud: CoapPointCloud = await adar.get_point_cloud()
    print(f"Received {len(point_cloud.points)} points")

    # Continuous observation
    async for point_cloud in adar.observe_point_cloud():
        print(f"Received {len(point_cloud.points)} points")
        for point in point_cloud.points:
            print(
                f"Point: x={point.x:.3f}m, y={point.y:.3f}m, z={point.z:.3f}m, "
                f"strength={point.strength}, classification={point.classification}"
            )


if __name__ == "__main__":
    asyncio.run(main())

API Reference

Error Handling

The API provides structured exception handling:

from adar_api import CoapException, CoapErrorException

try:
    point_cloud = await adar.get_point_cloud()
except CoapErrorException as e:
    print(f"CoAP protocol error: {e.response.code}")
except CoapException as e:
    print(f"General CoAP error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Response Code Handling

CoAP errors include response codes that indicate the type of failure or success.

For a complete list of response codes, see CoAP Response Codes in the protocol reference.

Usage Examples

Robust Point Cloud Observation

async def robust_observation():
    async for point_cloud in adar.observe_point_cloud(keep_running=True):
        try:
            # Process point cloud
            # Use to_thread to avoid blocking the underlying async network io task,
            # which could cause network buffer overflow if process_points takes too long.
            await asyncio.to_thread(process_points, point_cloud.points)
        except Exception as e:
            logger.warning(f"Processing error: {e}")
            # Continue observation despite processing errors

Direct CoAP Request

from aiocoap import Message, GET

# Access the underlying CoAP request method
response = await adar.send_request(Message(code=GET, uri=f"coap://{adar.ip_address}/status/v1"))

Network Configuration

from adar_api import NetworkConfig

# Get current configuration
config = await adar.get_network_config()
print(f"DHCP: {config.dhcp_enabled}")
print(f"Static IP: {config.static_ip}")
print(f"Device Tag: {config.device_tag}")

# To change the network configuration, create a new NetworkConfig with the desired parameters.
# Note: modifying attributes on an existing NetworkConfig does not update the underlying binary
# data. Always construct a new NetworkConfig when writing changes.
new_config = NetworkConfig(
    dhcp_enabled=False,
    static_ip="10.20.30.50",
    subnet_mask="255.255.255.0",
    gateway="10.20.30.1",
    device_tag="my-sensor",
)

# Apply configuration (requires login, device will reboot)
await adar.login(password="your_password")
await adar.set_network_config(new_config)

Transmission Code Configuration

# Get current transmission code
code_id = await adar.get_transmission_code_id()
print(f"Current transmission code: {code_id}")

# Set transmission code ID (valid values: 1, 2, 4, 8)
await adar.set_transmission_code_id(4)

Note: The Python API uses code IDs (1, 2, 4, 8), while the CoAP protocol uses code indices (0, 1, 2, 3). The relationship is: code ID = 2^index. The Python API handles this conversion automatically.

CoAP Resources and Data Formats

For developers integrating towards ADAR using other languages, this section documents the CoAP API resources and data formats.

Resource URI Structure

coap://<device_ip>/<resource>/<version>

Resource Reference

Resources that do not require authentication:

Resources that require authentication (see Authentication):

Note: Legacy v0 endpoints are deprecated and will return 5.01 Not Implemented.

Payload CRC

Every CoAP message that carries a non-empty payload, in both directions, includes a CRC-32 checksum as the last 4 bytes. This applies to all resource paths and all methods (GET responses, OBSERVE notifications, PUT requests, etc.). The CRC covers both the resource path and the payload data, in that order.

Messages with an empty payload (e.g., a GET request or a PUT to /reboot/v1) do not carry a CRC.

The device will respond with 4.00 Bad Request if a received message has an invalid or missing CRC.

Note: CRC was introduced together with the v1 resource paths. Older firmware with only v0 paths (e.g., pointcloud/v0) will accept messages with or without a trailing CRC, but will not include a CRC in its responses. Clients that need to support both old and new firmware can use the endpoint version as an indicator: v0 paths -> no CRC in responses, v1+ paths -> CRC always present.

CRC Calculation

The CRC-32 is computed over:

1. The URI path encoded as UTF-8, without leading or trailing slashes (e.g., pointcloud/v1)
2. The payload bytes (excluding the CRC itself)

The CRC algorithm is CRC-32 (polynomial 0x04C11DB7, also known as CRC-32/ISO-HDLC). The resulting 4-byte checksum is stored in little-endian byte order.

Receiving (GET responses, OBSERVE notifications)

When the device sends a response with a payload, the last 4 bytes are the CRC:

[ payload_data (N bytes) ] [ crc32 (4 bytes, little-endian) ]

To verify and decode:

1. Split the raw payload into data (all bytes except the last 4) and crc_bytes (the last 4 bytes)
2. Compute CRC-32 over the concatenation of the URI path bytes and data
3. Compare with the received CRC (interpret crc_bytes as a little-endian uint32)
4. If the CRC matches, parse data according to the resource's data format
5. If the CRC does not match, treat it as a communication error

Sending (PUT requests)

When sending a PUT request with a payload, append the CRC as the last 4 bytes:

1. Encode the payload data according to the resource's data format
2. Compute CRC-32 over the concatenation of the URI path bytes and data
3. Encode the CRC as 4 bytes in little-endian byte order and append them to data

Example

For a GET response on status/v1 with 8 bytes of device status data (00 03 00 00 00 00 00 00):

CRC input:  "status/v1" (as UTF-8) ++ 00 03 00 00 00 00 00 00
CRC output: 0xEF0EE5D0
Wire payload: [ 00 03 00 00 00 00 00 00 ] [ D0 E5 0E EF ]
                                            ^^ little-endian CRC

This can be used as a test vector when implementing CRC validation.

Data Format Specifications (little-endian)

Point Cloud Format

The point cloud resource uses CoAP Observe. A GET with the Observe Register option registers the client as an observer and starts continuous notifications. A GET without the Observe Register option deregisters the client and does not return a point cloud frame. The maximum number of concurrent observers is 2; additional attempts receive 4.29 Too Many Requests.

Binary payload structure:

Note: The number of points is determined by parsing 10-byte chunks until the payload ends. The total payload length minus the 16-byte header must be divisible by 10, or the data is considered corrupted.

Point Format

Note: The Python API converts coordinates from millimeters to meters.

Classification Flags

Note: Bit 4 (Not Classified) is set when no zone preset is configured on the device. When set, bits 0-3 are all zero.

Device Status Format

8-byte binary structure:

Device States

• 1: Init
• 2: SelfTest
• 3: Enabled
• 4: Disabled
• 5: Config
• 6: Error
• 7: Fault

Zone Status Flags

Device Error Bitmask

The Device Error field (uint32, little-endian) is a bitmask where each bit indicates a specific error condition. When the device state is Error or Fault, this field provides details about the cause. Multiple bits may be set simultaneously.

Bits 23-31 are reserved.

Device Info Format

Variable-length format with length-prefixed strings:

Length-prefixed String Format

• 4 bytes: String length (uint32, little-endian)
• N bytes: UTF-8 string data

Network Config Format

212-byte binary structure:

Configuration Flags

Note: When bit 2 (Sync source) is set, this device provides the sync signal for other devices. When bit 3 is set, the device only accepts synchronization from the IP specified in the Sync Server IP field (bytes 16-19).

Error Format

Variable-length format with error bitmask and description strings:

Error String Format

• 4 bytes: String length (uint32, little-endian)
• N bytes: UTF-8 error description

Transmission Code Format

Single byte payload:

Note: A PUT to this resource while the transmission code is locked is rejected with 4.03 Forbidden.

Authentication

Several resources require the client to be logged in. The authentication flow uses a challenge-response mechanism:

1. GET /login/v1 — The device returns an 8-byte login token (uint64, little-endian). This token is a one-time challenge.
2. The client encodes the device password using the received token.
3. PUT /login/v1 — The client sends the encoded password. On success, the device responds with a session token (length-prefixed UTF-8 string, up to 16 characters).
4. Subsequent authenticated requests include the session token as a URI query parameter: ?t=<session_token>.

The session ends when the client sends PUT /logout/v1, or when the device is rebooted.

Note: Only one user session is active at a time. A login attempt while another session is active will be rejected with 4.03 Forbidden. The existing session must be ended (via logout or device reboot) before a new login can succeed.

CoAP Response Codes

When working with ADAR resources, you may encounter these CoAP response codes:

Success Responses

• 2.02 Deleted - Resource successfully deleted
• 2.04 Changed - Resource successfully modified (PUT operations)
• 2.05 Content - Resource successfully retrieved (GET operations)

Client Error Responses

• 4.00 Bad Request - Malformed request or invalid payload data
• 4.04 Not Found - Resource does not exist (e.g., typos in resource paths like /pointclouds/v1 instead of /pointcloud/v1) or unauthorized access
• 4.05 Method Not Allowed - Invalid HTTP method for the resource (e.g., PUT to a read-only resource)
• 4.08 Request Entity Incomplete - Missing or incomplete payload for operations that require data
• 4.29 Too Many Requests - Observer limit exceeded (max 2 point cloud observers)

Server Error Responses

• 5.01 Not Implemented - Resource is deprecated or not supported in the current firmware version