NWled.WARLS 1.0.0

WLedUdpClient

WLedUdpClient is a .NET class that provides an easy interface for sending realtime UDP packets using the WARLS protocol to control WLED LED strips. This client enables direct UDP communication to drive LED effects�such as audio-reactive lighting or ambilight applications�by sending packets that update the LED colors in realtime.

Features

Realtime UDP Communication

• WARLS Protocol: Sends UDP packets using the WARLS protocol.
• Hostname & IP Resolution: Accepts hostnames (with or without "http://" or "https://") and IP addresses.
• Configurable UDP Port: Default port is 21324, but you can specify a custom port.

Packet Construction

The UDP packet is built according to the WARLS protocol:

• Byte 0: Protocol selector (1 for WARLS).
• Byte 1: Timeout value (in seconds). This indicates how long the WLED device should remain in realtime mode after the last packet.
• Bytes 2+: For each LED update, 4 bytes are appended:
  • LED index
  • Red value (0-255)
  • Green value (0-255)
  • Blue value (0-255)

Initialization

You can initialize the WLedUdpClient by providing a hostname or IP address and an optional UDP port.

// Initialize with a hostname (protocol prefix is optional) and default port 21324.
var udpClient = new WLedUdpClient("http://wled-279a34.local/");

Sending Realtime LED Updates

SendWarlsPacketAsync

Use this method to send a UDP packet with a specified timeout and LED updates.

// Prepare LED updates: for example, setting LED 0 to red.
var ledUpdates = new[]
{
    new LEDUpdate(index: 0, red: 255, green: 0, blue: 0)
};

// Send a WARLS packet with a timeout of 2 seconds.
await udpClient.SendWarlsPacketAsync(timeout: 2, ledUpdates: ledUpdates);

Usage Example

Below is a complete example demonstrating how to use the WLedUdpClient to send a realtime update:

using NWled.UDP;
using System.Threading.Tasks;

public class Example
{
    public static async Task Main()
    {
        // Initialize the UDP client with your WLED device hostname.
        var udpClient = new WLedUdpClient("http://wled-279a34.local/");

        // Create an LED update: set LED 0 to red.
        var ledUpdates = new LEDUpdate[]
        {
            new LEDUpdate(index: 0, red: 255, green: 0, blue: 0)
        };

        // Send the UDP realtime packet with a timeout of 2 seconds.
        await udpClient.SendWarlsPacketAsync(timeout: 2, ledUpdates: ledUpdates);
    }
}

Additional Notes

• Timeout Parameter:
  The timeout (in seconds) determines how long the WLED device remains in realtime mode after the last packet. A value between 1 and 2 seconds is typical; use 255 to disable the timeout.

• LEDUpdate Structure:
  Each update consists of an LED index and its corresponding RGB values. Make sure your LED indices and values conform to your WLED configuration.

• Network Considerations:
  Ensure that the device running the client is on the same network as your WLED device and that UDP traffic is allowed by your network configuration.

License

This project is licensed under the MIT License.