A Raspberry Pi dashboard on a Waveshare ePaper HAT

A picture frame that shows today at a glance

The problem this project solves is narrow and physical: you want a screen on a wall that tells you the date, the time, today's weather, any severe weather warnings, and what is on your calendar, without needing to pick up a phone. The target hardware is a Waveshare 7.5 inch ePaper HAT at 640x384, the panel size that a standard photo frame almost fits, and a Raspberry Pi Zero WH with a presoldered header.

E-paper is the reason the hardware is specific. A reflective panel holds its image with no backlight, so it is readable in a hallway and consumes almost nothing when idle. It also cannot scroll, animate or repaint at video rates, which dictates the design of everything above it. The application therefore composes a static page and pushes it to the display, rather than running a browser, a compositor or a server with a websocket feed.

The audience is a home lab or a small office where somebody wants a shared status panel for a wall. The project is not aimed at product teams building a fleet of displays, and it does not try to be a general kiosk framework.

The panel hangs off SPI, and SPI is switched on by hand

The mechanism is visible in the setup instructions and in the dependency list. The HAT connects to the Pi's GPIO pins, and the project enables the SPI bus with the raspi-config nonint command before rebooting. The Python side talks to the bus through spidev and RPi.GPIO, both of which appear in requirements.txt at pinned floors of spidev>=3.6 and RPi.GPIO>=0.7.1.

Rendering happens in two stages. The application draws a page, and that page is turned into the bitmapped image the panel expects. The requirements show how that pipeline is built: CairoSVG==2.9.0 for turning SVG into a raster, cairocffi and Pillow>=9.3.0 for the image surface, plus lxml, tinycss2, cssselect2 and defusedxml for parsing and styling the SVG tree. Rendering SVG rather than painting pixels directly is why the toolchain needs fontconfig, libcairo2 and libopenjp2-7 installed on the system, and why the apt install line includes the Noto and Ghostscript font packages.

The base image is Raspberry Pi OS Lite rather than a desktop build, and the project expects SSH access and network connectivity so packages can be fetched. That choice keeps the image small and the boot fast, but it also means the application is a service you operate rather than an app you open.

One config.toml drives every provider and every layout

The repository is organised as one application with pluggable data sources. The top level contains provider packages named weather_providers, calendar_providers and alert_providers, alongside lib for shared logic, templates for the pages that get rendered, utils, data, icons and docs. There is a config.example.toml at the root, and the README is explicit that you copy it to config.toml and that this is where all the settings will be stored.

That single file is the integration point for the whole system. Weather, warnings, calendars, location, units, display hardware, language and layout all live in it, and each provider adds its own section for credentials. The application itself is launched through run.sh, and scripts and a .gitmodules entry sit alongside the source directories.

Because the configuration is plain TOML and the providers are separate modules, adding a new data source is a matter of dropping a module into a provider directory and documenting a new section. The cost of that design is that there is no schema validation layer mentioned in the documentation, so a typo in a section name is discovered when the panel fails to update rather than at startup with a clear error.

The template layer is also how the display varies. The README lists a section on picking a layout, which means the arrangement of date, weather and calendar is a choice you make in configuration rather than a hard coded screen.

Installing on a Pi Zero WH, step by step

The documented path starts with the Raspberry Pi imager and a Raspberry Pi OS Lite install, with SSH and WiFi configured through the imager settings screen. With the Pi powered off, the HAT goes onto the GPIO pins and the ribbon from the panel is pushed into the connector with the black latch lifted. After that you SSH in and clone the project into /home/pi:

    cd ~
    sudo apt update && sudo apt upgrade
    sudo apt install git
    git clone --recursive https://github.com/mendhak/waveshare-epaper-display.git

The clone uses the recursive flag, which matters because the repository contains a .gitmodules entry, and it should leave a /home/pi/waveshare-epaper-display directory behind. Next come the Python dependencies, the virtual environment and the SPI switch:

    cd waveshare-epaper-display
    sudo apt install gsfonts fonts-noto python3 python3-pip pigpio libopenjp2-7 python3-venv libjpeg-dev libxslt1-dev fontconfig libcairo2
    python3 -m venv --system-site-packages .venv
    .venv/bin/pip3 install -r requirements.txt
    sudo raspi-config nonint do_spi 0  #This enables SPI
    sudo reboot

The virtual environment is created with the system site packages flag so that the apt installed graphics libraries are visible to pip. The final two lines are the part people miss, because without SPI enabled the panel never receives data. The configuration file is then created from the example, and the hardware revision is recorded in it:

    cd waveshare-epaper-display
    cp config.example.toml config.toml

    [display]
    waveshare_version = "2"

The README explains that newer Waveshare 7.5 inch modules are version 2 and that the red one is 2B, so this single value decides which driver path the application uses.

Nine weather providers, and the one key each of them expects

Weather is the part of the dashboard most likely to send you to a provider's documentation, because credentials differ per service. The README lists OpenWeatherMap, Met Office, AccuWeather, Met.no, Weather.gov, VisualCrossing, Climacell and SMHI as the choices, and the provider key in config.toml selects one:

    [weather]
    ... your location details from above ...
    provider = "metoffice"                # metoffice, climacell, accuweather, openweathermap, metno, met_eireann, weathergov, smhi, visualcrossing

Location and units sit in the same section, so the display shows what you asked for rather than a default:

    [weather]
    latitude  = 51.5077
    longitude = -0.1278
    format = "CELSIUS"

What differs between providers is the credential model, and this is where the project's provider abstraction earns its keep. OpenWeatherMap wants an api_key from its API Keys page. AccuWeather wants both an api_key and a location_key, and the location key is the last number in the URL of a search result on its site, which the README spells out with a London example. Met.no wants no key at all, only a self_identification email address, because its terms of service require you to identify yourself so the service can contact you if you overload its servers. The Met Office path asks for a subscription to the Site Specific product Global Spot on its DataHub site, and Met Éireann publishes its forecast data under a Creative Commons Attribution 4.0 International license.

There is also a functional difference that affects what the panel can show. The README notes that the Met.no API provides 6 hours of forecast rather than a full day, so on that provider the forecast section of the display is shorter by design.

Warnings and calendars arrive through separate provider chains

Severe weather warnings are configured independently from the forecast. The README has its own provider sections for the Met Office in the UK, Weather.gov in the US and Met Éireann in Ireland, and the top level alert_providers directory is where that code lives. Keeping alerts apart from weather matters for the layout: a warning provider is about attention, not about temperature, and a display that shows a warning has a different visual priority than one showing a high and low.

Calendars work the same way, with calendar_providers holding Google Calendar, Outlook Calendar, ICS Calendar and CalDav implementations. The project's description names Google and Outlook calendars as the headline sources, and the release history confirms the direction of travel: v11 in November 2022 was titled around Caldav and ICS calendar providers, which suggests the simpler subscription based calendars were added alongside the OAuth based ones rather than replacing them.

The difference in approach here is real and it is visible in the requirements. Google and Outlook access is served by google-api-python-client, google-auth, google-auth-oauthlib and msal, which are client libraries for OAuth based APIs and imply a token setup step. ICS and CalDav need icalendar, icalevents and caldav instead, and vobject, which are parsing libraries for calendar files and collections. Choosing ICS or CalDav means less credential plumbing; choosing Google or Outlook means a proper delegated login. The README also points at a section on debugging locally for working on the application away from the panel.

Privacy mode, custom data, fonts and language

The README carries sections for adding custom data, choosing a different display language, choosing a different font, and a dedicated Privacy Mode. The screenshots directory carries a file named pvt_literature_irl.png alongside the default display screenshot, and the privacy mode image in the default layout set is what confirms this is a real mode rather than a placeholder in the table of contents.

The mechanism behind custom data and privacy mode is the template layer. Since pages are rendered from templates and driven by config.toml, a display that hides personal details, or one that adds a field of your own, is a change to a template and a config section rather than a change to a driver. Language and font are handled the same way, which also explains why the apt install line pulls in gsfonts and fonts-noto: the renderer resolves fonts by name, and a missing family falls back to whatever fontconfig can find.

Custom data is the feature with the least detail in the README, and it is the one to check first if you want it, because the documentation for it is brief compared with the provider sections. A dashboard that shows a bus timetable, a garage door state or a build status is a different application with the same renderer underneath, and this project is a reasonable base for that as long as you are prepared to read the templates yourself.

Heavy dependencies, MIT licence, and a release history that trails the commits

The dependency list is long for a small display utility. requirements.txt names around fifty packages, and among them are cryptography, cffi, certifi, protobuf, PyJWT and msal, all of which come from the calendar integrations rather than from the display itself. The rendering stack is similarly heavy, with lxml and a pinned CairoSVG. That is a large surface to install on a Pi Zero, and the two apt packages for image libraries and fontconfig are part of the same story. A project of this size installed on a Pi Zero will spend real time on first install.

The licence is MIT, which permits commercial and private use and requires only that the copyright notice and licence text accompany copies of the source. It places no restriction on the images your dashboard renders, which matters if you plan to publish photographs of your own display.

On maintenance, the repository is not archived and the last push was on 2026-09-01. The recorded releases, however, stop much earlier: v13 with localization on 2023-02-13, v12 with SMHI on 2023-02-05, and v11 with the Caldav and ICS calendar providers on 2022-11-30. So the code has moved in the three and a half years since the newest tag without a new release being cut, and the tagged versions are the ones the README and the changelog talk about. There is a CHANGELOG.md at the root, which is the place to look for what changed after v13.

The bigger constraint is the display itself. A 640x384 ePaper panel has no animation and a slow refresh, so this application suits a static summary, not a live chart. If you need a scrolling ticker or a constantly updating counter, the hardware is the limit, not the software.

Editorial conclusion

Use mendhak/waveshare-epaper-display if you want a wall mounted display that shows a glanceable date, weather, warning and agenda without a backlight, and you are willing to run Raspberry Pi OS Lite with SPI enabled and hand over API keys to one weather provider. Skip it if you need a live, animated or interactive display, since the target hardware is a 640x384 ePaper panel and the project is built around refreshing that panel. Before you start, confirm that your Waveshare module is version 2 or 2B, since the setting is chosen in config.toml, and check that your chosen provider's API key is present in the matching [weather.providers] section.

Frequently asked questions

Official sources

1. License: MIT
2. mendhak/waveshare-epaper-display on GitHub
3. Project website
4. README
5. Releases