OpenEPaperLink: ESP32 Access Points and Custom E-Paper Tag Firmware

OpenEPaperLink's Hardware and Content-Delivery Role

OpenEPaperLink targets electronic shelf labels containing an 802.15.4 radio. It replaces the normal firmware and protocol so that an ESP32 access point can supply display content. This makes the project relevant to people building a private electronic shelf-label system, working with compatible labels, or developing custom tag and access-point hardware. It is not a general-purpose display controller for arbitrary e-paper screens.

The repository separates the software into access-point firmware and tag firmware. Its top-level layout reinforces that division through directories such as `ESP32_AP-Flasher`, `ARM_Tag_FW`, and `Tag_Flasher`. The README also points to designs for a Mini AP and a combined access point and flasher. Those links matter because the software is tied to physical radio boards, programming contacts, label variants, and an ESP32. Its usefulness depends on whether a particular label has compatible electronics and a known flashing procedure.

The stated design goals include low power, low latency, and reduced RF traffic. The README gives a current power figure of around 9 microamps, with a minimum latency of 40 seconds. It also states an approximate rate of about 5 kbyte/s under favorable RF conditions. Those are design claims, not guaranteed outcomes for every tag, board, antenna arrangement, or installation. The known-issues section warns that range varies because the boards are small and fragile, and even a small amount of hot glue can warp a board and damage soldered components.

The ESP32 Access Point and Tag-Flashing Path

The README describes a setup involving a few compatible tags, an ESP32, and a ZBS_Flasher. One tag supplies the 802.15.4 radio connection for the ESP32, while the ZBS_Flasher is used to program tags with the custom firmware. The tag can be connected to the ESP32 using modified wires or a flexible PCB. After programming, the ESP32 flashes AP firmware to the tag automatically, although some configurations require the hardware to be powered off and on again. The README directs users to inspect the serial console for status information.

The `mac` option in ZBS_Flasher has a practical purpose during this process. According to the README, it gives a tag running custom firmware a valid MAC address by using the stock address assigned to a tag that has not previously been flashed. The README also says that a user can set the address through the infopage, although it does not provide the detailed interface steps for doing so.

A separate filesystem operation is required after programming the ESP32. The README says this uploads the repository's `data` folder to the ESP32 and includes the web interface. This means a successful tag or access-point flash is not by itself the complete setup. The filesystem image must also be present.

The current README is explicitly marked as partly obsolete and points readers to the OpenEPaperLink Wiki for current information. Exact tag compatibility, board wiring, flashing controls, and the infopage procedure are therefore not fully documented in the repository's README. This documentation gap is a real adoption constraint, not a minor presentation issue.

OpenEPaperLink's 4 KB Check-In and Transfer Protocol

The protocol is built around periodic tag check-ins rather than a continuously connected session. A tag normally checks with the access point every 40 seconds or more. The exact interval depends on RF conditions and can be extended when the access point asks the tag to delay its next check-in. This reduces idle radio activity and supports the project's low-power objective.

The access point keeps a list of tag MAC addresses with pending transfers. When a tag checks in, it receives either no-data information or notice that a transfer is pending. Before requesting content, the tag compares the transfer information with data already in EEPROM or content already displayed. If it recognizes the transfer, it sends a `transfer complete` packet so that obsolete work can be cancelled.

For pending content, the tag requests 4096-byte blocks. The access point acknowledges the request and tells the tag how long it needs to gather the data. The tag sleeps during that interval. The access point then asks the ESP32 to fill its block buffer, providing an MD5 value and `blockID`. A complete data block takes about 42 packets according to the README.

Missing data is handled through a bitmask identifying missing parts. When a received block is incomplete, the tag requests that block again. If relatively few parts are missing, the access point can include duplicate parts to improve the chance that the retransmission succeeds. Once the tag has a full block, it computes a simple checksum. A matching checksum causes the 4 KB to be stored in EEPROM; a failed checksum causes a full block request. After all blocks arrive, the tag sends `transfer complete`, and the access point reports completion to the ESP32 before removing the transfer from its queue.

Linux Firmware Builds with SDCC 4.2.0

The core project is primarily written in C, and the README gives a specific compiler baseline: SDCC 4.2.0 on Linux. It warns that different SDCC versions can behave very differently. It also provides a setup script for obtaining and building a local copy. The first documented build-hygiene step is a clean between builds for different boards because the README says it helps with that transition.

A board build therefore has two separate toolchain concerns. First, SDCC must match the version expected by the project. Second, builds for different target boards should begin from a clean state. The repository's top-level contents, including `oepl-definitions.h`, `oepl-proto.h`, `oepl-esp-ap-proto.h`, and `tag_types.h`, indicate that the code is organized around protocol definitions and target-specific firmware. The README does not provide a complete list of supported build targets or their corresponding commands, so a new user should not guess a board name.

The documented commands are limited to these two operations. A clean should be performed between builds for different boards. The setup script can be sourced before compiling to establish a local SDCC build.

make clean

The README gives no further output that a reader should expect from this command. It presents the clean step as preparation for building another board.

The second command sources the repository's SDCC setup script so the local compiler can be used for compilation.

source sdcc/setup.sh

No specific subsequent build command is included in the README, and the Wiki is identified as the place for current build and hardware information. That omission limits this article to a setup tutorial rather than inventing a release or deployment command.

Label Variability, RF Range, and Physical Handling

The clearest limitation is that compatibility is hardware-specific. The README requires a tag with an 802.15.4 radio and describes several hardware designs, but it does not claim that every electronic shelf label is supported. It also warns that some tags perform better as access points than others. This means the ESP32-side software does not eliminate the need to identify and evaluate the exact tag electronics.

RF range is another boundary. The stated check-in interval and transfer speed depend on RF conditions. The project deliberately reduces packet acknowledgements and avoids retransmitting data already present on the tag, which supports efficiency but also means actual delivery timing depends on successful communication between the two devices. A slow or unreliable link can increase retries and extend the transfer.

Physical handling matters as well. The boards are described as tiny and fragile, and applying hot glue can cause enough heat to warp a board and damage components. Using a programming jig is recommended in the README's discussion of hardware designs and programming interfaces. Builders should also allow for the documented power-cycle step because automatic AP flashing does not complete on every configuration.

OpenEPaperLink is consequently the wrong tool when hardware identification, soldering, flashing, or serial-console diagnosis is outside the available skill set. It is also unsuitable when a buyer needs a confirmed, universal model list from the README. The Wiki's tag specifications and troubleshooting material must be checked for the exact label before procurement.

OpenEPaperLink Versus a Generic E-Paper Display Controller

The practical alternative is a generic e-paper display controller that accepts a display directly and does not replace shelf-label firmware or use the label's 802.15.4 radio as part of a content network. Such a controller focuses on driving compatible screen hardware. OpenEPaperLink instead integrates the display label into a radio network, stores transferred blocks in EEPROM, and coordinates periodic access-point check-ins.

This difference affects integration. A generic display controller may suit a prototype with one known panel and a wired serial interface. OpenEPaperLink suits an array of remote shelf labels because the access point tracks each tag's MAC address, pending content, missing blocks, and transfer completion. Its block protocol also avoids requesting the same data when the tag already has it, while sleeping while the access point prepares a requested block.

The trade-off is hardware dependence. OpenEPaperLink requires compatible tags, a ZBS_Flasher, an ESP32-based access point, and firmware build work. It is less suitable when a generic screen driver would meet the requirement. It is more relevant when the defining requirement is updating existing 802.15.4 shelf labels through custom low-power firmware.

The repository also documents automated compilation after pull requests and release files for OTA, but it does not describe OTA configuration or update procedures in the README. The project therefore offers evidence of build and release automation without enough documentation here to prescribe an upgrade workflow.

OpenEPaperLink Licensing, Releases, and Upgrade Work

The repository metadata categorizes its license as Other because GitHub cannot classify it, and directs readers to the `LICENSE` file. The README links to Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, abbreviated CC BY-NC-SA 4.0. This carries an apparent noncommercial restriction, but this review does not give legal advice or interpret how the custom LICENSE file applies to a particular deployment or product.

Commercial adoption should not be decided from the README's license link alone. The repository-level license classification and the explicit instruction to see `LICENSE` are concrete reasons to read the actual file before modifying, distributing, or selling hardware or firmware based on the project.

The repository is not archived. Its last push was on 2026-10-14, followed by release 2.95 on 2026-10-14. Earlier listed releases include 2.92 on 2026-09-10 and 2.91 on 2026-07-07. These dates show recent project changes, but upgrade cost cannot be quantified from release names alone. The README does not provide a migration guide, compatibility matrix for earlier tag firmware, or rollback procedure.

For firmware upgrades, the documented source-tree cost starts with clean builds and the SDCC 4.2.0 toolchain requirement. Hardware owners must also determine whether a new release affects their tag model, access-point design, filesystem upload, or infopage configuration. Release 2.95 includes the statement that release files are added to enable OTA, but the README does not explain how a device-side OTA update is initiated or recovered.

Editorial conclusion

OpenEPaperLink is appropriate for builders with compatible ESP32 hardware, a ZBS_Flasher, and at least one programmable 802.15.4 tag. It is a poor fit for users who need a generic label platform, turnkey setup, or commercial redistribution rights. Before adoption, verify the current Wiki instructions for the exact tag and access-point design, confirm that SDCC 4.2.0 is available on Linux, and read the repository's LICENSE file rather than relying only on the README's CC BY-NC-SA 4.0 link.

Frequently asked questions

Official sources

1. Issues
2. OpenEPaperLink/OpenEPaperLink on GitHub
3. Project website
4. README
5. Releases