From 4ce4c9f9f896279856f4bbfc8ef21f1637a390cb Mon Sep 17 00:00:00 2001 From: Hayodea Hakol Date: Thu, 4 Sep 2025 15:57:42 -0400 Subject: [PATCH] DAP Specs: Add specs for LivoxGen1 devices --- docs/livox-gen1-lidar-dap-spec.md | 160 ++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/livox-gen1-lidar-dap-spec.md diff --git a/docs/livox-gen1-lidar-dap-spec.md b/docs/livox-gen1-lidar-dap-spec.md new file mode 100644 index 0000000..10c7b8d --- /dev/null +++ b/docs/livox-gen1-lidar-dap-spec.md @@ -0,0 +1,160 @@ +# 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