MagInkDashPlus

This is a fork of the original MagInkDash -- replacing the Google Calendar integration with a generic ICS feed, removing the OpenAI integration, and using a Docker-based REST API that renders the image on-the-fly instead of a Raspberry Pi cronjob.

This repo contains the code needed to drive an E-Ink Magic Dashboard that uses a Docker container on a different host to automatically retrieve updated content from an ICS calendar and OpenWeatherMap, format them into the desired layout, before serving it to a battery powered E-Ink display (Inkplate 10). Note that the code has only been tested on the specific hardware mentioned, but can be easily modified to work with other hardware (for both the server or display).

Background

I liked the premise of MagInkDash but I'd rather have a containerized backend doing the rendering since that's easier to setup in my Docker-based homelab. Additionally, I'd like to enable the use of non-Google calendars and remove cloud dependencies like ChatGPT (maybe I'll add an Ollama integration in the future). Read more about the project in the MagInkDash README.

Hardware Required

• A machine that supports Docker: Used as a server to retrieve content and generate a dashboard for the E-Ink display. Just needs to have Docker and Docker Compose installed so any old machine or SBC would do. I would recommend that this container is not exposed to the public Internet since it shows your calendar information without authentication.

• Inkplate 10 Battery Powered E-Ink Display: Used as a client to display the generated dashboard. I went with this because it was an all-in-one with the enclosure and battery included so there's less hardware tinkering. But you could certainly go barebones and assemble the different parts yourself from scratch, i.e. display, microcontroller, case, and battery.

How It Works

On the backend, a Python API based on Docker and FastAPI is serving the image with all the desired info. As soon as the Inkplate requests the image, it pulls the calendar data and a weather forecast from OpenWeatherMap. The retrieved content is then formatted into the desired layout and served as a PNG image file.

On the Inkplate 10, a script will then connect to the server on the local network via a WiFi connection, retrieve the image and display it on the E-Ink screen. The Inkplate 10 then goes to sleep to conserve battery for 60 minutes or until the wake button is pressed. The dashboard remains displayed on the E-Ink screen, because well, E-Ink...

Some features of the dashboard:

• Battery Life: As with similar battery powered devices, the biggest question is the battery life. With the 3000mAh that comes with the manufacturer assembled Inkplate 10, we could potentially be looking at 6-8 month battery life. With this crazy battery life, there are much more options available. Perhaps solar power for unlimited battery life? Or reducing the refresh interval to 15 or 30min to increase the information timeliness?

• Calendar and Weather: I'm currently displaying calendar events and weather forecast for current day and the upcoming two days. No real reason other than the desire to know what my weekend looks like on a Friday, and therefore helping me to better plan my weekend. Unfortunately, if you have a busy calendar with numerous events on a single day, the space on the dashboard will be consumed very quickly. If so, you might wish to modify the code to reduce/limit the number of days/events to be displayed.

Setting Up

1. On the server host, make sure that docker and docker compose are installed.

2. Download the docker-compose.yml file from this repo and adjust the environment variables, see the section Config Reference below. If you are not sure how to get the ICS URL, refer to How to get the ICS URL below.

3. Start up the server with docker compose up -d. You can check the logs with docker compose logs -f and ensure that there are no errors.

4. Using the DNS name or IP of your host machine, you can go to http://IP_ADDRESS:5000/docs to see whether the API is running.

5. As for the Inkplate, I'm not going to devote too much space here since there are official resources that describe how to set it up. It may take some trial and error for those new to microcontroller programming but it's all worth it! Only the Arduino portion of the guide is relevant, and you'll need to be able to run *.ino scripts via Arduino IDE before proceeding. From there, run the inkplate10.ino file from the inkplate10 folder from the Arduino IDE when connected to the Inkplate.

6. That's all! Your Magic Dashboard should now be refreshed every hour!

How to get the ICS URL

MagInkDashPlus supports any standard ICS feed, here are a few popular calendars and how you can get the ICS feed URL. These instructions might change and are up-to-date as of December 2024.

Google Calendar

Go to the calendar you want to display, click Settings and sharing, and copy the Secret address in iCal format.

Proton Calendar

Go to the calendar you want to display, click Share, then Share with anyone, then Full view (see all event details), click Create, and copy the link.

Nextcloud

Go to the calendar you want to display, click the edit icon, create a share link, and Copy subscription link.

Config Reference

These are the config variables you can configure in the environment section of the Docker Compose file:

Variable	Required	Default	Description
ICS_URL	Yes		URL of the ICS calendar feed
OWM_API_KEY	Yes		OpenWeatherMap API key to retrieve weather forecast
DISPLAY_TZ	No	America/Los_Angeles	Time zone for displaying the calendar
LAT	No	34.118333	Latitude in decimal of the location to retrieve weather forecast for
LNG	No	-118.300333	Longitude in decimal of the location to retrieve weather forecast for
WEATHER_UNITS	No	metric	Units of measurement for the temperature, metric and imperial units are available
NUM_CAL_DAYS_TO_QUERY	No	30	Number of days to query from the calendar
IMAGE_WIDTH	No	1200	Width of image to be generated for display
IMAGE_HEIGHT	No	825	Height of image to be generated for display

Development

Run

poetry run python src/main.py

or

docker compose -f docker-compose.dev.yml up --build

locally to start the application, API docs will be served at http://localhost:5000/docs.

Acknowledgements

• Lexend Font and Tilt Warp Font: Fonts used for the dashboard display
• Bootstrap: Styling toolkit to customise the look of the dashboard
• Weather Icons: Icons used for displaying of weather forecast information
• Freepik: For the background image used in this dashboard

Contributing

Feel free to fork the repo and modify it for your own purpose or create an issue and I see whether I can help.