BP26 · Hardware walkthrough

An ESP32-C5 badge running Solana OS.

A conference badge that is really a dev board: a 320×240 color screen, a D-pad, eight RGB LEDs, a microSD slot, a 1000 mAh LiPo and three radios on one RISC-V chip. Flash it over USB-C, open it up, write apps for it.

RISC-V · 240 MHz Wi-Fi 6 · 2.4 + 5 GHz ESP-NOW 802.15.4 68.6 × 105 mm Board by Skyrizz

Specifications

01MCU
ESP32-C5 · RISC-V · 240 MHz
02Board
68.58 × 104.97 × 1.6 mm
03Flash
16 MB
04Display
320×240 ILI9341 TFT
05Wi-Fi
Wi-Fi 6 · 2.4 + 5 GHz
06Bluetooth
BLE 5
07Low-power radio
IEEE 802.15.4
08Input
D-pad · SELECT · CANCEL · BOOT
09Light
8× WS2812B RGB
10Storage
microSD
11Battery
3.7 V 1000 mAh LiPo · ADC gauge
12USB
USB-C · CH340C serial

Fig. 01 · Board view

Explore the hardware

Hover or focus a component to highlight it, click to jump to its module. Flip the board to see the module, battery and connectors on the back.

020403
0106050703
Illustration of the final black PCB, drawn from prototype photos. Exact dimensions: Case design below.

01 Module

Compute

A single RISC-V core with two radios bolted on.

The brain is an Espressif ESP32-C5-WROOM module, the shielded can on the back of the board. Inside is an ESP32-C5 (silicon rev 1.0; the prototypes had rev 1.2): a single-core 32-bit RISC-V CPU at 240 MHz, a 48 MHz crystal and 16 MB of flash.

The chip package also holds 8 MB of PSRAM, which Solana OS uses from 2.0.0: an app gets up to 6 MB of it for its Lua heap, and Wi-Fi buffers and secure connections live there too, which leaves the internal SRAM to the graphics stack, Bluetooth and the system. One app runs at a time, and every app frees its memory when you leave it.

Module
ESP32-C5-WROOM
SoC
ESP32-C5 rev 1.0
CPU
RISC-V, single core, 240 MHz
Crystal
48 MHz
Flash
16 MB
PSRAM
8 MB, in the package (Solana OS 2.0.0+)
SDK
ESP-IDF master (v6.3-dev) · FreeRTOS (unicore)
Pin map · Compute
SignalPinNote
Flash (reserved)16–2215 is PSRAM CS1
USB (reserved)13 / 14—
Unused, floating2 / 5 / 26free for hacks

02 Module

Display

320×240 pixels of color TFT over SPI.

An ILI9341 TFT sits in a bracket on the front, driven in landscape at 320×240 over the SPI2 bus. Its flex cable passes through a slot to an FPC connector on the back. The panel is BGR and needs color inversion (the prototypes’ panels didn’t), and the driver rotates it into place.

The UI is rendered with LVGL 9 through esp_lvgl_port. The backlight has its own GPIO, active high, with an external pull-down so it stays dark until firmware turns it on.

Boot splash · color check

Red, green, blue from left to right means the BGR order, inversion and rotation are all right.

Controller
ILI9341
Resolution
320×240, landscape
Bus
SPI2 (shared with microSD)
Color
BGR, inverted
Connector
FPC, on the back
Graphics
LVGL 9
Pin map · Display
SignalPinNote
SPI2 SCKGPIO 9shared with SD
SPI2 MOSIGPIO 10shared with SD
SPI2 MISOGPIO 8shared with SD
LCD CSGPIO 6—
LCD DCGPIO 7—
LCD RSTGPIO 0not independently verified
BacklightGPIO 3active high, ext. pull-down

03 Module

Input

A D-pad, SELECT and CANCEL on the front, BOOT and RST on the back.

The front has a four-way D-pad (UP, DOWN, LEFT, RIGHT) and two action buttons, SELECT and CANCEL. All six sit on a TCA9534 I2C GPIO expander at address 0x20, which pulls an interrupt line low when any of them changes, so the firmware does not have to poll the bus.

On the back, BOOT is wired straight to GPIO 28 with an external pull-up and works as Home in Solana OS. RST resets the chip. All buttons are active low, and Solana OS maps them to logical keys in one place, so apps never read raw button bits.

Signal path

  • 6 front buttons P0–P5 TCA9534
  • TCA9534 I2C 0x20 · SCL 23 / SDA 24 ESP32-C5
  • INT active low GPIO 25
  • BOOT ext. pull-up GPIO 28
Front
UP · DOWN · LEFT · RIGHT · SELECT · CANCEL
Back
BOOT (Home) · RST
Expander
TCA9534 @ I2C 0x20
Logic
Active low
Expander P6/P7
Not connected
Pin map · Input
SignalPinNote
I2C SCLGPIO 23—
I2C SDAGPIO 24—
TCA9534 INTGPIO 25active low
UP · LEFT · RIGHT · DOWNTCA9534 P0–P3active low
SELECT · CANCELTCA9534 P4–P5active low
BOOTGPIO 28ext. pull-up

04 Module

Light

Eight addressable RGB LEDs on a single data pin.

Eight WS2812B addressable LEDs are chained on one GPIO: six across the top edge (silkscreen D3–D8) and two beside the screen on the right edge (D9, D10). They are driven with Espressif's led_strip component.

Full power is blinding and pulls too much current, so the firmware caps brightness at about 24/255. In the reference firmware each held button lights its own LED.

Data chain · GPIO 27

LEDs
8× WS2812B
Layout
6 top (D3–D8) · 2 right (D9, D10)
Data
Single wire, chained
Brightness cap
≈ 24 / 255
Pin map · Light
SignalPinNote
WS2812B DINGPIO 27—

05 Module

Storage

A microSD slot that shares a bus with the screen.

The microSD slot is on the back, on the same SPI2 bus as the display, with its own chip-select on GPIO 4. There is no card-detect pin.

Sharing a bus with a display is harder than it sounds. A freshly powered card starts in SD-native mode and reads MOSI as its command line, whatever the chip-select level. The stock firmware ran about 4 s of LCD tests first, so pixel data reached the card as SD commands. The fix: mount the card before the display starts.

Slot
microSD, SPI mode
Bus
SPI2 (shared with LCD)
Card detect
None
Filesystem
FAT via FatFs
Pin map · Storage
SignalPinNote
SD CSGPIO 4ext. pull-up, reaches DAT3
SCK / MOSI / MISOGPIO 9 / 10 / 8shared with LCD

Boot order

  1. bsp_spi_bus_init()bring up SPI2
  2. bsp_sd_mount()card first, while the bus is quiet
  3. …buttons, LEDs, battery, radios
  4. bsp_display_start()LCD traffic starts last

Five things that broke the SD card

  1. 01

    Bus ordering

    A fresh card listens to MOSI regardless of CS. Solana OS mounts the SD card before it starts the display.

  2. 02

    Lagging error flags

    Some cards report errors on the next command. The driver answers the SDIO probes (CMD52, CMD5) itself instead of sending them.

  3. 03

    Invalid FAT32

    FAT32 volumes with fewer than 65,525 clusters are rejected by FatFs. The firmware detects this and offers an on-device format behind a confirmation.

  4. 04

    Flushes still on the bus

    The display driver lets go of the bus while a frame is still streaming out, so a card write mid-redraw crashed every over-the-air update. A frame now holds the bus until its last byte, and every SD command waits for it.

  5. 05

    Cards that ignore CS

    Some no-name cards keep executing bus traffic while deselected. The firmware detects them and refuses to use them rather than risk random reads or erases.

Takeaway: use a name-brand microSD card. The first four are fixed in firmware; the fifth is the card.

06 Module

Connectivity

Dual-band Wi-Fi 6, BLE 5 and 802.15.4 on one chip, plus USB-C.

The ESP32-C5 has dual-band Wi-Fi 6 (2.4 and 5 GHz), Bluetooth LE 5 and an IEEE 802.15.4 radio. Solana OS uses Wi-Fi on both bands and runs the badge-to-badge mesh over ESP-NOW, on a 2.4 GHz channel or, at events where every badge has updated, a 5 GHz one. From Solana OS 1.0.0, Bluetooth LE is there for apps. The 802.15.4 radio is unused.

For wired access there is a USB-C port on the back. UART0 goes through a CH340C USB-serial bridge, which carries flashing and a serial console at 115200 baud with commands like help, info, sd, ls, cat and rgb.

Wi-Fi
Wi-Fi 6, 2.4 + 5 GHz
Bluetooth
BLE 5 (for apps, Solana OS 1.0.0+)
Low-power radio
IEEE 802.15.4
USB
USB-C
USB-serial
CH340C
Console
115200 baud
Pin map · Connectivity
SignalPinNote
UART0 TXGPIO 11to CH340C
UART0 RXGPIO 12from CH340C

07 Module

Power

A 1000 mAh LiPo, an OFF/ON switch and an ADC fuel gauge.

A 3.7 V 1000 mAh LiPo pouch (523450) covers the lower half of the back and plugs into a JST connector. An OFF/ON slide switch on the left edge cuts power.

There is no dedicated fuel-gauge chip. The battery voltage goes through a 1:1 resistor divider into ADC1 on GPIO 1, and firmware doubles the reading. Solana OS shows the result as a percentage in the status bar while the badge runs on its battery (on USB it shows “USB”, because the badge cannot see the cell while it charges), and the Hardware Debug app shows millivolts too.

Charging is over USB-C at about 100 mA, so a flat battery takes about 10 hours to charge fully. A red LED on the back of the board is lit while it charges, and a blue LED when it is fully charged.

Battery sense

Vbat = 2 × VADC1 · GPIO 1

Battery
3.7 V 1000 mAh LiPo
Cell
523450 pouch
Connector
JST
Switch
OFF / ON slide
Fuel gauge
ADC, no gauge IC
Divider
1:1 (reading ×2)
Charging
USB-C, about 100 mA
Full charge
about 10 hours · blue LED when full
Pin map · Power
SignalPinNote
Battery senseGPIO 1ADC1, 1:1 divider

Fig. 02 · Case design

Make a case

Exact dimensions from the board's KiCad file, for anyone printing a case. Measurements are in millimetres from the board's top-left corner as seen from the front (the screen side). Parts on the back keep those coordinates, as if seen through the board.

1:1 in millimetres. The board outline is its own layer; the display, buttons, LEDs and the parts on the back are reference layers.

FRONT VIEW · MM
68.58104.97Display window48.89 × 36.72UPLEFTRIGHTDOWNSELECTCANCELUSB-CSwitchmicroSD
To scale. Display window (green), panel outline, buttons and LEDs. Orange marks: openings in the edges.

Board

Outline
68.58 × 104.97 mm Width × height, portrait
Thickness
1.6 mm Two-layer FR4
Corners
R 4 mm
Right-edge recesses
0.89 mm deep y 37.85–46.48 (45° ends from 36.96 / 47.37); y 51.24–59.88 (45° ends from 50.36 / 60.77)
Mounting holes
None Hold the board by its edges

Through-board cutouts

Lanyard slot, left
9.65 × 3.02 mm x 4.06–13.71, y 4.01–7.03, round ends
Lanyard slot, right
9.65 × 3.02 mm x 54.78–64.44, y 4.06–7.08, round ends
Display cable slot
3.56 × 16.26 mm x 35.75–39.31, y 33.61–49.86

Front

Display window
48.89 × 36.72 mm Active area: x 10.10–58.99, y 23.34–60.06
Display panel
60.26 × 42.75 mm Outline: x 1.40–61.66, y 20.32–63.07
Buttons
6 × 6 mm, turned 45° UP (16.18, 75.56) · LEFT (8.60, 83.69) · RIGHT (23.84, 83.69) · DOWN (16.18, 91.82) · SELECT (50.35, 88.77) · CANCEL (59.96, 78.61)
RGB LEDs
2 × 2 mm D3 (19.58, 5.84) · D4 (25.57, 5.82) · D5 (31.56, 5.84) · D6 (37.40, 5.84) · D7 (43.28, 5.84) · D8 (49.15, 5.82) · D9 (64.96, 26.75) · D10 (64.92, 56.77)

Edges (parts on the back)

USB-C, left edge
y 53.52–62.46 Receptacle 8.94 mm wide, centred at y 57.99, its face 0.12 mm inside the edge. Leave room for the plug’s overmold
Power switch, right edge
y 37.85–46.48 In a 0.89 mm edge recess. The 1.3 mm handle is drawn at y 38.56–39.86 and reaches x 68.49
microSD slot, right edge
y 50.31–61.31 The card (11 mm wide) goes in at the recessed edge. A card stands proud of the edge: leave a finger notch

Back

ESP32-C5-WROOM module
x 0.03–27.53, y 20.97–38.97 Antenna end at the left edge (x 0–6.5): keep metal and thick walls away from it
BOOT button
x 63.46–66.46, y 27.58–30.08 3.0 × 2.5 mm
RST button
x 55.84–58.84, y 27.58–30.08 3.0 × 2.5 mm
Display FPC connector
x 44.56–50.16, y 35.69–47.79 The panel's cable folds through the FPC slot into it
Battery connector
x 44.03–48.23, y 57.77–65.42 Molex PicoBlade, 1.25 mm pitch, 2 pins
Battery area (silkscreen)
x 23.88–46.35, y 69.98–87.76 The mark on the board, not the cell's size: measure your battery

Not in the board file, so measure your own badge: the height of the parts, the display panel's thickness and the battery's size. Leave clearance around the screen and buttons, and keep metal away from the antenna end (the left edge, y 21–39).

The printable case assembled: a green front bezel with a screen window over the top of the board, the buttons left open, on a purple back cover.

Printable case

Print one

A front bezel and a back cover that snap together around the badge with four PLA clips. The bezel covers the screen and LEDs and stops above the buttons, so you press the badge's own buttons: no caps to print. The lanyard slots, USB-C and one opening for the microSD card and power switch stay open, and the Solana logomark, 28 mm wide, is cut through the back. The outline, openings and windows come from the board file. The heights don't (it has no 3D models): behind the board the cover is slim, 7.2 mm from the board's ledge to the floor, measured on a badge's battery with 0.3 mm to spare; in front, 4 mm for the screen is still a guess, so check it on your badge. Closed, the case is 16 mm thick. Change the parameters at the top of the OpenSCAD file and render again.

  • PLA (the clips are sized for it), 0.2 mm layers, no supports. Print each part outside down, as exported; the 3MF holds both parts as separate objects, so you can give each its own filament.
  • The slim back leaves thin spots: 1.2 mm between the side opening's lower edge and the floor, 0.5 mm below the clip pockets. Look at them in your slicer.
  • Check the battery fits without pressing on it before you close the case. The logomark is a through-cut, so keep anything conductive away from it.
  • Battery and board go into the back cover, screen up; the board rests on a ledge.
  • Press the bezel on until all four clips click. Print part="test_front" and part="test_back" from the OpenSCAD file first to check one clip's fit.
  • BOOT and RST are reachable with a pin through the back.

Both parts check out as single watertight solids that don't overlap when closed, but this revision hasn't been printed and fitted to a badge yet.

Firmware · ESP-IDF v6.1-dev-9359-g4109c8923a5 · LVGL 9 · Lua 5.5

Solana OS

The badge firmware, open source (MIT) at solana-foundation/solana-os: a launcher, a status bar, one input layer, the game’s apps, Lua apps from the App Store and over-the-air updates, set in ABC Diatype on the device. It runs one app at a time and hands it the screen.

Try it in the emulator
Solana OS launcher with six app tiles

Screenshot from a real badge · 320×240

Launcher

The home screen is an app browser: a grid of every app on the badge, six to a page. The focused tile lights up.

  • Status bar: Solana logomark, app title, Wi-Fi, battery %
  • Move with the D-pad, open with SELECT
  • BOOT always brings you back here
  • One app runs at a time and frees its memory on exit

Controls

The default mapping. Apps read logical keys, so the mapping lives in one header and can change without touching apps.

ButtonDoesWhere
UPMove upFront · D-pad
DOWNMove downFront · D-pad
LEFTMove leftFront · D-pad
RIGHTMove rightFront · D-pad
SELECTOpen / confirmFront
CANCELCancel / go backFront
BOOTHomeBack

Built-in apps

Wi-Fi, My Badge, Guide, X Dex, Trade, Quests, App Store, Apps, ESP-NOW, HW Debug, Settings and About, plus Beacon on a badge paired as a quest beacon. Adding one is a new directory under apps/, one entry in sources.cmake and one line in the registry; the badge and the emulator both pick it up. The descriptor below is the real one from the firmware.

App model
// firmware/main/core/os.h - one descriptor per app,// listed in firmware/main/apps/registry.ctypedef struct {    const char *id;                 // console: "open wifi"    const char *name;               // launcher + status bar title    const char *symbol;             // LV_SYMBOL_* icon, or NULL...    const lv_image_dsc_t *icon;     // ...to use an image    uint32_t accent;    void (*on_enter)(lv_obj_t *root);   // build UI in the OS-owned root    void (*on_exit)(void);          // stop tasks/radios/timers, free memory    bool (*on_key)(os_key_t key, bool repeat);  // false = not handled    void (*on_tick)(void);          // every 100 ms, LVGL locked    void (*on_button)(uint32_t bit);    // optional: raw presses (calibration)    bool (*visible)(void);          // optional: in the launcher only while true} os_app_t;

Web Serial · USB-C

Flash your badge

Put Solana OS 2.4.0 on your badge straight from this page: plug it in over USB-C, pick its port, flash. Nothing to install. Developers can build it from source instead.

Erase options, release and re-link, and an offline download for esptool are on the Stock firmware page.

Loading the flasher…