salmanoff/docs/livox-gen1-lidar-dap-spec.md

# 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, counting high-intensity points per slot.

**Syntax**:
```
+idev | avia0 | pcloudAmbience | livoxGen1-pcloud(high-val=120) | 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` - Counts points with intensity >= threshold per slot

**Ambience High Value Parameter** (for pcloudAmbience quale-iface-api):
- **Parameter names**: `high-value` or `high-val` (synonyms)
- **Purpose**: Threshold value for counting high-intensity points in the ambience buffer
- **Default value**: 116
- **Usage**: Points with intensity >= `ambienceHighVal` are counted in the ambience buffer per slot
- **Configuration**: Specified in `stim-buff-api-params` when using `pcloudAmbience` quale interface
- **Example**: `high-val=120` or `high-value=120`

### 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` | High-intensity point count per slot |
| 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` |
| `high-value` / `high-val` | Threshold for counting high-intensity points in ambience buffer (for `pcloudAmbience` quale-iface-api) | 116 | `high-val=120` or `high-value=120` |

### 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 |

The `pcloudAmbience` quale-iface-api uses the `high-value` / `high-val` parameter (documented in Stim-Buff-API Parameters above) to determine the intensity threshold for counting high-intensity points per slot.

## 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