diff --git a/docs/livox-gen1-lidar-dap-spec.md b/docs/livox-gen1-lidar-dap-spec.md index 10c7b8d..123c5fc 100644 --- a/docs/livox-gen1-lidar-dap-spec.md +++ b/docs/livox-gen1-lidar-dap-spec.md @@ -2,60 +2,59 @@ ## 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. +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. -## Data Stream Types +## API Structure -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. +The LivoxGen1Lidar DAP uses a unified API name `livoxGen1` with mode-based parameters to specify which data interface to present. ## 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) +### 1. Point Cloud 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 ++idev | avia0 | structural-implexor | livoxGen1(mode=pointCloudIntensity) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39 ``` -**Parameters**: -- No API parameters required -- Uses the same server parameters as the coordinate device +**Alternative Syntax** (all equivalent): +``` ++idev | avia0 | structural-implexor | livoxGen1(stim=pcloudIntensity) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39 ++idev | avia0 | structural-implexor | livoxGen1(affordance=pCloudI) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39 +``` -**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 +**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(retry-delay-ms=3000) | 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) @@ -63,12 +62,11 @@ Additionally, the specification supports access to the LiDAR device's internal I **Syntax**: ``` -+idev | avia0 | gyro-implexor | gyro() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier ++idev | avia0 | gyro-implexor | livoxGen1(mode=gyro) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39 ``` -**Parameters**: -- No API parameters required -- Uses the same provider parameters as other livoxProto1 devices +**Mode Parameter Values**: +- `gyro` ### 4. IMU Accelerometer Data Device (Interoceptor) @@ -76,30 +74,54 @@ Additionally, the specification supports access to the LiDAR device's internal I **Syntax**: ``` -+idev | avia0 | accel-implexor | accel() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier ++idev | avia0 | accel-implexor | livoxGen1(mode=accel) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39 ``` -**Parameters**: -- No API parameters required -- Uses the same provider parameters as other livoxProto1 devices +**Mode Parameter Values**: +- `accel` -## Network Protocol +## Provider Parameters -The LivoxGen1Lidar DAP uses UDP communication with the following characteristics: +### livoxProto1 Provider -- **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 +The `livoxProto1` provider accepts the following parameters: -## Device Discovery +**retry-delay-ms** (required): +- 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 -The specification supports automatic device discovery through UDP broadcast messages on the command port. Devices respond with their identification information including: +## Parameter Summary -- Device serial number -- IP address -- Available data ports -- Supported coordinate formats +### 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: + +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 @@ -109,15 +131,15 @@ The specification supports automatic device discovery through UDP broadcast mess - 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 +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 @@ -134,14 +156,6 @@ The specification supports automatic device discovery through UDP broadcast mess - **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: @@ -151,10 +165,4 @@ The specification includes comprehensive error handling for: - 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 +- Connection retry timeouts \ No newline at end of file