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.
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.
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)
| Signal | Pin | Note |
|---|---|---|
| Flash (reserved) | 16–22 | 15 is PSRAM CS1 |
| USB (reserved) | 13 / 14 | — |
| Unused, floating | 2 / 5 / 26 | free 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
| Signal | Pin | Note |
|---|---|---|
| SPI2 SCK | GPIO 9 | shared with SD |
| SPI2 MOSI | GPIO 10 | shared with SD |
| SPI2 MISO | GPIO 8 | shared with SD |
| LCD CS | GPIO 6 | — |
| LCD DC | GPIO 7 | — |
| LCD RST | GPIO 0 | not independently verified |
| Backlight | GPIO 3 | active 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
| Signal | Pin | Note |
|---|---|---|
| I2C SCL | GPIO 23 | — |
| I2C SDA | GPIO 24 | — |
| TCA9534 INT | GPIO 25 | active low |
| UP · LEFT · RIGHT · DOWN | TCA9534 P0–P3 | active low |
| SELECT · CANCEL | TCA9534 P4–P5 | active low |
| BOOT | GPIO 28 | ext. 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
| Signal | Pin | Note |
|---|---|---|
| WS2812B DIN | GPIO 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
| Signal | Pin | Note |
|---|---|---|
| SD CS | GPIO 4 | ext. pull-up, reaches DAT3 |
| SCK / MOSI / MISO | GPIO 9 / 10 / 8 | shared with LCD |
Boot order
- bsp_spi_bus_init()bring up SPI2
- bsp_sd_mount()card first, while the bus is quiet
- …buttons, LEDs, battery, radios
- bsp_display_start()LCD traffic starts last
Five things that broke the SD card
- 01
Bus ordering
A fresh card listens to MOSI regardless of CS. Solana OS mounts the SD card before it starts the display.
- 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.
- 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.
- 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.
- 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
| Signal | Pin | Note |
|---|---|---|
| UART0 TX | GPIO 11 | to CH340C |
| UART0 RX | GPIO 12 | from 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
| Signal | Pin | Note |
|---|---|---|
| Battery sense | GPIO 1 | ADC1, 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.
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).
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"andpart="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
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.
| Button | Does | Where |
|---|---|---|
| UP | Move up | Front · D-pad |
| DOWN | Move down | Front · D-pad |
| LEFT | Move left | Front · D-pad |
| RIGHT | Move right | Front · D-pad |
| SELECT | Open / confirm | Front |
| CANCEL | Cancel / go back | Front |
| BOOT | Home | Back |
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.
// 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;The game on your badge
The Hitchhiker’s Guide to Solana
Your badge is your ticket into a game that runs across the whole conference. Collect the pages of the Guide, earn !LAMPs, swap cards with the people you meet and follow the characters around the venue.
- Guide Collect the pages of the Guide from packs: nine categories, four rarities. Duplicates count up.
- !LAMPs The game’s points. Earn them from bounties and quests, spend them on packs and apps.
- X Dex Swap cards with nearby badges. With X linked on both sides, every new person raises your Level and pays a bounty.
- Quests Characters wait at beacons around the venue. Talk to them on your badge.
- App Store Lua apps for the badge, made by attendees. Install them to the microSD card.
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…