Skip to content

Latest commit

 

History

History
102 lines (60 loc) · 7.39 KB

README.md

File metadata and controls

102 lines (60 loc) · 7.39 KB
Raw

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).

Dashboard Example

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

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.