// ADVANCED TOPICS

Gotchas

Notes for long-running apps, badge-to-badge IR exchanges, mouse overlay interfaces, orientation handling, and cleanup before exit.

Advanced IR Comms Gotchas

// ADVANCED

Advanced

Useful APIs for apps that need pointer-style input, orientation awareness, or firmware-native screen chrome.

mouse / overlay

mouse_overlay(True) enables a hardware-composited cursor. Joystick movement drives the cursor and button presses become click events.

imu / nametag

Use imu_face_down() or continuous imu_tilt_y() values to react when the badge hangs upside down.

ui / chrome

ui_header(), ui_action_bar(), and badge_ui helpers keep app screens visually consistent with firmware menus.

// IR COMMS

The MicroPython IR APIs let apps send compact NEC frames or larger multi-word payloads between badges.

start / required

Call ir_start() before sending or reading. Python gets exclusive access while IR mode is active.

frames / payload

Use ir_send(addr, cmd) for compact frames and ir_send_words(words) for multi-word payloads up to 64 32-bit words.

poll / 50 ms

Poll ir_read() or ir_read_words() within about 50 ms per frame or receiver buffers can drop data.

// GOTCHAS

Small habits that keep apps responsive, readable, and easy to exit during real badge use.

memory / 2 MB PSRAM

Avoid large temporary objects, reuse buffers, call gc.collect(), and split large source files into modules.

display / show

Drawing calls update the framebuffer. Call oled_show() before expecting pixels to appear.

leds / override

Wrap direct matrix drawing in led_override_begin() and led_override_end() so ambient firmware modes do not overwrite the frame.

input / once

button_pressed() consumes the event. Read it once per loop and store the value.

exit / safety

Holding all four face buttons for about one second force-exits a stuck app.

cleanup / exit

Before exiting, clear LEDs, stop haptics and tones, stop IR, and disable mouse overlay.