Create and display colorful animations using the Microsoft Expressive Pixels Application and display them on your Adafruit Matrix Portal! 

In this guide, you will connect the Expressive Pixels Windows app with an Adafruit Matrix Portal  RGB LED matrix panel to:

  • display dazzling animations on the RGB LED matrix
  • save images directly to the Matrix Portal using its built-in flash chip
  • trigger animations using the Matrix Portal's GPIO pins. 

The ExpressivePixels open-source firmware can run on a variety of different types of hardware. We've collaborated with Microsoft to create a platform implementation for the Adafruit Matrix Portal using the Adafruit_Protomatter RGB Matrix library

About Expressive Pixels

Expressive Pixels is a Microsoft Research project that combines an Open-Source embedded firmware with an application which lets you create, manage, and display animations on colorful RGB displays (or RGB Matrix shields).

Click here for more info about Expressive Pixels...

Expressive Pixels works with 32x64 and 32x32 matrices. 64x64 matrices are NOT supported!

Parts

The firmware in this guide is was designed for the Adafruit Matrix Portal add-on for RGB matrixes. 

Folks love our wide selection of RGB matrices and accessories, for making custom colorful LED displays... and our RGB Matrix Shields...

Adafruit carries a number of RGB LED Matrices, varying between the display resolution, space between LEDs (pitch) and whether rigid or flexible. Choose your favorite - larger pitch means the display is larger, width and height-wise but with the same number of pixels, and larger may be easier to read further away. Smaller for near your desk, for example.

Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them...
Bring a little bit of Times Square into your home with this totally adorable 5 inch square 32 x 32 RGB LED matrix panel. These panels are normally used to make video walls, here in New...
Bring a little bit of Times Square into your home with this 16 x 32 RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides...

If you'd like your LEDs diffused (and if your LED matrix is 4mm pitch or smaller), some dark acrylic may help:

A nice whoppin' slab of some lovely black acrylic to add some extra diffusion to your LED Matrix project. This material is 2.6mm (0.1") thick and is made of special cast...

You may use a USB C power supply or a USB micro B with a micro B to C adapter

As technology changes and adapts, so does Adafruit. This  USB Type A to Type C cable will help you with the transition to USB C, even if you're still...
The official Raspberry Pi USB-C power supply is here! And of course, we have 'em in classic Adafruit black! Superfast with just the right amount of cable length to get your Pi 4...
Our all-in-one 5V 2.5 Amp + MicroUSB cable power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's...
As technology changes and adapts, so does Adafruit, and speaking of adapting, this adapter has a Micro B USB jack and a USB C...

The ExpressivePixels open-source firmware can run on a variety of different types of hardware. We've collaborated with Microsoft to create a platform implementation for the Adafruit Matrix Portal.

The firmware on this page provides the underlying C code for driving RGB matrixes using the Adafruit_Protomatter library and the ExpressivePixels firmware for communicating with the ExpressivePixels Windows app.

Install Expressive Pixels

Follow the steps below to install the Expressive Pixels firmware on your Matrix Portal.

Click the link below to download the UF2 that matches your RGB matrix resolution.

Download and save it to your desktop (or wherever is handy).

Plug your Matrix Portal M4 into your computer using a known-good USB cable.

A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.

Double-click the Reset button (indicated by the green arrow) on your board, and you will see the NeoPixel RGB LED (indicated by the magenta arrow) turn green. If it turns red, check the USB cable, try another USB port, etc.

If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!

You will see a new disk drive appear called MATRIXBOOT in your computer file explorer/finder.

Drag the ExpressivePixels-MatrixPortal-etc.uf2 file to the MATRIXBOOT drive.

The MATRIXBOOT drive will disappear and the NeoPixel on the back of your Matrix Portal should glow white while the red LED flashes.

That's it, you're done!

The following step is optional and for advanced users.

(Optional) Change the Display Matrix Size

If you're using the Matrix Portal with a different sized RGB Matrix, you can edit the firmware within the Arduino IDE to specify a new resolution.

To start, you'll need the latest version of the Arduino IDE installed on your computer.

Follow the links on the ExpressivePixels Wiki Page for the Matrix Portal M4 to install the library dependencies to compile the firmware.

  • Note: Some of these libraries such as LittleFS and Express Pixels Arduino are not available from the Arduino library manager. You will need to manually add these libraries to the Arduino IDE's library directory.

Next, download the ExpressivePixels firmware to your computer and save it to your desktop. 

Open the Arduino IDE. Within Arduino, open the ExpressivePixels.ino sketch.

This sketch contains a file named config.h where you can edit the configuration for your matrix.

In the Arduino IDE menubar, click the config.h tab.

Scroll down until you see the following code:

The Matrix Portal is defined as a DISPLAY_MATRIX64x32 in the code. Change DISPLAYARRAY_WIDTH to reflect your RGB LED Matrixes' width and DISPLAYARRAY_HEIGHT to reflect the RGB LED Matrixes' height.

Next, verify that you are using the TinyUSB stack.

Under Tools > USB Stack, select TinyUSB.

Then, upload the firmware to your Matrix Portal.

To use Expressive Pixels, you need a Windows 10 PC with the May 2019 operating system update (version 18362.0) or higher. You can determine the version by going to STart -> Gear Icon (Settings) - System -> About and the info is at the bottom of the listed text.

On a Windows 10 computer, click the button below to download the Expressive Pixels App from the Microsoft Store.

In the Microsoft Store, click Install to install the Expressive Pixels application to your computer. 

Once installed, click the Launch button in the Microsoft Store to launch Expressive Pixels.

Expressive Pixels will launch and display a safety warning for those with photosensitive epilepsy or light sensitivities.

Click Acknowledge

The animations have blinking lights - it could trigger someone with sensitivities. Please be sure you'll be ok (or have someone else program things) if you have photosensitive epilepsy or light sensitivities.

Next, we'll connect the Matrix Portal to Expressive Pixels and start creating animations!

Connect to the Matrix Portal

Make sure your Matrix Portal is plugged into your computer via a known-good USB power+data cable (not the power-only cables that come with USB power banks). Then, launch the Expressive Pixels application.

In Expressive Pixels, click the Menu icon.

Click the Devices button.

Expressive Pixels should find the Matrix Portal connected to your computer. Click Connect and wait until the device is connected.

Once connected, clicking the Devices button again will bring up a menu for the Connected Device. From this menu, you can rename the device, check its battery level, and configure its brightness.

We have a collection of 64x32 animations you can download here for importing into the application

Drag the EPX files to your Documents/ExpressivePixels folder

Hovering over any animation on the My Animations page will automatically preview the animation on your device.

Matrix Portal not listed under Available Devices?

First, check that the Matrix Portal is not listed as a removable drive on your computer named MATRIXBOOT.

Then, following the steps on the previous page, re-flash the ExpressivePixels firmware to your Matrix Portal. 

Still an Issue - perhaps use a different USB cable or USB port.

Creating an Image

Next, let's create an image using Expressive Pixels.

In Expressive Pixels, Click the New Animation Button 

Enter the dimensions of your LED matrix. Then, click the '+' button to be brought to the Authoring Screen.

  • If the default array dimension specified in this window does not match your matrix's size, make sure the name of the firmware you downloaded contains the dimensions of your matrix.

Follow the tutorial video below from Microsoft Research to learn how to create an image and save it to your Animation Gallery.

Creating Animations

You can also create and save animations by adding frames and transitions to your images. 

Storing Animations on the Matrix Portal

You can store animations on the Matrix Portal's built-in SPI flash chip. Animations stored on the Matrix Portal will play on the Matrix Portal without the need to connect to your computer over USB.

Under My Animations, right-click on the animation you'd like to store on your Matrix Portal. 

From the menu, select Store to device.

After successfully storing an animation on the Matrix Portal, you can manage animations stored on your device within the Device Animations page.

On the sidebar menu, click the Device Animations button.

On this page, you can view and delete the animations stored on the Matrix Portal. The total storage left on your Matrix Portal's flash memory is displayed at the top of the page.

To play animations stored on the Matrix Portal, Click the Devices tab.

Under Connected Device, click the Disconnect button to disconnect your Matrix Portal. 

The reset button is located at the top of your Matrix Portal. Click it once to reset the Matrix Portal

Once the Matrix Portal resets, it will display animations on the RGB LED matrix in a loop. Connecting the Matrix Portal to the Expressive Pixels app will put the portal back in "authoring mode" and stops the animation loop.

Triggering Animations on the Matrix Portal

You can trigger a stored animation to display on a RGB Matrix using one of the Matrix Portal's four analog input pins (A1 through A4). A good method of triggering an animation is by wiring one of these inputs to a physical button (check out the selection of buttons in the Adafruit shop) or switch.

Within the Expressive Pixels app menu, click Developer Console.

  • If you do not see the COM# CONNECTED message on the Developer Console, make sure you are connected to the Matrix Portal.

Next, enter the following command in the console. Change A1 to the name of the GPIO pin you want use for triggering animations. Change Weather to the name of the animation you'd like to display.

SWITCHACTIVATION ADD A1 Weather

Press Enter. The Developer Console should show the command you just entered and "success" if the command was successful.

You can now try triggering an animation by pressing the button you wired up, or by using a wire to connect the GPIO pin to the Matrix Portal's GND pin.

This guide is designed to get you started using the Expressive Pixels application with the Matrix Portal. Below are some resources for taking your Expressive Pixels project further.

Tips and Tricks

This guide covered the basics of creating, saving and playing an animation using Expressive Pixels. If you want to learn more about the Expressive Pixels app's advanced authoring tools - Microsoft Research hosts a website with video tutorials for Expressive Pixels. Topics covered range from using layers to importing GIFS to use as animations.

Technical Information

The firmware which runs on the Matrix Portal is open source. Check out the ExpressivePixels GitHub repository for this project to view the source code and learn more.

This guide was first published on Dec 11, 2020. It was last updated on Dec 11, 2020.