SmartMatrix Library for Teensy 3, Teensy 4, and ESP32

SmartMatrix Library is designed to refresh HUB75 LED matrix panels and APA102-compatible addressable LEDs with high quality graphics, using simple Arduino sketches.

<img src="https://github.com/pixelmatix/SmartMatrix/wiki/photos/examples.gif" alt="" width="50%"/> 128x64 HUB75 Panel Driven with SmartLED Shield for Teensy 4

SmartMatrix Library 4 has support for Teensy 4.1, Teensy 4.0, Teensy 3.6, Teensy 3.5, Teensy 3.2/3.1, Teensy 3.0, as well as experimental support for ESP32.

The code to refresh HUB75 panels takes advantage of platform-specific peripherals like DMA, I2S, FlexIO, and once started runs in the background using interrupts. It takes a lot of work to port SmartMatrix Library to a new platform. We're working on an open source solution that will allow a lot more platforms to drive HUB75 panels, sign up for updates here if you're interested.

The documentation in this README contains the basic information you may need to run your first SmartMatrix Library sketch, but there is more detailed documentation in the SmartMatrix Wiki.

Hardware

SmartMatrix Library runs best on the Teensy 4.0 and 4.1 using the SmartLED Shield for Teensy 4, available from distributors in the US and China. If you want to use the less powerful but more mature Teensy 3, you can use the SmartLED Shield for Teensy 3, available from Adafruit, SparkFun, Digi-Key, and other distributors around the globe. The shield doesn't require any soldering to get started, besides putting pins on your Teensy board.

<img src="https://github.com/pixelmatix/SmartMatrix/wiki/photos/slsv4.jpg" alt="" width="50%" /> SmartLED Shield for Teensy 3 - Photo Courtesy Adafruit

There's an adapter PCB design to upgrade SmartLED Shield for Teensy 3 to work with the Teensy 4.

You can wire up a bare Teensy 3.x to a HUB75 panel, but at a minimum it's recommended to use 5V level shifters to drive the panels with the voltage level they are expecting. There's a recommended circuit with latch chip to use with the Teensy 3 that will reduce the amount of pins used. The Teensy 4 requires an external latch.

The shields are Open Source Hardware, with design files posted in the /extras/hardware/ directories.

Documentation for the SmartLED Shield Hardware is available here: SmartMatrix Docs

Teensy 4

Teensy 4 support was contributed by Eric Eason

Teensy 4 APA102 support depends on FlexIO_t4 by KurtE, which is included as a submodule in src/lib/. The original FlexIO_t4 library is on GitHub

ESP32

The ESP32 platform is supported with SmartMatrix Library 4.0, but not all features are up to par with the Teensy 3/4 ports. For details on the ESP32 port, see the Wiki

Changes from SmartMatrix Library 3.x

Sketches written for SmartMatrix Library 3.x should work with SmartMatrix Library 4.0 with a few changes.
See MIGRATION.md for details on how to update your SmartMatrix Library 3.x sketches for SmartMatrix Library 4.x
A lot of files were subtly renamed, just changing the case. If you're trying to use git to check out a commit and get an error like The following untracked working tree files would be overwritten by checkout, you may need to use git from the command line and add the -f parameter to force checkout (throwaway local modifications), as your git client might think it's overwriting the case-changed files and losing data.

New Features in SmartMatrix Library 4.0

Support for Teensy 4 and ESP32
Support for driving APA102 LEDs on Teensy platforms
New "GFX" layers rewritten for better efficiency, and using Adafruit_GFX for drawing, fonts, including much larger fonts
Support for panels with non-standard mapping, e.g. 16x32/4 (MOD4) panels
See more features in the SmartMatrix Wiki

HUB75 Panels

HUB75 RGB panels are typically used for LED billboards (e.g. Times Square), making them cost-effective and readily available. They’re much cheaper per-pixel than addressable LEDs, and available in a wide range of pixel pitch (as of now, 2 mm spacing up to 10 mm spacing per LED). They do require an external controller to continually send data to the panels to refresh them line by line, and that’s where the SmartLED Shield and SmartMatrix library come in. Adafruit, Sparkfun, and other distributors carry panels that are known to be compatible with SmartLED Shield and the SmartMatrix library, but most panels on AliExpress and other sources are compatible as well.

The pixel pitch and "RGB" are good search terms on Aliexpress, e.g. "P6 RGB" for a 6 mm pitch RGB HUB75 panel.

<img src="https://github.com/pixelmatix/SmartMatrix/wiki/photos/hub75panels.jpg" alt="" width="50%" /> HUB75 Panels Ranging from P2 to P10 pitch

Getting Started

To download in Arduino Library form, see Releases on GitHub, or use Arduino Library Manager.

Software and Teensy Setup

This documentation assumes you have a general knowledge of the Teensy 3 or Teensy 4, how to use the Arduino IDE, and the Teensyduino addon. If you need an overview of any of those tools, please use these references:

PJRC - Teensyduino
Arduino - Getting Started with Arduino
For general Teensy support, not related to the SmartMatrix Shield or SmartMatrix Library, post a question at the PJRC Forum

Make sure you have a supported version of the Arduino IDE and Teensyduino add-on installed.

Arduino IDE - version 1.6.5 or later recommended
Teensyduino - use the latest version

Before continuing, use the blink example in the Arduino IDE to verify you can compile and run a sketch on your Teensy 3.1/3.2.

Download the latest version of the SmartMatrix Library, or install it from Arduino Library Manager:
SmartMatrix Releases - GitHub

Note: "SmartMatrix" Library used to be listed in Arduino Library Manager under "SmartMatrix3". You may need to look for the library in Arduino Library Manager or your libraries folder under either "SmartMatrix" or "SmartMatrix3" as we transition to the new name.

If you're not using Arduino Library Manager, you need to import the library into Arduino, see instructions from Arduino here:
Arduino - Libraries

Some of the examples depend on other libraries, which you can download separately, or install from Arduino Library Manager. See "External Libraries" below.

Start with the FeatureDemo Example project, included with the library. From the Arduino File menu, choose Examples, SmartMatrix3 (or SmartMatrix), then FeatureDemo.

Find the section at the top with the note // uncomment one line to select your MatrixHardware configuration, and uncomment the file appropriate for your hardware.

You should already have most of the correct Arduino settings to load the FeatureDemo sketch on your Teensy, from running the blink example earlier. For Teensy 3: under Tools, CPU Speed, make sure either 48 MHz or 96MHz (overclock) is selected. (Some libraries are not compatible with the 72MHz CPU). For Teensy 4, use the default CPU speed.

The examples are configured to run on a 32x32-pixel panel. If your resolution is different, adjust the kMatrixWidth and kMatrixHeight variables at the top of the sketch. You may also need to change kPanelType. Some common kPanelType settings:

32-pixel high panels, e.g. 32x32, 64x32: SM_PANELTYPE_HUB75_32ROW_MOD16SCAN
16-pixel high panels, e.g. 32x16: SMARTMATRIX_HUB75_16ROW_MOD8SCAN
64-pixel high panels, e.g. 64x64, 128x64: SM_PANELTYPE_HUB75_64ROW_MOD32SCAN
For other less common panels, see more details in MatrixCommonHub75.h and [the wiki][https://github.com/pixelmatix/SmartMatrix/wiki)

You can chain several panels together to create a wider or taller display than one panel would allow. Set kMatrixWidth and kMatrixHeight to the overall width and height of your display. If your display is more than one panel high, set kMatrixOptions to how you tiled your panels:

Panel Order - By default, the first panel of each row starts on the same side, so you need a long ribbon cable to go from the last panel of the previous row to the first panel of the next row. SM_HUB75_OPTIONS_C_SHAPE_STACKING inverts the panel on each row to minimize the length of the cable going from the last panel of each row the first panel of the other row.
- Note SM_HUB75_OPTIONS_C_SHAPE_STACKING isn't compatible with panels that require the Multi Row Refresh Mapping feature (if your kPanelType value includes the column size, it likely requires Multi Row Refresh Mapping, e.g. SM_PANELTYPE_HUB75_16ROW_32COL_MOD2SCAN)
Panel Direction - By default the first panel is on the top row. To stack panels the other way, use `SM_HUB

SmartMatrix

Install / Use

README