CarbonClient Class Reference

Client for receiving frames from a Carbon LiDAR sensor. More...

#include <carbon_client.hpp>

Public Member Functions
	CarbonClient (const CarbonConfig &config)
	Construct a CarbonClient from a CarbonConfig. The config is cloned internally — it remains valid after this call.
	~CarbonClient ()
	CarbonClient (const CarbonClient &)=delete
CarbonClient &	operator= (const CarbonClient &)=delete
	CarbonClient (CarbonClient &&)=delete
CarbonClient &	operator= (CarbonClient &&)=delete
bool	start ()
	Start receiving and processing data.
void	stop ()
	Stop receiving and processing data. Safe to call multiple times. Can restart with start().
bool	isRunning () const
	Returns true if the client is running and no shutdown has been requested.
std::optional< VoyantFrame >	tryReceiveFrame ()
	Try to receive the next frame from the internal buffer.
SensorState	getSensorState () const
	Get the latest sensor state from the most recent heartbeat.
TimeSyncState	getTimeSyncState () const
	Get the latest host↔FPGA time-sync state (quality, offset, jitter).
SdlStatus	sendSdl (const SdlCommandParams &cmd)
	Send an SDL command to the sensor FPGA without blocking.
SdlStatus	pollSdl ()
	Poll for SDL command confirmation after sendSdl().
SdlStatus	sendSdlBlocking (const SdlCommandParams &cmd)
	Send an SDL command and block until it is confirmed or times out.
bool	waitForHeartbeat ()
	Block until the sensor's first heartbeat arrives, or a fixed timeout elapses.
bool	ensureIdleForCalibration ()
	Drive the sensor to Idle using the fixed background-noise calibration config, blocking until confirmed.
bool	applyDefaultBackgroundNoise ()
	Apply the compiled-in default background-noise calibration for the connected box, blocking until done.
bool	refineBackgroundNoise (uint32_t iterations=0)
	Refine the background-noise calibration for the connected box from a covered-window capture, blocking until done (roughly 10–20 seconds).
bool	startDiagnosticCapture (const std::string &path, bool overwrite=false)
	Begin a diagnostic capture for Voyant support: the raw peak stream is written to a .vynt sidecar log (peak messages interleaved with each heartbeat's sensor state) while the point cloud keeps running. Record frames alongside it — together they form the support bundle.
void	stopDiagnosticCapture ()
	Request the active diagnostic capture to stop. Returns immediately; the file ends on a whole frame. Poll isDiagnosticCapturing() for completion.
bool	isDiagnosticCapturing () const
	Returns true while a diagnostic capture is running.
std::string	diagnosticCaptureError () const
	Why the last diagnostic capture ended badly, if it did.

Static Public Member Functions
static void	setupSignalHandling (int signal=SIGINT)
	Set up OS signal handling for graceful termination.
static bool	isTerminated ()
	Returns true if a termination signal has been received.
static void	resetTerminationFlag ()
	Resets the termination flag.

Static Private Member Functions
static void	signalHandler (int)

Private Attributes
CarbonClientHandleC *	handle_

Static Private Attributes
static volatile std::sig_atomic_t	terminated_

Detailed Description

Client for receiving frames from a Carbon LiDAR sensor.

Example:

CarbonClient::setupSignalHandling();
 
CarbonConfig config;
config.setBindAddr("0.0.0.0:5678")
      .setGroupAddr("239.255.48.84")
      .setInterfaceAddr("0.0.0.0");
 
CarbonClient client(config);
client.start();
 
while (client.isRunning() && !CarbonClient::isTerminated()) {
    if (auto frame = client.tryReceiveFrame()) {
        std::cout << *frame << std::endl;
    }
}
client.stop();

Constructor & Destructor Documentation

CarbonClient() [1/3]

CarbonClient::CarbonClient ( const CarbonConfig & config )

explicit

Construct a CarbonClient from a CarbonConfig. The config is cloned internally — it remains valid after this call.

Parameters

config

CarbonConfig with all desired settings.

Exceptions

std::runtime_error

if client creation fails.

~CarbonClient()

CarbonClient::~CarbonClient

(

)

CarbonClient() [2/3]

CarbonClient::CarbonClient ( const CarbonClient & )

delete

CarbonClient() [3/3]

CarbonClient::CarbonClient ( CarbonClient && )

delete

Member Function Documentation

applyDefaultBackgroundNoise()

bool CarbonClient::applyDefaultBackgroundNoise

(

)

Apply the compiled-in default background-noise calibration for the connected box, blocking until done.

Writes the built-in default mask. The sensor must be in Idle; this does not change the sensor's state. Blocks for a few seconds.

Returns

true on success; false if the sensor is not Idle, no calibration is embedded for the box, or a write fails.

diagnosticCaptureError()

std::string CarbonClient::diagnosticCaptureError

(

)

const

Why the last diagnostic capture ended badly, if it did.

Returns

The failure reason, or an empty string for a capture that completed or is still running — so a caller polling isDiagnosticCapturing() can tell a finished capture from a broken one.

ensureIdleForCalibration()

bool CarbonClient::ensureIdleForCalibration

(

)

Drive the sensor to Idle using the fixed background-noise calibration config, blocking until confirmed.

Both calibration operations require Idle on entry; this reaches it from any state.

Returns

true once Idle is confirmed; false on failure.

getSensorState()

SensorState CarbonClient::getSensorState

(

)

const

Get the latest sensor state from the most recent heartbeat.

Returns

Snapshot of the latest SensorState in physical units.

getTimeSyncState()

TimeSyncState CarbonClient::getTimeSyncState

(

)

const

Get the latest host↔FPGA time-sync state (quality, offset, jitter).

Returns a snapshot — call again to get updated values. Reads SyncQuality::Unsynced until the background time-sync task records its first measurement (or if time-sync is disabled in the config).

Returns

Snapshot of the latest TimeSyncState.

isDiagnosticCapturing()

bool CarbonClient::isDiagnosticCapturing

(

)

const

Returns true while a diagnostic capture is running.

isRunning()

bool CarbonClient::isRunning

(

)

const

Returns true if the client is running and no shutdown has been requested.

isTerminated()

bool CarbonClient::isTerminated ( )

static

Returns true if a termination signal has been received.

operator=() [1/2]

CarbonClient & CarbonClient::operator= ( CarbonClient && )

delete

operator=() [2/2]

CarbonClient & CarbonClient::operator= ( const CarbonClient & )

delete

pollSdl()

SdlStatus CarbonClient::pollSdl

(

)

Poll for SDL command confirmation after sendSdl().

This belongs with the lower-level non-blocking sendSdl() path. For normal SDL commands, prefer sendSdlBlocking().

Returns

SdlStatus::Idle if no command is in flight, SdlStatus::Pending while waiting for heartbeat confirmation, or a terminal status once resolved.

refineBackgroundNoise()

bool CarbonClient::refineBackgroundNoise

(

uint32_t

iterations = 0

)

Refine the background-noise calibration for the connected box from a covered-window capture, blocking until done (roughly 10–20 seconds).

The sensor must be in Idle on entry and the window must be covered (the capture assumes background noise only). Cycles the sensor between Idle and Point Cloud internally and returns to Idle when finished. While it runs, SDL commands and diagnostic captures on this client are rejected; do not run a second client against the sensor.

Parameters

iterations

Refinement iterations, or 0 to use the built-in default.

Returns

true on success; false if the sensor is not Idle, no calibration is embedded for the box, or a transition/capture/write fails.

resetTerminationFlag()

void CarbonClient::resetTerminationFlag ( )

static

Resets the termination flag.

sendSdl()

SdlStatus CarbonClient::sendSdl

(

const SdlCommandParams &

cmd

)

Send an SDL command to the sensor FPGA without blocking.

This is the non-blocking path; drive pollSdl() to confirm. A PointCloud request is applied transparently as a two-step transition (settings in Idle, then PointCloud resumed), advanced by pollSdl(). For commands where blocking is acceptable, prefer sendSdlBlocking().

Parameters

cmd	SdlCommandParams configured with the desired sensor parameters.

Returns

SdlStatus::Pending (first command in flight; drive pollSdl() to confirm), SdlStatus::SendFailed (UDP send failed), SdlStatus::PreviousCommandPending (a command is already in flight), or another rejection status (e.g. SdlStatus::InvalidParameter) if rejected before sending.

sendSdlBlocking()

SdlStatus CarbonClient::sendSdlBlocking

(

const SdlCommandParams &

cmd

)

Send an SDL command and block until it is confirmed or times out.

Use this for normal SDL commands: it sends the command, applies the requested settings, and waits for the sensor to confirm. A PointCloud request is applied as a two-step transition (settings in Idle, then PointCloud); the timeout from CarbonConfig sdl.timeout_sec is enforced per command, so it can take up to roughly twice that long.

Parameters

cmd	SdlCommandParams to send.

Returns

Terminal SdlStatus (Applied on success).

setupSignalHandling()

void CarbonClient::setupSignalHandling ( int signal = SIGINT )

static

Set up OS signal handling for graceful termination.

Parameters

signal

Signal to handle (default: SIGINT)

signalHandler()

void CarbonClient::signalHandler ( int )

staticprivate

start()

bool CarbonClient::start

(

)

Start receiving and processing data.

Returns

true on success, false on failure.

startDiagnosticCapture()

bool CarbonClient::startDiagnosticCapture	(	const std::string &	path,
		bool	overwrite = false )

Begin a diagnostic capture for Voyant support: the raw peak stream is written to a .vynt sidecar log (peak messages interleaved with each heartbeat's sensor state) while the point cloud keeps running. Record frames alongside it — together they form the support bundle.

Requires diagnostic_mode in the client config (set before starting the client). The capture runs until stopDiagnosticCapture(). The writer runs on its own thread, so this returns immediately.

Parameters

path	Output .vynt path, used verbatim. Name it after the frame recording it accompanies, e.g. my_recording_peaks.vynt.
overwrite	Allow overwriting an existing sidecar file (false = fail instead). Match the recorder's overwrite setting.

Returns

true if the capture started; false if diagnostic_mode is off, the client is not running, or a capture is already in progress.

stop()

void CarbonClient::stop

(

)

Stop receiving and processing data. Safe to call multiple times. Can restart with start().

stopDiagnosticCapture()

void CarbonClient::stopDiagnosticCapture

(

)

Request the active diagnostic capture to stop. Returns immediately; the file ends on a whole frame. Poll isDiagnosticCapturing() for completion.

tryReceiveFrame()

std::optional< VoyantFrame > CarbonClient::tryReceiveFrame

(

)

Try to receive the next frame from the internal buffer.

Frames are delivered oldest-first. If the pipeline produces frames faster than the caller consumes them, the small buffer fills and the newest incoming frames are dropped.

Returns

The dequeued frame, or nullopt if none is currently available.

waitForHeartbeat()

bool CarbonClient::waitForHeartbeat

(

)

Block until the sensor's first heartbeat arrives, or a fixed timeout elapses.

SDL confirmation and both background-noise calibration operations need a heartbeat first — the box serial and the frame counter used for confirmation come from it.

Returns

true once a heartbeat is observed; false on timeout.

Member Data Documentation

handle_

CarbonClientHandleC* CarbonClient::handle_

private

terminated_

volatile std::sig_atomic_t CarbonClient::terminated_

staticprivate

---

The documentation for this class was generated from the following file:

• /usr/include/voyant_api/carbon_client.hpp