SmartMatrix Library 4.0

This release adds support for Teensy 4, new Layers compatible with Adafruit_GFX, limited ESP32 support, and a lot of the core code was refactored.

There are some minor changes needed to migrate a SmartMatrix 3.x sketch to SmartMatrix 4.0, see MIGRATION.md for more details

To get this release on Arduino Library Manager, install "SmartMatrix". Previously SmartMatrix Library 3.x was available on Arduino Library Manager under "SmartMatrix3".

Big thanks to @easone for contributing the Teensy 4 support!

64x64 /32 Panel Support

New Feature

• Support for 64x64 /32 panels with SmartLED Shield V4
  • Enable by setting kPanelType = SMARTMATRIX_HUB75_64ROW_MOD32SCAN
  • These panels are available in high density 2-3mm/pixel, e.g. these 3mm panels available from Adafruit and SparkFun
  • Be careful when buying from other vendors, e.g. Aliexpress, as some of these panels only have two address lines "AB", and these are not compatible with SmartMatrix Library. Look for 5x address lines "ABCDE" and make sure your vendor actually ships you a panel that matches the photos in their listing. (More details here)

Misc

• SmartLED Shield V4 is now the default config in the included examples, so the #include <SmartLEDShieldV4.h> line is now uncommented by default. Make sure to comment out this line if using SmartMatrix Shield V3 or earlier or driving panels directly from the Teensy (or though a buffer, not a latch).

Support for Teensy 3.5/3.6 and SmartLED Shield V4

New Features

• Initial support for Teensy 3.5/3.6
  • Workaround for other DMA use (e.g. SDIO) delaying shifting data out to panel and messing up timing
  • Workaround for faster clock speed of Teensy 3.5/3.6 shifting out data too fast to panel and causing glitches (observed at 140MHz and higher)
• Support for new SmartLED Shield V4 (formerly "SmartMatrix Shield")
  • SmartLED Shield V4 hardware design added to /extras/hardware folder
  • ADDX signals are now output on matrix data lines, to be stored by external 74AHCT374 flip flop, triggered by LATCH signal. Driving ADDX pins separately via Teensy pins is now optional, for more efficient DMA usage and savings of 4 GPIO pins over SmartMatrix Shield V3 and earlier.
  • Add extra #include <SmartLEDShieldV4.h> to all examples. Needs to be uncommented if using SmartLED Shield V4

Bug Fixes

• Fix bug when using swapBuffers(false) and backBuffer() - add new isSwapPending() function

Misc

• Bring AnimatedGIFs sketch up to date
  • Add SmartLED Shield V4 and Teensy 3.5/3.6 support
  • Refactored with GifDecoder class that uses templates to set the max size of the GIF and LZW decoder complexity: GIF Decoding is now a lot more stable
• Added example for SmartMatrix Library V4: FastLED_Panel_Plus_APA. Example shows how to set up FastLED to drive APA102 LEDs through the 4-pin JST connector on the SmartLED Shield, in parallel with driving the panel.

Support for Arduino 1.6.8 and Teensyduino 1.28

This minor release is specifically to add compatibility with Arduino 1.6.8 and Teensyduino 1.28

New Features

Support for Arduino 1.6.8 and Teensyduino 1.28

Bug Fixes

Increment row after loadMatrixBuffers() call to avoid tearing appearance on row 0

Misc

FastLED Compatibility Change - SmartMatrix Library now requires FastLED 3.1 or higher

Note: Version 3.0.1 and the Version 3.0.2 you may see in the Arduino Library Manager are identical

SmartMatrix 3

SmartMatrix Library v3 is a major update focused on supporting larger sized panels, and separating the Layer code from the Refresh code. A single version of the library can support all panel sizes in contrast to the separate releases for SmartMatrix_32x32 and SmartMatrix_16x32 before. The library is not backwards compatible with sketches created for SmartMatrix 2.x, but by following the MIGRATION.md document you can update your sketch by using find and replace in your text editor. You can have SmartMatrix3 installed in parallel with an existing SmartMatrix_32x32 or SmartMatrix_16x32 library without conflicts.

Big thanks to contributors @gregfriedland and @mrwastl for extensive help with this release.

New Features

Support for chaining panels to create larger matrix

• Combine several panels to make a long chain, or stack chained panels in a Z or C shape to make a larger display
• Largest supported sizes: 64x64-pixel or 32x128-pixel display using 4x 32x32 panels - 90Hz refresh rate with Teensy 3.1 at 96MHz. Even larger sizes are possible (e.g. 96x64 by sacrificing refresh rate and color depth).
• Examples are set to 32x32 by default, but can run at larger resolutions just by changing the kMatrixWidth and kMatrixHeight constants in the sketch
• Thanks @ncortot, @GaryBoone, and @mrwastl for pioneering this feature, and @mrwastl for testing and feedback during v3 development

Support for configuring library in sketch

• User-configuration options include: matrix size, layer color depth, refresh color depth, refresh buffer sizes, panel type, refresh and layer options.
• Thanks @gregfriedland for setting up the library for C++ templates.

New Layer class and Background, Scrolling, and Indexed Layers

• Include just the layers you need for your sketch, saving resources on the Teensy
• Add multiple transparent Layers e.g. multiple scrolling text layers (see MultipleTextLayers example)
• It's possible to create a custom Layer in your sketch (see the port of Fadecandy firmware to SmartMatrix for an example)
• Layer-specific methods were moved from the SmartMatrix class to the appropriate Layer class: e.g. matrix.scrollText() is now scrollingLayer.start()
• The new Indexed Layer can be used to draw simple graphics (1 bit per pixel with transparency) to the screen while saving memory. The buffers for a 32x32-pixel Indexed layer are only 256 bytes, vs 6kB using the Background layer.
• Library examples were reworked to use the minimum number of layers and demonstrate the new Layer features

Improvements

Refresh code now recovers from refresh rate being set too high instead of crashing

• If the refresh code can't keep up with with the current refresh rate, it blanks the screen until it's caught up, and automatically lowers the refresh rate by 1Hz to move toward a sustainable refresh rate
• If the refresh code is just barely keeping up but not allowing the sketch to run, it lowers the refresh rate by 1Hz until the sketch has time to run.

Refresh rate calculation is now accurate; in SmartMatrix 2.x the calculation was off by around 10%. The default refresh rate used to be 135Hz which resulted in an actual refresh rate of 120Hz. The default is now an accurate 120Hz.

AnimatedGIFs example now has a more accurate GIF decoding framerate, and has initial support for larger display sizes (works at 64x64 and 32x128 with minor modifications).

Retired

Support for FastLED's SMART_MATRIX controller (though SmartMatrix still works with FastLED!)

• The SMART_MATRIX controller was based on SmartMatrix 2.x, and is incompatible with SmartMatrix 3
• The FastLED_Controller example is removed, but FastLED_Functions with the same functionality still works
• See the MIGRATION.md document for how to modify sketches like FastLED_Controller for SmartMatrix 3
• Let us know if you want to see support for the FastLED SMART_MATRIX controller in the future

Note for Beta Testers

The changes since SmartMatrix 3 - Beta 1 are minimal:

• The variables used for dimensions and coordinates for the Layer class and for drawing are now uint16_t/int16_t to support a 256-pixel wide display. (Briefly tested with a 16x256 display - this may be officially supported in the future)
• You can now compile with Teensyduino option USB Type: "No USB"

SmartMatrix 3 - Beta 1

SmartMatrix Library v3 is a major update focused on supporting larger sized panels, and separating the Layer code from the Refresh code. A single version of the library can support all panel sizes in contrast to the separate releases for SmartMatrix_32x32 and SmartMatrix_16x32 before. The library is not backwards compatible with sketches created for SmartMatrix 2.x, but by following the MIGRATION.md document you can update your sketch by using find and replace in your text editor.

Big thanks to contributors @gregfriedland and @mrwastl for extensive help with this release.

New Features

Support for chaining panels to create larger matrix

• Combine several panels to make a long chain, or stack chained panels in a Z or C shape to make a larger display
• Largest supported sizes: 64x64-pixel or 32x128-pixel display using 4x 32x32 panels - 90Hz refresh rate with Teensy 3.1 at 96MHz. Even larger sizes are possible (e.g. 96x64 by sacrificing refresh rate and color depth).
• Examples are set to 32x32 by default, but can run at larger resolutions just by changing the kMatrixWidth and kMatrixHeight constants in the sketch
• Thanks @ncortot, @GaryBoone, and @mrwastl for pioneering this feature, and @mrwastl for testing and feedback during v3 development

Support for configuring library in sketch

• User-configuration options include: matrix size, layer color depth, refresh color depth, refresh buffer sizes, panel type, refresh and layer options.
• Thanks @gregfriedland for setting up the library for C++ templates.

New Layer class and Background, Scrolling, and Indexed Layers

• Include just the layers you need for your sketch, saving resources on the Teensy
• Add multiple transparent Layers e.g. multiple scrolling text layers (see MultipleTextLayers example)
• It's possible to create a custom Layer in your sketch (example coming soon)
• Layer-specific methods were moved from the SmartMatrix class to the appropriate Layer class: e.g. matrix.scrollText() is now scrollingLayer.start()
• Library examples were reworked to use the minimum number of layers and demonstrate the new Layer features

Improvements

Refresh code now recovers from refresh rate being set too high

• If the refresh code can't keep up with with the current refresh rate, it blanks the screen until it's caught up, and automatically lowers the refresh rate by 1Hz instead of crashing
• If the refresh code is just barely keeping up but not allowing the sketch to run, it lowers the refresh rate by 1Hz until the sketch has time to run.

Refresh rate calculation is now accurate; in SmartMatrix 2.x the calculation was off by around 10%. The default refresh rate used to be 135Hz which resulted in an actual 120Hz. The default is now an accurate 120Hz.

AnimatedGIFs example now has a more accurate framerate, and has initial support for larger display sizes (works at 64x64 and 32x128).

Retired

Support for FastLED's SMART_MATRIX controller (though SmartMatrix still works with FastLED!)

• The SMART_MATRIX controller was based on SmartMatrix 2.x, and is incompatible with SmartMatrix 3
• The FastLED_Controller example is removed, but FastLED_Functions with the same functionality still works
• See the MIGRATION.md document for how to modify sketches like FastLED_Controller for SmartMatrix 3
• Let us know if you want to see support for the FastLED SMART_MATRIX controller in the future

Version 2.2

New Features

• All examples work with both 16x32 and 32x32 panels
• New example: MatrixClock - shows how to use I2C with SmartMatrix and RTC module
• Modified example: Bitmaps (was BitmapTest) - support for 16x32 panel, support for smaller bitmaps, easier to read
• New drawEllipse function (Thanks @echamberlain)
• New updateScrollText function (Thanks @twonk)

Bugfixes

• Can now see experimental static foreground drawing functions without scrolling text first

Misc

• Better comments in example headers
• Updated Hardware folder with latest designs
• Fixed keywords.txt (was using spaces instead of tabs)

Support for Teensy Audio Library

Major New Features

• Support for Teensy Audio Library, included with Teensyduino 1.20
• New SpectrumAnalyzer Example Sketch to demonstrate using Teensy Audio Library with SmartMatrix
• AnimatedGIFs example now uses built in Arduino Sd library instead of SdFat

Bug Fixes

• AnimatedGIFs has support for more GIF files

Misc

• AnimatedGIFs now displays error messages to the screen and Serial when it can't play any GIF files
• Included example GIFs for AnimatedGIFs

Version 2.0 - 36-bit Color, FastLED Support, AnimatedGIFs example

Major New Features

• 36 and 48-bit color support
• FastLED library support (thanks @focalintent)
  • Support for using the FastLED library helper functions with a normal SmartMatrix sketch
  • Support for using FastLED's "SMART_MATRIX" controller
  • Depends on using a recent copy of the FastLED2.1 Branch from here https://github.com/FastLED/FastLED
  • See examples for two sketches showing two ways to use FastLED
• AnimatedGIFs example (thanks @craiglindley)
• Adjustable background layer brightness through gamma correction lookup table
• Added new font "gohufont" with regular and bold versions (thanks @TwystNyko)
• Added experimental foreground drawing routines - can set individual pixels in the foreground layer in addition to scrolling text
• More control over scrolling text
  • new scroll mode wrapForwardFromLeft, which starts text at the left edge of the screen, then wraps just like wrapForward (thanks @pup05)
  • setScrollStartOffsetFromLeft() - sets the position where text starts scrolling for the
  • setScrollOffsetFromEdge() to setScrollOffsetFromTop() to clarify position

Bug fixes

• Fix several corner cases in fillRectangle (thanks @Vipor26 and @craiglindley)
• Draw single point circle with radius of 0 (thanks @pup05)

Misc

• changed swapBuffers() so it can return immediately without copying on swapBuffers(bool copy = false), allows applications that fill the full frame before each swapBuffers() call to run at a higher frame rate.
• Optimizations to refresh routines (thanks @ecdr and @focalintent)
• Arduino Keywords.txt, more readable MatrixForeground and DMA code (thanks @Vipor26)

Initial Public Release

Initial Public Release

Changes from last beta version:

• Tested compatibility with Teensyduino 1.18
• Added support for new Teensy 3.1 48MHz option available in Teensyduino 1.18
• Changed defaults to full brightness and 120Hz refresh rate
• Removed MatrixHardware_KitV2_.h, use MatrixHardware_KitV1_.h instead (keeping naming of header consistent with V1 of the hardware)