hayodea
632a227985
We no longer do intrin specs as a separate stimbuff; rather now we do them as a specifier segment within the pipeline spec of a normal nontrin spec.
256 lines
11 KiB
Markdown
256 lines
11 KiB
Markdown
# LivoxGen1Lidar Device Attachment Pipeline (DAP) Specification
|
||
|
||
## Overview
|
||
|
||
The LivoxGen1Lidar DAP specification describes how to attach to Livox Gen1
|
||
LiDAR devices and access their various data streams. The Livox Gen1 LiDAR
|
||
presents multiple stim features, each with its own dedicated stim-buff-api.
|
||
|
||
## Stim-Buff-API Structure
|
||
|
||
The LivoxGen1Lidar DAP uses multiple stim-buff-api names, one for each stim feature it presents:
|
||
|
||
* `livoxGen1-pcloud` - Point cloud coordinate data
|
||
* `livoxGen1-pcloudIntensity` - Point cloud intensity/reflectivity data
|
||
* `livoxGen1-gyro` - Gyroscope data from internal IMU
|
||
* `livoxGen1-accel` - Accelerometer data from internal IMU
|
||
|
||
Each stim-buff-api is designed to work with specific stim-iface libraries that understand the data format and processing requirements for that particular stim feature.
|
||
|
||
## DAP Specifications
|
||
|
||
### 1. Point Cloud Intensity Data Device (Interoceptor)
|
||
|
||
**Purpose**: Provides light intensity/reflectivity data from the LiDAR point cloud.
|
||
|
||
**Syntax**:
|
||
```
|
||
+idev | avia0 | pcloudIntensity | livoxGen1-pcloudIntensity(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Stim-Buff-API**: `livoxGen1-pcloudIntensity`
|
||
**Quale-Iface-API**: `pcloudIntensity` - Processes intensity/reflectivity data from point clouds
|
||
|
||
### 2. Point Cloud Ambience Data Device (Interoceptor)
|
||
|
||
**Purpose**: Provides ambience data from the LiDAR point cloud as a **vector of per-dagram average intensities** (one `float` per UDP datagram slot in the staging frame, length `n-dgrams-per-frame`). The OpenCL collate kernel writes these values directly into the acquired ambience `StimulusFrame` buffer.
|
||
|
||
**Syntax**:
|
||
```
|
||
+idev | avia0 | pcloudAmbience | livoxGen1-pcloud() | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Stim-Buff-API**: `livoxGen1-pcloud`
|
||
**Quale-Iface-API**: `pcloudAmbience` - Delivers per-dagram average intensity floats (sensory stream only).
|
||
|
||
Passband comparators (`passband-count-lt-val`, `passband-count-gt-val`) belong on
|
||
`pcloudAmbience(...)` itself, and both may appear together — `lt` drives the
|
||
postrin path, `gt` drives the negtrin path. Intrinsic threshold params
|
||
(`interest-*`, `distraction-*`, `stupefaction-*`/`stupefying-*`, `intolerable-*`)
|
||
live inside `postrin(...)` / `negtrin(...)` segments attached to the same DAP
|
||
line. See `docs/design/intrin-thresholds.md`.
|
||
|
||
### 3. Point Cloud Coordinate Data Device (Extrospector)
|
||
|
||
**Purpose**: Provides spatial coordinate data from the LiDAR point cloud.
|
||
|
||
**Syntax**:
|
||
```
|
||
+edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Example with n-dgrams-per-frame parameter**:
|
||
```
|
||
+edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10,n-dgrams-per-frame=84) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Alternative Format Examples**:
|
||
```
|
||
+edev | avia0 | pcloud(format=spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
+edev | avia0 | pcloud(format=spherical-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
+edev | avia0 | pcloud(format=dual-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
+edev | avia0 | pcloud(format=dual-spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Stim-Buff-API**: `livoxGen1-pcloud`
|
||
**Quale-Iface-API**: `pcloud` - Processes spatial coordinate data from point clouds
|
||
|
||
**Format Parameter Values** (for pcloud quale-iface-api):
|
||
- `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`
|
||
|
||
### 4. IMU Gyroscope Data Device (Interoceptor)
|
||
|
||
**Purpose**: Provides gyroscope data from the LiDAR's internal IMU.
|
||
|
||
**Syntax**:
|
||
```
|
||
+idev | avia0 | gyro | livoxGen1-gyro(data-rate-hz=100) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Stim-Buff-API**: `livoxGen1-gyro`
|
||
**Quale-Iface-API**: `gyro` - Processes gyroscope angular velocity data
|
||
|
||
### 5. IMU Accelerometer Data Device (Interoceptor)
|
||
|
||
**Purpose**: Provides accelerometer data from the LiDAR's internal IMU.
|
||
|
||
**Syntax**:
|
||
```
|
||
+idev | avia0 | accel | livoxGen1-accel(data-rate-hz=100) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
|
||
```
|
||
|
||
**Stim-Buff-API**: `livoxGen1-accel`
|
||
**Quale-Iface-API**: `accel` - Processes accelerometer linear acceleration data
|
||
|
||
## Provider Parameters
|
||
|
||
### livoxProto1 Provider
|
||
|
||
The `livoxProto1` provider accepts the following parameters:
|
||
|
||
**command-timeout-ms** / **cmd-timeout-ms** (optional, synonyms):
|
||
- Specifies the timeout for command operations when communicating with devices
|
||
- Value: Integer number of milliseconds
|
||
- Example: `command-timeout-ms=1000` or `cmd-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
|
||
|
||
### Stim-Buff-API Names
|
||
|
||
| Stim Feature | Stim-Buff-API | Quale-Iface-API | Description |
|
||
|--------------|---------------|----------------|-------------|
|
||
| Point Cloud Intensity | `livoxGen1-pcloudIntensity` | `pcloudIntensity` | Light intensity/reflectivity data |
|
||
| Point Cloud Ambience | `livoxGen1-pcloud` | `pcloudAmbience` | Per-dagram average intensity vector (`float` × `n-dgrams-per-frame`). Accepts `postrin(...)` / `negtrin(...)` segments on the same DAP line for intrin thresholds; see `docs/design/intrin-thresholds.md`. |
|
||
| Point Cloud Coordinates | `livoxGen1-pcloud` | `pcloud` | Spatial coordinate data |
|
||
| Gyroscope | `livoxGen1-gyro` | `gyro` | Angular velocity measurements |
|
||
| Accelerometer | `livoxGen1-accel` | `accel` | Linear acceleration measurements |
|
||
|
||
### Stim-Buff-API Parameters
|
||
|
||
Each stim-buff-api accepts device-specific parameters:
|
||
|
||
| Parameter | Description | Default | Example |
|
||
|-----------|-------------|---------|---------|
|
||
| `data-rate-hz` | Data sampling rate in Hz | - | `data-rate-hz=10` |
|
||
| `n-dgrams-per-frame` / `num-dgrams-per-frame` | Number of UDP datagrams per staging buffer frame | 84 | `n-dgrams-per-frame=84` or `num-dgrams-per-frame=84` |
|
||
|
||
### Quale-Iface-API Parameters
|
||
|
||
The `pcloud` quale-iface-api accepts format parameters:
|
||
|
||
| 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
|