Tobers Multidisplay for ESP8266 and ESP32

Overview

Tobers Multidisplay is a LED-Matrix display controlled by an ESP8266 or an ESP32. It can show current time and date, news, current weather & forecast, up to four custom messages, one guest message and - if ESP32 - information about the song currently playing on Spotify.

Tobers Multidisplay is widely and easily configurable via web interface.

Inspiration

Being fascinated by all kind of LED matrixes and always searching the web for inspiration, I discovered the fantastic Parola Library, which makes it easy to get nice text animations on a matrix. There is a great number of projects online basing on this library - all kinds of clocks, message displays, news displays etc. A really nice one is the Display made by ericBcreator, which was a significant inspiration for my project. In the beginning it was my goal to get something like this running on an ESP8266. Finally it endend up with a - under the hood - completely different project. One thing I appreciated very much about the cited project and that I adopted for my own project is the idea of implementing a "local language" definition in the code, which makes it very simple to set up the display for other languages.

Parts required:

ESP8266 with 4MB flash or ESP32
If you want Spotify support, you must choose an ESP32. Otherwise I recommend an ESP8266 - except Spotify support there is no significant difference between these two multidisplay variants.

(Explanation: The program is driving the ESP8266 at its heap limits, that's the reason why Spotify support isn't possible. With all the other features simultaniously running, the https connection with Spotify needs too much heap and makes the ESP8266 crashing as I guess. Beyond that, there are no disadvantages of an ESP8266.)

MAX7219 8x8 LED Matrix Modules
The number of the daisy chained modules must be defined in the code. So you can decide on how many modules you want to use. The Multidisplay shown on the pictures here uses eight 8x8 modules. (In many shops there are also pre-assembled blocks of four daisy chained modules available. Having received some pre-assembled blocks with gaps between the modules, I now prefer single modules and put them together by myself. It's more laborious - but it's worth it.)

Software required

Arduino IDE - compiled with ARDUINO V 1.8.12 - 1.8.19 on Win 10

• installed boards:
  Arduino Core for ESP8266 (compiled with V 2.7.4)
  or
  Arduino Core for ESP32 (compiled with V 2.0.2)
• installed libraries:
  MAX72xx Library by majicDesigns (compiled with V 3.3.0)
  Parola Library by majicDesigns (compiled with V 3.5.6)
  Arduino Json library by Benoit Blanchon (compiled with V 6.19.1)
  WifiManager_for_Multidisplay, my own fork of WiFiManager by tzapu
• installed tools
  ESP8266 Sketch Data Upload
  or
  ESP32 Sketch Data Upload

Accounts required

Weather: get your weather api key on openweathermap.org

News: get your news api key on newsapi.org

Spotify: Spotify account and developer registration of the device. You can find further information on this process later on in this post under "Spotify Integration".

Get started

• Ensure you have installed the required boards and libraries.
• Visit my Github repository and download from the releases site the Zip-File multidisplay_1.x_EN for English language or multidisplay_1.x_DE for German language. The Zip file contains the Arduino ino file with the code and all other reqired files.
• Unzip the file into your Arduino Sketch Directory.
• Open the multidisplay_1.x_EN.ino respectively multidisplay_1.x_DE.ino file.
• Upload "data" folder to your ESP using Arduino->Tools->ESP Sketch Data Upload.

Before you start compiling..

...you have to do some settings and #defines in the code. All custom variables and #defines are placed in the //// SETTINGS //// section at the beginning of the code.

You have to define or set (in order of appearence in code):

• #define ESP32 if you're using an ESP32
• optional: #define SPOTIFY (works only with ESP32!)
• optional: #define DEBUG for debugging messages via serial monitor (57600)
• #define HARDWARE_TYPE of your LED modules
• #define MAX_DEVICES number of your LED modules
• optional: set password for Access Point with variable AP_PW
• optional: change variables timezone and ntpServer
• set variable "WeatherApiKey"
• set your two personal weather City-IDs in array "ownCityIDs"
• optional: set varibale imperial to true for temperature in Fahrenheit
• set variable "NewsApiKey"
• optional: change the four news sources in array "ownNewsSources"
• Spotify variable "clientID" (only if Spotify is defined in code)
• Spotify variable "clientSecret" (only if Spotify is defined in code)
• optional: change of variables "www_username" and "www_password"

I encourage you to take a deeper look into the code before compiling. I added a lot of comments and links so I hope you can discover and understand the functions of the program.

On first start up...

The first time your device starts up after successful compiling it doesn't connect to your WiFi - no surprise because we didn't define WiFi credentials in the code. Instead of that the device starts an Access Point ("Tobers_Multidisplay"). Connect to that AP and enter your WiFi credentials in the config portal. After successful connection to your WiFi the ESP writes the WiFi credentials persistently into its flash memory.

[Note: It's possible to skip the config portal via "Exit". In this case the config portal is closed and the ESP works as AP only ("Tobers_Multidisplay"). Though this operation mode without internet conncetion doesn't make much sense (no time, date, weather, news...), I implemented it to enable offline operation with the custom messages only.]

Regular Operation

On start up the Multidisplay connects to your WiFi, gets data from time, news and weather (and optionally Spotify) server and loads the saved configuration. Having passed this steps successfully, the display shows a welcome message with the IP address you can reach the device at in your local network. Enter this IP address into your browser to access the web interface.

Web Interface

The web interface is the control center of your display. It has two zones:

The public zone:
Everyone in your local network can reach these sites. It is possible to send a guest message to the display ("ownmessage"), to browse news, weather forecast* and Spotify info shown on display.

[* the site weather.html must be changed manually. Due to limitations with the free widgets from "openweathermap.org" I embedded the widgets from "wetteronline.de". Just take a look at weather.html and change the html code according to your city and region. Of course you can embed widgets from any other weather site if you know better ones. This can also be done later uploading the html file via spiffs.html]

-------------------------------------------

The private zone:
These sites are admin only and require a html authentification with the credentials we defined in the code above ("www_username" and "www_password"). As an admin you can reach the following sites:

admin.html:

• configure custom messages, activate/deactivate all messages
• save current messages and parameters
• load saved messages and parameters
• load default messages and parameters

config.html:

• change and persistently save global configuration values intensity and global scroll speed (for other than custom messages which are configured via admin.html)
• manually refresh news data and optionally enable XL version of news shown on display
• manually refresh weather data
• restart device
• erase WiFi credentials
• over the air update (OTA) via web interface

spiffs.html:

• manually up-, download or delete files on SPIFFS memory -> Don't do anything here, if you're not sure what's going on!

Spotify Integration (ESP32 only)

Access to the Spotify API is a really nice feature. Unfortunately the way to get there is not trivial and it took me quite a lot of time and cost me some nerves to implement this feature successfully. If you're interested in the API authentication process (OAuth 2.0) you can take a look here at the Spotify page. Otherwise just follow these steps to authenticate your device with your Spotify account.
Note: You must take these steps before compiling the code!

• Step 1: Browse to https://developer.spotify.com/dashboard/ and log in with your Spotify account (free or premium)
• Step 2: Click on "Create an app", enter a hardware name and a hardware description, check "I don't know" under "What are you bulding?" Read the conditions and if you agree check them and click on submit.
• Step 3: You can find the Client ID and the Client Secret under your display's name on the left side. You'll need them later on for the varibales in the program code.
• Step 4: Click on "Edit Settings" and enter the following Redirect URI: http://esp.local/callback/ (Don't forget the slash at the end!) Click on "Save".
• Step 5: Now you've finished all preparations. Go to your code and write the client keys into the variables "clientID" and "clientSecret". Finally you're ready for compiling!
• Step 6: Once your device is configured and running in normal WiFi mode browse to its webportal. Then enter the following address in the browser: xxx.xxx.xxx.xxx/spotiauth
  For instance, if your device has the local IP 192.168.4.120 you must enter 192.168.4.120/spotiauth
  Important Note: Android browsers are not able to handle this process, so start it from your computer's browser.
• Step 7: You will be redirected to a Spotify site. Log in and grant the permissions asked for. Once you did this, the following process automatically runs in background and some moments later you should see a success message in the browser. This authentication process must only be done once - all required data are saved persistently into a file on the device.
  (Calling spotiauth again doesn't harm, but it is not necessary.) That's all - you made it and your device is ready to receive data from Spotify!

Housing

If your device is running fine, you can start think about making an attractive housing for it. The housing I made can be an inspiration, but I'm sure there is a endless number of possibilities and ideas how to prettify your display with a proper housing. My original plan was to build a wooden box coated with a veneer the display can shine through. There exist some nice examples for this, like here.

So I ordered a wooden box, some pieces of a nice oak veneer and tested my display with the (really thin) veneer over it. The result was a little disappointing: it was nice with static display, but the scrolling effects were blurred because of the strong grain of the oak veneer. I tried sanding the veneer to make it even thinner, but that also didn't help. So I had to change my plans and cut a window in my box. After fitting the LED matrix into the box I covered the window with a thin black film cutted from a plastic folder. Finally I coated the box (except the window...) with my nice oak veneer (which was difficult enough, having worked with veneer for the first time. After many attempts to cut the veneer the only method that worked for me was using a small multifunction rotary tool.)

Known Issues

ESP32

• Sometimes after skipping the config portal (- regular setup with Wifi credentials works fine -) the webserver can't be reached, though the AP has been established. Power cycling the ESP32 can help.
  I guess this could be related to an other known issue (connection only every second time). You won't notice that issue, because I made a workaround for this in the code.
• The following issue is gone since V1.0.5 of ESP32 core for Arduino!
  [The most annoying issue is related to the webserver: sending the guest message via index.html or updating the messages via admin.html can result in a failure indication on the website, though the messages have been sent successfully - a page reload shows that. Beside that, the call of the html sites "news.html" and "spiffs.html" can partially fail - but only with Chromium based browsers. With Firefox everything works fine - I can confirm this for Windows and Android.
  Note: This doesn't affect the messages shown on display - they are running without any problems!
  It would be nice if someone had an idea how to get this running or how to set up a workaround for this issue.
  Update V 1.0.1 : I made a small change in some html files with an ugly workaround for that issue: I just added a line with a short delay which helps in most situations; because this is really not a satisfying solution and would negatively affect non-Chrome users, you must uncomment the line manually. You will easily find it in the files news.html, spiffs.html and spotify.html.
  Update V 1.1 : I improved the manual workaround in nearly all html files. Changes to be made are marked with "// FIX".]

ESP8266
In some rare cases, there can occur some heap problems calling weather Data - but only if debug mode is active. So if you don't need it, disable debugging and everything works fine. (I was able to confirm this, writing the successful calls of weather data into a log file for several days.)

Credits

This project wouldn't have been possible without the work of many others:

• Special thanks to Marco Colli (MajicDesigns) for his libraries, the excellent documentation and the support via arduino forum.
• Special thanks to Benoit Blanchon for his great Arduino Json Library and his friendly support.
• Local language concept and some parts of weather functions inspired by ericBcreator and his great display project
• SPIFFS administration taken and adopted from the great Arduino ESP website https://fipsok.de/ by Jens Fleischer
• HTML background pattern graphic by Henry Daubrez, taken from http://thepatternlibrary.com/

Thanks to the many, many other programmers and enthusiasts in the web whose work and helpfulness enabled me to realize such a project.