214 lines
7.7 KiB
Markdown
214 lines
7.7 KiB
Markdown
# LivoxGen1Lidar Device Attachment Pipeline (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 stim-buff-api with mode-based parameter selection.
|
|
|
|
## Stim-Buff-API Structure
|
|
|
|
The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-based parameters to specify which data interface to present.
|
|
|
|
## DAP Specifications
|
|
|
|
### 1. Point Cloud Intensity Data Device (Interoceptor)
|
|
|
|
**Purpose**: Provides light intensity/reflectivity data from the LiDAR point cloud.
|
|
|
|
**Syntax**:
|
|
```
|
|
+idev | avia0 | structural-stimiface | 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-stimiface | 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-stimiface | 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-stimiface | 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-stimiface | 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-stimiface | 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 |