DOCSEARCHbyAlgolia
Submit Docs

ArtnetWifi Library

repository·master·Indexed 19 days ago

https://github.com/rstephan/artnetwifi

An Art-Net protocol library for WiFi-enabled Arduino devices, allowing microcontrollers to receive Art-Net DMX data for LED control (such as WS2811/WS2812) or transmit Art-Net data. It provides the ArtnetWifi class for managing services, supports C-style and C++11 callbacks for Art-DMX data, and includes examples for FastLED and Adafruit NeoPixel integration.

Tokens
1.4K
Snippets
4
Records
8
Agent score
16%

What's inside ArtnetWifi

  1. Art-Net Universe and LED Mapping Constraints

    master

    When using the FastLED or NeoPixel examples to control large numbers of LEDs across multiple universes, keep the following data constraints in mind:

    • Frame Size: A standard Art-Net frame handles 512 bytes.
    • LED Capacity per Universe: Since each LED requires 3 bytes (Red, Green, Blue), a single universe can support a maximum of 170 LEDs. The last 2 bytes of the 512-byte frame are reserved/lost.
    • Data Transmission: You only need to send 510 bytes of DMX data per frame. Any extra bytes at the end of the frame will be ignored.

    Example Calculation (240 LEDs across 2 Universes):

    • Universe 1: Bytes 1-510 (Controls LEDs 1-170).
    • Universe 2: Bytes 1-210 (Controls LEDs 171-240).

  2. Overview of ArtnetWifi Examples

    master

    The library provides several examples for different use cases:

    • ArtnetWifiDebug: A basic test for WiFi, Serial, and Art-Net connectivity. If this example fails, there is likely an issue with your hardware or network setup.
    • ArtnetWifiDebug2: A version of the debug example using C++11 style (note: compatibility varies by controller).
    • ArtnetWifiFastLED: Receives multiple Art-Net universes to control WS2812 LED strips using the FastLED library. Optimized for ESP32 and ESP8266.
    • ArtnetWifiNeoPixel: Receives multiple Art-Net universes to control WS2811 LED strips using the Adafruit NeoPixel library.
    • ArtnetWifiTransmit: A simple transmitter example that sends 3 bytes over Art-Net to create an RGB white light ramp-up.

  3. Install ArtnetWifi

    master

    You can install the ArtnetWifi library using the Arduino IDE, PlatformIO, or by manual installation.

    Arduino IDE

    1. Navigate to Sketch -> Include Library -> Manage Libraries....
    2. Search for ArtnetWifi.
    3. Click Install.

    PlatformIO Core (CLI)

    Use the following commands to initialize your project and install the library:

    $ pio init --board nodemcuv2
$ pio lib install artnetwifi

    Manual Installation

    Place the library folder directly into your ~/Documents/Arduino/libraries folder.

  4. Configure outgoing Art-Net packets

    master

    When preparing to send Art-Net data using write(), configure the packet properties using these methods:

    • setUniverse(uint16_t universe): Sets the outgoing DMX universe.
    • setLength(uint16_t len): Sets the length of the DMX data to be sent.
    • setPhysical(uint8_t port): Sets the physical port/address.
    • setByte(uint16_t pos, uint8_t value): Sets a specific byte in the packet buffer at pos to value.

  5. Handle incoming Art-DMX data via callbacks

    master

    You can handle incoming Art-DMX packets using two different callback methods depending on your hardware architecture.

    1. Standard C-style Callback

    Use setArtDmxCallback to register a function pointer. This is available on all supported architectures.

    Callback Signature: void callback(uint16_t universe, uint16_t length, uint8_t sequence, uint8_t* data)

    2. C++11 std::function Callback

    On architectures that support it (excluding ARDUINO_AVR_UNO_WIFI_REV2), you can use setArtDmxFunc to pass a std::function. This allows for more flexible usage, such as passing lambdas with captures.

    Callback Signature: void callback(uint16_t universe, uint16_t length, uint8_t sequence, uint8_t* data)

    // C-style callback example
void myDmxHandler(uint16_t universe, uint16_t length, uint8_t sequence, uint8_t* data) {
  // Handle DMX data
}

void setup() {
  artnet.begin();
  artnet.setArtDmxCallback(myDmxHandler);
}

  6. Initialize and use the ArtnetWifi class

    master

    The ArtnetWifi class is the primary interface for receiving and sending Art-Net data over WiFi.

    To use it:

    1. Instantiate ArtnetWifi.
    2. Call begin(String hostname) to start the service. You can optionally provide a hostname.
    3. Use read() to process incoming packets. It returns the opcode of the packet read, or 0 if there is a problem.
    4. Use write() or write(IPAddress ip) to transmit Art-Net packets.
    5. Call stop() to halt the service.
    ArtnetWifi artnet;

void setup() {
  artnet.begin("MyArtnetNode");
}

void loop() {
  if (artnet.read() > 0) {
    // Packet received
  }
}

  7. Access Art-Net packet metadata and DMX data

    master

    After a successful read(), you can inspect the packet details using the following methods:

    • getOpcode(): Returns the Art-Net opcode (e.g., ART_DMX, ART_SYNC).
    • getUniverse(): Returns the incoming DMX universe number.
    • getSequence(): Returns the sequence number.
    • getLength(): Returns the length of the DMX data.
    • getDmxFrame(): Returns a uint8_t* pointer to the start of the actual DMX payload.
    • getSenderIp(): Returns the IPAddress of the sender.

  8. Art-Net Constants and Protocol Definitions

    master

    The library defines several constants used for Art-Net protocol compliance:

    Port and ID

    • ART_NET_PORT: The default UDP port (6454).
    • ART_NET_ID: The required Art-Net identifier string ("Art-Net").

    Opcodes

    • ART_POLL: 0x2000
    • ART_DMX: 0x5000
    • ART_SYNC: 0x5200

    Buffer Offsets

    • ART_DMX_START: The offset (18) where the DMX data payload begins within the packet.
    #define ART_NET_PORT 6454
#define ART_POLL 0x2000
#define ART_DMX 0x5000
#define ART_SYNC 0x5200
#define ART_NET_ID "Art-Net"
#define ART_DMX_START 18