// MICROPYTHON CALLS

API Reference

Function groups and constants for the Replay 2026 Badge MicroPython API. The exhaustive reference is also available on-device as /docs/API_REFERENCE.md.

Init OLED Display Native UI Chrome Python Helpers Buttons & Joystick LED Matrix Matrix App Host IMU Haptics HTTP & Serial IR Identity Persistent KV Script Control Mouse Overlay Native Surface Constants

// INIT

Init

init() initializes the badge runtime bindings.

// DISPLAY

OLED Display

Text

oled_print(text), oled_println(text), oled_set_cursor(x, y), oled_set_text_size(size)

Refresh

oled_clear([show]), oled_show(), oled_invert(enable)

Fonts

oled_set_font(name), oled_get_fonts(), oled_get_current_font()

Pixels

oled_set_pixel(x, y, color), oled_get_pixel(x, y), oled_draw_box(x, y, w, h), oled_set_draw_color(color)

Measure

oled_text_width(text), oled_text_height()

Framebuffer

oled_get_framebuffer(), oled_set_framebuffer(data), oled_get_framebuffer_size()

// CHROME

Native UI Chrome

Layout

ui_header(title, [right]), ui_action_bar(...), ui_chrome(...)

Hints

ui_inline_hint(x, y, hint), ui_inline_hint_right(right_x, y, hint), ui_measure_hint(hint)

Grid

ui_grid_cell(col, row, label, selected, [icon]), ui_grid_footer([description])

List

ui_list_row(row, label, selected), ui_list_rows_visible()

Button hints accept labels such as A:open, B:back, X:edit, Y:menu, Confirm:select, Back:exit, Left/Right:move, and All:reset. The native renderer turns recognized button names into the badge's standard glyphs, so prefer these helpers over hand-drawn footer text.

// PYTHON HELPERS

Helper Modules

`badge_ui`

screen(), chrome(), chrome_tall(), header(), footer(), action_bar(), tall_action_bar(), hint(), hint_row(), inline_hint(), inline_hint_right(), status_box(), spinner()

`badge_app`

run_app(), with_led_override(), ButtonLatch, GCTicker, DualScreenSession, read_stick_4way(), load_score(), save_score()

`badge_kv`

from badge_kv import kv, then use kv.get(), kv.put(), kv.delete(), and kv.keys().

import badge_ui as ui
from badge import *

ui.chrome("My App", right="1/3", left_button="B", left_label="back",
          right_button="A", right_label="open")
ui.line(0, "Hello from MicroPython")
ui.inline_hint(0, 53, "Left/Right:move")
oled_show()

// INPUT

Buttons & Joystick

Buttons

button(id), button_pressed(id), button_held_ms(id)

Joystick

joy_x(), joy_y()

Constants

BTN_RIGHT, BTN_DOWN, BTN_LEFT, BTN_UP, BTN_CONFIRM, BTN_BACK

// LEDS

LED Matrix

Draw

led_brightness(value), led_clear(), led_fill([brightness]), led_set_pixel(x, y, brightness), led_get_pixel(x, y)

Images

led_show_image(name), led_set_frame(rows, [brightness])

Animation

led_start_animation(name, [interval_ms]), led_stop_animation()

Override

led_override_begin(), led_override_end()

// BACKGROUND MATRIX

Matrix App Host

matrix_app_start(callback, [interval_ms], [brightness]), matrix_app_set_speed(interval_ms), matrix_app_set_brightness(brightness), matrix_app_stop(), matrix_app_active(), and matrix_app_info().

// MOTION

IMU

imu_ready(), imu_tilt_x(), imu_tilt_y(), imu_accel_z(), imu_face_down(), and imu_motion().

// FEEDBACK

Haptics

haptic_pulse([strength], [duration_ms], [freq_hz]), haptic_strength([value]), haptic_off(), tone(freq_hz, [duration_ms], [duty]), no_tone(), and tone_playing().

// COMMS

IR Send/Receive

Mode

ir_start(), ir_stop(), ir_flush()

Simple Frames

ir_send(addr, cmd), ir_available(), ir_read()

Word Frames

ir_send_words(words), ir_read_words(), 1-64 words

Consumer NEC

ir_set_mode("nec"), ir_nec_send(addr, cmd, [repeats]), ir_nec_read()

Raw Symbols

ir_set_mode("raw"), ir_raw_capture(), ir_raw_send(buf, [carrier_hz]), ir_activity()

Power

ir_tx_power([percent])

// NETWORK

HTTP & Serial

HTTP

http_get(url) returns a response body string. http_post(url, body) posts a string body and returns the response body. Responses are capped at 8192 bytes.

Serial

serial_available() returns True when at least one USB serial byte is queued. serial_read() reads one byte or returns None.

// IDENTITY

Badge Identity

contact() returns editable contact fields: name, title, company, email, and website. set_contact(dict) updates any of those fields in persistent memory. set_time(epoch) sets the badge wall clock from a Unix epoch timestamp.

// PERSISTENCE

Persistent KV

kv_put(key, value), kv_get(key, [default]), kv_delete(key), and kv_keys() store small app settings in NVS so they survive firmware updates and filesystem reflashes. Use badge_kv.kv for a friendlier wrapper.

// CONTROL

Script Control & Files

Use exit() to return to firmware. Dev builds also expose dev(*args). rescan_apps() asks the native app registry to rescan installed MicroPython apps after files change. set_repl_trace(enable) is a developer diagnostic toggle for serial REPL tracing. Filesystem access uses standard open() and os APIs.

// POINTER

Mouse Overlay

Enable

mouse_overlay(enable), mouse_set_bitmap(data, w, h)

Position

mouse_x(), mouse_y(), mouse_set_pos(x, y)

Input

mouse_clicked(), mouse_set_speed(speed), mouse_set_mode(mode)

// C / C++ SURFACE

Native Surface

App authors should treat the Python badge, badge_ui, badge_app, and badge_kv modules as the public API. The C/C++ bridge in firmware/micropython/usermods/temporalbadge/ and firmware/src/micropython/badge_mp_api/ is for firmware contributors adding new bindings. Native UI consistency lives in OLEDLayout and ButtonGlyphs; expose shared behavior through the MicroPython bindings rather than duplicating C++ internals in app code.

// CONSTANTS

Constants Reference

Group	Constants
Buttons	`BTN_RIGHT`, `BTN_DOWN`, `BTN_LEFT`, `BTN_UP`, `BTN_CIRCLE`, `BTN_CROSS`, `BTN_SQUARE`, `BTN_TRIANGLE`, `BTN_CONFIRM`, `BTN_SAVE`, `BTN_BACK`, `BTN_PRESETS`
LED Images	`IMG_SMILEY`, `IMG_HEART`, `IMG_ARROW_UP`, `IMG_ARROW_DOWN`, `IMG_X_MARK`, `IMG_DOT`
LED Animations	`ANIM_SPINNER`, `ANIM_BLINK_SMILEY`, `ANIM_PULSE_HEART`
Mouse Modes	`MOUSE_ABSOLUTE`, `MOUSE_RELATIVE`