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. This specification handles device attachment for 2 kinds of interoceptor devices and 1 kind of extrospector device by logically splitting the point cloud data received from the LiDAR into different data types.

Data Stream Types

The LivoxGen1Lidar DAP spec logically splits point cloud data into two categories:

1. Coordinate Data (Extrospective) - Spatial position information
2. Reflectivity Data (Interoceptive) - Light intensity/reflectivity information

Additionally, the specification supports access to the LiDAR device's internal IMU data when specified in the device attachment specification.

Device Attachment Specifications

1. Coordinate Data Device (Extrospector)

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

Syntax:

+edev | avia0 | structural-implexor | pointCloudCoords(format=xyz) | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | 3JEDK380010Z39

Parameters:

• format: Specifies the coordinate format for the point cloud data
  • xyz: Standard Cartesian coordinates (X, Y, Z)
  • spherical-cartesian or spherical-xyz: Spherical coordinates converted to Cartesian (these are equivalent)
  • spherical: Raw spherical coordinates
  • dual-cartesian: Dual Cartesian coordinate system
  • dual-spherical: Dual spherical coordinate system

Network Configuration:

• command-port: UDP port for sending commands to the device (default: 5683)
• data-port: UDP port for receiving point cloud data (default: 5684)
• imu-data-port: UDP port for receiving IMU data (default: 5685)

Device Identifier: 3JEDK380010Z39 (example device serial number)

2. Intensity Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | structural-implexor | pointCloudIntensity() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier

Parameters:

• No API parameters required
• Uses the same server parameters as the coordinate device

Network Configuration: Same as coordinate device

• command-port: UDP port for sending commands to the device
• data-port: UDP port for receiving point cloud data
• imu-data-port: UDP port for receiving IMU data

3. IMU Gyroscope Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | gyro-implexor | gyro() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier

Parameters:

• No API parameters required
• Uses the same provider parameters as other livoxProto1 devices

4. IMU Accelerometer Data Device (Interoceptor)

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

Syntax:

+idev | avia0 | accel-implexor | accel() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier

Parameters:

• No API parameters required
• Uses the same provider parameters as other livoxProto1 devices

Network Protocol

The LivoxGen1Lidar DAP uses UDP communication with the following characteristics:

• Command Channel: Bidirectional UDP communication for device control
• Data Channel: Unidirectional UDP stream for point cloud data
• IMU Channel: Unidirectional UDP stream for IMU sensor data
• Broadcast Support: Commands can be broadcast to discover and control multiple devices

Device Discovery

The specification supports automatic device discovery through UDP broadcast messages on the command port. Devices respond with their identification information including:

• Device serial number
• IP address
• Available data ports
• Supported coordinate formats

Data Formats

Point Cloud Coordinate Formats

1. XYZ Format: Standard 3D Cartesian coordinates

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

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

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

3. Spherical Format: Raw spherical coordinates

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

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

Implementation Notes

• All network communication is asynchronous using the provided io_service
• Device connections are managed with reference counting for shared access
• Automatic reconnection handling for network interruptions
• Thread-safe operations for concurrent data access
• Support for multiple simultaneous device connections

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

Security Considerations

• UDP communication is inherently unencrypted
• Device identification relies on network-level security
• Command authentication may be required for production deployments
• Consider network segmentation for sensitive applications