Chapter 214: Art-Net Protocol for DMX over Ethernet

Chapter Objectives

By the end of this chapter, you will be able to:

• Explain the purpose of Art-Net and its role in modern lighting systems.
• Describe the Art-Net client/server architecture and its use of UDP.
• Understand the structure of the primary Art-Net packet, ArtDmx.
• Configure an ESP32 to connect to a Wi-Fi network and listen for UDP packets.
• Write robust C code to receive, parse, and validate Art-Net data.
• Build a functional Art-Net to DMX gateway that drives physical lighting fixtures.

Introduction

In Chapter 201, we mastered the DMX512 protocol, the workhorse for controlling lighting fixtures. We learned that DMX operates over a daisy-chained physical wire, which is perfect for a single stage or room. But what happens when a project scales up? Imagine an architectural lighting installation spanning an entire building, a theme park with thousands of lights, or a concert with multiple stages. Running long, dedicated DMX cables for dozens or even hundreds of “universes” (a set of 512 channels) quickly becomes impractical and expensive.

This is the problem that Art-Net solves. Developed by Artistic Licence, Art-Net is a royalty-free protocol that transports DMX512 data over standard IP networks, such as Ethernet and Wi-Fi. It wraps up DMX data into network packets that can be sent from a single lighting controller to numerous receiver nodes across a large area.

In this chapter, we will leverage the networking capabilities of the ESP32 to build a compact, cost-effective Art-Net node. Our device will join a Wi-Fi network, listen for lighting data, and translate it back into the electrical DMX512 signal needed to control physical fixtures.

Theory

1. Art-Net Architecture

Art-Net operates on a simple controller-node (or server-client) model.

• Controller (Server): This is the “brain” of the lighting system. It can be a dedicated hardware lighting console or, more commonly, software running on a PC (like QLC+, Madrix, or Resolume). The controller generates the lighting looks and sends them out as Art-Net packets onto the network.
• Node (Client): This is a hardware device that listens on the network for Art-Net packets. When it receives a packet addressed to it, it unpacks the DMX data and outputs it as a standard DMX512 electrical signal. Our ESP32 will function as a Node.

graph TD
    subgraph "Lighting Controller"
        A[<b>Laptop / PC</b><br><i>Running QLC+, Madrix, etc.</i>]
    end

    subgraph "Network Infrastructure"
        B((Wi-Fi Router /<br>Ethernet Switch))
    end

    subgraph "Art-Net Nodes (Clients)"
        C[<b>ESP32 Node 1</b><br><i>Universe 0</i>]
        D[<b>ESP32 Node 2</b><br><i>Universe 1</i>]
        E[<b>ESP32 Node 3</b><br><i>Universe 2</i>]
    end

    subgraph "DMX Fixtures"
        F1[<font size=5>💡</font><br>Spotlight]
        F2[<font size=5>💡</font><br>PAR Can]
        F3[<font size=5>💡</font><br>Moving Head]

        G1[<font size=5>💡</font><br>LED Bar]
        G2[<font size=5>💡</font><br>Strobe]
        
        H1[<font size=5>💡</font><br>Pixel Strip]
        H2[<font size=5>💡</font><br>Laser]
        H3[<font size=5>💡</font><br>Fog Machine]
    end

    A -- "Art-Net Packets<br>(UDP Port 6454)" --> B
    B -- "Wi-Fi / Ethernet" --> C
    B -- "Wi-Fi / Ethernet" --> D
    B -- "Wi-Fi / Ethernet" --> E

    C -- "DMX512 Signal" --> F1 & F2 & F3
    D -- "DMX512 Signal" --> G1 & G2
    E -- "DMX512 Signal" --> H1 & H2 & H3

    classDef controller fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E40AF
    classDef network fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E
    classDef node fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6
    classDef fixture fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#065F46

    class A controller
    class B network
    class C,D,E node
    class F1,F2,F3,G1,G2,H1,H2,H3 fixture

2. Networking Fundamentals: UDP Port 6454

Art-Net is built on top of UDP (User Datagram Protocol). As we learned in Volume 4, UDP is a connectionless protocol. It’s like sending a postcard: you send the data without first establishing a formal connection, and there’s no guarantee of delivery. For lighting data, this is an acceptable trade-off.

• Speed: UDP has very low overhead, making it fast. Lighting control is real-time, and fresh data is sent many times per second (typically 30-44 Hz), so speed is critical.
• Efficiency: If a single packet is lost due to network congestion, a new one with updated lighting values will arrive just a few milliseconds later. The visual glitch is often imperceptible.
• Broadcast/Unicast: Art-Net packets can be sent to a specific node’s IP address (unicast) or to all devices on the subnet (broadcast).

By convention, Art-Net communication occurs on UDP port 6454. Any device wishing to participate in an Art-Net network must listen for data on this port.

3. The Art-Net Packet Structure

Art-Net defines several packet types for discovery, time-syncing, and configuration. The most important one for us is ArtDmx, which carries the actual lighting data. All Art-Net packets are little-endian.

An ArtDmx packet (OpCode 0x5000) has the following structure:

Universe Addressing:

Art-Net supports a vast number of DMX universes (32,768 to be exact). The target universe is specified by a combination of the Net and SubUni fields. For most common applications, we only care about the lower 4 bits of SubUni, giving us 16 universes (0-15) on the default Net and Sub-Net. We will configure our ESP32 to listen for a specific universe, for example, Universe 0.

Practical Examples

This example will guide you through building a single-universe Wi-Fi Art-Net to DMX node.

Prerequisites

1. Hardware:
   • An ESP32 development board.
   • A MAX485 or similar RS-485 transceiver IC.
   • An XLR connector (3-pin or 5-pin female) for the DMX output.
   • A 120Ω termination resistor (optional but recommended).
   • A DMX-controllable light fixture.
2. Software:
   • VS Code with the ESP-IDF v5.x extension.
   • A computer on the same Wi-Fi network.
   • Art-Net controller software. QLC+ is an excellent free, open-source choice.

Step 1: Hardware Assembly

The hardware for this project is identical to the DMX512 transmitter we built in Chapter 201.

1. Connect a UART TX pin from your ESP32 (e.g., GPIO17) to the DI (Driver Input) pin of the MAX485.
2. Connect a GPIO pin (e.g., GPIO16) to both the DE (Driver Enable) and RE (Receiver Enable, active low) pins of the MAX485. This pin will control the data direction.
3. Connect the A and B outputs of the MAX485 to pins 2 and 3 of the XLR connector, respectively. Connect GND to pin 1.
4. Power the ESP32 and the MAX485.

Step 2: Project Setup and DMX Driver

1. Create a new ESP-IDF project.
2. Use idf.py menuconfig to set your Wi-Fi SSID and Password under Example Connection Configuration.
3. We need a DMX driver. For this chapter to be self-contained, here is a minimal RMT-based DMX512 driver. Place this code in a file like dmx_driver.c and create a corresponding header dmx_driver.h.

dmx_driver.h

#pragma once
#include <stdint.h>
#include "esp_err.h"

#define DMX_CHANNEL_COUNT 512

esp_err_t dmx_driver_init(void);
esp_err_t dmx_send_data(const uint8_t *data, size_t length);

dmx_driver.c

#include "dmx_driver.h"
#include "driver/rmt_tx.h"
#include "driver/gpio.h"
#include "esp_log.h"

#define DMX_RMT_CHANNEL     RMT_CHANNEL_0
#define DMX_TX_GPIO         17
#define DMX_ENABLE_GPIO     16
#define RMT_RESOLUTION_HZ   1000000 // 1us resolution

static const char *TAG = "DMX_DRIVER";
static rmt_channel_handle_t tx_channel = NULL;
static rmt_encoder_handle_t bytes_encoder = NULL;
static rmt_symbol_word_t start_symbol;
static uint8_t dmx_buffer[DMX_CHANNEL_COUNT + 1]; // +1 for start code

esp_err_t dmx_driver_init(void) {
    // GPIO for MAX485 direction control
    gpio_set_direction(DMX_ENABLE_GPIO, GPIO_MODE_OUTPUT);
    gpio_set_level(DMX_ENABLE_GPIO, 0); // Set to receive mode initially

    // RMT TX channel
    rmt_tx_channel_config_t tx_chan_config = {
        .clk_src = RMT_CLK_SRC_DEFAULT,
        .gpio_num = DMX_TX_GPIO,
        .mem_block_symbols = 128, // More memory for DMX packets
        .resolution_hz = RMT_RESOLUTION_HZ,
        .trans_queue_depth = 4,
    };
    ESP_ERROR_CHECK(rmt_new_tx_channel(&tx_chan_config, &tx_channel));

    // DMX uses inverted logic and specific baud rate (250k)
    // 1 bit = 4us. 8 data bits, 1 start, 2 stop bits = 11 bits = 44us
    rmt_bytes_encoder_config_t bytes_enc_config = {
        .bit0 = {.duration0 = 2, .level0 = 0, .duration1 = 2, .level1 = 1}, // 4us
        .bit1 = {.duration0 = 2, .level0 = 1, .duration1 = 2, .level1 = 0}, // 4us
        .flags.msb_first = 0,
    };
    ESP_ERROR_CHECK(rmt_new_bytes_encoder(&bytes_enc_config, &bytes_encoder));

    // Symbol for DMX Break and Mark-After-Break (MAB)
    start_symbol = (rmt_symbol_word_t) {
        .duration0 = 100, .level0 = 0, // BREAK (min 88us)
        .duration1 = 12, .level1 = 1, // MAB (min 8us)
    };

    ESP_ERROR_CHECK(rmt_enable(tx_channel));
    ESP_LOGI(TAG, "DMX driver initialized.");
    return ESP_OK;
}

esp_err_t dmx_send_data(const uint8_t *data, size_t length) {
    if (length > DMX_CHANNEL_COUNT) {
        length = DMX_CHANNEL_COUNT;
    }

    gpio_set_level(DMX_ENABLE_GPIO, 1); // Set to transmit mode

    rmt_transmit_config_t tx_config = {.loop_count = 0};
    
    // Send Break + MAB
    ESP_ERROR_CHECK(rmt_transmit(tx_channel, bytes_encoder, &start_symbol, sizeof(start_symbol), &tx_config));
    ESP_ERROR_CHECK(rmt_tx_wait_all_done(tx_channel, -1));

    // Prepare data packet (Start Code + DMX data)
    dmx_buffer[0] = 0x00; // Standard DMX Start Code
    memcpy(&dmx_buffer[1], data, length);
    
    // Send data
    ESP_ERROR_CHECK(rmt_transmit(tx_channel, bytes_encoder, dmx_buffer, length + 1, &tx_config));
    ESP_ERROR_CHECK(rmt_tx_wait_all_done(tx_channel, -1));

    gpio_set_level(DMX_ENABLE_GPIO, 0); // Return to receive mode
    return ESP_OK;
}

Step 3: Writing the Main Application Logic

sequenceDiagram
    participant User
    participant QLC
    participant ESP32
    participant Light

    User->>+QLC: Moves fader for Channel X
    QLC->>QLC: Generate ArtDmx Packet<br>Universe: 0, Data[X-1]: New Value
    QLC-->>ESP32: Send UDP Packet to Port 6454
    
    activate ESP32
    Note over ESP32: artnet_receive_task is listening...
    ESP32->>ESP32: recvfrom() gets data
    
    alt Packet is Valid ArtDmx for Universe 0
        ESP32->>ESP32: Parse Packet: ID, OpCode, Universe all OK
        ESP32->>ESP32: Call dmx_send_data(payload)
        Note over ESP32: RMT peripheral constructs<br>DMX signal with BREAK, MAB, Start Code
        ESP32-->>+Light: Send DMX512 Signal
        Light->>Light: Update to new color/position
    else Packet is invalid or for another universe
        ESP32->>ESP32: Discard packet, continue listening
    end
    deactivate ESP32
    deactivate QLC

/* main/artnet_node_main.c */
#include <stdio.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"
#include "lwip/err.h"
#include "lwip/sockets.h"
#include "lwip/sys.h"
#include <lwip/netdb.h>

#include "dmx_driver.h" // Our DMX driver

#define ARTNET_PORT 6454
#define ARTNET_UNIVERSE_TO_LISTEN 0 // We will listen for Universe 0

static const char *TAG = "ARTNET_NODE";

// Art-Net packet structure
#pragma pack(push, 1)
typedef struct {
    uint8_t id[8];
    uint16_t opcode;
    uint16_t prot_ver;
    uint8_t sequence;
    uint8_t physical;
    uint8_t sub_uni;
    uint8_t net;
    uint16_t length;
    uint8_t data[DMX_CHANNEL_COUNT];
} artnet_packet_t;
#pragma pack(pop)

static void wifi_event_handler(void* arg, esp_event_base_t event_base, int32_t event_id, void* event_data) {
    if (event_id == WIFI_EVENT_STA_START) {
        esp_wifi_connect();
    } else if (event_id == WIFI_EVENT_STA_DISCONNECTED) {
        esp_wifi_connect();
        ESP_LOGI(TAG, "retry to connect to the AP");
    } else if (event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t* event = (ip_event_got_ip_t*) event_data;
        ESP_LOGI(TAG, "got ip:" IPSTR, IP2STR(&event->ip_info.ip));
    }
}

void wifi_init_sta(void) {
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    esp_netif_create_default_wifi_sta();

    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));

    esp_event_handler_instance_t instance_any_id;
    esp_event_handler_instance_t instance_got_ip;
    ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL, &instance_any_id));
    ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &wifi_event_handler, NULL, &instance_got_ip));

    wifi_config_t wifi_config = {
        .sta = {
            .ssid = CONFIG_ESP_WIFI_SSID,
            .password = CONFIG_ESP_WIFI_PASSWORD,
        },
    };
    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
    ESP_ERROR_CHECK(esp_wifi_start());
    ESP_LOGI(TAG, "wifi_init_sta finished.");
}

static void artnet_receive_task(void *pvParameters) {
    char rx_buffer[1024];
    struct sockaddr_in dest_addr;
    struct sockaddr_in *dest_addr_ip4 = (struct sockaddr_in *)&dest_addr;
    dest_addr_ip4->sin_addr.s_addr = htonl(INADDR_ANY);
    dest_addr_ip4->sin_family = AF_INET;
    dest_addr_ip4->sin_port = htons(ARTNET_PORT);
    int ip_protocol = IPPROTO_IP;

    int sock = socket(AF_INET, SOCK_DGRAM, ip_protocol);
    if (sock < 0) {
        ESP_LOGE(TAG, "Unable to create socket: errno %d", errno);
        vTaskDelete(NULL);
        return;
    }
    ESP_LOGI(TAG, "Socket created");

    int err = bind(sock, (struct sockaddr *)&dest_addr, sizeof(dest_addr));
    if (err < 0) {
        ESP_LOGE(TAG, "Socket unable to bind: errno %d", errno);
        close(sock);
        vTaskDelete(NULL);
        return;
    }
    ESP_LOGI(TAG, "Socket bound on port %d", ARTNET_PORT);

    while (1) {
        struct sockaddr_storage source_addr;
        socklen_t socklen = sizeof(source_addr);
        int len = recvfrom(sock, rx_buffer, sizeof(rx_buffer) - 1, 0, (struct sockaddr *)&source_addr, &socklen);

        if (len < 0) {
            ESP_LOGE(TAG, "recvfrom failed: errno %d", errno);
            break;
        } else {
            // Data received
            if (len > sizeof(artnet_packet_t)) continue; // Packet too large
            
            artnet_packet_t *packet = (artnet_packet_t *)rx_buffer;

            // 1. Validate Art-Net ID and OpCode
            if (memcmp(packet->id, "Art-Net\0", 8) != 0 || packet->opcode != 0x5000) {
                continue; // Not a valid ArtDmx packet
            }
            
            // 2. Check if the universe matches the one we are listening for
            uint16_t universe = (packet->net << 8) | packet->sub_uni;
            if (universe == ARTNET_UNIVERSE_TO_LISTEN) {
                ESP_LOGD(TAG, "Received Art-Net for universe %d, length %d", universe, ntohs(packet->length));
                // 3. Send the data to the DMX bus
                dmx_send_data(packet->data, ntohs(packet->length));
            }
        }
    }

    close(sock);
    vTaskDelete(NULL);
}


void app_main(void) {
    // Initialize NVS
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
      ESP_ERROR_CHECK(nvs_flash_erase());
      ret = nvs_flash_init();
    }
    ESP_ERROR_CHECK(ret);
    
    // Initialize networking
    wifi_init_sta();

    // Initialize DMX driver
    dmx_driver_init();
    
    // Start the UDP receiver task
    xTaskCreate(artnet_receive_task, "artnet_task", 4096, NULL, 5, NULL);
}

Step 4: Build, Flash, and Test

1. Build the project: idf.py build.
2. Flash the firmware: idf.py -p [YOUR_PORT] flash.
3. Monitor the output to see the ESP32 connect to Wi-Fi and get an IP address. Note this IP address.
4. Configure QLC+:
   • Open QLC+ and go to the “Inputs/Outputs” tab.
   • Select “Art-Net” and check the box under “Output” for an entry corresponding to your network adapter.
   • Go to the “Simple Desk” tab.
   • Ensure Universe 1 in QLC+ is selected (this corresponds to Art-Net Universe 0).
   • Move the faders for the channels your light fixture responds to.
5. Observe: Your DMX light should respond in real-time to the fader movements in QLC+.

Variant Notes

• Wi-Fi Nodes (ESP32, S3, C3, C6, H2): Any ESP32 with Wi-Fi is perfectly suited for this application, especially for single-universe nodes. The networking and RMT performance are more than adequate.
• Wired Ethernet Nodes (ESP32 Original): For professional installations where network reliability is paramount, a wired connection is preferred. The original ESP32 has a built-in Ethernet MAC peripheral, making it the ideal choice for creating a robust, wired Art-Net node. You would use the ESP-IDF Ethernet driver instead of the Wi-Fi driver.
• SPI Ethernet (All Variants): You can add wired Ethernet capability to any ESP32 variant by using a SPI-based Ethernet module like the W5500. This is a great way to add reliability to variants that lack a native Ethernet MAC.

Common Mistakes & Troubleshooting Tips

Exercises

1. Implement ArtPollReply: Art-Net controllers discover nodes by broadcasting an ArtPoll packet. Read the Art-Net specification for ArtPoll (OpCode 0x2000) and ArtPollReply (OpCode 0x2100). Modify the artnet_receive_task to detect an ArtPoll and respond with an ArtPollReply containing your ESP32’s IP address and a custom name. This will make your node automatically appear in your controller’s list of devices.
2. Web-Based Configuration: Add a simple web server to the project. The web page should allow the user to configure the Art-Net Universe that the device listens to. Save this setting to NVS so it persists across reboots.
3. Two-Universe Node: Upgrade the hardware with a second MAX485 and XLR connector on different GPIOs. Modify the firmware to initialize two DMX drivers. In the artnet_receive_task, check the incoming packet’s universe and route the DMX data to the correct physical output.
4. sACN (E1.31) Support: Research the sACN protocol, another common standard for DMX over Ethernet. It uses multicast UDP. Modify your project to listen for and parse sACN packets in addition to Art-Net, creating a dual-protocol node.

Summary

• Art-Net is a protocol for sending DMX512 data over standard IP networks using UDP on port 6454.
• It enables large-scale, flexible lighting systems by replacing long DMX cables with network infrastructure.
• The primary data packet is ArtDmx (OpCode 0x5000), which contains the universe address and up to 512 channels of lighting data.
• An Art-Net Node (our ESP32) listens for UDP packets, validates them, and converts the data back into a physical DMX512 signal using a driver like RMT.
• Proper network configuration, packet validation, and data structure handling (pragma pack) are critical for a robust implementation.

Further Reading

• Art-Net Protocol Specification: The official documentation from Artistic Licence is the ultimate reference. (http://art-net.org.uk)
• QLC+ (Q Light Controller Plus) Documentation: An excellent resource for understanding how to use a free, powerful lighting controller. (https://www.qlcplus.org/)
• ESP-IDF LwIP Socket Documentation: For more advanced socket programming options. (https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/lwip.html)
• Chapter 85: UDP Socket Programming: A refresher on the concepts used in this chapter.
• Chapter 201: DMX512 Protocol Implementation: For a deeper dive into the physical DMX driver.