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.
bool	tryReceiveFrame ()
	Try to receive the next frame from the internal buffer.
VoyantFrameWrapper &	latestFrame ()
	Access the frame most recently dequeued by tryReceiveFrame().
const VoyantFrameWrapper &	latestFrame () const
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	startPeakDump (const std::string &path, uint64_t maxFrames=0, uint64_t maxPeaks=0, bool addTimestamp=false)
	Begin dumping the raw peak stream to a CSV file while the point cloud keeps running. The client must be running.
void	stopPeakDump ()
	Request the active peak dump to stop. Returns immediately; the file ends on a whole frame. Poll isPeakDumping() for completion.
bool	isPeakDumping () const
	Returns true while a peak dump is running.

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_
std::unique_ptr< uint8_t[]>	buffer_
VoyantFrameWrapper	latestFrame_

Static Private Attributes
static constexpr size_t	kBufferSize_ = 8 * 1024 * 1024
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 (client.tryReceiveFrame()) {
        std::cout << client.latestFrame() << 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.

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.

isPeakDumping()

bool CarbonClient::isPeakDumping

(

)

const

Returns true while a peak dump 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.

latestFrame() [1/2]

VoyantFrameWrapper & CarbonClient::latestFrame

(

)

Access the frame most recently dequeued by tryReceiveFrame().

Only valid after a successful tryReceiveFrame() call.

latestFrame() [2/2]

const VoyantFrameWrapper & CarbonClient::latestFrame

(

)

const

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 peak dumps 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.

startPeakDump()

bool CarbonClient::startPeakDump	(	const std::string &	path,
		uint64_t	maxFrames = 0,
		uint64_t	maxPeaks = 0,
		bool	addTimestamp = false )

Begin dumping the raw peak stream to a CSV file while the point cloud keeps running. The client must be running.

The first of maxFrames / maxPeaks to be hit ends the dump (pass 0 for unbounded). addTimestamp inserts a timestamp into the filename. The writer runs on its own thread, so this returns immediately; poll isPeakDumping() for completion.

Parameters

path	Output CSV path.
maxFrames	Stop after this many whole frames, or 0 for unbounded.
maxPeaks	Stop after this many CSV rows, or 0 for unbounded.
addTimestamp	Insert a timestamp into the filename.

Returns

true if the dump started; false if the client is not running or a dump is already in progress.

stop()

void CarbonClient::stop

(

)

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

stopPeakDump()

void CarbonClient::stopPeakDump

(

)

Request the active peak dump to stop. Returns immediately; the file ends on a whole frame. Poll isPeakDumping() for completion.

tryReceiveFrame()

bool 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

true if a frame was dequeued into latestFrame().

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

buffer_

std::unique_ptr<uint8_t[]> CarbonClient::buffer_

private

handle_

CarbonClientHandleC* CarbonClient::handle_

private

kBufferSize_

size_t CarbonClient::kBufferSize_ = 8 * 1024 * 1024

staticconstexprprivate

latestFrame_

VoyantFrameWrapper CarbonClient::latestFrame_

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