Inkycal - Your personal e-paper dashboard

Learn how to create your own e-paper dashboard using Inkycal, a python software that requires no coding skills!

E-Paper displays are finding more and more use-cases far beyond the amazon kindle paperwhite and digital price tags in shops. However, most applications are limited for business-clients and manufacturers or resellers don't often provide software meant to be used by consumer end-clients. Instead, they provide you with just the driver and some examples on how to add text, but many people want to see more awesome products utilising e-paper in the market.

Inkycal is essentially the name of the python software (with me being the author) to make your own personal dashboard with much more ease, options to configure and lots of customisation options, without requiring any coding skills. This is because to make the dashboard, you only need a single file, which a site will generate for you after you specify how you want your dashboard to look.

Why E-Paper?

There is no doubt that the majority of displays are based on LCD. This means a lot of power is required to make anything visible at all as the internal lighting is fighting with the external lighting to make something visible to the eye. In short, if you remove the power, you see nothing, in this case, your screen is black.

E-Paper on the other hand can sort of "flip" pixels from black to white (and sometime other colours) too. So power is only needed when needing to change the content, but not to maintain it. It's sort of like paper. You write something, it stays. To remove it, you need to erase what you drew previously. Then you can write again.

The flipping of the pixels takes much more time than LCDs. One image on e-paper can sometimes take 30 seconds to display, while LCD displays can display 144 different images in one second. However, many applications don't have data changing every few seconds or minutes, e.g. the weather or news etc. Therefore, e-paper displays are much more efficient in certain applications than their counterpart LCDs and therefore more eco-friendly for these applications. This motivated me to develop Inkycal, which you can see here on Github: https://github.com/aceinnolab/Inkycal

Why an e-paper dashboard or calendar?

E-Paper displays are very close to the look and feel of paper. With a lifetime of ~5 years (although I have several running for ell over this time), it is a suitable alternative to paper where the content can only be written a very limited amount of times. Furthermore, while it looks and feels like paper, it is still digital, allowing a computer to fetch and display the information for you in just one place rather than having to look it up each time. It's basically the dashboard of the future, switching away from power-hungry LCDs or non-reusable paper to the more eco-friendly e-paper technology

Supplies

To get started, you'll need the following supplies:

Raspberry Pi with 40-pin GPIO and WiFi. If you do not know how to solder, please get one with pre-soldered headers. I personally recommend the Zero W or Zero WH as it's powerful enough while requiring only little power
Micro SD Card (min. 8GB)
Power supply cable for your Raspberry Pi (e.g. microUSB (USB-TypeC cable)
A 2-colour or 3-colour 7.5" e-paper display from Waveshare with the driver board
Access to a computer (for flashing the OS)
Some kind of housing for the hardware and display, e.g. an Ikea Ribba photo-frame

P.S.: Don't worry if you cannot get hold of these supplies yourself. If you'd rather buy a fully pre-assembled version, we also offer that on Tindie: Get Inkycal on Tindie

Step 1: Flashing Raspberry Pi OS

To install Raspberry Pi OS on the microSD card, the easiest way now is to use Raspberry Pi Imager, which you can download from the official Raspberry Pi website:

https://www.raspberrypi.com/software/

After downloading, please download this specific version of Raspberry Pi OS:

https://downloads.raspberrypi.com/raspios_lite_armhf/images/raspios_lite_armhf-2023-12-11/2023-12-11-raspios-bookworm-armhf-lite.img.xz

Then, you can flash the OS according to this video I made in advance:

https://www.youtube.com/watch?v=IiIv_nWE5KI

Head over to the next step while the OS is being written on the microSD card as this can take several minutes.

Step 2: Setting Up the Dashboard

While you wait for the OS to be written to the microSD card, you can go ahead and generate a settings.json file, which will contain all information needed for making and customising your dashboard.

For this, head over to the web-ui:

https://aceinnolab.com/inkycal/ui

Make sure you first select the display you have. If you do not know this, you can check the order details, more specifically the resolution of the e-paper display and the supported colours. Then, you can add modules via the add-module button from a growing number of modules, including but not limited to:

Weather
News (RSS or Atom)
Google-Calendar (without needing an API-key)
Comics (xkcd)
Stocks
Images
Jokes
Text
Todoist

For each module, the website will tell you what you need to set up this module. Apart from this, you can also set the height of each module. Feel free to play around with the settings and mix and match the modules tailored for your needs.

A default, just works-out-of-box config can consist of something similar to:

Weather with height 15
Calendar with height 60
News with height 20
Jokes with height 5

You can use the preview function to see how it will look on your display. Once you're happy, press on generate to get the settings.json file.

Once the writing of the OS from the previous step has completed, remove, then re-insert the microSD card in your PC. Finally, copy the settings.json file into the bootfs folder, which should be the only visible one.

Step 3: Setting Up the OS

Out of the box, the Raspberry Pi OS image does not even know what Inkycal is. Therefore, we will need to access the Raspberry Pi via SSH. Don't worry if you've not heard about it, I'm using Termius for this, which you can download from here: https://termius.com/download/windows . It basically allows you to control a computer remotely, in this case your Raspberry Pi Zero. To connect to your Raspberry Pi, you need three things at least:

hostname: assuming you set the hostname as inkycal, this will be inkycal.local
username: this is the username you set before
password: this will be the password you set when flashing the OS

After connecting, you can install Inkycal by following the instructions of the README of the repo here:

https://github.com/aceinnolab/Inkycal?tab=readme-ov-file#configuring-the-raspberry-pi

I'm deliberately not copying the instructions here as with nearly all tech products, instructions change over time and even small changes can break big things.

However, please note that although you only need copy-pasting skills, the installation can sometimes take hours. If you want to skip over this waiting time, you can also get access to the pre-configured version of Inkycal, namely InkycalOS-Lite via the sponsor button on the same repo, where all these steps are done in advance for you

Step 4: Playing Lego...err I Mean Assembling the Hardware

Assembling the lego blocks isn't difficult, but there are a few gotchas, which I will go through here:

1) Assemble the driver hat on the Raspberry Pi. It's difficult to get this wrong

2) There will be two teeny switches on the driver board. Ensure they are set to mode B (0.47 Ohm) and 4-line SPI

3) Place your e-paper display with the front-side facing up. Then, connect it with the driver hat by inserting the flex-cable in the connector

Step 5: Is There Even Life?

Well done making it so far! What's left now is to restart the Raspberry Pi. You can either plug the power cable or type sudo reboot via SSH. If everything went fine, roughly 10 minutes after reboot, you will see your magical dashboard appear after a series of flickering on the display 🎉

At this stage, Inkycal will run in the background once the OS has booted up. Congratulations on your Inkycal! 🥇

Step 6: Debugging and Shooting Trouble

In case at this stage, you've waited plenty and there still isn't an image, you're not left alone by yourself to help find and fix the issue. In fact, Inkycal has a dedicated Discord server for providing support for Inkycal, which you can join for relatively fast help: https://discord.gg/sHYKeSM

To find out what went wrong, you can run the following commands after connecting to your Raspberry Pi via SSH:

cd ~/Inkycal
source venv/bin/activate
python inky_run.py
# at this stage, you will soon see the exact error. Please copy the entire error and post it on Discord
# You will soon receive the help to fix the issue

If you do not have Discord, you can also get help via Github Issues from here:

https://github.com/aceinnolab/Inkycal/issues

Just create a new issue with the error and you'll get help :D

That's all for this time!

Please don't forget to like/vote the project if you like it. Until next time 😉