This past week saw the release of PixelMaestro 2.0, and with it, a bunch of fixes to device communication and control. You can now plug in any Arduino-compatible board with an attached LED strip or matrix and start controlling it in a matter of minutes. Not only can you send commands to it in real-time, but you can upload complete configurations and store them in EEPROM for long-term storage, even across reboots. This was possible in previous versions of PixelMaestro, but now it’s even easier.
This post demonstrates some of PixelMaestro’s new device integration features and example sketches.
If you’re not already familiar with PixelMaestro, check out the project repository and Wiki. In short, PixelMaestro is a tool for animating LED displays. It consists of a C++ library as well as a desktop application. The library provides an API for defining a grid of pixels, creating animations, drawing animated bitmap images, adding post-processing effects, and more. It also provides a serial data protocol for storing or transmitting commands (more details on that later).
In short, PixelMaestro is a tool for fully customizing LED displays on a number of devices, including PCs and microcontrollers.
Pairing PixelMaestro with an Arduino Mega
I’ve been designing PixelMaestro around Arduinos because they’re so easy to use, well supported, and have a great community. Plug in a few WS2812 LEDs to a PWM-enabled pin, download an appropriate library like the venerable NeoPixel library, and in seconds you’ll have an LED project up and running. PixelMaestro adds a layer on top of this by adding a ton of animation options, but not a lot of complexity.
I wanted to make it as easy as possible to customize a PixelMaestro instance without having to write code or upload a sketch. That’s how PixelMaestro Studio came about. PixelMaestro Studio uses a custom protocol to send commands to an Arduino running PixelMaestro over USB (although technically it will work over any serial connection). Almost every action in PixelMaestro Studio generates a command that can be sent over this protocol, displayed in the app, or saved to a file.
These commands (called Cues) can be sent to a device in one of two ways:
- On-demand as one complete package called a Cuefile.
- In real-time as you perform actions in PixelMaestro Studio.
But before we can do this, we first need to connect the device.
Connecting the Device
First, plug in your Arduino to your PC and flash the USB Live sketch. Once it’s restarted, launch PixelMaestro Studio and click on the Devices tab. The Device List will be empty, but that just means you haven’t yet configured a device. Click the Add button above the Device list.
Here, you can configure your device. Enter (or use the drop-down button to select) the port that your device is connected on. Check Auto-connect to automatically connect to the device the next time you open PixelMaestro Studio (and the device is physically connected over USB). Also check Live Updates, as this will automatically update your device in real-time as you use PixelMaestro Studio. You can ignore the Map Sections button for now, or read the Wiki for more information. Click OK to add your device.
Once your device is in the Device List, select it and click Connect. This will open a serial connection to your device that will close when you exit PixelMaestro or click Disconnect. To show that your device is connected, it will appear white in the drop-down list. You’ll also see a small icon in the Device Tab.
Now that the device is connected and Live Updates are enabled, any changes you make in PixelMaestro Studio will be automatically sent to your device. You can select an Animation, create a Canvas, add a Layer, change the brightness, mirror the Section, and even create a Show, and all your changes will be automatically and instantly sent over. The only exceptions are any blocks that were applied in the sketch, but by default these are only limited to:
- Changing the grid size (for memory reasons)
- Changing the Section’s brightness (for power consumption reasons)
- Creating a Show (for memory reasons)
You can, of course, replace these or remove them altogether.
Sending Your Entire Configuration
Let’s say you performed several actions in PixelMaestro Studio, but for some reason, they didn’t get sent over. Maybe you plugged in your device after making the changes, or you had to reset the device during your session. You can re-send all of your changes in one go by opening the Device Tab, selecting your device, and clicking Upload. Keep in mind that it may take a second or two for the changes to get sent over, depending on the size of your changes. In the meantime, PixelMaestro Studio will show the current progress of the transmission next to the Upload button.
This button also serves a dual purpose when writing to EEPROM, but I’ll explain this more in the next section.
Persisting Your Changes
Live Updates have one major drawback: as soon as you power off your device, all of your changes will be lost. Arduino’s memory space is volatile, and its contents are lost whenever it loses power. But Arduinos do, however, have a non-volatile memory space known as EEPROM. Using EEPROM, you can write your PixelMaestro Studio configuration to your device and reapply it on each reboot.
To do this, disconnect your device from PixelMaestro Studio and flash the PixelMaestro EEPROM sample sketch. Before reconnecting it to PixelMaestro Studio, select your device in the Device Tab and click Edit. Uncheck Live Updates, then click OK. Having Live Updates enabled will write all of your actions to EEPROM, which will reduce the lifespan of your EEPROM and likely cause unintended side effects. Once that’s done and the sketch uploaded, click Connect.
When you have your Animations, Canvases, and other effects configured the way you want, go back to the Device Tab. The File Size text box shows you the current size of your combined configurations (the Cuefile) in bytes. Make sure to compare this to your device’s EEPROM size. If your Cuefile is too big to fit into your EEPROM, nothing will be stored on your device. Arduino Unos can store 2,048 bytes in EEPROM, and Arduino Megas can store 8,192 bytes.
When you’re ready, click the Upload button. This will send your entire configuration to your device, and the Arduino will copy it to EEPROM. You can confirm this by resetting or unplugging your device and plugging it back in. After a few seconds, your last configuration should appear.
Peeking Under the Hood
If you want to see what customizations make up a Cuefile (or if you want to export a Cuefile as C++ code), open the Device Tab and click View. This opens a window showing each individual customization along with its description, the size of its corresponding Cue (in bytes), and its representation as a C-style array so you can copy it to a sketch or other program. For example, the second image in this post shows a screenshot of a Cuefile after we set the Maestro’s refresh interval, set the Section’s brightness, added a Radial animation, and set the Section’s scroll rate. Copying the code is useful if you want to create your own sketch and want to cherry-pick commands without having to recreate or rewrite them. Just follow the instructions for Running Cues in the wiki.
Conclusion
PixelMaestro and PixelMaestro Studio are still works in progress, but version 2.0 is a big step. Check it out by downloading the latest release and let me know what you think!
