voyant_types_ffi.hpp File Reference

#include <cstdarg>
#include <cstdint>
#include <cstdlib>
#include <ostream>
#include <new>
#include <sdl_types_generated.hpp>

Go to the source code of this file.

Classes
struct	SdlDeviceState
struct	HealthState
struct	CounterState
struct	DeviceInfo
struct	CalibrationState
struct	DspHeaderState
struct	SensorState
struct	VoyantFrameMeta
struct	HostState
struct	PointDataV1
struct	VoyantVec3
struct	TimeSyncState

Enumerations
enum class	ProductId : uint8_t {   Unknown = 0 , Lark = 1 , Meadowlark = 2 , CarbonBenchtop = 3 ,   Carbon30 = 4 , VivadoSimulator = 250 , VerilatorSimulator = 251 , XceliumSimulator = 252 ,   IsaacSim = 253 , SoftwareSimulator = 254 }
enum class	SdlStatus : uint8_t {   Unknown = 0 , Idle = 1 , Pending = 2 , Applied = 3 ,   BadFovCenterCombo = 4 , InvalidParameter = 5 , InvalidStateTransition = 6 , MissingCalibration = 7 ,   UnableToCalibrate = 8 , ParseError = 9 , ApplicationError = 10 , FovFpsError = 11 ,   CommandBuildFailed = 12 , PreviousCommandPending = 13 , SendFailed = 14 , Timeout = 15 ,   MaxRetriesExceeded = 16 , StreamReset = 17 , MessageReadyForMcu = 18 , ValidMessageParsed = 19 ,   ObserverOnly = 20 }
enum class	StateProvenance : uint8_t { Unknown = 0 , Measured = 1 , Absent = 2 }
enum class	SyncQuality : uint8_t {   Unsynced , Poor , Fair , Good ,   Excellent }

Functions
SensorState	voyant_frame_sensor_state (const VoyantFrameMeta *meta)
HostState	voyant_frame_host_state (const VoyantFrameMeta *meta)
uintptr_t	voyant_frame_device_id (const VoyantFrameMeta *meta, char *buf, uintptr_t capacity)
bool	voyant_synthetic_frame_meta (uint8_t source, int64_t timestamp_seconds, int32_t timestamp_nanoseconds, uint32_t frame_index, VoyantFrameMeta *out)
bool	voyant_stateless_frame_meta (uint8_t source, uint32_t serial_number, int64_t timestamp_seconds, int32_t timestamp_nanoseconds, uint32_t frame_index, VoyantFrameMeta *out)
bool	voyant_frame_meta_with_sdl (VoyantFrameMeta *meta, uint8_t req_state, float frame_rate_fps, float hfov_deg, float hfov_center_deg, float ramp_bandwidth_ghz)
bool	voyant_points_xyz (const PointDataV1 *points, uintptr_t n_points, VoyantVec3 *out)
bool	voyant_points_set_xyz (PointDataV1 *points, uintptr_t n_points, const VoyantVec3 *positions)
uintptr_t	voyant_api_version_string (char *buf, uintptr_t capacity)
uintptr_t	voyant_interface_contract_version_string (char *buf, uintptr_t capacity)

Enumeration Type Documentation

ProductId

enum class ProductId : uint8_t

strong

Hardware and simulation product identifiers.

Sent in the heartbeat product_id field. Values 250–252 are FPGA/RTL simulators; 253 is Isaac Sim; 254 is the basic software simulator; 255 is reserved.

Unknown or future variants are preserved as Unknown so that the rest of the pipeline never panics on an unrecognised ID.

Enumerator
Unknown
Lark
Meadowlark
CarbonBenchtop
Carbon30
VivadoSimulator
VerilatorSimulator
XceliumSimulator
IsaacSim
SoftwareSimulator	Basic software simulator (lightweight, no physics/FPGA).

SdlStatus

enum class SdlStatus : uint8_t

strong

Outcome of an SDL command, either from the sensor heartbeat or detected client-side.

The raw msg_status wire values from the sensor are mapped here in from_msg_status — the discriminants in this enum are contiguous and have no relationship to the wire protocol values.

Enumerator
Unknown	Unrecognized or default wire status from the sensor heartbeat. Not returned by the send/poll API in normal operation.
Idle	No SDL command is currently in flight. Returned by poll_sdl() when called with nothing pending.
Pending	Command sent, awaiting sensor confirmation via heartbeat. Returned by send_sdl() on a successful UDP send, or by poll_sdl() while waiting for heartbeat confirmation.
Applied	Sensor confirmed the command was successfully applied.
BadFovCenterCombo	The FOV and center combination is not valid. May be rejected client-side before sending, or by the sensor.
InvalidParameter	A parameter value is out of range or otherwise invalid. May be rejected client-side before sending, or by the sensor.
InvalidStateTransition	The requested state transition is not permitted from the current state.
MissingCalibration	Sensor cannot apply the command due to missing calibration data.
UnableToCalibrate	Sensor attempted calibration but was unable to complete it.
ParseError	Sensor could not parse the SDL message.
ApplicationError	Sensor parsed the command but failed to apply it.
FovFpsError	The FOV/FPS combination exceeds hardware performance limits. Command was not sent.
CommandBuildFailed	The SDL command could not be constructed from the supplied parameters.
PreviousCommandPending	A previous command is still awaiting confirmation; wait for it to resolve before sending another.
SendFailed	The underlying UDP send failed. Check logs for detail.
Timeout	No heartbeat confirmation arrived within the configured timeout window.
MaxRetriesExceeded	Command was retransmitted the maximum number of times without confirmation.
StreamReset	Heartbeat frame counter jumped backwards — stream was reset.
MessageReadyForMcu	Sensor has received the message and it is ready for MCU processing.
ValidMessageParsed	Sensor parsed a valid SDL message but did not apply the requested change.
ObserverOnly	The client is in observer-only mode and cannot issue SDL commands; nothing was sent. A primary (non-observer) client owns the sensor. Appended out of group order to keep discriminants stable (the values are exposed to Python via eq_int).

StateProvenance

enum class StateProvenance : uint8_t

strong

Whether a frame's state regions hold a real snapshot. Zeros in an absent region convert to plausible physical values (-273.15 °C), so consumers must report it as absent. In-memory only — on disk this is the entry's PayloadFormat.

Enumerator
Unknown	Nobody declared it; treated as [Absent](Self::Absent), so a forgetful producer withholds state rather than inventing it.
Measured	The regions hold a real snapshot.
Absent	Never recorded; only mirrored frame identity is real.

SyncQuality

enum class SyncQuality : uint8_t

strong

Qualitative health of the host↔FPGA clock synchronization, judged by the absolute clock difference |host − FPGA|. Ordered worst-to-best (Unsynced … Excellent), so ordering comparisons (e.g. "at least `Good`") are meaningful.

Enumerator
Unsynced	No fresh measurement — link down, or never measured.
Poor	Off by more than 1 ms; timestamps are unreliable.
Fair	Within 1 ms but worse than 100 µs; usable, but watch for drift.
Good	Within 100 µs but worse than 1 µs of the host; trustworthy.
Excellent	Within 1 µs of the host — sub-microsecond alignment.

Function Documentation

voyant_api_version_string()

uintptr_t voyant_api_version_string	(	char *	buf,
		uintptr_t	capacity )

Version of the linked voyant-api library, e.g. "1.0.0" or "1.0.0-dev". Unrelated to voyant_playback_api_version, which reports the version that wrote a recording.

voyant_frame_device_id()

uintptr_t voyant_frame_device_id	(	const VoyantFrameMeta *	meta,
		char *	buf,
		uintptr_t	capacity )

Formatted device ID, e.g. "CAR-30-005". Recorded frames carry a real one whether or not they carry state; a frame built from scratch reports an unset device. A null meta writes nothing and returns 0.

voyant_frame_host_state()

HostState voyant_frame_host_state

(

const VoyantFrameMeta *

meta

)

Host-side context from a frame's raw region; same carries-state caveat as voyant_frame_sensor_state. A null meta gives all zeros.

voyant_frame_meta_with_sdl()

bool voyant_frame_meta_with_sdl	(	VoyantFrameMeta *	meta,
		uint8_t	req_state,
		float	frame_rate_fps,
		float	hfov_deg,
		float	hfov_center_deg,
		float	ramp_bandwidth_ghz )

Set meta's SDL region as if the sensor had applied the given configuration (msg_status = Applied) — the FFI behind C++ withSdl. Nothing outside that region changes, bar the simulator-only bandwidth derivation that SensorStateRawV1::apply_sdl_command documents. Physical units, field-range checked but not put through the live client's send-time checks (hfov_deg == 0 builds a static line; ramp length is firmware-fixed). Returns false and leaves meta untouched on a null pointer, a rejected value, or a meta that carries no state.

voyant_frame_sensor_state()

SensorState voyant_frame_sensor_state

(

const VoyantFrameMeta *

meta

)

Sensor state in physical units from a frame's raw region.

Meaningful only for a frame that carries state (state_provenance Measured) — an absent region converts to plausible-looking values that are not readings. A null meta converts an all-zero region.

voyant_interface_contract_version_string()

uintptr_t voyant_interface_contract_version_string	(	char *	buf,
		uintptr_t	capacity )

Version of the FPGA interface contract this library was built against, e.g. "1.5.6".

voyant_points_set_xyz()

bool voyant_points_set_xyz	(	PointDataV1 *	points,
		uintptr_t	n_points,
		const VoyantVec3 *	positions )

Set n_points points' stored spherical geometry from cartesian positions (one Vec3 per point, index-aligned). Only range_m/azimuth_rad/elevation_rad are touched. Returns false on null pointers.

The inverse of [voyant_points_xyz], and the only supported one: a caller that rebuilds the angles itself is duplicating this projection and will drift if it ever changes. A position shorter than one f32 epsilon, or a non-finite one, leaves the point at range 0 with zeroed angles — the same "no position" state voyant_points_xyz reads a dropped point out as.

voyant_points_xyz()

bool voyant_points_xyz	(	const PointDataV1 *	points,
		uintptr_t	n_points,
		VoyantVec3 *	out )

Compute cartesian positions for n_points points into out (one VoyantVec3 per point, index-aligned with the input). Returns false on null pointers.

Projects whatever spherical values each point holds; only a valid return's result is a position. A dropped point may carry any range, including a placeholder the datum offset leaves negative, so check drop_reason (see DROP_REASON_VALID) before using one — the sign alone says nothing about whether a measurement happened.

voyant_stateless_frame_meta()

bool voyant_stateless_frame_meta	(	uint8_t	source,
		uint32_t	serial_number,
		int64_t	timestamp_seconds,
		int32_t	timestamp_nanoseconds,
		uint32_t	frame_index,
		VoyantFrameMeta *	out )

Fill out with a stateless frame's meta: frame identity only (mirrored into the state regions, so playback's frame_index reconstruction holds), marked StateProvenance::Absent. A real sensor source/serial_number is allowed, unlike voyant_synthetic_frame_meta: the frame claims no measurements, so naming the sensor the points came from is provenance, not a claim about state. An out-of-epoch timestamp clamps rather than failing. Returns false on a null out or an unrecognized source.

voyant_synthetic_frame_meta()

bool voyant_synthetic_frame_meta	(	uint8_t	source,
		int64_t	timestamp_seconds,
		int32_t	timestamp_nanoseconds,
		uint32_t	frame_index,
		VoyantFrameMeta *	out )

Fill out with a synthetic frame's meta: a measured frame from a software source, carrying source as the device identity and the given frame identity (mirrored into the state regions, so it records and replays like a real log). source is a ProductId discriminant and must be a simulator or Unknown — anything else, including real sensor ids (user code can never claim one), returns false and leaves out untouched, as does a null pointer or a timestamp outside the epoch (seconds >= 0, nanoseconds 0..=999999999).