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

## Data Stream Types

The LivoxGen1Lidar DAP spec logically splits point cloud data into two categories:

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

### 1. Coordinate Data Device (Extrospector)

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

**Syntax**:
```
+idev | avia0 | structural-implexor | pointCloudIntensity() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier
```

**Parameters**:
- No API parameters required
- Uses the same server parameters as the coordinate device

**Network Configuration**: Same as coordinate device
- `command-port`: UDP port for sending commands to the device
- `data-port`: UDP port for receiving point cloud data  
- `imu-data-port`: UDP port for receiving IMU data

### 3. IMU Gyroscope Data Device (Interoceptor)

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

**Syntax**:
```
+idev | avia0 | gyro-implexor | gyro() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier
```

**Parameters**:
- No API parameters required
- Uses the same provider parameters as other livoxProto1 devices

### 4. IMU Accelerometer Data Device (Interoceptor)

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

**Syntax**:
```
+idev | avia0 | accel-implexor | accel() | livoxProto1(command-port=5683|data-port=5684|imu-data-port=5685) | dev-identifier
```

**Parameters**:
- No API parameters required
- Uses the same provider parameters as other livoxProto1 devices

## Network Protocol

The LivoxGen1Lidar DAP uses UDP communication with the following characteristics:

- **Command Channel**: Bidirectional UDP communication for device control
- **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

The specification supports automatic device discovery through UDP broadcast messages on the command port. Devices respond with their identification information including:

- Device serial number
- IP address
- Available data ports
- Supported coordinate formats

## Data Formats

### Point Cloud Coordinate Formats

1. **XYZ Format**: Standard 3D Cartesian coordinates
   - X, Y, Z in meters
   - Standard coordinate system orientation

2. **Spherical-Cartesian Format**: Spherical coordinates converted to Cartesian
   - Range, azimuth, elevation converted to X, Y, Z
   - Maintains spherical measurement precision

3. **Spherical Format**: Raw spherical coordinates
   - Range (distance) in meters
   - Azimuth angle in degrees/radians
   - Elevation angle in degrees/radians

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

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

The specification includes comprehensive error handling for:

- Network connectivity issues
- Device communication timeouts
- Invalid coordinate format requests
- IMU data stream interruptions
- Device discovery failures

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