Driving an LED Matrix From a Raspberry Pi

If you use the C libraries that are in the files section, there are 2 macros that are important to set to match the hardware configuration. The first one is in the MatrixDriver_MAX7221.h file at the top of the Defines area:

//=========================================================================
// Defines
//=========================================================================
#define NUM_DISPLAY_MODULES (3)   // Number of display modules on the SPI / I2C bus

Set NUM_DISPLAY_MODULES to the number of MAX7221 chips on the SPI chain.

The second one is in the the file MatrixDriver_MAX7221.c at the top of the Defines area:

//=========================================================================
// Defines
//=========================================================================
// Uncomment to run a left to right (physical) SPI chain. The early single
// driver boards ran left to right data flow, and since the first byte out
// of the SPI Master winds up in the far end of the SPI chain, the                                                  
// character display data needs to have it's order swapped. Later versions                                         // and the dual driver versions run a right to left SPI chain and do not
// need the order swapped.
#define LEFT_TO_RIGHT_SPI_CHAIN

This one pertains to the physical direction of the SPI chain. If the SPI chain runs from the leftmost module to the rightmost module, you want this uncommented. Conversely, if the SPI chain runs from the rightmost module to the leftmost module, comment this define out.

The NUM_DISPLAY_MODULES value is used in many places in the MatrixDriver_MAX7221 file and will be useful in the top level application code for sizing output arrays and such.

The LEFT_TO_RIGHT_SPI_CHAIN value is only used in the Send_Buffer() function in the MatrixDriver_MAX7221.c file to determine the assembly order in the translation from ASCII string to MAX7221 data.

In order to test this code and have something to play with, I wrote a simple driver stub. It contains the main() function and accepts typed in characters and can modify the display brightness. It is all in the top.c file. If the driver code were used in a real application, this entire file would be replaced.

/*---------------------------------------------------------------------------
* Filename:  top.c
* $Revision: 1.2 $
* Author: Bob Harbour
* $Date: 2020-11-26 20:59:58 $
*
*
* Revisions:
*------------------------------------------------------------------------*/


//===================================================================
// INCLUDES
//===================================================================
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>

#include "std_constants.h"
#include "chargen_5x8.h"
#include "MatrixDriver_MAX7221.h"

//===================================================================
// Defines
//===================================================================

//===================================================================
// Globals
//===================================================================

//===================================================================
// Externals
//===================================================================

//===================================================================
// Function Prototypes
//===================================================================
int strip_newline_from_string (char *instr, int maxlen);

//===================================================================
// Functions
//===================================================================
int main (int argc, char *argv[])
{
  int retval, len, trunc_boundary, done, count;
  char inbuffer [SHORT_BUFFER_LEN], *inptr;
  uint8_t brightness;

  retval = OK;
  done = FALSE;
  brightness = MX_DEFAULT_BRIGHTNESS;

  if ((retval = init_matrix_display_system ()) == OK)
  {
    count = 0;

    fprintf (stdout,"<ESC>Q to quit, <ESC>+ or <ESC>- adjust brightness\n");

    while (!done)
    {
      // get user input
      if (fgets (inbuffer, SHORT_BUFFER_LEN, stdin) != NULL)
      {
        len = strip_newline_from_string (inbuffer, SHORT_BUFFER_LEN);
        if (inbuffer[0] == ESC)
        {
          if ((inbuffer[1] == 'Q') || (inbuffer[1] == 'q'))
            done = TRUE;
          else
            if (inbuffer[1] == '+')
            {
              if (brightness < MX_MAX_BRIGHTNESS)
              {
                brightness += 1;
                set_display_brightness (brightness);
                fprintf (stdout,"brightness: %1d\n", brightness);
              }
              else
                fprintf (stdout,"Already at MAX brightness\n");
            }
            else
            if (inbuffer[1] == '-')
            {
              if (brightness > MX_MIN_BRIGHTNESS)
              {
                brightness -= 1;
                set_display_brightness (brightness);
                fprintf (stdout,"brightness: %1d\n", brightness);
              }
              else
                fprintf (stdout,"Already at MIN brightness\n");
            }
            else
            {
              fprintf (stdout,"Unrecognized Escape Sequence: ESC %c\n",
                       inbuffer[1]);
            }
        }  // pairs with: if (inbuffer[0] == ESC)
        else
        {
          //retval = insert_display_chars_from_left (inbuffer, len, &trunc_boundary);
          retval = insert_display_chars_from_right (inbuffer, len, &trunc_boundary);
          printf ("truncation boundary: %1d\n", trunc_boundary);
          count += 1;
        }  // pairs with: if (inbuffer[0] == ESC) else
      }   // pairs with: if (fgets () )
      else
      {
        if (feof (stdin))
        {
          done = TRUE;
        }
      }      // pairs with: if (fgets () != NULL)  else
    }  // pairs with : while (!done)
    shutdown_matrix_display_system (FALSE);
  }
  else
  {
    fprintf (stderr,"ERROR, init_matrix_display_system() barfed\n");
  }

  exit (retval);
}

//===================================================================
//  strip_newline_from_string()
//  Removes the newline character from a string.
//  Returns the number of characters in the resulting string
//
//  8/2007
//===================================================================
int strip_newline_from_string (char *instr, int maxlen)
{
  char *ptr;
  int len;

  ptr = instr;
  len = 0;
  // leave room for terminator
  maxlen -= 1;

  // count to end of line
  while ((*ptr != CR) && (*ptr != LF) && (*ptr != EOS) && (len < maxlen))
  {
    ptr++;
    len += 1;
  }

  // replace possible CR or LF with end of string
  if ((*ptr == CR) || (*ptr == LF))
  {
    *ptr = EOS;
  }
  else
  {
    if (len == maxlen)
    {
      *ptr = EOS;
    }
  }

  return (len);
}

To build this program on a Raspberry Pi, place the tarball in a directory by itself and unpack the tarball:

> tar -xzvf MAX_Single_Driver_RasPi_11_27_2020.tgz

Build the program with make

> make

Connect the displays to the SPI interface on the Raspberry Pi similarly to the block diagram at the top of this article.

Run the program:

> ./top

Type a few characters, they should show up on your display modules. If you have 4 display modules hooked up, the first 4 characters that you types should  display.

In order to quit, hit the escape key followed by Q and then hit the enter key.

<esc>Q<enter>

To increase the display brightness one step:

<esc>+<enter>

To decrease the display brightnes one step:

<esc>-<enter>