salmanoff/docs/livox-gen1-lidar-dap-spec.md

LivoxGen1Lidar Device Attachment Pipeline (DAP) Specification

Overview

The LivoxGen1Lidar DAP specification describes how to attach to Livox Gen1 LiDAR devices and access their various data streams. The Livox Gen1 LiDAR presents multiple stim features, each with its own dedicated stim-buff-api.

Stim-Buff-API Structure

The LivoxGen1Lidar DAP uses multiple stim-buff-api names, one for each stim feature it presents:

• livoxGen1-pcloud - Point cloud coordinate data
• livoxGen1-pcloudIntensity - Point cloud intensity/reflectivity data
• livoxGen1-gyro - Gyroscope data from internal IMU
• livoxGen1-accel - Accelerometer data from internal IMU

Each stim-buff-api is designed to work with specific stim-iface libraries that understand the data format and processing requirements for that particular stim feature.

DAP Specifications

1. Point Cloud Intensity Data Device (Interoceptor)

Purpose: Provides light intensity/reflectivity data from the LiDAR point cloud.

Syntax:

+idev | avia0 | pcloudIntensity | livoxGen1-pcloudIntensity(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Stim-Buff-API: livoxGen1-pcloudIntensity Quale-Iface-API: pcloudIntensity - Processes intensity/reflectivity data from point clouds

2. Point Cloud Ambience Data Device (Interoceptor)

Purpose: Provides ambience data from the LiDAR point cloud as a vector of per-dagram average intensities (one float per UDP datagram slot in the staging frame, length n-dgrams-per-frame). The OpenCL collate kernel writes these values directly into the acquired ambience StimulusFrame buffer.

Syntax:

+idev | avia0 | pcloudAmbience | livoxGen1-pcloud() | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Stim-Buff-API: livoxGen1-pcloud Quale-Iface-API: pcloudAmbience - Delivers per-dagram average intensity floats; postrin/negtrin binding and passband-style aggregation are being revised (see intrinsic parameters below).

Intrinsic Stimuli Support (for pcloudAmbience quale-iface-api): The pcloudAmbience quale-iface-api is intended to export both a postrin and a negtrin whose thresholds are configurable via standard quale-iface-api-params:

• Postrin interest threshold: Configurable via postrin-interest-[percentage|pc|threshold|thresh|thr]
• Negtrin interest threshold: Configurable via negtrin-interest-[percentage|pc|threshold|thresh|thr]

The -percentage and -pc variants take percentages in the range 0-100. The -threshold, -thresh, and -thr variants take an absolute number whose interpretation is defined by the API library itself. Users should specify only one unit-suffixed variant per targeted intrinsic threshold; if multiple such variants are supplied, the lattermost one takes precedence. Shorthand forms without a unit suffix are not valid.

3. Point Cloud Coordinate Data Device (Extrospector)

Purpose: Provides spatial coordinate data from the LiDAR point cloud.

Syntax:

+edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Example with n-dgrams-per-frame parameter:

+edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10,n-dgrams-per-frame=84) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Alternative Format Examples:

+edev | avia0 | pcloud(format=spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
+edev | avia0 | pcloud(format=spherical-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
+edev | avia0 | pcloud(format=dual-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
+edev | avia0 | pcloud(format=dual-spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Stim-Buff-API: livoxGen1-pcloud Quale-Iface-API: pcloud - Processes spatial coordinate data from point clouds

Format Parameter Values (for pcloud quale-iface-api):

• xyz: Standard Cartesian coordinates (X, Y, Z)
• spherical: Raw spherical coordinates
• spherical-cartesian: Spherical coordinates converted to Cartesian
• dual-cartesian: Dual Cartesian coordinate system
• dual-spherical: Dual spherical coordinate system

Alternative Format Parameter Names (synonymous):

• format or fmt

4. IMU Gyroscope Data Device (Interoceptor)

Purpose: Provides gyroscope data from the LiDAR's internal IMU.

Syntax:

+idev | avia0 | gyro | livoxGen1-gyro(data-rate-hz=100) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Stim-Buff-API: livoxGen1-gyro Quale-Iface-API: gyro - Processes gyroscope angular velocity data

5. IMU Accelerometer Data Device (Interoceptor)

Purpose: Provides accelerometer data from the LiDAR's internal IMU.

Syntax:

+idev | avia0 | accel | livoxGen1-accel(data-rate-hz=100) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Stim-Buff-API: livoxGen1-accel Quale-Iface-API: accel - Processes accelerometer linear acceleration data

Provider Parameters

livoxProto1 Provider

The livoxProto1 provider accepts the following parameters:

command-timeout-ms / cmd-timeout-ms (optional, synonyms):

• Specifies the timeout for command operations when communicating with devices
• Value: Integer number of milliseconds
• Example: command-timeout-ms=1000 or cmd-timeout-ms=1000 (1 second timeout)
• Default: 1000ms if not specified

retry-delay-ms (optional):

• Specifies how long to wait for broadcast messages to arrive after attempting an initial direct connection
• Value: Integer number of milliseconds
• Example: retry-delay-ms=3000 (wait 3 seconds)
• Default: 3000ms if not specified

subnet (optional):

• Specifies the IP subnet for device IP address calculation
• Value: IP address in the form X.X.0.0 where non-subnet bits must be 0
• Example: subnet=10.42.0.0 (use 10.42.x.x subnet)
• Default: 0.0.0.0 (use default 192.168.1.x subnet)

data-port (optional):

• Specifies the UDP port for receiving point cloud data from the device
• Value: Integer port number
• Example: data-port=56000
• Default: 56000 if not specified

cmd-port (optional):

• Specifies the UDP port for receiving command responses from the device
• Value: Integer port number
• Example: cmd-port=56001
• Default: 56001 if not specified

imu-port (optional):

• Specifies the UDP port for receiving IMU data from the device
• Value: Integer port number
• Example: imu-port=56002
• Default: 56002 if not specified

Parameter Summary

Stim-Buff-API Names

Stim Feature	Stim-Buff-API	Quale-Iface-API	Description
Point Cloud Intensity	livoxGen1-pcloudIntensity	pcloudIntensity	Light intensity/reflectivity data
Point Cloud Ambience	livoxGen1-pcloud	pcloudAmbience	Per-dagram average intensity vector (float × n-dgrams-per-frame)
Point Cloud Coordinates	livoxGen1-pcloud	pcloud	Spatial coordinate data
Gyroscope	livoxGen1-gyro	gyro	Angular velocity measurements
Accelerometer	livoxGen1-accel	accel	Linear acceleration measurements

Stim-Buff-API Parameters

Each stim-buff-api accepts device-specific parameters:

Parameter	Description	Default	Example
data-rate-hz	Data sampling rate in Hz	-	data-rate-hz=10
n-dgrams-per-frame / num-dgrams-per-frame	Number of UDP datagrams per staging buffer frame	84	n-dgrams-per-frame=84 or num-dgrams-per-frame=84

Quale-Iface-API Parameters

The pcloud quale-iface-api accepts format parameters:

Format	Description
xyz	Standard Cartesian coordinates (X, Y, Z)
spherical	Raw spherical coordinates (range, azimuth, elevation)
spherical-cartesian	Spherical coordinates converted to Cartesian
dual-cartesian	Dual Cartesian coordinate system
dual-spherical	Dual spherical coordinate system

Device Discovery and Connection

The specification uses a retry-based connection strategy with two different approaches:

Connection Methods

1. Broadcast-Based Connection (connectToKnownDeviceReq)

• Uses device IP addresses discovered from broadcast advertisements
• smo-ip parameter: Optional - if omitted, driver auto-detects the appropriate interface
• smo-subnet-nbits parameter: Optional - used for validation if smo-ip is provided
• When to use: When devices are actively broadcasting their presence

2. Heuristic Connection (connectByDeviceIdentifierReq)

• Generates device IP addresses from serial numbers using network prefix
• smo-ip parameter: Required - needed to determine network prefix for IP generation
• smo-subnet-nbits parameter: Required - needed to calculate valid device IP addresses
• When to use: When devices are not broadcasting or for initial setup

Connection Strategy

1. Initial Check: Check if device is already known from broadcasts
2. Direct Connect: Attempt direct connection based on calculated IP address
3. Retry Wait: If direct connect fails, wait for retry-delay-ms for broadcast messages
4. Final Check: Check known devices again after retry delay
5. Report Result: Success or failure based on final check

Data Formats

Point Cloud Coordinate Formats

1. XYZ Format: Standard 3D Cartesian coordinates

   • X, Y, Z in meters
   • Standard coordinate system orientation

2. Spherical Format: Raw spherical coordinates

   • Range (distance) in meters
   • Azimuth angle in degrees/radians
   • Elevation angle in degrees/radians

3. Spherical-Cartesian Format: Spherical coordinates converted to Cartesian

   • Range, azimuth, elevation converted to X, Y, Z
   • Maintains spherical measurement precision

4. Dual Formats: Support for dual-coordinate systems

   • Useful for devices with multiple measurement modes
   • Provides redundancy and validation capabilities

Intensity Data

• Reflectivity values typically in the range 0-255
• Normalized intensity measurements
• Calibrated for material reflectivity analysis

IMU Data

• Gyroscope: Angular velocity measurements (rad/s)
• Accelerometer: Linear acceleration measurements (m/s²)
• Timestamped data synchronized with point cloud measurements

Error Handling

The specification includes comprehensive error handling for:

• Network connectivity issues
• Device communication timeouts
• Invalid coordinate format requests
• IMU data stream interruptions
• Device discovery failures
• Connection retry timeouts