trmnlframe

A TRMNL client for the Pimoroni Inky Frame 7.3" color e-ink display.

Runs the full TRMNL wake-fetch-display-sleep cycle on a Raspberry Pi Pico W, pulling dashboard content from the TRMNL cloud or a self-hosted BYOS server and rendering it on the 7-color ACeP e-ink panel.

Hardware

• Display: 800x480, 7-color ACeP (black, white, red, green, blue, yellow, orange), 5:3 aspect ratio
• MCU: Raspberry Pi Pico W (RP2040, 264KB SRAM, 2MB flash, WiFi)
• Features: 5 buttons with LEDs, microSD slot, JST battery connector, 8MB PSRAM
• Power: ~20uA deep sleep, battery operation via 3xAA or LiPo

Setup

1. Flash firmware

Download the latest Pimoroni MicroPython firmware from pimoroni/inky-frame releases. Use the pico_w_inky-*-with-filesystem.uf2 build (or pico2_w_inky-* for Pico 2 W).

Hold BOOT, tap RESET, copy the .uf2 to the RPI-RP2 drive.

2. Configure WiFi

Edit secrets.py with your credentials:

WIFI_SSID = "your_network"
WIFI_PASSWORD = "your_password"
WIFI_COUNTRY = "CA"  # your 2-letter country code (required for Pico W)

3. Configure TRMNL

Add your TRMNL API key to secrets.py:

TRMNL_BASE_URL = "https://trmnl.com"
TRMNL_API_KEY = "your_api_key"

# Optional: send a different MAC address to TRMNL (e.g. to reuse a
# device already registered on trmnl.com). Leave empty to use the
# Pico W's real MAC.
TRMNL_MAC_OVERRIDE = ""

Get your API key from your TRMNL device settings.

4. Copy files to Pico

Install mpremote and copy the project:

pipx install mpremote
mpremote cp secrets.py :secrets.py
mpremote cp main.py :main.py
mpremote mkdir lib
mpremote cp lib/trmnl_api.py :lib/trmnl_api.py
mpremote cp lib/trmnl_display.py :lib/trmnl_display.py
mpremote cp lib/trmnl_network.py :lib/trmnl_network.py
mpremote cp lib/trmnl_power.py :lib/trmnl_power.py
mpremote cp lib/trmnl_storage.py :lib/trmnl_storage.py

5. Insert SD card

A FAT-formatted microSD card is required for image caching and state persistence.

6. Reset

Press the reset button. The device will connect to WiFi, fetch content from TRMNL, render it on the display, and enter deep sleep until the next refresh cycle (~15 minutes by default).

Buttons

Button	Function
A	Force refresh
B	Show device info (MAC, battery, refresh rate)
E	Reset credentials and re-register

Project structure

main.py              Entry point: wake -> fetch -> display -> sleep
secrets.py           WiFi and TRMNL configuration
lib/
  trmnl_api.py       TRMNL API client (setup, display, download, log)
  trmnl_display.py   Image rendering (PNG/JPEG/BMP) and status screens
  trmnl_network.py   WiFi management and MAC address
  trmnl_power.py     Battery voltage reading and deep sleep
  trmnl_storage.py   SD card and state persistence
tools/
  mock_server.py     Local test server for development

Development

Run the mock server on your laptop for testing without the TRMNL cloud:

python3 tools/mock_server.py --port 8080

Then set TRMNL_BASE_URL = "http://<laptop-ip>:8080" in secrets.py.

Notes

• WiFi country code (WIFI_COUNTRY) is required on the Pico W or connections will fail
• Battery voltage must be read before WiFi is activated (GPIO29 shares SPI with the wireless chip)
• On USB power with no battery, voltage reports as 5.0V to avoid triggering low-battery screens
• The display supports 7 colors; TRMNL's monochrome images render as black on white, while BYOS servers can serve full-color images that get auto-dithered

License

MIT