voyant_types_ffi.hpp

Go to the documentation of this file.

// Copyright (c) 2024-2025 Voyant Photonics, Inc.
// All rights reserved.
 
#pragma once
 
#include <cstdarg>
#include <cstdint>
#include <cstdlib>
#include <ostream>
#include <new>
#include <sdl_types_generated.hpp>

constexpr static const uint8_t DROP_REASON_VALID = 1;

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,
};

struct SdlDeviceState {
  SdlState device_state;
  SdlStatus sdl_status;
  float frame_rate_fps;
  float hfov_deg;
  float hfov_center_deg;
  float ramp_bandwidth_ghz;
  SdlRampLength ramp_length;
};

struct HealthState {
  uint64_t error_word;
  uint32_t hardware_health;
  uint8_t power_health;
  float clarity_board_temp_c;
  float carat_board_temp_c;
  float pic_temp_c;
  float soa_temp_c;
  float adc_temp_c;
  float fpga_temp_c;
  float ll_fom;
  float ll_fom_smoothed;
  uint16_t lo_power_mon;
};

struct CounterState {
  uint64_t total_frame_count;
  uint64_t total_ramp_count;
  uint32_t total_drops_count;
  uint8_t any_drops_sticky;
  uint32_t mcu_cycles_counter;
};

struct DeviceInfo {
  uint32_t serial_number;
  ProductId product_id;
  uint8_t fpga_version_major;
  uint8_t fpga_version_minor;
  uint8_t fpga_version_patch;
  uint8_t mcu_version_major;
  uint8_t mcu_version_minor;
  uint8_t mcu_version_patch;
};

struct CalibrationState {
  int16_t encoder_azimuth_offset;
  float doppler_calibration_mirror_bias;
  float doppler_calibration_mirror_offset;
  float chirp_bandwidth_hz;
  float datum_delta_x_m;
  float datum_delta_y_m;
  float datum_delta_z_m;
  float encoder_eccentricity_coeffs[6];
  float reflectance_poly_coeffs[4];
  float reflectance_channel_scales[7];
};

struct DspHeaderState {
  int64_t timestamp_seconds;
  int32_t timestamp_nanoseconds;
  DspFrameStartToggle frame_start_toggle;
};

struct SensorState {
  SdlDeviceState sdl;
  HealthState health;
  CounterState counters;
  DeviceInfo device;
  CalibrationState calibration;
  DspHeaderState dsp_header;
  uint32_t peaks_per_frame;
  uint64_t last_heartbeat_frame;
};

struct VoyantFrameMeta {
  uint8_t sensor_state_raw[154];
  uint8_t host_state_raw[21];
  uint8_t state_provenance;
  int64_t timestamp_seconds;
  int32_t timestamp_nanoseconds;
  uint32_t frame_index;
  uintptr_t n_points;
};

struct HostState {
  int16_t state_age_frames;
  uint16_t dropped_ramps;
  bool sync_valid;
  int64_t sync_offset_ns;
  uint32_t sync_jitter_ns;
  uint32_t sync_round_trip_ns;
};

struct PointDataV1 {
  float range_m;
  float azimuth_rad;
  float elevation_rad;
  float doppler_mps;
  float snr;
  float calibrated_reflectance;
  uint32_t timestamp_nanosecs;
  uint16_t azimuth_idx;
  uint16_t elevation_idx;
  uint8_t drop_reason;
  uint8_t combine_method;
  uint8_t user_data[2];
};

struct VoyantVec3 {
  float x;
  float y;
  float z;
};

struct TimeSyncState {
  SyncQuality quality;
  uint8_t valid;
  int64_t offset_ns;
  int64_t round_trip_ns;
  int64_t jitter_ns;
  uint32_t sample_count;
  uint64_t age_ms;
};
 
extern "C" {

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);
 
}  // extern "C"