docs: enhance hardware protocol documentation and reorganize project docs
- Complete hardware communication protocol documentation with: * Add ping/pong health check protocol (0x01) * Add hardware control protocols (0x03 brightness, 0x04 volume) * Add mDNS service discovery specifications * Add connection state management and retry logic * Add comprehensive troubleshooting guide * Update hardware implementation examples - Reorganize project documentation: * Move device auto-refresh docs from root to docs/ directory * Rename files to follow kebab-case convention * Maintain complete technical implementation details - Fix markdown formatting issues: * Add proper language tags to code blocks * Ensure consistent documentation structure
This commit is contained in:
@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
UDP-based protocol for sending LED color data from desktop application to ambient light hardware boards. The hardware acts as a simple UDP-to-WS2812 bridge, directly forwarding color data without any processing or LED type distinction.
|
||||
UDP-based bidirectional protocol for communication between desktop application and ambient light hardware boards. The protocol supports LED color data transmission, device health monitoring, and remote control capabilities.
|
||||
|
||||
## Connection
|
||||
|
||||
@ -11,12 +11,61 @@ UDP-based protocol for sending LED color data from desktop application to ambien
|
||||
- **Discovery**: mDNS (`_ambient_light._udp.local.`)
|
||||
- **Example Board**: `192.168.31.206:23042`
|
||||
|
||||
## Packet Format
|
||||
## mDNS Service Discovery
|
||||
|
||||
### Service Registration (Hardware Side)
|
||||
|
||||
Hardware boards must register the following mDNS service:
|
||||
|
||||
- **Service Type**: `_ambient_light._udp.local.`
|
||||
- **Port**: 23042
|
||||
- **TXT Records**: Optional, can include device information
|
||||
|
||||
### Service Discovery (Desktop Side)
|
||||
|
||||
Desktop application continuously browses for `_ambient_light._udp.local.` services and automatically connects to discovered devices.
|
||||
|
||||
## Protocol Messages
|
||||
|
||||
The protocol uses different message headers to distinguish message types:
|
||||
|
||||
| Header | Direction | Purpose | Format |
|
||||
|--------|-----------|---------|---------|
|
||||
| 0x01 | Desktop → Hardware | Ping (Health Check) | `[0x01]` |
|
||||
| 0x01 | Hardware → Desktop | Pong (Health Response) | `[0x01]` |
|
||||
| 0x02 | Desktop → Hardware | LED Color Data | `[0x02][Offset_H][Offset_L][Color_Data...]` |
|
||||
| 0x03 | Hardware → Desktop | Display Brightness Control | `[0x03][Display_Index][Brightness]` |
|
||||
| 0x04 | Hardware → Desktop | Volume Control | `[0x04][Volume_Percent]` |
|
||||
|
||||
## Health Check Protocol (Ping/Pong)
|
||||
|
||||
### Desktop → Hardware (Ping)
|
||||
|
||||
```text
|
||||
Byte 0: Header (0x01)
|
||||
```
|
||||
|
||||
### Hardware → Desktop (Pong)
|
||||
|
||||
```text
|
||||
Byte 0: Header (0x01)
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
|
||||
- Desktop sends ping every 1 second to each connected device
|
||||
- Hardware must respond with pong within 1 second
|
||||
- Timeout or incorrect response triggers reconnection logic
|
||||
- After 10 failed attempts, device is marked as disconnected
|
||||
|
||||
## LED Color Data Protocol
|
||||
|
||||
### Packet Format
|
||||
|
||||
```text
|
||||
Byte 0: Header (0x02)
|
||||
Byte 1: Offset High (upper 8 bits of LED start position)
|
||||
Byte 2: Offset Low (lower 8 bits of LED start position)
|
||||
Byte 2: Offset Low (lower 8 bits of LED start position)
|
||||
Byte 3+: LED Color Data (variable length)
|
||||
```
|
||||
|
||||
@ -24,13 +73,13 @@ Byte 3+: LED Color Data (variable length)
|
||||
|
||||
### RGB LEDs (3 bytes per LED)
|
||||
|
||||
```
|
||||
```text
|
||||
[R][G][B][R][G][B][R][G][B]...
|
||||
```
|
||||
|
||||
### RGBW LEDs (4 bytes per LED)
|
||||
|
||||
```
|
||||
```text
|
||||
[R][G][B][W][R][G][B][W][R][G][B][W]...
|
||||
```
|
||||
|
||||
@ -57,13 +106,78 @@ calibrated_b = (original_b * calibration_b) / 255
|
||||
calibrated_w = calibration_w // Direct value
|
||||
```
|
||||
|
||||
## Hardware Control Protocol (Hardware → Desktop)
|
||||
|
||||
### Display Brightness Control
|
||||
|
||||
Hardware can send display brightness adjustment commands to the desktop:
|
||||
|
||||
```text
|
||||
Byte 0: Header (0x03)
|
||||
Byte 1: Display Index (0-based display number)
|
||||
Byte 2: Brightness (0-255, where 255 = 100% brightness)
|
||||
```
|
||||
|
||||
**Example:** Set display 0 to 50% brightness
|
||||
|
||||
```text
|
||||
03 00 80
|
||||
│ │ └─ Brightness (128 = ~50%)
|
||||
│ └─ Display Index (0)
|
||||
└─ Header (0x03)
|
||||
```
|
||||
|
||||
### Volume Control
|
||||
|
||||
Hardware can send system volume adjustment commands to the desktop:
|
||||
|
||||
```text
|
||||
Byte 0: Header (0x04)
|
||||
Byte 1: Volume Percent (0-100)
|
||||
```
|
||||
|
||||
**Example:** Set system volume to 75%
|
||||
|
||||
```text
|
||||
04 4B
|
||||
│ └─ Volume (75%)
|
||||
└─ Header (0x04)
|
||||
```
|
||||
|
||||
## Connection State Management
|
||||
|
||||
### Connection States
|
||||
|
||||
- **Unknown**: Initial state when device is first discovered
|
||||
- **Connecting**: Device is being tested, includes retry count (1-10)
|
||||
- **Connected**: Device is responding to ping requests normally
|
||||
- **Disconnected**: Device failed to respond after 10 retry attempts
|
||||
|
||||
### State Transitions
|
||||
|
||||
```text
|
||||
Unknown → Connecting(1) → Connected
|
||||
↓ ↓ ↓
|
||||
↓ Connecting(2-10) ↓
|
||||
↓ ↓ ↓
|
||||
└─→ Disconnected ←────────┘
|
||||
```
|
||||
|
||||
### Retry Logic
|
||||
|
||||
1. **Initial Connection**: When device discovered via mDNS
|
||||
2. **Health Check Failure**: If ping timeout or wrong response
|
||||
3. **Retry Attempts**: Up to 10 attempts with 1-second intervals
|
||||
4. **Disconnection**: After 10 failed attempts, mark as disconnected
|
||||
5. **Recovery**: Disconnected devices continue to receive ping attempts
|
||||
|
||||
## Packet Examples
|
||||
|
||||
### RGB Example
|
||||
|
||||
3 RGB LEDs starting at position 0: Red, Green, Blue
|
||||
|
||||
```
|
||||
```text
|
||||
02 00 00 FF 00 00 00 FF 00 00 00 FF
|
||||
│ │ │ └─────────────────────────── 9 bytes color data
|
||||
│ │ └─ Offset Low (0)
|
||||
@ -71,11 +185,11 @@ calibrated_w = calibration_w // Direct value
|
||||
└─ Header (0x02)
|
||||
```
|
||||
|
||||
### RGBW Example
|
||||
### RGBW Example
|
||||
|
||||
2 RGBW LEDs starting at position 10: White, Warm White
|
||||
|
||||
```
|
||||
```text
|
||||
02 00 0A FF FF FF FF FF C8 96 C8
|
||||
│ │ │ └─────────────────────── 8 bytes color data
|
||||
│ │ └─ Offset Low (10)
|
||||
@ -94,20 +208,48 @@ calibrated_w = calibration_w // Direct value
|
||||
|
||||
## Hardware Implementation
|
||||
|
||||
The hardware board acts as a simple UDP-to-WS2812 bridge, directly forwarding color data to the LED strips without any processing or type distinction.
|
||||
The hardware board handles multiple protocol functions: UDP-to-WS2812 bridge for LED data, health monitoring, and optional control input capabilities.
|
||||
|
||||
### Packet Processing
|
||||
### Required Functions
|
||||
|
||||
1. **Validation**: Check minimum 3 bytes and header (0x02)
|
||||
2. **Extract Offset**: Parse 16-bit LED start position
|
||||
3. **Forward Data**: Send color data directly to WS2812 controller
|
||||
4. **No Type Logic**: Hardware doesn't distinguish RGB/RGBW - just forwards bytes
|
||||
1. **mDNS Service Registration**: Advertise `_ambient_light._udp.local.` service
|
||||
2. **UDP Server**: Listen on port 23042 for incoming packets
|
||||
3. **Packet Processing**: Handle different message types based on header
|
||||
4. **Health Monitoring**: Respond to ping requests with pong
|
||||
5. **LED Control**: Forward color data to WS2812 strips
|
||||
6. **Optional Control**: Send brightness/volume commands to desktop
|
||||
|
||||
### Example C Code
|
||||
### Packet Processing Logic
|
||||
|
||||
```c
|
||||
void process_packet(uint8_t* data, size_t len) {
|
||||
if (len < 3 || data[0] != 0x02) return;
|
||||
if (len < 1) return;
|
||||
|
||||
switch (data[0]) {
|
||||
case 0x01: // Ping request
|
||||
handle_ping(data, len);
|
||||
break;
|
||||
|
||||
case 0x02: // LED color data
|
||||
handle_led_data(data, len);
|
||||
break;
|
||||
|
||||
default:
|
||||
// Unknown packet type, ignore
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
void handle_ping(uint8_t* data, size_t len) {
|
||||
if (len != 1) return;
|
||||
|
||||
// Respond with pong
|
||||
uint8_t pong = 0x01;
|
||||
udp_send_response(&pong, 1);
|
||||
}
|
||||
|
||||
void handle_led_data(uint8_t* data, size_t len) {
|
||||
if (len < 3) return;
|
||||
|
||||
uint16_t offset = (data[1] << 8) | data[2];
|
||||
uint8_t* color_data = &data[3];
|
||||
@ -118,23 +260,119 @@ void process_packet(uint8_t* data, size_t len) {
|
||||
}
|
||||
```
|
||||
|
||||
### Key Simplifications
|
||||
### Optional Control Features
|
||||
|
||||
- **No LED Type Detection**: Hardware doesn't need to know RGB vs RGBW
|
||||
- **Direct Data Forward**: Color bytes sent as-is to WS2812 controller
|
||||
- **Desktop Handles Logic**: All RGB/RGBW processing done on desktop side
|
||||
- **Simple Bridge**: Hardware is just a UDP-to-WS2812 data bridge
|
||||
Hardware can optionally send control commands to desktop:
|
||||
|
||||
```c
|
||||
// Send display brightness control
|
||||
void send_brightness_control(uint8_t display_index, uint8_t brightness) {
|
||||
uint8_t packet[3] = {0x03, display_index, brightness};
|
||||
udp_send_to_desktop(packet, 3);
|
||||
}
|
||||
|
||||
// Send volume control
|
||||
void send_volume_control(uint8_t volume_percent) {
|
||||
uint8_t packet[2] = {0x04, volume_percent};
|
||||
udp_send_to_desktop(packet, 2);
|
||||
}
|
||||
```
|
||||
|
||||
### Key Implementation Notes
|
||||
|
||||
- **Ping Response**: Must respond to ping (0x01) within 1 second
|
||||
- **LED Data**: Direct forward to WS2812, no processing required
|
||||
- **Control Commands**: Optional feature for hardware with input capabilities
|
||||
- **mDNS Registration**: Essential for automatic device discovery
|
||||
- **UDP Server**: Must handle concurrent connections from multiple desktops
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**No Updates**: Check network connectivity, mDNS discovery, port 23042
|
||||
**Wrong Colors**: Verify calibration settings on desktop application
|
||||
**Flickering**: Monitor packet rate, network congestion, power supply
|
||||
**Partial Updates**: Check strip configuration, offset calculations
|
||||
**Hardware Issues**: Verify WS2812 wiring, power supply, data signal integrity
|
||||
### Device Discovery Issues
|
||||
|
||||
**Device Not Found**:
|
||||
|
||||
- Verify mDNS service registration on hardware
|
||||
- Check service type: `_ambient_light._udp.local.`
|
||||
- Ensure port 23042 is accessible
|
||||
- Verify network connectivity between desktop and hardware
|
||||
|
||||
**Device Shows as Disconnected**:
|
||||
|
||||
- Check ping/pong response implementation
|
||||
- Verify hardware responds to 0x01 packets within 1 second
|
||||
- Monitor network latency and packet loss
|
||||
- Check UDP server implementation on hardware
|
||||
|
||||
### LED Control Issues
|
||||
|
||||
**No LED Updates**:
|
||||
|
||||
- Verify hardware processes 0x02 packets correctly
|
||||
- Check WS2812 wiring and power supply
|
||||
- Monitor packet reception on hardware side
|
||||
- Verify offset calculations and LED strip configuration
|
||||
|
||||
**Wrong Colors**:
|
||||
|
||||
- Check color calibration settings on desktop
|
||||
- Verify RGB/RGBW data format matches LED strip type
|
||||
- Monitor color data in packets (bytes 3+)
|
||||
- Check WS2812 color order (GRB vs RGB)
|
||||
|
||||
**Flickering or Lag**:
|
||||
|
||||
- Monitor packet rate and network congestion
|
||||
- Check power supply stability for LED strips
|
||||
- Verify WS2812 data signal integrity
|
||||
- Consider reducing update frequency
|
||||
|
||||
### Control Protocol Issues
|
||||
|
||||
**Brightness/Volume Control Not Working**:
|
||||
|
||||
- Verify hardware sends correct packet format (0x03/0x04)
|
||||
- Check desktop receives and processes control packets
|
||||
- Monitor packet transmission from hardware
|
||||
- Verify display index and value ranges
|
||||
|
||||
### Connection State Issues
|
||||
|
||||
**Frequent Disconnections**:
|
||||
|
||||
- Check network stability and latency
|
||||
- Verify ping response timing (< 1 second)
|
||||
- Monitor retry logic and connection state transitions
|
||||
- Check for UDP packet loss
|
||||
|
||||
**Stuck in Connecting State**:
|
||||
|
||||
- Verify ping/pong packet format
|
||||
- Check hardware UDP server implementation
|
||||
- Monitor ping response timing
|
||||
- Verify network firewall settings
|
||||
|
||||
### Network Debugging
|
||||
|
||||
**Packet Monitoring**:
|
||||
|
||||
```bash
|
||||
# Monitor UDP traffic on port 23042
|
||||
tcpdump -i any -X port 23042
|
||||
|
||||
# Check mDNS service discovery
|
||||
dns-sd -B _ambient_light._udp.local.
|
||||
```
|
||||
|
||||
**Hardware Debug Output**:
|
||||
|
||||
- Log received packet headers and lengths
|
||||
- Monitor ping/pong timing
|
||||
- Track LED data processing
|
||||
- Log mDNS service registration status
|
||||
|
||||
## Protocol Version
|
||||
|
||||
- **Current**: 1.0
|
||||
- **Header**: 0x02
|
||||
- **Future**: Different headers for backward compatibility
|
||||
- **Headers**: 0x01 (Ping/Pong), 0x02 (LED Data), 0x03 (Brightness), 0x04 (Volume)
|
||||
- **Future**: Additional headers for new features, backward compatibility maintained
|
||||
|
||||
Reference in New Issue
Block a user