// TEMPORAL BADGE

Developer Guide

A compact local version of the Jumperless Temporal Badge MicroPython guide, organized around the sections in the upstream Developer Guide navigation.

1. What Is This Badge? 2. Getting Started with JumperIDE 3. Your First App 4. App Structure 5. MicroPython Cheat Sheet 6. Hardware Guide 7. Advanced Topics 8. Badge-to-Badge Communication 9. Tips and Gotchas Quick Reference Card

// SECTION 1

What Is This Badge?

The Temporal Badge is a wearable conference badge based on the ESP32-S3-WROOM-1 16N8 module. It runs Arduino C++ firmware with an embedded MicroPython v1.27 runtime so Python apps can control the hardware directly.

Core

Dual-core 240 MHz ESP32-S3, 16 MB flash, 8 MB PSRAM, and a 128 KB MicroPython heap.

Display Stack

128x64 monochrome SSD1306 OLED plus an 8x8 red IS31FL3731 LED matrix with PWM per pixel.

Interaction

Four face buttons, analog joystick, LIS2DH12 accelerometer, haptics, and NEC-style IR send/receive.

// SECTION 2

Getting Started with JumperIDE

Use JumperIDE to connect to the badge over WebSerial, edit files on the badge, and run scripts through the MicroPython raw REPL.

Connect

Connect to your badge with a USB-C cable. Wait a moment for the badge to activate. Open ide.jumperless.org to access the IDE. Click the Connect button. In the dialog that appears, select the USB JTAG/serial item, and click Connect.

WebSerial

Run

Press Run / Stop or F5. Print output and exceptions appear in the terminal pane.

raw REPL

Save

Save with Ctrl + S or the green Save button to write files to the badge filesystem.

filesystem

Browse

The file tree exposes /apps, /lib, and /tests.

direct edit

// SECTION 3

Your First App

Start with OLED output, an LED matrix image, and a clean exit. Add input with button_pressed() for one-shot events and button() for held controls.

import time

oled_clear()
oled_println("Hello")
oled_println("Badge")
oled_show()

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

// SECTION 4

App Structure

Put small experiments directly in /apps. For larger apps, create a folder with main.py and import sibling modules from that folder.

Single-File Apps

Great for short demos. Badge functions are auto-imported in the entry script.

Multi-File Apps

Use sys.path.insert() in main.py, then delegate to modules.

Save Data

Use regular open() and os APIs for app state and local files.

// SECTION 5

MicroPython Cheat Sheet

Supported modules include sys, os, time, random, math, cmath, struct, array, binascii, json, collections, errno, gc, io, micropython, and badge.

Use time.sleep_ms(), ticks_ms(), and ticks_diff() for timing.

Keep foreground loops cooperative. Sleep briefly so input and render work stays responsive.

There is no pip package install path. Put shared local code in /lib.

The Python heap is 128 KB. Use gc.collect() in long-running apps.

// SECTION 6

Hardware Guide

The hardware APIs are grouped by device. Most display work is buffered, so draw first and call oled_show() when the frame is ready.

OLED

oled_clear(), oled_println(), oled_set_pixel(), oled_show()

LED Matrix

led_set_pixel(), led_show_image(), led_start_animation()

Buttons

button(), button_pressed(), button_held_ms()

Joystick

joy_x() and joy_y() return 0-4095 raw ADC values.

IMU

imu_tilt_x(), imu_tilt_y(), imu_face_down(), imu_motion()

Haptics

haptic_pulse(), haptic_strength(), tone(), no_tone()

IR

ir_start(), ir_send(), ir_read(), ir_stop()

// SECTION 7

Advanced Topics

Use mouse overlay for point-and-click interfaces, IMU orientation for nametag-aware apps, and native UI chrome for firmware-matched headers, footers, and button glyphs.

Mouse Overlay

Enable cursor mode with mouse_overlay(True) and read clicks with mouse_clicked().

Flip Detection

Use imu_face_down() or tilt values to show idle, QR, or pause states.

Native UI

Use ui_header(), ui_action_bar(), or badge_ui helpers.

// SECTION 8

Badge-to-Badge Communication

IR is line-of-sight. Start IR mode first, exchange compact or multi-word frames, poll quickly, then stop and flush when done.

ir_start()
ir_flush()
ir_send(0x42, 0x01)

while not ir_available():
    time.sleep_ms(20)

addr, cmd = ir_read()
ir_stop()

// SECTION 9

Tips and Gotchas

Exit: Hold all four face buttons for about one second to force-exit.

Memory: 128 KB heap. Reuse buffers and call gc.collect().

Display: Call oled_show() after drawing.

Matrix: Use override mode before direct matrix drawing.

IR: Read within about 50 ms per frame and call ir_stop().

Input: Read button_pressed() once per loop.

// QUICK REFERENCE

Card

OLED:      oled_clear() -> oled_println() -> oled_show()
Matrix:    led_show_image(IMG_HEART), led_set_frame(rows, brightness)
Buttons:   button_pressed(BTN_CONFIRM), button(BTN_UP)
Joystick:  joy_x() and joy_y() return 0-4095
Haptics:   haptic_pulse(), tone(440, 200), no_tone()
IR:        ir_start() -> ir_send(a, c) -> ir_read() -> ir_stop()
IMU:       imu_tilt_x(), imu_motion(), imu_face_down()
Mouse:     mouse_overlay(True), mouse_clicked()
Files:     open("/apps/my_app/save.json", "w").write(data)
Exit:      exit() or hold all four face buttons