DMX4ESP is a lightweight and efficient library for sending and receiving DMX-512 data using any esp32 microcontroller.

✅ Send DMX-512 data

⚠️ Receive DMX-512 data (experimental)

✅ Uses esp32 hardware UART

✅ Compatible with ESP-IDF

• DMX-512 explained
• Getting Started

DMX-512 (Digital Multiplex) is the standard protocol used in the entertainment and lighting industry for example to control stage lighting, effects and other devices. It was developed by the Engineering Commission of the United States Institute for Theatre Technology (USITT) in 1986.

The DMX-512 Protocol is based on the RS-485 Standard as the physical layer for communication.

OSI Model how dmx is transmitted/received.

• Differential Communication with A/B data lines
• Up to 1000m distance without significant data loss
• Noise immunity

Any DMX Frame has to consist of the following components:

1. Break Signal (>88µs)
   • Signals the start of the DMX packet
   • Set Break Signal by inversing the two data lines
2. Mark After Break Signal (>8µs)
   • Prepare receivers to receive data
3. Channel Slots (1 Byte)
   • Slots for each Byte
4. Start Code (1 Byte)
   • Normally 0x00 for default control
   • See examples for other usecases
5. DMX Data (512 Bytes)
   • Data of each 512 DMX Channels with an 8-bit resolution (0 - 255)

timing diagram of a dmx-512 data stream [1]

common start codes for DMX

• ESP32 Microcontroller
• RS-485 interface. Supported chipsets:
  • MAX485
  • 74HC04D

Clone the src folder inside your own components directory.

#include "dmx4esp.h"

MAX485 Breakboard with esp32

//configure pinout for rx, tx & direction ports
dmxPinout dmxPins = {
    .tx = GPIO_NUM_43,
    .rx = GPIO_NUM_44,
    .dir = GPIO_NUM_1
};

//apply pinout
setupDMX(dmxPins);

//start dmx service
initDMX(true); //true => DMX send mode

//alt.: receive mode
initDMX(false); //false => DMX receive mode 

//now, the esp is constantly sending the internally stored dmx data (startup: blackout)

//array to store the data you wish to send
uint8_t full[512];
memset(full, 255, sizeof(full));

//apply data
sendDMX(full);

//change DMX address to value 255
sendAddress(1, 255);

//array to store the dmx values
uint8_t receivedSignal[512];

//update state
for(;;){
    //get the current dmx frame as an array
    uint8_t* readBuffer = readDMX();
		
    //check if operation was successfull
    if(readBuffer != NULL){
        //copy the received data into a static array
        memcpy(receivedSignal, readBuffer, 512);
				
        //important: free the dynamic buffer
        free(readBuffer);
				
        //wait a custom interval before reading
        vTaskDelay(REFRESH_RATE);
    }
		
}

Note: further examples are in the examples  directory.

For full documentation, see the Doxygen documentation.

[1] https://www.dmx512.de/dmx512a/index.htm

https://community.element14.com/technologies/open-source-hardware/b/blog/posts/dmx-explained-dmx512-and-rs-485-protocol-detail-for-lighting-applications

https://hbernstaedt.de/__KnowHow/Steuersignale/Protokolle/DMX/DMX2/DMX2.htm

https://wiki.production-partner.de/licht/lichtsteuerung-mit-dmx-512/

NOTE: this integration currently supports following chipsets: MAX485, 74HC04D