DAP Specs: Add specs for LivoxGen1 devices

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

@@ -0,0 +1,160 @@
+# 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