Name that Tune

Spotify Song Display with ESP32 and E-Paper Display

Heikki Hietala

Issue 58, May 2022

An ESP32-based e-Paper display and speech-driven hub that shows the artist, album and song details playing on your Spotify account.

This curious-looking project, submitted by maker Heikki Hietala via our website, caught our attention. The system uses an ESP32 to connect to his Spotify account, then it goes to see what song is playing, and displays the artist, album and song on an e-paper display, which is housed in a custom 3D printed box. The system also has a stand for an Amazon Echo Dot, which is speech driven, so Heikki can change song and ask for songs without using a computer. The Echo Dot and the display need not know of each other either. The link is the Spotify account.

We got in touch with Heikki to find out more about the project.

Thank you for your project submission. Please introduce yourself to our readers, and what got you interested in electronics.

I’m not an engineer. I have a Master’s degree in English, but ICT was my minor (that was in the 1980s, mind you).

I’ve been in the IT business since 1986, working in a variety of roles, until in 2003 I joined Haaga-Helia University of Applied Sciences as a Senior Lecturer. Here I have been teaching many courses, but lately, IoT, Innovation, User Experience, and 3D modeling and printing.

That sounds like a dream job to us. What was the motivation behind making your project?

I wanted to see if I could make this. I am always trying to think of demo devices to build as lures for the students, and to show them that if you can think it, you can build it. I am always trying to tell my students that it’s not what you can do, it’s what you want to do, and that learning by failing is the best way.

Agreed. Getting hands-on, giving things a go, and learning from any challenges along the way is a great way to learn. How does your project work and what parts does it use?

This is a simple device. It has an ESP32 as the centerpiece. It’s connected to the 3D + Robo Lab WLAN, and every three seconds, it polls my Spotify account to see what’s playing. That information is then displayed on a 2.9” e-paper display, where it remains even if the device is unplugged.

It has an old mobile phone charger as power, and a single button to restart it. The device is housed in a 3D printed box that also acts as the stand for the Amazon Echo Dot, which actually plays the music. The two devices are not aware of each other, it’s the Spotify account that is the link.

We love the use of an e-paper display. Many of us makers usually reach for an LCD module instead. What made you choose e-Paper?

Mostly because I bought five of them for the University 3D + Robo Lab, and since some students reported them to be more complex to use than LCDs, I wanted to have a look so I can support my students later. It also has more space for information than even a 4 x 20 character LCD does.

Did you need to do any prototyping? And, what challenges did you need to overcome and how?

As always, I test the parts one by one, doing “hello world” on the Spotify link first, then learning to use the display, and finally adding them together. I don’t usually redo much of my projects, the first is usually the final. Except for my 8mm film scanner – that is now in Version IV (see https://www.sabulo.com/sb/category/8mm-film/).

Will it work with other types of Hubs such as Google Home?

As the link between the devices is Spotify, yes, when you link the Google Home to your Spotify. The ESP32 doesn’t know what is at the other end, it just polls Spotify.

Brilliant! How did you go about coding it? Did you code from scratch or remix someone's code?

I don’t flatter myself as such a skilled coder as to be able to write this from scratch. There is a wonderful library for connecting ESP32 to Spotify, namely
https://github.com/witnessmenow/spotify-api-arduino written by Brian Lough. The display also had demo code on its driver library, so it was just some trial and error to get it to work.

The display’s libraries are from https://www.waveshare.com/wiki/E-Paper_Driver_HAT, and the usual WLAN stuff from ESP32.

Tell us about the 3D printed case and what printer you own.

At the Lab we have eight filament printers of four different types, so we can run intensive courses on printing. We also have a Formlabs Form 3 for detailed resin prints. The design of the box and the echo Dot stand took something like 20 minutes, and the print in three parts maybe three hours. It’s not perfectly neat, but it works, so I don’t want to redo it.

You’re certainly spoilt for choice for 3D printer. We’re very jealous. If our readers want to make something similar for themselves do you have the code and 3D print files available?

All of my work and building instructions make their way to my blog at www.sabulo.com at some point. Code is available on my GitHub, as well as the STLs for the printable parts. I know that at least five people did build a 8mm scanner inspired by my system, and I would hope this easy build would encourage people to try the ESP32s and e-paper.

It’s so wonderful that you have made this open-source. Is there anything we haven't discussed that our readers should know about your project?

As I always say, if I can build this, anyone can. My code needs a little more commenting, but it will be on GitHub, so this would be an easy build for people who want to see how to use the Spotify API on ESP32.

Great! Thank you for sharing your project and build details with us. We look forward to seeing what else you build in the future.

The Build:

Setting up ESP32 and Spotify

First, you must go to the Spotify Web API page to get your account set up. This will give you access to the Developer Dashboard where you can create test apps for your web pages and get to know the interface. When you create the account, you will receive a client ID, which is a long string of characters. Note it down, you will need it. You will also see a link for a Client Secret, which you will also need, but never disclose either of these to anyone, because that could compromise your account.

Next, use Brian’s file called getrefreshToken.ino. This file, available as all the files on the GitHub, needs to be run on your ESP32. When you run it, its Serial Monitor will return to you the last piece https://developer.spotify.com/documentation/web-api/quick-start/

So, download the file, install the libraries that are required, and update the following before running the file:

char ssid[] = "SSID";
// your network SSID (name)
char password[] = "password";
// your network password
char clientId[] = "56t4373258u3405u43u543";
// Your client ID of your spotify APP
char clientSecret[] = "56t4373258u3405u43u543";
// Your client Secret of your spotifyAPP
// (Do Not share this!)

When you then run the code, it will show the refresher code in the Serial Monitor. Note it down and keep it secure.

After this, you can move to the other files in the examples folder on GitHub, such as GetCurrentlyPlaying.ino. The relevant parts in it are these:

//------- Replace the following! ------
char ssid[] = "SSID"; // your network SSID (name)
char password[] = "password";
// your network password
char clientId[] = "56t4373258u3405u43u543";
// Your client ID of your spotify APP
char clientSecret[] = "56t4373258u3405u43u543";
// Your client Secret of your spotifyAPP
// Country code, including this is advisable

Add your own, and your ESP32 then has access to your Spotify account. In this example, ESP32 goes to Spotify every 60 seconds to check what is playing, and then shows the data to you on the Serial Monitor. This is all fine and dandy, when you want to move to the next level, ie. install a display to show whatever is showing and not have to use the Serial Monitor for that.

Installing and using an e-Paper display

The e-Paper displays I bought for the Lab are Waveshare 2.9" black and white displays, which are clear to read. They come with a bunch of libraries, which you must install, and the setup is rather complex, but when you install the libraries, you get the examples into the File / Examples menu, so you can just try them out first and get used to them.

The good thing is that you get various fonts too:

#include <GxEPD.h>
#include <GxGDEH029A1/GxGDEH029A1.h> // 2.9" b/w
#include <GxIO/GxIO_SPI/GxIO_SPI.h>
#include <GxIO/GxIO.h>
#include <Fonts/FreeMonoBold9pt7b.h> 
// this font is referred to below with the 
// namemaxfontmono1
#include <Fonts/FreeMonoBold12pt7b.h>
#include <Fonts/FreeMonoBold18pt7b.h>
#include <Fonts/FreeMonoBold24pt7b.h>

… see website for complete code

This may look complicated, but all you do is install font libraries, and then create names for the fonts to use when you refer to them. You’ll see in a moment.

ESP32 pins to e-paper

There are eight pins you need to hook up in the ESP32:



















After that, code like this will initialize the screen and allow you to write whatever you want.

display.setCursor(30, 30);
display.println("Spotify Song Display");
display.println(); display.setCursor(60, 70);
display.println("Entering network and");
display.setCursor(60, 90);
display.println("getting Spotify data...");

SetRotation(1) makes the display horizontal. FillScreen and setTextColor are rather self-explanatory, as is setFont. The name you use here is the one you set in the setup part of the program. The setCursor function is used to place the text on the screen, and it takes some practice to get it right. This part shows the text while the system enters the WLAN and connects to Spotify.

The actual Spotify data pickup

In the main loop of the program, a function call asks Spotify for the song that is currently playing.

int status = spotify.getCurrentlyPlaying

The reason it goes into an int variable called status is that if the request returns 200, everything is fine and we can go on to show the data. Otherwise, if it’s 204, Spotify isn’t playing anything, and if it returns anything else, we have an error, and it is carried in the payload of the status.

if (status == 200)
Serial.println("Successfully got currently playing");
else if (status == 204)
Serial.println("Doesn't seem to be anything playing");
Serial.print("Error: ");

Going to the spotify.getCurrentlyPlaying() function, we have all the data in an object called currentlyPlaying:

mySong = currentlyPlaying.trackName;
Serial.println("Artists: ");
for (int i = 0; i < currentlyPlaying
.numArtists; i++)
Serial.print("Name: ");
myArtist = currentlyPlaying.artists[0].artistName;
Serial.print("Album: ");
myAlbum = currentlyPlaying.albumName;
long progress = currentlyPlaying.progressMs;
// duration passed in the song
long duration = currentlyPlaying.durationMs;
// Length of Song
Serial.print("Elapsed time of song (ms): ");
Serial.print(" of ");

The variables mySong, my Artist, and myAlbum are then used in the function calleddrawSpotifyData:

void drawSpotifyData()
display.setCursor(0, 20);
display.println("Song: " + mySong);
display.println("Artist: " + myArtist);
display.println("Album: " + myAlbum);

And there you have it. Every three seconds, the loop runs, and goes to check whether mySong is the same as myOldSong. If yes, it doesn’t update the screen, but if the song name has changed, the screen is redrawn with new song data.

I had it first set up so that since we know the length of each song, I used that information as the length of the delay, but if you call out “Alexa – next!”, the screen wouldn’t update until the old song would have run its course. Therefore I opted for a 3 second delay.

That’s basically it. The code is available on GitHub, and Brian’s fantastic libraries are there too. The STL files for printing the box and the Echo Dot frame will be there too.

Reading & Resources:

HEIKKI'S GITHUB https://github.com/HeikkiHietala/spotify-song-display

HEIKKI'S BLOG https://www.sabulo.com/sb/3d-printing-2/spotify-song-display-with-esp32-and-e-paper-display/

E-Paper Driver HAT https://www.waveshare.com/wiki/E-Paper_Driver_HAT

SPOTIFY WEB API https://developer.spotify.com/documentation/web-api/quick-start/

Heikki Hietala

Lecturer at Haaga-Helia UAS. 3D and robotics tinkerer, Finland.