Display your Mastodon followers count on a 4 digit TM1637 display

If you ever wanted to show how many followers on Mastodon you have without pointing people to your account, but instead present it on a physical numeric display, you have come to the right place.

This is a quick and simple project that with the right hardware you can finish in maybe 15 minutes. And can be infinitely expanded by presenting other information as well, or toggling through data, or doing simple animations. The sky (but not Bluesky) is the limit.

What you need

1. A single board computer with GPIOs, any Raspberry Pi or its clone will do. I wrote the script to be run a full-fledged computer running Pi OS, but with minor modifications can also be run on a microcontroller like a Pi Pico. For brevity, I will assume you are using a Raspberry Pi.

2. A TM1637 based four digit display. You can buy them cheap from Arduino or any other electronics store.

3. Female to female connecting cables.

Create access creds for Mastodon API

The Pi will need to talk to Mastodon using the Mastodon API. For that to happen, access credentials need to be generated. Open your Mastodon account page, and go to Preferences, next Developer, and click New Application. Fill in the form, the name and website can be anything, it does not matter. In the Scopes section select only “read all your account’s data”. That is all that is needed, and it is a good practice to give such creds only the minimal set of permissions, so don’t select anything else.

Once you created an application, you will be given the Client key, the Client secret and the Access token. Save them in a secure place and do not share them with anyone. Let’s now move to setting up the Pi.

Hardware Setup

I assume you have a working single board computer running Linux, which you can access using a keyboard and a screen, or via SSH. I will not dive into configuring and starting an SBC here.

Once you have an SBC ready, make sure it is powered down before connecting the display to the Pi.

Here’s the pinout diagram which I have taken from the Pi’s official documentation. If you are using a different board, check its docs.

The display has four pins: VCC, GND, CLK and DIO.

Connect the VCC pin to the 3.3V pin on the Pi, this is GPIO 1. Connect the GND pin to any of the ground pins on the Pi, I connected it to the ground pin next to the 5V pins, as it’s the closest one to the 3.3V one.

The CLK and DIO pins can be connected to any digital input/output pin on the Pi.

I connected them to GPIO 2 and GPIO 3 respectively as again, they are the closest ones.

Start the Pi and open the terminal.

Software Setup

I am assuming you are running a Debian-like distro. If not, use the package manager that comes with it. This will be the only distro-specific part.

First, make sure you have python-venv and git installed. We will need them later.

sudo apt-get install python3-venv git

Copy my repo to fetch the required files

git clone https://codeberg.org/stfn/mastodon-followers-display.git

Now it’s time for setting up the script. It is good practice to never mess with the system Python environment, so let’s create a virtual environment to install the dependencies needed to run the script.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The next step is to set the access credentials so that the script will be able to talk to Mastodon. Copy the .env-example file to a new one called .env and fill in the variables with the credentials you got when setting up the Mastodon API. The API_BASE_URL is the url of your instance.

cd mastodon-followers-display
cp .env-example .env
nano .env

Running and adding to cron

Once the setup is done, it’s time to actually test the script

python script.py

The display should come to life, first show 0000, and once the Pi logs into Mastodon, it should show your followers count. If nothing happens, make sure that the pins are connected correctly, maybe DIO and CLK are the other way round.

The final step is adding the script to cron so that it will be run periodically, for example every five minutes.

Open cron:

crontab -e

At the bottom of the file, add this line:

*/5  * * * * /home/stfn/mastodon-followers-display/venv/bin/python /home/stfn/mastodon-followers-display/script.py

The first part of the line is the cron time statement. This one means “every ten minutes”. Use crontab guru if you want to have a different time period. Cron requires absolute paths, that’s why we are providing first the path to the python binary that is in the virtual environment created during setup, and then the absolute path to the script file. Remember to change the paths to your actual ones!

Aaand done, now you can put the Pi with the display on a shelf and boast how many people follow you on Mastodon, after all, this is all that matters, right? Right?

( ͡° ͜ʖ ͡ – ✧)

Thanks for reading! Please leave me feedback via email or Mastodon, and if you really enjoyed this short post, consider helping with funding my future projects by supporting me on these crowdfunding sites: