Driving Matrix Orbital LCD Displays with Python

Admittedly, this post is even more “techie” than my last one on hardware RNGs. I feel compelled to deliver the same public service announcement: If learning how to use python to drive a Matrix Orbital display is not your cup of tea, this might be a hard pass. Otherwise, read on if you’re technically curious. If I can save one person hours of work, then the effort was well worth it.

I’m a big fan of the Matrix Orbital VK204-25 LCD module and have used it in a bunch of projects. It’s an older device, but you can’t beat how good the throwback vacuum fluorescent display looks when you want a retro type aesthetic.

A new module can be expensive, however, you can find older ones relatively cheap on eBay if you keep your eyes open.

The older boards communicated over either I2C or RS232. I prefer using I2C as my projects typically use Raspberry Pis, and the GPIO includes native support. I’m not going to spend any time here on how to connect the module to a Pi as Adafruit has a wonderful in-depth tutorial on interfacing Pis with I2C components.

When I first started using these displays I was surprised (and frustrated) that there were limited python libraries available for driving the display over I2C. I eventually decided to hack together my own since the command structure is well documented and easy to implement with python’s smbus module. You can find my code here.

Usage is straight forward. Characters to display on the LCD are chosen by using the correct binary or hex value. The Matrix Orbital documentation includes a matrix that maps each ASCII character to the appropriate hex code.

The script takes a single word as input, iterates over each character in the word to find the corresponding hex value and then sends the display command using the board’s bus address.

In addition to the character mappings, the script includes a few basic commands that can turn the display on or off or clear any text.

Here are a few usage examples. First, turning on the display:


busAddr is the I2C address for the board. You can determine this on a Raspberry Pi by using the i2cdetect command as discussed here. If my board was addressed using 0x28 I would issue the following:


Here the script will use the busAddr, send 0xFE (a code prefix that indicates a control command is being issued), and then send the hex value for the command itself. In the above case 0x42, which means turn on the display.

Here’s how to write single or multiple words to the display:


busAddr is the board I2C address and wordDisp is the word to display. For example:

orbitalWrite.write_display(0x28,some words here)

Behind the scenes, the script will iterate through each letter (including spaces) and send each character individually to the display.

Just for fun, I included a timer as part of the character display function so that there’s a slight pause of random length before writing. The effect is like an old style typewriter.

That’s it! If you have a Matrix Orbital display and use my code, drop me a line and let me know about your project.