// FLASH AND HACK

Get Started

Flash the public firmware with Ignition, the Temporal-powered system we built for bulk badge flashing, then connect with JumperIDE to inspect files, use the REPL, and write MicroPython. Firmware updates come from Ignition, the badge FW UPDATE tile, or JumperIDE when it offers a compatible device update action. The source lives in the public GitHub repo.

Flash With Ignition

Use Ignition as the default path for one badge or many badges. It runs local Temporal workflows to build, flash, retry, and verify a whole connected batch. Start by cloning or forking the GitHub repo.

Install the repo dependencies from ignition/ with ./setup.sh.
Run ./doctor.sh to check Python, certificates, PlatformIO, Temporal, and USB.
Connect the badge over USB-C.
Run ./start.sh --latest-release.
Ignition downloads replay2026-factory-16MB.bin from the latest GitHub Release, caches it locally, flashes the badge, and verifies the result.
To build from source and preload WiFi, add --wifi-ssid "YourNetwork" --wifi-pass "YourPassword" to a source build command, or create firmware/wifi.local.env from the example.
Source builds use ./start.sh -e replay2026 --firmware-dir ../firmware. Direct download flashes use ./start.sh --release-tag v1.0.0 for a specific release.

Connect JumperIDE

Open JumperIDE and select the badge serial device to edit files, use the REPL, and sync filesystem files.

Use a browser that supports WebSerial.
Press Connect and choose the ESP32-S3 USB/JTAG serial port.
Use the file browser and REPL for MicroPython development. For firmware updates, use the badge FW UPDATE tile or Ignition.
Browse /apps, /lib, /docs, and /micropython_tests on the badge filesystem.

PlatformIO Option

Use direct PlatformIO commands from the GitHub source tree when you want the lower-level path.

From firmware/, run pio run -e replay2026.
Flash firmware with pio run -e replay2026 -t upload.
Flash the filesystem with pio run -e replay2026 -t uploadfs.

Factory Image

Use the GitHub release image when you do not want to build locally.

Run ./start.sh --latest-release from ignition/ to download, cache, and flash the latest release image.
To recover from a manually downloaded image, download replay2026-factory-16MB.bin from GitHub Releases.
The badge OTA updater uses the release asset named firmware.bin.
Use Ignition to flash a manual release image with ./start.sh --no-build --factory-image ~/Downloads/replay2026-factory-16MB.bin. Use ./start.sh --release-tag v1.0.0 when you want Ignition to fetch a specific release for you.
Factory flashing restores firmware and filesystem contents and wipes existing on-badge data.

// HELLO BADGE

Starter Script

In a single-file app, the badge hardware calls are already injected into the global scope. Imported modules should use from badge import *.

import time

oled_clear()
oled_println("Hello")
oled_println("Temporal")
oled_show()

led_override_begin()
led_show_image(IMG_HEART)
time.sleep(3)

led_clear()
led_override_end()
exit()

// INPUT LOOP

Read Buttons Once

Use edge-triggered input for menu navigation and level-triggered input for continuous movement.

`button_pressed(id)`

Returns true once per press, then stays false until release and a new press. Store the result if more than one branch needs it.

`button(id)`

Returns true while the button is held. Use it for movement, repeated actions, or joystick-style controls.