// BADGE SPEC

Hardware

The badge is an ESP32-S3 wearable with OLED, LED matrix, face buttons, analog joystick, IMU, haptics, IR, FatFS storage, and an embedded MicroPython runtime. Public KiCad source, fabrication outputs, mechanical references, and artwork are included in the repository hardware package.

// HARDWARE FILES

Source Package

The public hardware package lives under hardware/. Use hardware/pcb/PCB-A/ for the main badge KiCad project, hardware/pcb/PCB-B/ for the backplate, and hardware/fab/ for released Gerber, BOM, and placement outputs.

MCU

ESP32-S3-WROOM-1 16N8

Dual-core 240 MHz module with 16 MB flash and 8 MB PSRAM.

Runtime

MicroPython v1.27

Arduino C++ firmware hosts a 2 MB Python heap from PSRAM.

Storage

FatFS App Storage

App files live on the FFat partition. Factory images restore the bundled filesystem and wipe existing on-badge data.

Orientation

Auto Nametag Mode

The IMU can detect when the badge hangs upside down, then flip display, matrix, and input orientation.

// HARDWARE AT A GLANCE

Board Features

Component	Spec	Primary Calls
Display	128x64 SSD1309-compatible monochrome OLED	`oled_println()`, `oled_show()`
LED Matrix	8x8 red LED matrix, IS31FL3731, per-pixel PWM	`led_set_pixel()`, `led_show_image()`
Input	4 d-pad buttons and analog joystick	`button_pressed()`, `joy_x()`
Motion	LIS2DH12 3-axis accelerometer	`imu_tilt_y()`, `imu_face_down()`
IR	NEC-protocol TX LED and TSOP receiver	`ir_start()`, `ir_send_words()`
Haptics	Vibration motor with coil-tone support	`haptic_pulse()`, `tone()`

// CONTROLS

Input Map

Use semantic constants for menu behavior and physical constants for game controls.

Physical Buttons

Use direction constants for navigation and semantic constants for actions that may follow user preferences.

0-3

Aliases

PlayStation-style aliases are available: BTN_TRIANGLE, BTN_CROSS, BTN_SQUARE, and BTN_CIRCLE.

mapped

Confirm / Back

BTN_CONFIRM and BTN_BACK follow the user confirm/back swap setting.

semantic

Joystick

joy_x() and joy_y() return raw values from 0 to 4095. Center is usually near 2048.

ADC