desktop/docs/hardware-protocol.md

LED Hardware Communication Protocol

Overview

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

• Protocol: UDP
• Port: 23042
• Discovery: mDNS (_ambient_light._udp.local.)
• Example Board: 192.168.31.206:23042

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)

Byte 0: Header (0x01)

Hardware → Desktop (Pong)

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

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 3+: LED Color Data (variable length)

LED Color Data

RGB LEDs (3 bytes per LED)

[R][G][B][R][G][B][R][G][B]...

RGBW LEDs (4 bytes per LED)

[R][G][B][W][R][G][B][W][R][G][B][W]...

All values are 0-255.

Color Calibration

Colors are calibrated before transmission:

RGB:

calibrated_r = (original_r * calibration_r) / 255
calibrated_g = (original_g * calibration_g) / 255  
calibrated_b = (original_b * calibration_b) / 255

RGBW:

calibrated_r = (original_r * calibration_r) / 255
calibrated_g = (original_g * calibration_g) / 255
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:

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

03 00 80
│  │  └─ Brightness (128 = ~50%)
│  └─ Display Index (0)
└─ Header (0x03)

Volume Control

Hardware can send system volume adjustment commands to the desktop:

Byte 0: Header (0x04)
Byte 1: Volume Percent (0-100)

Example: Set system volume to 75%

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

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

02 00 00 FF 00 00 00 FF 00 00 00 FF
│  │  │  └─────────────────────────── 9 bytes color data
│  │  └─ Offset Low (0)
│  └─ Offset High (0)
└─ Header (0x02)

RGBW Example

2 RGBW LEDs starting at position 10: White, Warm White

02 00 0A FF FF FF FF FF C8 96 C8
│  │  │  └─────────────────────── 8 bytes color data
│  │  └─ Offset Low (10)
│  └─ Offset High (0)
└─ Header (0x02)

Implementation Notes

• Byte Order: Big-endian for multi-byte values (offset field)
• Delivery: Fire-and-forget UDP (no acknowledgment required)
• Hardware Role: Simple UDP-to-WS2812 bridge, no data processing
• LED Type Logic: Handled entirely on desktop side, not hardware
• Mixed Types: Same display can have both RGB and RGBW strips
• Data Flow: Desktop → UDP → Hardware → WS2812 (direct forward)

Hardware Implementation

The hardware board handles multiple protocol functions: UDP-to-WS2812 bridge for LED data, health monitoring, and optional control input capabilities.

Required Functions

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

Packet Processing Logic

void process_packet(uint8_t* data, size_t len) {
    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];
    size_t color_len = len - 3;

    // Direct forward to WS2812 - no RGB/RGBW distinction needed
    ws2812_update(offset, color_data, color_len);
}

Optional Control Features

Hardware can optionally send control commands to desktop:

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

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:

# 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
• Headers: 0x01 (Ping/Pong), 0x02 (LED Data), 0x03 (Brightness), 0x04 (Volume)
• Future: Additional headers for new features, backward compatibility maintained