Ex: SDL Command

Reconfigure a Carbon sensor at runtime with Python.

This example demonstrates how to send a Software Defined LiDAR (SDL) command to a Carbon sensor. SDL commands change the sensor’s operating state, field of view, frame rate, and waveform parameters at runtime — no restart required.

Requires pip install voyant-api.

What You’ll Learn

How to build an SdlCommand from the current sensor state
How to apply settings with the recommended blocking path (send_sdl_blocking)
How the non-blocking send_sdl / poll_sdl path fits an event loop

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: sdl_command.py

Key Concepts

Building the Command

Wait for a heartbeat, then build the command from the sensor’s current read-back with to_sdl_command() and override only the fields you want to change:

from voyant_api import CarbonClient, CarbonConfig, SdlState, SdlStatus, init_voyant_logging

init_voyant_logging()
client = CarbonClient(CarbonConfig())
client.start()

client.wait_for_heartbeat()
state = client.sensor_state()

cmd = state.to_sdl_command()
cmd.req_state = SdlState.PointCloud
cmd.hfov_deg = 60.0
cmd.hfov_center_deg = 0.0   # steering not yet supported — must be 0 for now
cmd.frame_rate_fps = 10.0

Applying It (Blocking)

send_sdl_blocking() sends the command and waits for the sensor to confirm. It returns an SdlStatus — SdlStatus.Applied on success:

status = client.send_sdl_blocking(cmd)
if status == SdlStatus.Applied:
    print("SDL command applied successfully.")
else:
    print(f"SDL command failed: {status}")

Non-blocking Alternative

For event loops that must keep processing frames while a command is in flight, send_sdl() starts the command and poll_sdl() drives it to completion. Poll until the status is no longer SdlStatus.Pending. The blocking path is recommended for normal use.

Command Line Options

python sdl_command.py --help

# Set field of view and frame rate
python sdl_command.py --hfov 90 --frame-rate 15

# Load a JSON device config
python sdl_command.py --config config/device_config.json

--hfov-center must be 0 for now — beam steering is not yet supported.

Expected Output

CarbonClient started. Press Ctrl+C to stop.

Sending SDL command: SdlCommand(...)
SDL command applied successfully.

Frame 1: 21500 points
Frame 2: 21498 points
...

Next Steps

Live Client — inspect the frames your new configuration produces
API Reference — full CarbonClient and SDL reference