leddisplay/libraries/SmartMatrix/MIGRATION.md

Migrating from SmartMatrix 2.x to SmartMatrix 3.0

SmartMatrix 3.0 has separated out the single SmartMatrix class into a core class for refreshing the display, and separate layer classes for storing data. The library is not backwards compatible with sketches created for SmartMatrix 2.x, but by following this document it should be relatively easy to update your sketches to get access to the new features. You can have SmartMatrix3 installed in parallel with an existing SmartMatrix_32x32 or SmartMatrix_16x32 library without conflicts.

(If you're Updating a sketch using FastLED's SMART_MATRIX controller, see the "Update FastLED Sketch" section later in the document)

Updating Normal SmartMatrix Sketch

#Include

The Library is now named "SmartMatrix3" to avoid conflicts with the previous versions of the library. Replace the #include at the top of the sketch.

#include <SmartMatrix_32x32.h>

replace with:

#include <SmartMatrix3.h>

At this point if you try to compile you'll get a lot of errors like this:

'class SmartMatrix' has no member named 'setScrollOffsetFromEdge'

or like this:

'MATRIX_WIDTH' was not declared in this scope

Allocation

This single line needs to be replaced with a large section, as your sketch can now set a lot of options instead of being limited to the defaults of the library.

SmartMatrix matrix;

Replace with:

#define COLOR_DEPTH 24                  // known working: 24, 48 - If the sketch uses type `rgb24` directly, COLOR_DEPTH must be 24
const uint8_t kMatrixWidth = 32;        // known working: 32, 64, 96, 128
const uint8_t kMatrixHeight = 32;       // known working: 16, 32, 48, 64
const uint8_t kRefreshDepth = 36;       // known working: 24, 36, 48
const uint8_t kDmaBufferRows = 4;       // known working: 2-4, use 2 to save memory, more to keep from dropping frames and automatically lowering refresh rate
const uint8_t kPanelType = SMARTMATRIX_HUB75_32ROW_MOD16SCAN;   // use SMARTMATRIX_HUB75_16ROW_MOD8SCAN for common 16x32 panels
const uint8_t kMatrixOptions = (SMARTMATRIX_OPTIONS_NONE);      // see http://docs.pixelmatix.com/SmartMatrix for options
const uint8_t kBackgroundLayerOptions = (SM_BACKGROUND_OPTIONS_NONE);
const uint8_t kScrollingLayerOptions = (SM_SCROLLING_OPTIONS_NONE);
const uint8_t kIndexedLayerOptions = (SM_INDEXED_OPTIONS_NONE);

SMARTMATRIX_ALLOCATE_BUFFERS(matrix, kMatrixWidth, kMatrixHeight, kRefreshDepth, kDmaBufferRows, kPanelType, kMatrixOptions);
SMARTMATRIX_ALLOCATE_BACKGROUND_LAYER(backgroundLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kBackgroundLayerOptions);
SMARTMATRIX_ALLOCATE_SCROLLING_LAYER(scrollingLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kScrollingLayerOptions);
SMARTMATRIX_ALLOCATE_INDEXED_LAYER(indexedLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kIndexedLayerOptions);

The options are the defaults for a 32x32 pixel panel, similar defaults to the SmartMatrix_32x32 library. If you are using a 16x32 panel, change kMatrixHeight to 16, and kPanelType to SMARTMATRIX_HUB75_16ROW_MOD8SCAN.

At this point if you try to compile, you'll get a lot of errors like:

'class SmartMatrix3<36, 32, 32, 0u, 0u>' has no member named 'setScrollOffsetFromEdge'

Setup()

The layers allocated at the top of the sketch need to be added before calling matrix.begin().

matrix.begin()

replace with:

  matrix.addLayer(&backgroundLayer); 
  matrix.addLayer(&scrollingLayer); 
  matrix.addLayer(&indexedLayer); 
  matrix.begin();

If you don't need all the layers, delete the addLayer call for the ones you don't need, and delete the corresponding SMARTMATRIX_ALLOCATE macros at the top of the sketch.

Background Layer

The methods for drawing to the background layer were moved from the SmartMatrix class to the background layer class, called backgroundLayer by default. Do find-replace in your text editor, finding the text on the first line of each pair, and replacing with the text from the second line.

matrix.setBackgroundBrightness
backgroundLayer.setBrightness

matrix.swapBuffers
backgroundLayer.swapBuffers

matrix.drawPixel
backgroundLayer.drawPixel

matrix.fillScreen
backgroundLayer.fillScreen

matrix.setColorCorrection
backgroundLayer.enableColorCorrection

matrix.drawLine
backgroundLayer.drawLine

matrix.drawCircle
backgroundLayer.drawCircle

matrix.drawTriangle
backgroundLayer.drawTriangle

matrix.drawRectangle
backgroundLayer.drawRectangle

matrix.drawRoundRectangle
backgroundLayer.drawRoundRectangle

matrix.fillCircle
backgroundLayer.fillCircle

matrix.fillTriangle
backgroundLayer.fillTriangle

matrix.fillRectangle
backgroundLayer.fillRectangle

matrix.fillRoundRectangle
backgroundLayer.fillRoundRectangle

matrix.fillCircle
backgroundLayer.fillCircle

matrix.drawEllipse
backgroundLayer.drawEllipse

matrix.drawFastVLine
backgroundLayer.drawFastVLine

matrix.drawFastHLine
backgroundLayer.drawFastHLine

matrix.drawString
backgroundLayer.drawString

matrix.setFont
backgroundLayer.setFont

matrix.drawChar
backgroundLayer.drawChar

matrix.drawMonoBitmap
backgroundLayer.drawMonoBitmap

matrix.setBackgroundBrightness
backgroundLayer.setBrightness

matrix.readPixel
backgroundLayer.readPixel

matrix.backBuffer
backgroundLayer.backBuffer

Scrolling layer (formerly "Foreground")

The methods for drawing to the scrolling text layer (formerly called "Foreground" when only two layers were possible) were moved from the SmartMatrix class to the scrolling layer class, called scrollingLayer by default. Do find-replace in your text editor, finding the text on the first line of each pair, and replacing with the text from the second line.

matrix.getScrollStatus
scrollingLayer.getStatus

matrix.setScrollStartOffsetFromLeft
scrollingLayer.setStartOffsetFromLeft

matrix.updateScrollText
scrollingLayer.update

matrix.stopScrollText
scrollingLayer.stop

matrix.setScrollOffsetFromTop
scrollingLayer.setOffsetFromTop

matrix.setScrollOffsetFromEdge
scrollingLayer.setOffsetFromTop

matrix.scrollText
scrollingLayer.start

matrix.setScrollColor
scrollingLayer.setColor

matrix.setScrollMode
scrollingLayer.setMode

matrix.setScrollSpeed
scrollingLayer.setSpeed

matrix.setScrollFont
scrollingLayer.setFont

Indexed Layer (formerly part of Foreground)

It's unlikely you used these methods as they were not documented or included in examples.

It's more complicated than using find and replace to update these as the order and number of some of the arguments changed. Use the class definition in Layer_Indexed.h as a reference.

Find/Replace

matrix.setForegroundFont
indexedLayer.setFont

matrix.displayForegroundDrawing
indexedLayer.swapBuffers

matrix.drawForegroundPixel
indexedLayer.drawPixel

Update more carefully, see notes

fillScreen(index) replaces clearForeground() - use 0 to fill with transparent (equivalent to clearing the screen):

matrix.clearForeground()
indexedLayer.fillScreen(0)

new function to set color of layer (before was setForegroundColor which is now used by scrolling layer), use 1 for index:

setIndexedColor(1, RGB)

order of arguments changed, swap char and opaque, optionally replace true with 1 for index:

matrix.drawForegroundChar
indexedLayer.drawChar

order changed, swap string and opaque, optionally replace true with 1 for index:

matrix.drawForegroundString
indexedLayer.drawString

order changed, swap bitmap and opaque, optionally replace true with 1 for index:

matrix.drawForegroundMonoBitmap
indexedLayer.drawMonoBitmap

Troubleshooting

Code Compiles and runs but the screen is blank

Make sure the calls to matrix.addLayers() before matrix.begin() are added

If you're still getting errors after following the instructions above, please post your sketch and the full error report you get from Arduino in the SmartMatrix Community. Make sure you have "Show verbose output during: compilation" checked in Arduino preferences to get the full error report.

Update FastLED Sketch

FastLED's SMART_MATRIX controller was based on SmartMatrix 2.x, and is incompatible with SmartMatrix 3.0. You can get similar features by using FastLED's helper functions but drawing to the SmartMatrix background layer directly instead of through FastLED. Let us know if you want to see support for the FastLED SMART_MATRIX controller in the future.

#Include

Start by updating the #include to <SmartMatrix3.h>

#include <SmartMatrix_32x32.h>

replace with:

#include <SmartMatrix3.h>

If you try to compile you'll now get errors like

FastLED_ControllerMigration.ino:18:23: error: 'MATRIX_WIDTH' was not declared in this scope

Allocation

Add the Allocation code to your sketch, following FastLED_Functions as an example of where it goes:

#define COLOR_DEPTH 24                  // This sketch and FastLED uses type `rgb24` directly, COLOR_DEPTH must be 24
const uint8_t kMatrixWidth = 32;        // known working: 32, 64, 96, 128
const uint8_t kMatrixHeight = 32;       // known working: 16, 32, 48, 64
const uint8_t kRefreshDepth = 36;       // known working: 24, 36, 48
const uint8_t kDmaBufferRows = 4;       // known working: 2-4, use 2 to save memory, more to keep from dropping frames and automatically lowering refresh rate
const uint8_t kPanelType = SMARTMATRIX_HUB75_32ROW_MOD16SCAN;   // use SMARTMATRIX_HUB75_16ROW_MOD8SCAN for common 16x32 panels
const uint8_t kMatrixOptions = (SMARTMATRIX_OPTIONS_NONE);      // see http://docs.pixelmatix.com/SmartMatrix for options
const uint8_t kBackgroundLayerOptions = (SM_BACKGROUND_OPTIONS_NONE);
const uint8_t kScrollingLayerOptions = (SM_SCROLLING_OPTIONS_NONE);

SMARTMATRIX_ALLOCATE_BUFFERS(matrix, kMatrixWidth, kMatrixHeight, kRefreshDepth, kDmaBufferRows, kPanelType, kMatrixOptions);
SMARTMATRIX_ALLOCATE_BACKGROUND_LAYER(backgroundLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kBackgroundLayerOptions);
SMARTMATRIX_ALLOCATE_SCROLLING_LAYER(scrollingLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kScrollingLayerOptions);

If your sketch has a #define for kMatrixWidth and kMatrixHeight, remove those definitions as they are now a constant in the allocation section.

If you sketch depends on definitions for MATRIX_WIDTH and MATRIX_HEIGHT, replace those with kMatrixWidth and kMatrixHeight.

Setup

  LEDS.addLeds<SMART_MATRIX>(leds,NUM_LEDS);

replace with:

  matrix.addLayer(&backgroundLayer); 
  matrix.addLayer(&scrollingLayer); 
  matrix.begin();

At a minimum you just need backgroundLayer for sketches using FastLED. The FastLED_Functions example adds scrolling text on top of the FastLED graphics. If you don't need scrolling text, delete the addLayer call for scrollingLayer, and delete the corresponding SMARTMATRIX_ALLOCATE_SCROLLING_LAYER macro at the top of the sketch.

Replace LEDS Methods

Find any code refering to LEDS and replace it.

setBrightness

LEDS.setBrightness

If you want to control the brightness of the background layer only (keeping the scrolling text layer bright), replace with:

backgroundLayer.setBrightness

If you want to control the brightness of the entire panel, replace with:

matrix.setBrightness

LEDS.show

LEDS.show();

replace with:

backgroundLayer.swapBuffers();

LEDS.countFPS

LEDS.countFPS();

delete, or replace with:

matrix.countFPS();

Use SmartMatrix Methods Directly

For any code that starts with pSmartMatrix->, search for the same function beginning with "matrix." in the sections above and replace. e.g.

pSmartMatrix->setScrollMode

replace with:

scrollingLayer.setMode

Update leds

Find the CRGB leds array and delete it (backgroundLayer will hold the pixel data now)

CRGB leds[kMatrixWidth * kMatrixHeight];

Add this line at the top of loop() to get a pointer to the current draw buffer in the background layer:

  rgb24 *buffer = backgroundLayer.backBuffer();

Now buffer can be used like the leds array. For example:

      leds[XY(i,j)] = CHSV(noise[j][i],255,noise[i][j]);

replace with:

      buffer[XY(i,j)] = CHSV(noise[j][i],255,noise[i][j]);

Keep in mind that you need to get an updated pointer from backBuffer() after every call to swapBuffers(). If you call swapBuffers() more than once per pass through loop(), make sure to update the buffer pointer by calling backBuffer() after each swap, not just at the top of loop().

CHSV to CRGB Conversion

This won't work quite yet, you'll get an error like:

no known conversion for argument 1 from 'CHSV' to 'const rgb24&'

There's no automatic conversion from FastLED's CHSV to rgb24, so help the compiler out by wrapping any CHSV values in CRGB().

      buffer[XY(i,j)] = CRGB(CHSV(noise[j][i],255,noise[i][j]));

CRGB Pointers

You may also get this error if using functions that expect a pointer to a CRGB array:

no known conversion for argument 1 from 'rgb24*' to 'CRGB*'

You can cast the rgb24* buffer pointer as type CRGB*, e.g.

    fill_solid(leds, NUM_LEDS, CRGB::Black);

becomes:

    fill_solid((CRGB*)buffer, NUM_LEDS, CRGB::Black);

Other CRGB Conversions

You may also get this function if using a CRGB::HTMLColorCode:

no known conversion for argument 1 from 'CRGB::HTMLColorCode' to 'const rgb24&'

You can cast the CRGB::HTMLColorCode as type CRGB:

        buffer[XY(i, j)] = CRGB::Black;

becomes:

        buffer[XY(i, j)] = (CRGB)CRGB::Black;

FastLED Troubleshooting

This document may not cover all the FastLED sketch modifications that need to be made to migrate to SmartMatrix3. If you're still getting errors after following the instructions above, please post your sketch and the full error report you get from Arduino in the SmartMatrix Community. Make sure you have "Show verbose output during: compilation" checked in Arduino preferences to get the full error report.