Parts list

What you need.

The list is short on purpose. Two boards are supported — the E290 is recommended because the larger display reads better from across a desk. The E213 is a valid alternative if you want something smaller.

Part	Notes	Cost
Heltec Vision Master E290 (recommended)	2.90″ e-ink, 296×128 px. ESP32-S3, Wi-Fi, USB-C, Li-Po charge circuit built in. Search "Heltec Vision Master E290" on Heltec's site or AliExpress.	~$22
Heltec Vision Master E213 (alternative)	2.13″ e-ink, 250×122 px. Same firmware, smaller display. Both boards are hardware-tested.	~$18
3.7 V Li-Po battery	803040 size, PH 1.25 connector (the standard Heltec battery connector). ~800–1000 mAh is enough for weeks between charges at a 1-day refresh interval.	~$5
USB-C cable	For uploading firmware and charging the battery. Any standard USB-C data cable works.	~$3
Desk stand or case	A flat stone, a wood block, a 3D-printed case, or a small metal stand. The board is light and stands at whatever angle you like. STL files are in the repo.	$0+

Arduino libraries

Five installs in the Library Manager.

Open Arduino IDE, go to Tools > Manage Libraries, and search for each by name. Install the version shown in the Library Manager — the firmware is tested against current stable releases of each.

heltec-eink-modules

By Todd Herbert. Drives the e-ink display on both Heltec board variants. This is the core display library — the firmware will not compile without it.

Heltec ESP32 Dev-Boards

Board support package for the Heltec ESP32 family. Also installs the Heltec board definitions in Tools > Board so you can select E213 or E290.

ArduinoJson

By Benoit Blanchon. Used for parsing BTC price responses from CoinGecko and mempool.space, and for reading saved settings off flash storage.

PubSubClient

By Nick O'Leary. MQTT client used in MQTT portfolio mode. Required even if you do not plan to use MQTT — the firmware includes it.

Adafruit GFX Library

By Adafruit. Graphics primitives used by the display layer. Install this before the heltec-eink-modules library or the dependency check will flag it.

Upload steps

Eight steps, one upload.

The hard parts — display driver, Wi-Fi setup portal, BTC price fetching, OTA updates — are already done. You are running existing code, not writing new code.

Download and install the Arduino IDE from arduino.cc/en/software. Free, available for Mac, Windows, and Linux.
Install the five libraries listed above via Tools > Manage Libraries.
Download the firmware from GitHub. Use the green "Code > Download ZIP" button if you are not using git. Unzip the folder.
Open Freedom_Clock_HeltecVME.ino in the Arduino IDE. It is in the root of the downloaded folder.
Connect the board via USB-C. Go to Tools > Port and select the board port — usually /dev/cu.usbmodem1101 on Mac or COM3 on Windows.
Select the correct board profile. Go to Tools > Board and select Heltec Vision Master E290 (or E213 if that is your board). Do not flash the wrong profile — an E213 binary will not run on an E290.
Click Upload. Watch for the progress bar. When it appears, press the RST button on the board once. The upload takes about a minute.
Join the setup Wi-Fi. After upload, the e-ink display shows a Wi-Fi network name and password. Join from your phone or laptop, open a browser, and follow the setup page to enter your home Wi-Fi, financial settings, and display preferences. Save. The device connects and shows your freedom time on its first refresh.

First setup

What the setup page asks for.

On first boot — or after a factory reset — the device creates its own local Wi-Fi network. The name is stable and unique per board, based on a short ID derived from the hardware MAC. Join it from any browser and configure:

Identity and life model

Owner name (shown on the settings screen), birth year, and life expectancy. These feed the lifetime-left calculation. They stay on the device and are never sent anywhere.

Portfolio model

Choose between three modes: Static net worth (enter total wealth in your currency), Static BTC + price online (enter a BTC amount; device fetches live price from CoinGecko), or Automatic BTC via MQTT (price and balance come from your local MQTT broker).

Spend model

Monthly selling or yearly borrowing (borrow against BTC). Set monthly expenses, optional monthly income, spend growth (inflation), and optional borrow fee. These are the same inputs as the browser calculator.

Display and refresh

Light or dark theme. Refresh interval — 1 day is the default and the most battery-friendly. Daily refresh time and timezone. Privacy toggles to hide the wealth change and settings screens from button navigation.

Wi-Fi and MQTT

Home Wi-Fi credentials. Optional MQTT broker address, port, and topics for automatic BTC mode. Saved to encrypted flash storage on the device.

Setup PIN (optional)

A numeric PIN that locks the setup page. Useful if the device is in a shared space. Stored as a hash — the PIN itself is never saved in plaintext.

What it shows

The screens.

The FUNCTION button (GPIO21, marked "x" on the case) wakes the display and cycles through the enabled screens. The HOME button (RST, marked "o") restarts and returns to the main screen.

Main screen

Expected freedom time, expected lifetime left, and freedom coverage — the three quiet signals. A small warning icon appears if the displayed data is stale.

Quote screen

A short motivational line from the built-in library, with compact freedom time, coverage, and lifetime stats along the bottom edge. Rotates between quotes on each refresh. You can edit or replace the library.

Freedom change screen

Shows how freedom time has moved since the last reading — the trend over time, not just the current number. Opened with the FUNCTION button.

Wealth change screen

Current portfolio value and recent change in selected currency. Can be hidden from the setup page for privacy.

Settings screen

Saved parameters and firmware version. Useful for confirming what the device is calculating with. Can be hidden from the setup page.

Unavailable data

If BTC price or balance cannot be fetched, the device shows N/A instead of a misleading number. It can reuse the last-good cached price and balance, with a timestamp shown so you know how stale it is.

Portfolio modes

Three ways to feed it numbers.

The device is not opinionated about where your numbers come from. Pick the mode that fits your setup.

Static net worth

Enter total wealth directly in USD, EUR, or CHF on the setup page. The device uses this fixed number with your growth and inflation assumptions. Best for people who do not hold Bitcoin or who want a simple, stable starting point.

Static BTC + price online

Enter a BTC amount on the setup page. The device fetches the live BTC price from CoinGecko on each refresh, with mempool.space as a fallback. The price provider can see your network IP — noted for privacy-minded builders.

Automatic BTC via MQTT

BTC amount and price come from local MQTT topics published by your own infrastructure — a home server, Bitcoin node, or self-hosted dashboard. No external price fetch. Best for people who already run local node infrastructure and want full data sovereignty.

3D-printable case

A case for the E290.

The repository includes a printable case for the E290 in hardware/case/. Two parts: body and cover. The source model is in OpenSCAD so you can adapt it.

body.stl

The main shell. Holds the board and battery. Print in PLA or PETG. No supports needed on most printers.

cover.stl

Snaps over the back. Keeps the battery contained. Print in the same material as the body.

freedom_clock_e290_case.scad

The OpenSCAD source. Change wall thickness, add ventilation, adapt the stand angle, or remix entirely. OpenSCAD is free and available at openscad.org.

No printer? A flat stone or a short piece of wood works fine. The board is light enough that a small easel-style stand holds it at a readable angle.

Staying current

Firmware updates.

Once the device is running, you do not need the Arduino IDE again to update it. Two paths from the setup page:

Online check from GitHub

The setup page can check for the latest GitHub Release and install it over Wi-Fi. HTTPS certificate validation is required — if the device cannot sync time via NTP, online updates fail closed. Automatic updates can also be enabled.

Manual .bin upload

Download the correct release asset from GitHub Releases (FreedomClock-<version>-E290-manual-update-open.bin for the E290) and upload it from the setup page. Works from a phone or laptop. Use the E290 binary for E290 boards — the assets are board-specific.

Build questions

Things builders ask first.

Do I need to solder?

No. The Heltec boards have the display, Wi-Fi, USB-C port, and battery charge circuit built in. The battery clips onto a standard connector. The only tools you need are a computer and a USB-C cable.

Which board should I buy — E290 or E213?

The E290 (2.90″) is recommended. The larger display is easier to read from across a desk, which is the whole point of the object. The E213 (2.13″) works with the same firmware and is a valid choice if you want something smaller or if the E290 is out of stock.

What battery fits?

An 803040 Li-Po with a PH 1.25 connector. This is the standard Heltec battery connector — search for "803040 PH1.25" or "3.7V 1000mAh PH1.25" on AliExpress or your preferred electronics supplier. An 800–1000 mAh cell is enough for weeks between charges at a one-day refresh interval.

Does it need to be connected to the internet?

It needs your home Wi-Fi for initial setup and for fetching live BTC price if you use Static BTC + price online mode. In Static net worth mode, it only needs Wi-Fi for the setup page and OTA updates — it does not make external calls during normal operation. MQTT mode keeps everything on your local network.

Can I use it without any Bitcoin?

Yes. Static net worth mode takes a total portfolio value in USD, EUR, or CHF. Enter your savings, set your spend and growth rates, and the device calculates freedom time from those numbers alone.

Is there a 3D-printable case?

Yes. The repository includes body.stl, cover.stl, and an OpenSCAD source file in hardware/case/. The STL files are ready to slice. If you do not have a printer, a flat stone or small wood block works just as well.

How do I reset the device to factory settings?

Hold the SETUP button (marked with a square on the case back, physical BOOT/GPIO0) for approximately 10 seconds. This clears saved Wi-Fi, MQTT, and settings and returns the device to the first-boot setup mode. Avoid pressing SETUP and HOME simultaneously — that combination can enter the ESP32 bootloader.

Can I contribute to the project?

Yes. The firmware is MIT-licensed and the repository is open. Practical fixes, better build notes, and improvements that keep the object useful without making it noisier are welcome. Open an issue or pull request on GitHub.