Ex: Live Client

Connect to a Carbon sensor and capture incoming frames with Python.

This example demonstrates how to receive live Carbon data over UDP using the Python bindings.

Requires pip install voyant-api.

What You’ll Learn

How to create a CarbonClient from a CarbonConfig
How to receive frames in a polling loop
How to access point cloud data as NumPy arrays
How to read back sensor and time-sync state

Prerequisites

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Carbon sensor, or the bundled carbon_simulator running locally

Example Code

View the complete example on GitHub: client_example.py

Key Concepts

Creating the Client

CarbonClient is created from a CarbonConfig. Use the defaults, or load a JSON device config (for example to set your sensor’s interface_addr):

from voyant_api import CarbonClient, CarbonConfig, init_voyant_logging

init_voyant_logging()

# Default config, or CarbonConfig.from_json("config/device_config.json")
config = CarbonConfig()

client = CarbonClient(config)
client.start()

Polling for Frames

try_receive_frame() is non-blocking — it returns None if no new frame is available yet:

while client.is_running():
    frame = client.try_receive_frame()
    if frame is not None:
        xyzv = frame.xyzv()  # NumPy array (N x 4): [x, y, z, radial_vel]
        print(frame)

        # Device health, SDL state, calibration
        print(client.sensor_state())
        # Host<->FPGA clock sync health (quality, offset, jitter)
        print(client.time_sync_state())
    else:
        time.sleep(0.001)

Command Line Options

python client_example.py --help

# Load a JSON device config (e.g. with your sensor interface_addr)
python client_example.py --config config/device_config.json

Expected Output

Using config:
CarbonConfig { ... }

Starting CarbonClient...
Press Ctrl+C to stop

Frame 1: VoyantFrame(frame_index=133, n_points=23040, n_valid=21500, timestamp=1742330842.722)
xyzv data:
[[ 5.820  0.194 11.043  1.230]
 ...]
Sensor state: SensorState{ ... }
Time sync: TimeSyncState{ quality=Good valid=True offset=... jitter=... }

Next Steps

SDL Command — reconfigure the sensor (state, FOV, frame rate) at runtime
Recorder — save live frames to disk
Playback — replay recordings offline