Docs: update DAP specs for livoxGen1 devices
This commit is contained in:
@@ -2,60 +2,59 @@
|
|||||||
|
|
||||||
## Overview
|
## 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:
|
The LivoxGen1Lidar DAP uses a unified API name `livoxGen1` with mode-based parameters to specify which data interface to present.
|
||||||
|
|
||||||
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
|
## Device Attachment Specifications
|
||||||
|
|
||||||
### 1. Coordinate Data Device (Extrospector)
|
### 1. Point Cloud Intensity Data Device (Interoceptor)
|
||||||
|
|
||||||
**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.
|
**Purpose**: Provides light intensity/reflectivity data from the LiDAR point cloud.
|
||||||
|
|
||||||
**Syntax**:
|
**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**:
|
**Alternative Syntax** (all equivalent):
|
||||||
- No API parameters required
|
```
|
||||||
- Uses the same server parameters as the coordinate device
|
+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
|
**Mode Parameter Values** (synonymous):
|
||||||
- `command-port`: UDP port for sending commands to the device
|
- `pointCloudIntensity`
|
||||||
- `data-port`: UDP port for receiving point cloud data
|
- `pcloudIntensity`
|
||||||
- `imu-data-port`: UDP port for receiving IMU data
|
- `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)
|
### 3. IMU Gyroscope Data Device (Interoceptor)
|
||||||
|
|
||||||
@@ -63,12 +62,11 @@ Additionally, the specification supports access to the LiDAR device's internal I
|
|||||||
|
|
||||||
**Syntax**:
|
**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**:
|
**Mode Parameter Values**:
|
||||||
- No API parameters required
|
- `gyro`
|
||||||
- Uses the same provider parameters as other livoxProto1 devices
|
|
||||||
|
|
||||||
### 4. IMU Accelerometer Data Device (Interoceptor)
|
### 4. IMU Accelerometer Data Device (Interoceptor)
|
||||||
|
|
||||||
@@ -76,30 +74,54 @@ Additionally, the specification supports access to the LiDAR device's internal I
|
|||||||
|
|
||||||
**Syntax**:
|
**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**:
|
**Mode Parameter Values**:
|
||||||
- No API parameters required
|
- `accel`
|
||||||
- Uses the same provider parameters as other livoxProto1 devices
|
|
||||||
|
|
||||||
## Network Protocol
|
## Provider Parameters
|
||||||
|
|
||||||
The LivoxGen1Lidar DAP uses UDP communication with the following characteristics:
|
### livoxProto1 Provider
|
||||||
|
|
||||||
- **Command Channel**: Bidirectional UDP communication for device control
|
The `livoxProto1` provider accepts the following parameters:
|
||||||
- **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
|
**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
|
### Mode/Stim/Affordance Parameter Values
|
||||||
- IP address
|
|
||||||
- Available data ports
|
| Data Type | Mode Values | Description |
|
||||||
- Supported coordinate formats
|
|-----------|-------------|-------------|
|
||||||
|
| 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
|
## Data Formats
|
||||||
|
|
||||||
@@ -109,15 +131,15 @@ The specification supports automatic device discovery through UDP broadcast mess
|
|||||||
- X, Y, Z in meters
|
- X, Y, Z in meters
|
||||||
- Standard coordinate system orientation
|
- Standard coordinate system orientation
|
||||||
|
|
||||||
2. **Spherical-Cartesian Format**: Spherical coordinates converted to Cartesian
|
2. **Spherical Format**: Raw spherical coordinates
|
||||||
- Range, azimuth, elevation converted to X, Y, Z
|
|
||||||
- Maintains spherical measurement precision
|
|
||||||
|
|
||||||
3. **Spherical Format**: Raw spherical coordinates
|
|
||||||
- Range (distance) in meters
|
- Range (distance) in meters
|
||||||
- Azimuth angle in degrees/radians
|
- Azimuth angle in degrees/radians
|
||||||
- Elevation 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
|
4. **Dual Formats**: Support for dual-coordinate systems
|
||||||
- Useful for devices with multiple measurement modes
|
- Useful for devices with multiple measurement modes
|
||||||
- Provides redundancy and validation capabilities
|
- 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²)
|
- **Accelerometer**: Linear acceleration measurements (m/s²)
|
||||||
- Timestamped data synchronized with point cloud measurements
|
- 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
|
## Error Handling
|
||||||
|
|
||||||
The specification includes comprehensive error handling for:
|
The specification includes comprehensive error handling for:
|
||||||
@@ -151,10 +165,4 @@ The specification includes comprehensive error handling for:
|
|||||||
- Invalid coordinate format requests
|
- Invalid coordinate format requests
|
||||||
- IMU data stream interruptions
|
- IMU data stream interruptions
|
||||||
- Device discovery failures
|
- Device discovery failures
|
||||||
|
- Connection retry timeouts
|
||||||
## 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
|
|
||||||
Reference in New Issue
Block a user