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

LivoxGen1Lidar Device Attachment Protocol (DAP) Specification

Overview

The LivoxGen1Lidar DAP specification defines how to attach to Livox Gen1 LiDAR devices and access their various data streams using a unified API with mode-based parameter selection.

API Structure

The LivoxGen1Lidar DAP uses a unified API name livoxGen1 with mode-based parameters to specify which data interface to present.

Device Attachment Specifications

1. Point Cloud Intensity Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | structural-implexor | livoxGen1(mode=pointCloudIntensity) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Alternative Syntax (all equivalent):

+idev | avia0 | structural-implexor | livoxGen1(stim=pcloudIntensity) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
+idev | avia0 | structural-implexor | livoxGen1(affordance=pCloudI) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Mode Parameter Values (synonymous):

• pointCloudIntensity
• pcloudIntensity
• pCloudIntensity
• pCloudI
• pcloudI

2. Point Cloud Coordinate Data Device (Extrospector)

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

Syntax:

+edev | avia0 | structural-implexor | livoxGen1(mode=pcloud,format=xyz) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Mode Parameter Values (synonymous):

• pcloud
• pCloud
• pointCloud

Format Parameter (for point cloud modes):

• 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

3. IMU Gyroscope Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | gyro-implexor | livoxGen1(mode=gyro) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Mode Parameter Values:

• gyro

4. IMU Accelerometer Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | accel-implexor | livoxGen1(mode=accel) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39

Mode Parameter Values:

• accel

Provider Parameters

livoxProto1 Provider

The livoxProto1 provider accepts the following parameters:

handshake-timeout-ms (optional):

• Specifies the timeout for handshake operations when connecting to devices
• Value: Integer number of milliseconds
• Example: handshake-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

Mode/Stim/Affordance Parameter Values

Data Type	Mode Values	Description
Point Cloud Intensity	pointCloudIntensity, pcloudIntensity, pCloudIntensity, pCloudI, pcloudI	Light intensity/reflectivity data
Point Cloud Coordinates	pcloud, pCloud, pointCloud	Spatial coordinate data
Gyroscope	gyro	Angular velocity measurements
Accelerometer	accel	Linear acceleration measurements

Format Parameter Values (for point cloud modes)

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