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

# LivoxGen1Lidar Device Attachment Protocol (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 API with mode-based parameter selection.

## API Structure

The LivoxGen1Lidar DAP uses a unified API name `livoxGen1` with mode-based parameters to specify which data interface to present.

## Device Attachment Specifications

### 1. Point Cloud Intensity Data Device (Interoceptor)

**Purpose**: Provides light intensity/reflectivity data from the LiDAR point cloud.

**Syntax**:
```
+idev | avia0 | structural-implexor | livoxGen1(mode=pointCloudIntensity) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39
```

**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
```

**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)

**Purpose**: Provides gyroscope data from the LiDAR's internal IMU.

**Syntax**:
```
+idev | avia0 | gyro-implexor | livoxGen1(mode=gyro) | livoxProto1(retry-delay-ms=3000) | 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-implexor | livoxGen1(mode=accel) | livoxProto1(retry-delay-ms=3000) | 3JEDK380010Z39
```

**Mode Parameter Values**:
- `accel`

## Provider Parameters

### livoxProto1 Provider

The `livoxProto1` provider accepts the following parameters:

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

**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:

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