EPD-nRF5: an e-paper calendar and photo frame on a Nordic nRF5

A calendar firmware first, a photo frame second

EPD-nRF5 is described as e-paper display firmware for the Nordic nRF51 and nRF52 families, and the first thing to understand about it is that the calendar is the product. The project positions itself as e-paper display calendar firmware with support for the Chinese lunar calendar, solar terms and holiday schedules. The calendar interface is adapted for common 4.2-inch and 7.5-inch e-paper resolutions, and the same firmware drives different screen sizes, with the size and driver switched through the web interface rather than by recompiling.

The second capability is image transfer. The firmware can receive images over Bluetooth and display them, which turns the same panel into a digital photo frame. The web interface supports several dithering algorithms, lets you doodle on an image and add text, and can switch between photo frame mode and calendar mode. Chinese lunar calendar, solar terms, holidays and work schedule adjustments all live in that same interface, which is what makes the combination coherent: one device, one panel, two jobs, chosen by a setting rather than by a rebuild.

The audience is therefore a maker with a specific panel and a specific Nordic board, not a developer looking for a general e-paper driver. The firmware is tied to a supported MCU list and a set of panel driver families, and it assumes a phone or computer nearby with Bluetooth.

The supported hardware list is short and specific

Four microcontrollers are named: nrf51822, nrf51802, nrf52811 and nrf52810. The topic tags add nrf51822 and nrf52811, which are the parts that appear in the naming of the project itself. For displays, the firmware supports the common UC81xx and SSD16xx series drivers, and the project says plainly that this covers black and white, 3-color and 4-color panels. That is a narrow but useful statement, because the colour depth of a panel determines what the dithering algorithms in the web interface can do.

Two hardware features go beyond simple display output. The first is custom pin mapping from the e-paper display to the MCU, so the firmware is not tied to one particular board layout. The second is sleep and wake functionality, with NFC and wireless charger named as the wake paths. For a device that spends nearly all its time showing a static calendar, the wake path is the interesting design decision: the panel is refreshed rarely, and the board sleeps between refreshes.

Bluetooth OTA firmware updates are supported as well, which is the mechanism that keeps a deployed panel current without physical access. The combination of a BLE link for images, a separate BLE path for firmware updates, and NFC or charger based wake is the feature set that distinguishes this project from a bare e-paper driver library.

The web interface is the control surface, built on Web Bluetooth

Control happens through a web based interface implemented with the Web Bluetooth API. The project publishes it at https://tsl0922.github.io/EPD-nRF5, and the documentation also says you can open it on your phone or computer, or double-click html/index.html locally to run the same files from disk. The html directory sits at the top level of the repository alongside the firmware sources, so the interface is versioned with the firmware it talks to.

What the interface does is concrete: it selects the screen size and the panel driver on the connected device, it transfers images for photo frame mode, it offers multiple dithering algorithms, it provides doodling and text addition, and it switches the device into calendar mode with monthly calendars, lunar calendar, solar terms, holidays and work schedule adjustments.

The constraint that comes with the Web Bluetooth API is that the browser has to implement it, and the connection is made from the browser rather than from a mobile app. There is no native application in the repository, and no other transport is described, so the BLE link is a hard dependency of the whole workflow. The project also points to a discussion group and a demo video, which tells you where to look when the hardware and the interface disagree about what a panel supports.

The Makefile builds a Windows desktop emulator, not the firmware

There is a desktop build target in the repository, and it is worth understanding what it is before you reach for it. The top level Makefile does not build firmware for the microcontroller. It compiles a set of GUI sources into emulator.exe:

CC = gcc
CFLAGS = -Wall -IGUI -D__HEAP_SIZE=32768
LDFLAGS = -lgdi32 -mwindows
all: $(TARGET)

The compiled sources are listed as GUI/Adafruit_GFX.c, GUI/u8g2_font.c, GUI/fonts.c, GUI/GUI.c, GUI/Lunar.c and emulator.c, and the target name is emulator.exe. Two details in the flags tell you where this runs. The -mwindows option selects a Windows GUI subsystem binary, and -lgdi32 links against the Windows GDI drawing library, so the emulator renders through Win32 rather than through a terminal or a cross platform toolkit. The heap is capped with -D__HEAP_SIZE=32768, a constraint carried over from the embedded side where memory is scarce. A clean target exists as well:

SRCS = GUI/Adafruit_GFX.c GUI/u8g2_font.c GUI/fonts.c GUI/GUI.c GUI/Lunar.c emulator.c
TARGET = emulator.exe
clean:

The practical consequence is that the desktop iteration loop is Windows only, and it reuses the same GUI and font code as the firmware so the screen layout you see locally matches the panel. Everything else in the tree, including the Keil directory, the SDK directory, main.c and the EPD directory, belongs to the embedded build, and the project points to docs/develop.md for that toolchain rather than listing the steps in the README.

Repository layout tells you where the boundaries sit

The top level directory listing is a map of the project. EPD/ holds the display side, GUI/ holds the drawing layer built on Adafruit_GFX and u8g2 fonts, with a separate Lunar.c for the lunar calendar computation. SDK/ and Keil/ are the embedded toolchain pieces, main.c and main.h are the firmware entry points, and tools/ holds supporting utilities. The html/ directory is the web interface, and the docs/ directory holds the device list and the development guide, referenced from the README as docs/devices.md and docs/develop.md.

Two structural points follow from this. First, the display abstraction is not isolated: the GUI layer, the fonts and the calendar logic are compiled both into the firmware and into the emulator, so a change to a font or to the calendar rendering shows up in both builds. Second, the supported hardware list lives in documentation rather than in code you can grep, which means the firmware will compile for a panel it was never configured for, and the pairing of driver and pin mapping is something you verify against docs/devices.md.

The code is written in C and the tree carries a .clang-format file, so the project has a defined formatting style for the embedded sources. There is also a .github directory, which is where the release and build automation for the published versions lives.

Developing against the emulator instead of a panel on your desk

The emulator is the alternative to the obvious workflow of wiring a panel to an nRF board and reflashing over and over. The difference in approach is that the emulator reuses the real GUI and calendar code and draws into a desktop window, so the layout, the fonts and the lunar calendar rendering can be checked without an e-paper panel, a dev board, or a BLE connection. The cost is that the emulator inherits the embedded constraints. The heap is fixed at 32768 bytes, the code is C compiled with warnings on, and the drawing is done through the GDI32 path rather than through the panel driver, so a display bug that only appears on a specific UC81xx or SSD16xx controller will not be caught here.

The other side of that choice is the real device loop, and it is the one that BLE makes expensive. With the hardware in hand you can select the driver and the pin mapping from the web interface, push an image, and then wait for the panel to refresh, because e-paper refresh is slow by nature. Building for that loop means using the toolchain in docs/develop.md and the Keil or SDK directories, and the project documentation does not spell out those steps.

The two loops are complementary rather than exclusive. A workflow that sketches the calendar layout in the emulator, then switches to the panel for dithering and refresh behaviour, covers more ground than either one alone, and the emulator is the cheaper half of that pair.

Release pace, GPL-3.0 and the code this project builds on

The repository is not archived, and the last push was on 2026-09-08. Releases are published and reasonably spaced: version 1.10 came out on 2026-08-08, version 1.9 on 2025-10-25 and version 1.8 on 2025-07-27. The project publishes a homepage at https://tsl0922.github.io/EPD-nRF5, which is where the releases and the device documentation are presented.

The licence is GPL-3.0, and for firmware that distinction is more than a formality. If you derive your own board firmware from this repository and you distribute it, the GPL obligations attach to the derived work. If you only run it on your own hardware without passing it on, you are not distributing anything, so the practical pressure appears when you share a build, sell a product or hand modified sources to a customer. A commercial product built on this code therefore needs a licence decision made early, and the LICENSE file in the repository is the text that governs it.

The acknowledgements list three upstream code bases: ZinggJM/GxEPD2, waveshareteam/e-Paper and atc1441/ATC_TLSR_Paper. The project documentation does not state the licences of those three projects, and because one of them is a different vendor's firmware family, the answer is not obvious. Check each of them against GPL-3.0 yourself before shipping, and treat the combination of upstream e-paper code with GPL-3.0 as the licensing question to resolve, rather than the licence of this repository alone.

Editorial conclusion

EPD-nRF5 is worth adopting if your hardware is a common UC81xx or SSD16xx e-paper panel wired to an nRF51822, nRF51802, nRF52810 or nRF52811, and if a calendar plus a BLE image push is what the device should do. It is the wrong choice for a general purpose e-paper driver, for a panel you intend to rotate, and for a Linux workstation, because the desktop emulator target links against GDI32 and builds emulator.exe. Before you commit, read docs/develop.md for the toolchain, confirm your panel driver and pin mapping appear in docs/devices.md, and check the licences of the three upstream code bases the acknowledgements list, since GPL-3.0 applies to the firmware you derive from this repository.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. tsl0922/EPD-nRF5 on GitHub