ESP8266/Arduino: MAX7219 8×8 Led Matrix Library

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 Daniel Eichhorn

Daniel Eichhorn is a software engineer and an enthusiastic maker. He loves working on projects related to the Internet of Things, electronics, and embedded software. He owns two 3D printers: a Creality Ender 3 V2 and an Elegoo Mars 3. In 2018, he co-founded ThingPulse along with Marcel Stör. Together, they develop IoT hardware and distribute it to various locations around the world.


  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…

    • Hi Daniel, many thanks for your library, it helps a lot in my projects. Hi David, can you expalin how you rotate the matrix view please ?

  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.

  6. Hello. I have a 4 in 1 block of max7219 How to rotate text on 90 degrees counterclockwise on each matrix? Thanks

  7. Same question like Alex. I’ve got a 4 in a row block, also. Is there an easy way to rotate the allignment? It is like to exchange x and y axis and to exchange the order. Is there an option in your library to do something like that?

Leave a Reply