| MD_MAX72xx LED Matrix Arduino Library 2.4 Library to control connected MAX72XX devices as a pixel array

- Main Page
- Related Pages
- Classes
- Files

- Class List
- Class Index
- Class Members

All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Classes | Public Types | Public Member Functions | List of all members
MD_MAX72XX Class Reference

`#include <MD_MAX72xx.h>`

## Public Types
enum | controlRequest_t { SHUTDOWN = 0, SCANLIMIT = 1, INTENSITY = 2, TEST = 3, DECODE = 4, UPDATE = 10, WRAPAROUND = 11 }
enum | controlValue_t { OFF = 0, ON = 1 }
enum | transformType_t { TSL, TSR, TSU, TSD, TFLR, TFUD, TRC, TINV }
typedef uint8_t PROGMEM * | fontType_t

## Public Member Functions
| MD_MAX72XX (uint8_t dataPin, uint8_t clkPin, uint8_t csPin, uint8_t numDevices=1)
| MD_MAX72XX (uint8_t csPin, uint8_t numDevices=1)
void | begin (void)
| ~MD_MAX72XX ()
Methods for object and hardware control.
bool | control (uint8_t dev, controlRequest_t mode, int value)
void | control (controlRequest_t mode, int value)
bool | control (uint8_t startDev, uint8_t endDev, controlRequest_t mode, int value)
uint8_t | getDeviceCount (void)
uint16_t | getColumnCount (void)
void | setShiftDataInCallback (uint8_t(*cb)(uint8_t dev, transformType_t t))
void | setShiftDataOutCallback (void(*cb)(uint8_t dev, transformType_t t, uint8_t colData))
Methods for graphics and bitmap related abstraction.
void | clear (void)
void | clear (uint8_t startDev, uint8_t endDev)
bool | drawLine (uint8_t r1, uint16_t c1, uint8_t r2, uint16_t c2, bool state)
bool | getBuffer (uint16_t col, uint8_t size, uint8_t *pd)
uint8_t | getColumn (uint8_t c)
bool | getPoint (uint8_t r, uint16_t c)
bool | setBuffer (uint16_t col, uint8_t size, uint8_t *pd)
bool | setColumn (uint8_t c, uint8_t value)
bool | setPoint (uint8_t r, uint16_t c, bool state)
bool | setRow (uint8_t r, uint8_t value)
bool | setRow (uint8_t startDev, uint8_t endDev, uint8_t r, uint8_t value)
bool | transform (transformType_t ttype)
bool | transform (uint8_t startDev, uint8_t endDev, transformType_t ttype)
void | update (controlValue_t mode)
void | update (void)
void | wraparound (controlValue_t mode)
Methods for managing specific devices or display buffers.
bool | clear (uint8_t buf)
uint8_t | getColumn (uint8_t buf, uint8_t c)
uint8_t | getRow (uint8_t buf, uint8_t r)
bool | setColumn (uint8_t buf, uint8_t c, uint8_t value)
bool | setRow (uint8_t buf, uint8_t r, uint8_t value)
bool | transform (uint8_t buf, transformType_t ttype)
void | update (uint8_t buf)
Methods for font and characters.
uint8_t | getChar (uint8_t c, uint8_t size, uint8_t *buf)
uint8_t | setChar (uint16_t col, uint8_t c)
bool | setFont (fontType_t f)

## Detailed Description

Core object for the MD_MAX72XX library

## Member Typedef Documentation

typedef uint8_t PROGMEM* MD_MAX72XX::fontType_t

Font definition type.

This type is used in the setFont() method to set the font to be used

## Member Enumeration Documentation

enum MD_MAX72XX::controlRequest_t

Control Request enumerated type.

This enumerated type is used with the control() method to identify the control action request.

Enumerator
SHUTDOWN | Shut down the MAX72XX. Requires ON/OFF value. Library default is OFF.
SCANLIMIT | Set the scan limit for the MAX72XX. Requires numeric value [0..MAX_SCANLIMIT]. Library default is all on.
INTENSITY | Set the LED intensity for the MAX72XX. Requires numeric value [0..MAX_INTENSITY]. LIbrary default is MAX_INTENSITY/2.
TEST | Set the MAX72XX in test mode. Requires ON/OFF value. Library default is OFF.
DECODE | Set the MAX72XX 7 segment decode mode. Requires ON/OFF value. Library default is OFF.
UPDATE | Enable or disable auto updates of the devices from the library. Requires ON/OFF value. Library default is ON.
WRAPAROUND | Enable or disable wraparound when shifting (circular buffer). Requires ON/OFF value. Library default is OFF.

enum MD_MAX72XX::controlValue_t

Control Value enumerated type.

This enumerated type is used with the control() method as the ON/OFF value for a control request. Other values may be used if numeric data is required.

Enumerator
OFF | General OFF status request.
ON | General ON status request.

enum MD_MAX72XX::transformType_t

Transformation Types enumerated type.

This enumerated type is used in the transform() methods to identify a specific transformation of the display data in the device buffers.

Enumerator
TSL | Transform Shift Left one pixel element.
TSR | Transform Shift Right one pixel element.
TSU | Transform Shift Up one pixel element.
TSD | Transform Shift Down one pixel element.
TFLR | Transform Flip Left to Right.
TFUD | Transform Flip Up to Down.
TRC | Transform Rotate Clockwise 90 degrees.
TINV | Transform INVert (pixels inverted)

## Constructor & Destructor Documentation

MD_MAX72XX::MD_MAX72XX | ( | uint8_t | dataPin,
|  | uint8_t | clkPin,
|  | uint8_t | csPin,
|  | uint8_t | numDevices = `1`
| ) |  |

Class Constructor - arbitrary digital interface.

Instantiate a new instance of the class. The parameters passed are used to connect the software to the hardware. Multiple instances may co-exist but they should not share the same hardware CS pin (SPI interface).

Parameters

  dataPin | output on the Arduino where data gets shifted out.
  clkPin | output for the clock signal.
  csPin | output for selecting the device.
  numDevices | number of devices connected. Default is 1 if not supplied. Memory for device buffers is dynamically allocated based on this parameter.

MD_MAX72XX::MD_MAX72XX | ( | uint8_t | csPin,
|  | uint8_t | numDevices = `1`
| ) |  |

Class Constructor - SPI hardware interface.

Instantiate a new instance of the class. The parameters passed are used to connect the software to the hardware. Multiple instances may co-exist but they should not share the same hardware CS pin (SPI interface). The dataPin and the clockPin are defined by the Arduino hardware definition (SPI MOSI and SCK signals).

Parameters

  csPin | output for selecting the device.
  numDevices | number of devices connected. Default is 1 if not supplied. Memory for device buffers is dynamically allocated based on this parameter.

MD_MAX72XX::~MD_MAX72XX | ( | void |  | ) |

Class Destructor.

Released allocated memory and does the necessary to clean up once the object is no longer required.

## Member Function Documentation

void MD_MAX72XX::begin | ( | void |  | ) |

Initialize the object.

Initialise the object data. This needs to be called during setup() to initialise new data for the class that cannot be done during the object creation.

The LED hardware is initialized to the middle intensity value, all rows showing, and all LEDs cleared (off). Test, shutdown and decode modes are off. Display updates are on and wraparound is off.

void MD_MAX72XX::clear | ( | void |  | ) |

Clear all the display data on all the display devices.

Returns
  No return value.

void MD_MAX72XX::clear | ( | uint8_t | startDev,
|  | uint8_t | endDev
| ) |  |

Clear all the display data on a subset of devices.

endDev must be greater than or equal to startDev.

Parameters

  startDev | the first device to clear [0..getDeviceCount()-1]
  endDev | the last device to clear [0..getDeviceCount()-1]

Returns
  No return value.

bool MD_MAX72XX::clear | ( | uint8_t | buf | ) |

Clear all display data in the specified buffer.

Parameters

  buf | address of the buffer to clear [0..getDeviceCount()-1].

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::control | ( | uint8_t | dev,
|  | controlRequest_t | mode,
|  | int | value
| ) |  |

Set the control status of the specified parameter for the specified device.

The device has a number of control parameters that can be set through this method. The type of control action required is passed through the mode parameter and should be one of the control actions defined by controlRequest_t. The value that needs to be supplied on the control action required is one of the defined actions in controlValue_t or a numeric parameter suitable for the control action.

Parameters

  dev | address of the device to control [0..getDeviceCount()-1].
  mode | one of the defined control requests.
  value | parameter value or one of the control status defined.

Returns
  false if parameter errors, true otherwise.

void MD_MAX72XX::control | ( | controlRequest_t | mode,
|  | int | value
| ) |  |

Set the control status of the specified parameter for all devices.

Invokes the control function for each device in turn. as this is a wrapper for the control(startDev, endDev, ...) methods, see the documentation for that method.

Parameters

  mode | one of the defined control requests.
  value | parameter value or one of the control status defined.

Returns
  No return value.

bool MD_MAX72XX::control | ( | uint8_t | startDev,
|  | uint8_t | endDev,
|  | controlRequest_t | mode,
|  | int | value
| ) |  |

Set the control status of the specified parameter for contiguous subset of devices.

Invokes the control function for each device in turn for the devices in the subset. See documentation for the control() method.

Parameters

  startDev | the first device for the transformation [0..getDeviceCount()-1]
  endDev | the last device for the transformation [0..getDeviceCount()-1]
  mode | one of the defined control requests.
  value | parameter value or one of the control status defined.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::drawLine | ( | uint8_t | r1,
|  | uint16_t | c1,
|  | uint8_t | r2,
|  | uint16_t | c2,
|  | bool | state
| ) |  |

Draw a line between two points on the display

Draw a line between the specified points. The LED will be turned on or off depending on the value supplied. The column number will be dereferenced into the device and column within the device, allowing the LEDs to be treated as a continuous pixel field.

Parameters

  r1 | starting row coordinate for the point [0..ROW_SIZE-1].
  c1 | starting column coordinate for the point [0..getColumnCount()-1].
  r2 | ending row coordinate for the point [0..ROW_SIZE-1].
  c2 | ending column coordinate for the point [0..getColumnCount())-1].
  state | true - switch on; false - switch off.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::getBuffer | ( | uint16_t | col,
|  | uint8_t | size,
|  | uint8_t * | pd
| ) |  |

Load a bitmap from the display buffers to a user buffer.

Allows the calling program to read bitmaps (characters or graphic) elements from the library display buffers. The data buffer pointer should be a block of uint8_t data of size elements that will contain the returned data.

Parameters

  col | address of the display column [0..getColumnCount()-1].
  size | number of columns of data to return.
  *pd | Pointer to a data buffer [0..size-1].

Returns
  false if parameter errors, true otherwise. If true, data will be in the buffer at *pd.

uint8_t MD_MAX72XX::getChar | ( | uint8_t | c,
|  | uint8_t | size,
|  | uint8_t * | buf
| ) |  |

Load a character from the font data into a user buffer.

Copy the bitmap for a library font character (current font set by setFont()) and return it in the data area passed by the user. If the user buffer is not large enough, only the first size elements are copied to the buffer.

NOTE: This function is only available if the library defined value USE_LOCAL_FONT is set to 1.

Parameters

  c | the character to retrieve.
  size | the size of the user buffer in unit8_t units.
  buf | address of the user buffer supplied.

Returns
  width (in columns) of the character, 0 if parameter errors.

uint8_t MD_MAX72XX::getColumn | ( | uint8_t | c | ) |

Get the LEDS status for the specified column.

This method operates on a specific buffer

This method operates on one column, getting the bit field value of the LEDs in the column. The column is referenced with the absolute column number (ie, the device number is inferred from the column).

Parameters

  c | column which is to be set [0..getColumnCount()-1].

Returns
  uint8_t value with each bit set to 1 if the corresponding LED is lit. 0 is returned for parameter error.

uint8_t MD_MAX72XX::getColumn | ( | uint8_t | buf,
|  | uint8_t | c
| ) |  |

Get the state of the LEDs in a specific column.

This method operates on the specific buffer, returning the bit field value of the LEDs in the column.

Parameters

  buf | address of the display [0..getDeviceCount()-1].
  c | column which is to be set [0..COL_SIZE-1].

Returns
  uint8_t value with each bit set to 1 if the corresponding LED is lit. 0 is returned for parameter error.

uint16_t MD_MAX72XX::getColumnCount | ( | void |  | ) |

Gets the maximum number of columns for devices attached to this class instance.

Returns
  uint16_t representing the number of columns.

uint8_t MD_MAX72XX::getDeviceCount | ( | void |  | ) |

Gets the number of devices attached to this class instance.

Returns
  uint8_t representing the number of devices attached to this object.

bool MD_MAX72XX::getPoint | ( | uint8_t | r,
|  | uint16_t | c
| ) |  |

Get the status of a single LED, addressed as a pixel.

The method will get the status of a specific LED element based on its coordinate position. The column number is dereferenced into the device and column within the device, allowing the LEDs to be treated as a continuous pixel field.

Parameters

  r | row coordinate for the point [0..ROW_SIZE-1].
  c | column coordinate for the point [0..getColumnCount()-1].

Returns
  true if LED is on, false if off or parameter errors.

uint8_t MD_MAX72XX::getRow | ( | uint8_t | buf,
|  | uint8_t | r
| ) |  |

Get the state of the LEDs in a specified row.

This method operates on the specific buffer, returning the bit field value of the LEDs in the row.

Parameters

  buf | address of the display [0..getDeviceCount()-1].
  r | row which is to be set [0..ROW_SIZE-1].

Returns
  uint8_t value with each bit set to 1 if the corresponding LED is lit. 0 is returned for parameter error.

bool MD_MAX72XX::setBuffer | ( | uint16_t | col,
|  | uint8_t | size,
|  | uint8_t * | pd
| ) |  |

Load a bitfield from the user buffer to a display buffer.

Allows the calling program to define bitmaps (characters or graphic) elements and pass them to the library for display. The data buffer pointer should be a block of uint8_t data of size elements that define the bitmap.

Parameters

  col | address of the display column [0..getColumnCount()-1].
  size | number of columns of data following.
  *pd | Pointer to a data buffer [0..size-1].

Returns
  false if parameter errors, true otherwise.

uint8_t MD_MAX72XX::setChar | ( | uint16_t | col,
|  | uint8_t | c
| ) |  |

Load a character from the font data starting at a specific column.

Load a character from the font table directly into the display at the column specified. The currently selected font table is used as the source.

NOTE: This function is only available if the library defined value USE_LOCAL_FONT is set to 1.

Parameters

  col | column of the display in the range accepted [0..getColumnCount()-1].
  c | the character to display.

Returns
  width (in columns) of the character, 0 if parameter errors.

bool MD_MAX72XX::setColumn | ( | uint8_t | c,
|  | uint8_t | value
| ) |  |

Set all LEDs in a specific column to a new state.

This method operates on one column, setting the value of the LEDs in the column to the specified value bitfield. The column is referenced with the absolute column number (ie, the device number is inferred from the column). The method is useful for drawing vertical lines and patterns when the display is being treated as a pixel field. The least significant bit of the value is the lowest row number.

Parameters

  c | column which is to be set [0..getColumnCount()-1].
  value | each bit set to 1 will light up the corresponding LED.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setColumn | ( | uint8_t | buf,
|  | uint8_t | c,
|  | uint8_t | value
| ) |  |

Set all LEDs in a column to a new state.

This method operates on a specific buffer, setting the value of the LEDs in the column to the specified value bit field. The method is useful for drawing patterns and lines vertically on the display device. The least significant bit of the value is the lowest column number.

Parameters

  buf | address of the display [0..getDeviceCount()-1].
  c | column which is to be set [0..COL_SIZE-1].
  value | each bit set to 1 will light up the corresponding LED.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setFont | ( | fontType_t | f | ) |

Set the current font table.

Font data is stored in PROGMEM, in the format described elsewhere in the documentation. All characters retrieved or used after this call will use the nominated font (default or user defined). To specify a user defined character set, pass the PROGMEM address of the font table. Passing a NULL pointer resets the font table to the library default table. This function also causes the font index table to be recreated if the library defined value USE_INDEX_TABLE is set to 1.

NOTE: This function is only available if the library defined value USE_LOCAL_FONT is set to 1.

Parameters

  f | fontType_t pointer to the table of font data in PROGMEM or NULL.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setPoint | ( | uint8_t | r,
|  | uint16_t | c,
|  | bool | state
| ) |  |

Set the status of a single LED, addressed as a pixel.

The method will set the value of a specific LED element based on its coordinate position. The LED will be turned on or off depending on the value supplied. The column number is dereferenced into the device and column within the device, allowing the LEDs to be treated as a continuous pixel field.

Parameters

  r | row coordinate for the point [0..ROW_SIZE-1].
  c | column coordinate for the point [0..getColumnCount()-1].
  state | true - switch on; false - switch off.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setRow | ( | uint8_t | r,
|  | uint8_t | value
| ) |  |

Set all LEDs in a row to a new state on all devices.

This method operates on all devices, setting the value of the LEDs in the row to the specified value bit field. The method is useful for drawing patterns and lines horizontally across on the entire display. The least significant bit of the value is the lowest column number.

Parameters

  r | row which is to be set [0..ROW_SIZE-1].
  value | each bit set to 1 will light up the corresponding LED on each device.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setRow | ( | uint8_t | startDev,
|  | uint8_t | endDev,
|  | uint8_t | r,
|  | uint8_t | value
| ) |  |

Set all LEDs in a row to a new state on contiguous subset of devices.

This method operates on a contiguous subset of devices, setting the value of the LEDs in the row to the specified value bit field. The method is useful for drawing patterns and lines horizontally across specific devices only. endDev must be greater than or equal to startDev. The least significant bit of the value is the lowest column number.

Parameters

  startDev | the first device for the transformation [0..getDeviceCount()-1]
  endDev | the last device for the transformation [0..getDeviceCount()-1]
  r | row which is to be set [0..ROW_SIZE-1].
  value | each bit set to 1 will light up the corresponding LED on each device.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::setRow | ( | uint8_t | buf,
|  | uint8_t | r,
|  | uint8_t | value
| ) |  |

Set all LEDs in a row to a new state.

This method operates on a specific device, setting the value of the LEDs in the row to the specified value bit field. The method is useful for drawing patterns and lines horizontally across the display device. The least significant bit of the value is the lowest row number.

Parameters

  buf | address of the display [0..getDeviceCount()-1].
  r | row which is to be set [0..ROW_SIZE-1].
  value | each bit set to 1 within this byte will light up the corresponding LED.

Returns
  false if parameter errors, true otherwise.

void MD_MAX72XX::setShiftDataInCallback | ( | uint8_t(*)(uint8_t dev, transformType_t t) | cb | ) |

Set the Shift Data In callback function.

The callback function is called from the library when a transform shift left or shift right operation is executed and the library needs to obtain data for the end element of the shift (ie, conceptually this is the new data that is shifted 'into' the display). The callback function is invoked when

- WRAPAROUND is not active, as the data would automatically supplied within the library.
- the call to transform() is global (ie, not for an individual buffer).

The callback function takes 2 parameters:

- the device number requesting the data [0..getDeviceCount()-1]
- one of the transformation types in transformType_t) that tells the callback function what shift is being performed The return value is the data for the column to be shifted into the display.

Parameters

  cb | the address of the function to be called from the library.

Returns
  No return data

void MD_MAX72XX::setShiftDataOutCallback | ( | void(*)(uint8_t dev, transformType_t t, uint8_t colData) | cb | ) |

Set the Shift Data Out callback function.

The callback function is called from the library when a transform shift left or shift right operation is executed and the library is about to discard the data for the first element of the shift (ie, conceptually this is the data that 'falls' off the front end of the scrolling display). The callback function is invoked when

- WRAPAROUND is not active, as the data would automatically supplied to the tail end.
- the call to transform() is global (ie, not for an individual buffer).

The callback function is with supplied 3 parameters, with no return value required:

- the device number that is the source of the data [0..getDeviceCount()-1]
- one of the transformation types transformType_t that tells the callback function the type of shifting being executed
- the data for the column being shifted out

Parameters

  cb | the address of the function to be called from the library.

Returns
  No return data

bool MD_MAX72XX::transform | ( | transformType_t | ttype | ) |

Apply a transformation to the data in all the devices.

The buffers for all devices can be transformed using one of the enumerated transformations in transformType_t. The transformation is carried across device boundaries (ie, there is overflow to an adjacent devices if appropriate).

Parameters

  ttype | one of the transformation types in transformType_t.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::transform | ( | uint8_t | startDev,
|  | uint8_t | endDev,
|  | transformType_t | ttype
| ) |  |

Apply a transformation to the data in contiguous subset of devices.

The buffers for all devices in the subset can be transformed using one of the enumerated transformations in transformType_t. The transformation is carried across device boundaries (ie, there is overflow to an adjacent devices if appropriate). endDev must be greater than or equal to startDev.

Parameters

  startDev | the first device for the transformation [0..getDeviceCount()-1]
  endDev | the last device for the transformation [0..getDeviceCount()-1]
  ttype | one of the transformation types in transformType_t.

Returns
  false if parameter errors, true otherwise.

bool MD_MAX72XX::transform | ( | uint8_t | buf,
|  | transformType_t | ttype
| ) |  |

Apply a transformation to the data in the specified device.

The buffer for one device can be transformed using one of the enumerated transformations in transformType_t. The transformation is limited to the nominated device buffer only (ie, there is no overflow to an adjacent device).

Parameters

  buf | address of the display [0..getBufferCount()-1].
  ttype | one of the transformation types in transformType_t.

Returns
  false if parameter errors, true otherwise.

void MD_MAX72XX::update | ( | controlValue_t | mode | ) |

Turn auto display updates on or off.

Turn auto updates on and off, as required. When auto updates are turned OFF the display will not update after each operation. Display updates can be forced at any time using using a call to update() with no parameters.

This function is a convenience wrapper for the more general control() function call.

Parameters

  mode | one of the types in controlValue_t (ON/OFF).

Returns
  No return value.

void MD_MAX72XX::update | ( | void |  | ) |

Force an update of all devices

Used when auto updates have been turned off through the control method. This will force all buffered changes to be written to all the connected devices.

Returns
  no return value.

void MD_MAX72XX::update | ( | uint8_t | buf | ) |

Force an update of one buffer.

Used when auto updates have been turned off through the control() method. This will force all buffered display changes to be written to the specified device at the same time. Note that control() messages are not buffered but cause immediate action.

Parameters

  buf | address of the display [0..getBufferCount()-1].

Returns
  No return value.

void MD_MAX72XX::wraparound | ( | controlValue_t | mode | ) |

Turn display wraparound on or off.

When shifting left or right, up or down, the outermost edge is normally lost and a blank row or column inserted on the opposite side. If this options is enabled, the edge is wrapped around to the opposite side.

This function is a convenience wrapper for the more general control() function call.

Parameters

  mode | one of the types in controlValue_t (ON/OFF).

Returns
  No return value.

The documentation for this class was generated from the following files:

- MD_MAX72xx.h
- MD_MAX72xx.cpp
- MD_MAX72xx_buf.cpp
- MD_MAX72xx_font.cpp
- MD_MAX72xx_pix.cpp