TK webusb_dmx512_controller.jpg
I love to control all the lights and I always try to find new ways of doing so. Currently I'm in love with DMX512 and WebUSB.
This article describes how you can build your own DMX512 controller by using an Arduino and how this controller can be used directly in the browser by leveraging WebUSB. It will answer the following questions:
TK Link ToC
Wikipedia defines DMX512 like this:
DMX512 (Digital Multiplex) is a standard for digital communication networks that are commonly used to control stage lighting and effects. It was originally intended as a standardized method for controlling light dimmers, which, prior to DMX512, had employed various incompatible proprietary protocols.
DMX512 is used in many theaters, clubs and festivals to control all the lights and beyond: From static lights to moving heads and lasers to fog machines.
In my basement I have a collection of DMX512 lights:
TK: newyears_eve_2017.jpg
DMX512 combines a set of lights (called fixtures) into a bus network of fixtures (called Universe). Each fixture has one or more functionalities, such as
- Color in RGB (Red, Green, Blue)
- Dimmer
- UV
- Movement (horizontally or vertically)
- Blinking effect
- Generate fog
- Blow bubbles
Each functionality can be controlled by one or more channels. This means that each fixture has a different amount of channels, depending which functionality the fixture has. It also means that you can't change the functionality of a fixture, you can only configure which of the predefined set of channels is used.
Each channel can be filled with a value between 0 and 255. In most situations it has the following meaning:
0 = 0%: no intensity, zero speed, no blinking255 = 100%: full color, full speed, fast blinking
Every fixture comes with a manual that holds all the informations you need to use the it. It includes a list all predefined channel sets + the meaning of the channel values and general information about the fixture.
I will describe two of my favorites fixtures to get started with DMX512.
TK Image of fog machine
The purpose of the "AF-150" by Stairville is to produce smoke. This helps to improve the visibility of the lights and the overall atmosphere.
https://gist.github.com/3fe64a5db59d15ace08edbe4365180ee
- 0 = fan is turned off
- 255 = fan is at highest speed
TK Image of Flat PAR
Let's take a look at a very basic fixture: The "SePar Quad LED RGBUV IR" by Fun Generation. What does all of this mean?
- SePar = This is a PAR light with 5 LEDs
- Quad LED RGBUV = The LEDs can create any RGB color and UV light at the same time
- IR = Fixture can be controlled via infrared
The Flat PAR's manual is more exciting than to the one of the Fog Machine, because the PAR has 8 channels in 4 different sets (2, 4, 6 or 8):
https://gist.github.com/3385106dab2b9ad92ce3a62ee99c95c5
https://gist.github.com/fcdbcdd1ff1f9b98146c8cf223fe0cd1
https://gist.github.com/130c76d3dff82286f66dc1dfe7f1608b
https://gist.github.com/224639a52ea1917037be6116a4307fbf
Which set of channels should you use? That depends on what you actually want to do with the fixture. In this case I want to set the RGB color and use the dimmer, so I will use the 6 channels set.
But where can we set that? Every fixture has some kind of interface that can be used to configure it. In many cases you will find a display and some buttons:
TK flat_par_configure_channel_set_using_display.jpg
This display let's you change the configuration of the fixture, for example the set of channels that should be used.
It's also possible to set the address.
TK flat_par_configure_address_using_display.jpg
The 512 in DMX512 stands for 512 channels. A combination of fixtures in a network is called a universe. Every fixture in the universe can have a specific address, so that it's possible to set the channels of a specific device in the universe.
This means that the more fixtures we have in a universe, the more channels are blocked by a fixture. That means that we should always choose a set of channels based on what we want to achieve. If we don't want to specific functionality, we choose the set that doesn't contain it.
To calculate the next free address in a universe we can do it like this: address of fixture a + # channels of fixture a = address of fixture b
Attention: This is not required, but it's always a good idea to give every fixture it's own space. Only use the same address more than once if you want to have fixtures of the same type that are in sync with each other. Because in the end they all get the same channel values if they share the same address.
Let's say we have three fixtures:
- 2 x Flat PAR with 6 channels
- 1 x Fog machine with 1 channel
The first fixture is a Flat PAR with the address of 1. Using the formula 1 + 6, then the next fixture can start at 7. Then we add the second Flat PAR at address 7 and the Fog Machine at address 13.
TK Image dmx512_universe_webusb_controller.png
The next thing we need is a WebUSB DMX512 controller to send the data (= an Array of 512 values) into the universe.
TK Separator
Wikipedia defines Arduino like this:
Arduino is an open source computer hardware and software company, project, and user community that designs and manufactures single-board microcontrollers and microcontroller kits for building digital devices and interactive objects that can sense and control objects in the physical and digital world.
The project's products are distributed as open-source hardware and software, which are licensed under the GNU Lesser General Public License (LGPL) or the GNU General Public License (GPL),[1] permitting the manufacture of Arduino boards and software distribution by anyone.
Arduino boards are available commercially in preassembled form, or as do-it-yourself (DIY) kits.
This is the perfect foundation to create our own WebUSB DMX512 Controller, because some Arduino (like the Arduino Leonardo with the ATmega32U4 chip) have the ability to be recognized by the computer as an external USB device. This makes it possible to use the Arduino over WebUSB.
KT arduino_leonardo_explained.jpg
The Arduino has a set of female headers at the top with 18 connectors and the bottom with 14 connectors. They can be used to attach all kind of electronic devices or shields to the Arduino.
An Arduino shield can extend the functionality of the Arduino by adding it on top of the headers. This makes it possible for everyone to use all kind of devices without having to know anything about electrical engineering or soldering.
In order to control a DMX512 universe with the Arduino we use the "2.5kV Isolated DMX512 Shield for Arduino - R2" on tindie.
Let's put it on top of the Arduino:
TK webusb_dmx512_controller_explained.jpg
- The DMX512 shield, with two DMX connectors (I and II). I is the output to send data into the universe. II is empty.
- The Arduino Leonardo, connected over MicroUSB to the computer.
Attention: As of writing this article there is no DMX512 shield for the small Arduino boards (like the Arduino Micro). This means that in order to use this shield you have to at least get an Arduino Leonardo or similar in terms of the size, because the position of the headers must be the same.
A list of boards that can be used in combination with the shield:
The hardware is ready, so let's jump into the software.
TK Separator
In order to be able to upload the code to the Arduino you have to setup the following stuff:
-
Checkout the NERDDISCO/webusb-dmx512-controller repository to your computer https://gist.github.com/c1333ee83634cc2dc2a4d0779cd5df82
-
Install npm dependencies https://gist.github.com/80145a9803d92ed779dd1590146ca10a
-
Download & install the Arduino IDE >= 1.8.5, so you are able to write & push code onto the Arduino
-
Open the Arduino IDE
-
Open the preferences: Arduino > Preferences
-
In the preferences dialog you have to change the Sketchbook location so that it points to the sketchbook folder that comes with the repository:
7. Close the Arduino IDE and then open it again (this is needed to load the new sketchbook that we selected in the step before)
8. Now we need to configure the Arduino IDE so that it can recognize our Arduino Leonardo:
- Select the model: Tools > Board > Arduino Leonardo (WebUSB) (or one of the other supported boards underneath the NERDDISCO: WebUSB DMX512 Controller headline in the menu)
- Select the USB port: Tools > Port > /dev/tty.usbmodem$ (The $ is a placeholder and will be different for every Arduino you are using)
**Attention**: This can only be selected if your Arduino is actually attached to your computer!
-
Open the sketch (if it's not already open): File > Sketchbook > webusb_dmx512_controller
-
Verify that the sketch is working: Sketch > Verify/Compile. This will produce an output like this: https://gist.github.com/5b41e99c7388de030190289657631fac
-
Upload the sketch to the Arduino: Sketch > Upload This will produce a similar output as step 10.
Attention: If the steps 10 or 11 did not work as promised, please open an issue on GitHub in my repository
When you are done your Arduino IDE should look like this:
The applications that you upload on the Arduino are called sketch. They contain all the code and external libraries that are needed in order to control what the Arduino should do for you.
You can "split" the sketch itself into three different parts, so let's see what is happening in each of them.
https://gist.github.com/7f6d421dc5233972cfe7d4622a322c95
(a) Import the external libraries that are needed:
- WebUSB to handle the WebUSB connection
- Conceptinetics to handle the DMX512 shield (which is maintained by the same person that is selling the shield)
👉 Those two libraries are already part of the sketchbook that came with the repository.
(b) For security reasons the WebUSB device has to whitelist the URLs that are allowed to use the device in the browser. In this case it points to my demo page. Please change this when you want to use the controller on your URL!
(c) Use Serial instead of WebUSBSerial
(d) Set the amount of channels in the universe to 512
(e) Initialize the dmx_master which is used to send data to the DMX512 shield
(f) Create an array of bytes that has the size of 512 to save the data that is coming over WebUSB to the Arduino
https://gist.github.com/d422e6bf3717053623fc79625c1c69be
(a) Every time the Arduino is started (for example when you connect it over USB to your computer), the setup() function is triggered once. It can be used to initialize everything.
(b) Fill the incoming array of bytes with 0, so that every channel in the universe has a default value. This is needed to put the universe in a clean state.
(c) Wait until the WebUB connection in the browser was successfully established with the Arduino
(d) When (c) is fulfilled, start the communication with the DMX512 shield
https://gist.github.com/03539aecfd4810f5419f19465dfd419d
(a) The main logic of the code is happening in loop(), because this function is called over and over again (and not only once as setup() does)
(b) When the WebUSB connection in the browser was successfully established with the Arduino
(c) Read 512 bytes that are send via WebUSB to the Arduino and save them into incoming
(d) Iterate over all 512 values
(e) Set the value of each channel of the universe according to the data that was received over WebUSB. First channel is 1.
TK Separator
Wikipedia defines USB like this:
USB, short for Universal Serial Bus, is an industry standard that was developed to define cables, connectors and protocols for connection, communication, and power supply between personal computers and their peripheral devices.
USB gives us the power to use devices regardless of the OS. Well, that is not entirely true, because only devices with standard functionality (= keyboard, mice, audio, video and storage devices) can be used everywhere. Non-standard devices always need some kind of OS-specific driver or SDK from the hardware manufacturer. This makes it super hard for developers to actually use these USB devices on the web.
WebUSB is here to overcome this problem, as it provides a safe way to expose non-standard USB devices in the browser. But what does safe even mean? The WebUSB standard defines different kind of protections:
- You can use it locally on localhost for testing
- You can use it online only secured via https
- You need a device that can handle URL whitelisting, meaning that the device has to allow on which URLs it can be used (which we already saw in the Arduino Sketch)
- The user has to allow using the USB device by triggering an explicit gesture (for example a click)
As of right now you can use WebUSB in Google Chrome 63 (native support) and as a port in Node.js. This might change in the future, so let's keep track on the implementation status.
At this point you already have the hardware ready, but to actually make use of it in the browser I created a module. It is part of the NERDDISCO/webusb-dmx512-controller repository and you can find it in controller.js. The module itself is also published on npm, so you can install it into your project: npm install webusb-dmx512-controller
https://gist.github.com/7e2d8b8fc04be3a17821cbc2b9395d10
(a) Import the ES6 module
(b) Create an instance of the module
(c) Get a reference to the button (or any other element the user can interact with to trigger the user gesture required by WebUSB protection mentioned earlier)
(d) Listen for click events on the button (which have to be triggered by the user)
(e) This will enable WebUSB and open a dialog for the user in which they can select the Arduino. The dialog looks like this (Chrome on macOS):
(f) We can create a connection to the Arduino when (e) was successful
Now that we have a connection to the Arduino from the browser, we can update the universe by using a single function:
https://gist.github.com/0f8f307ef8db4caf92befaae3b2e44d2
- The first parameter is the
channeland expects anumber - The second parameter is the
valueand expects either anumberor anarrayof numbers
The function itself has two "modes":
- Single = Update one
channel. This happens when thevalueis anumber - Multiple = Update multiple channels starting at
channel. This happens whenvalueis anarray
Before we start to use the function, let's recapture what we have in our DMX512 universe:
(I) Flat PAR with 6 channels at address 1
(II) Flat PAR with 6 channels at address 7
(III) Smoke machine with 1 channel at address 13
Let's assume we want to set the Color (= channels 1, 2 & 3) to red for (I):
https://gist.github.com/aaeee07c5309ae296708fb6d5709f39f
Yaaaay, our (I) is now in red. Or isn't it? Well no, setting the Color alone is not enough. You also have to set the Dimmer on channel 5, because that controls how bright the LEDs are. Initially all channels are set to 0, which means that the brightness is "turned off". So let's set the Dimmer to 255:
https://gist.github.com/8c202fc5b5c7f0381f4c495b8c8ba31f
Now the fixture (I) is shining in bright red.
TK flat_par_color_red_dimmer_255.jpg
Let's also set the color of fixture (II) (address: 7) to yellow and use a slow strobe (= blinking at low frequency):
https://gist.github.com/8647fb12ae407e56390508472dcdf71e
To improve the lighting effect of the two lights, we also activate the smoke of fixture (III) (address 13):
https://gist.github.com/d18ec7912b4bc753a03401d653c6e3a8
Every time you use the updateUniverse() function, the controller.universe array gets updated with the specified value(s), converted to an Uint8Array and finally send to the Arduino. The array itself looks like this (after we called it several times above):
https://gist.github.com/2f9d53e6f72bf6a0a35fda043567b16e
You can find the full API documentation on GitHub.
TK separator
In order to test the WebUSB DMX512 Controller directly in the browser, I have created a demo that is using the webusb-dmx512-controller module and wraps it in a basic UI:
TK webusb_dmx512_controller_demo_explained.jpg
- Activate WebUSB (& select the Arduino)
- Disconnect from the Arduino
- Set the value (0 - 255) of any channel (1 - 512) in the universe
- Use the example fixture (Flat PAR with 6 channels) from above and set the Color in RGB, UV, Dimmer and Strobe
- Console to show what is happening behind the scenes. It's also possible to print out the content of the universe when using the "log universe" checkbox
TK Separator
This was just a very basic introduction in the world of visualizations with DMX512. You want to dive even deeper? GREAT.
This project by Martin Schuhfuss provides a super nice abstraction to control DMX512 light-equipment. Everything I know and did with DMX512 is because of his library, so please go check it out: fivetwelve on GitHub
If you come that far, you should already know that I LOVE LIGHTS. And because I wanted to have a browser-based software to manage everything related to DMX512 and beyond, I created luminave. You can use luminave to create visual experiences, because it is providing different kind of integrations to other soft- and hardware:
- WebUSB DMX512 Controller
- fivetwelve to connect with other DMX512 controllers
- modV 1.0 for creating music visualizations in the browser
So what can you do? Let's watch this video of luminave in action:
Attention: The video contains flashing lights & music!
https://www.youtube.com/watch?time_continue=223&v=Qq9V5KHAf0s
The fixtures in the video are part of the installation I have in my basement:
- 1 x "Starburst" by ADJ
- 4 x "SePar Quad LED RGBUV IR" by Fun Generation
- 1 x "PixBar 600 PRO" by Cameo
- 1 x "TMH-8" by Eurolite
- 1 x "Wookie 200 RGY" by Cameo
- 1 x "Bowl Beam 604 LED COB" by Stairville (discontinued)
- 1 x "AF-150" by Stairville
TK Separator