SmartMatrix Library 4.0 - Changes to MatrixHardware #includes

When SmartMatrix Library 3.0 was released, there was only one processor family supported (the Teensy 3.x), and only one type of SmartMatrix Shield. Now there’s two types of shields for the Teensy 3, preliminary ESP32 support with many potential hardware configurations, and Teensy 4 support is coming with multiple possible hardware configurations as well.

With SmartMatrix Library 4.0, I’m planning to make it easier (and mandatory) to choose the hardware configuration in the sketch. It will also be possible to use a custom hardware configuration without modifying the library by adding a file into the sketch directory.

Selecting Hardware Configuration

For all projects, a MatrixHardware*.h file must be included before including <SmartMatrix4.h>

#include <MatrixHardware_KitV4.h>
//#include <MatrixHardware_KitV1.h>
#include <SmartMatrix4.h>

If there’s no MatrixHardware file included, the compiler will throw an error:

No MatrixHardware*.h file included - You must include one at the top of your sketch

If you accidentally include multiple files, a different error:

Multiple MatrixHardware*.h files included - Only include one MatrixHardware file at the top of your sketch

The MatrixHardware configuration will be printed out with a message in the compiler output, e.g.: #pragma message "MatrixHardware: SmartLED Shield V4"

Custom MatrixHardware File

If the files included with the library aren’t suitable, you can copy the closest pinout to what you need from the library to your sketch directory, tweak it to your liking, and include it in your sketch:

#include "MatrixHardware_KitV4_custom.h"
//#include <MatrixHardware_KitV4.h>
#include <SmartMatrix4.h>

To handle the case where a HUB75 panel manufacturer has used non-standard color order in their HUB75 pinout, you can swap the order in the MatrixHardware file.


Does this new method seem like a good improvement? Did I overlook anything that might be useful?

@marcmerlin I’m particularly interested in hearing your opinion on this, as you’ve added a number of ESP32 alt configurations, plus you added the #pragma message displaying board type, which I’ve found to be very useful

Thanks for the ping. I think that’s a better solution than having ever more ifs in a file that you maintain, and allows for someone to have their local definition in their sketch without modifying the lib.
I assume this will break ESP32 users right now, but that’s fine with me, it’s not like it was a supported platform anyway and it probably doesn’t have too many users.
While you’re at it, if you can coordinate this with a merge of teensylc back in master, maybe even merge teensylc into master first and then make your change, so teensylc keeps the old unsupported way, and master now supports ESP32 with the new way.

The plan is to migrate the teensylc branch to a new SmartMatrix Library 4 repo, where it will be released in parallel with SmartMatrix Library 3, not replacing. If I used the existing SmartMatrix Library 3 repo for SmartMatrix Library 4, someone could upgrade their library using Arduino Library Manager, and then wonder why their existing sketches don’t compile (because of the MatrixHardware headers at a minimum, and possibly other changes).

You make a good point though about introducing major changes to the teensylc branch, as enough people are using it that it would probably cause confusion if I quietly introduced these MatrixHardware header changes to that branch.

I prototyped the MatrixHardware changes, and edited the examples to show how different boards can be selected. The ESP32 file hasn’t been split out into several individual files yet. It’s in a separate branch, not teensylc, and I don’t plan on merging it into teensylc. (As of now, the plan is for this “NT” branch to be merged into “teensy4”, and “teensy4” will eventually become SmartMatrix Library 4 in a new repo)

I’ve already made some changes to allow for easier customization of the Teensy 3 MatrixHardware files to rearrange RGB pins (and made it more clear what can be tweaked by the user, and what should be left alone):

1 Like