ESP8266/Arduino: MAX7219 8×8 Led Matrix Library

Do you like this post? A regular project like the PlaneSpotter Color takes many hours of my free time to develop and maintain. Would you offer me a beer for my hard work if I was your neighbour? Modern technology called teleportation makes it easy to send me a beer. Just click here. Thank you!

Twice a year the company I work for (Netcetera) organizes a retreat for programmers, usually in the mountains. In the Spring issue this year we went to a resort in a beautiful mountain region. Inspired by the wonderful landscape I managed to write a library for the recently published Arduino IDE for ESP8266 which allows you to manipulate pixels and write animated text on 8×8 led matrices with a MAX7219 driver.These boards (affiliate link) only cost a bit more than $2/piece and you can connect several of them by daisy chaining one with the next. This allows you to create wonderful led bar on the cheap: lets say you buy 10 of them plus an ESP8266 and mount them on a piece of card board you’ll have a wonderful remote programmable eye catcher for shop display for less than $30!

Not being fluent anymore in C/C++ I had to get used again to the hard work of managing memory, dealing with a weird String object (yes, even weirder than the String object in Java;-)) and some other pitfalls for a 10+ years Java programmer.

But I finally managed it and here you can see the result:

Connect the Modules like this:

Led Matrix ESP8266
VCC +3.3V
CS Choose free GPIO, e.g. GPIO2

Here you’ll find the library:

Please note:

  • this library is made for the ESP8266 and might or might not work for “normal” Arduino boards.
  • I had to patch the Mac OS X release with the SPI folder from Github. In other words there wasn’t an up-to-date release for Mac OS X (and maybe for the other platforms as well) and the SPI.h/SPI.cpp wouldn’t compile


Posted by squix78


  1. Hi Dani,
    My matrixes arrived yesterday and I've been playing with them on an Arduino just to make sure I built them properly. Everything checks out.
    Now I'm trying to move to the ESP and I'm having compile problems.
    I tried Arduino 1.6.4 and I get these errors (I hope they'll copy in here…)

    Arduino: 1.6.4 (Windows 8.1), Board: "Generic ESP8266 Module, 80 MHz, 115200, 512K (64K SPIFFS)"

    Build options changed, rebuilding all

    C:Program FilesArduinolibrariesMAX7219LedMatrix-masterLedMatrix.cpp: In member function 'void LedMatrix::scrollTextLeft()':
    C:Program FilesArduinolibrariesMAX7219LedMatrix-masterLedMatrix.cpp:122:18: error: ambiguous overload for 'operator=' (operand types are 'String' and 'int')
    myNextText = NULL;
    C:Program FilesArduinolibrariesMAX7219LedMatrix-masterLedMatrix.cpp:122:18: note: candidates are:
    In file included from C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/Arduino.h:209:0,
    from C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdelibrariesSPI/SPI.h:24,
    from C:Program FilesArduinolibrariesMAX7219LedMatrix-masterLedMatrix.cpp:2:
    C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/WString.h:85:18: note: String& String::operator=(const String&)
    String & operator =(const String &rhs);
    C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/WString.h:86:18: note: String& String::operator=(const char*)
    String & operator =(const char *cstr);
    C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/WString.h:87:18: note: String& String::operator=(const __FlashStringHelper*)
    String & operator = (const __FlashStringHelper *str);
    C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/WString.h:89:18: note: String& String::operator=(String&&)
    String & operator =(String &&rval);
    C:UsersMichaelAppDataRoamingArduino15packagesesp8266hardwareesp82661.6.4-628-g545ffdecoresesp8266/WString.h:90:18: note: String& String::operator=(StringSumHelper&&)
    String & operator =(StringSumHelper &&rval);
    Error compiling.

    This report would have more information with
    "Show verbose output during compilation"
    enabled in File > Preferences.

    I didn't do the verbose messages – would that help?
    Have you seen these kind of errors before?

  2. Hi Dani, I'm reza.

    Nice work!
    I can compile and upload to my ESP-12 but the Led Matrix doesn't show the word i want (just blinking and turn the leds randomly).
    I use DIN at GPIO13, CS at GPIO12, and CLK at GPIO14.
    Can you fixed the error please?

  3. My 8×8 (4 off) are already joined together as a unit and the letters scroll vertically. Basically I'm asking if I can alter the code to swing the matrix character map through 90 degrees. thanks

  4. Brilliant programming – lots of features. Can even add a wifi access point server alongside to change the scrolling text. Also have rotated the font so that it could be viewed as a vertically scrolling display. One question, I cannot see, software-wise why it should not work for more than 8 modules – though cannot get it to work. I wonder if the power drain is too great. Will try a non-inverting 5V level shifter for my Wemos D1 R2. Thanks again Daniel.

    • Hi David. That sounds interesting. How did you attach the 8 (and more) modules? All on the same I2C bus or on different pins? I also don’t see a reason why more shouldn’t work, except maybe for the memory. If you have separate instances of the display driver each allocates a part of the memory for buffering before writing to the display. It could be that you use all the available memory…

  5. Thanks for the code! Works great after a couple of tries. For those who tried to use the supplied AnimateText Arduino code and didn’t work, try including the font library that is bundled with it. For some reason it was left out.

    I also couldn’t define CS_PIN 2 to something else. I tried pin 12 (since it’s right next to pins 13 and 14) but didn’t seem to respond so I switched it back. Not sure if anyone has found the solution to this, but not a big deal.

Leave a Reply