Badge.Team documentation

• 1: Badges
• 1.1: Bornhack 2026 badge
• 1.1.1: Getting started
• 1.1.2: Quick reference
• 1.1.3: Mesh & messaging
• 1.1.4: NFC & tokens
• 1.1.5: Clock, alarm & calendar
• 1.1.6: Games
• 1.1.7: Hardware
• 1.1.8: FAQ & troubleshooting
• 1.1.9: Flash your badge
• 1.1.10: DOOM
• 1.1.11: CircuitPython
• 1.2: Konsool badge
• 1.2.1: Konsool quick start
• 1.2.2: Compatibility
• 1.2.2.1: Camera
• 1.2.3: Konsool FAQ
• 1.2.4: konsool hardware
• 1.2.4.1: Konsool specifications
• 1.2.4.1.1: Konsool battery
• 1.2.4.1.2: Konsool ESP-C6
• 1.2.4.1.3: Konsool ESP-P4
• 1.2.4.1.4: Konsool keyboard
• 1.2.4.1.5: Konsool screen
• 1.2.4.2: Camera
• 1.2.4.3: Konsool connectors
• 1.2.4.4: Konsool pinouts
• 1.2.4.4.1: Konsool connectors
• 1.2.4.4.1.1: CATT pinout
• 1.2.4.4.1.2: QWIIC pinout
• 1.2.4.4.1.3: Internal expansion port
• 1.2.4.4.2: IC pinouts
• 1.2.4.4.2.1: CH32V203 pinout
• 1.2.4.4.2.2: ESP32C6 pinout
• 1.2.4.4.2.3: ESP32-P4 pinout
• 1.2.4.5: Frontpanel
• 1.2.4.5.1: Konsool artwork
• 1.2.5: Konsool software
• 1.2.5.1: Konsool apps
• 1.2.5.1.1: Konsool local apps
• 1.2.5.1.2: Software Hub for Konsool
• 1.2.5.1.2.1: Creating apps
• 1.2.5.1.2.2: Downloading Apps
• 1.2.5.1.2.3: Uploading apps
• 1.2.5.2: Konsool settings
• 1.2.5.2.1: Konsool LoRa
• 1.2.5.2.2: Konsool Software Hub settings
• 1.2.5.2.3: Konsool wifi
• 1.2.5.3: Konsool updating
• 1.2.5.3.1: Konsool apps
• 1.2.5.3.2: Konsool firmware
• 1.2.6: Konsool expansion boards
• 1.2.6.1: 18650 extension
• 1.2.6.2: Zero expansion boards
• 1.3: Hackerhotel 2024
• 1.3.1: Hackerhotel 2024 photos
• 1.3.2: Software Development
• 1.3.2.1: Modify Standard Firmware
• 1.4: Hackerhotel 2023
• 1.5: MCH2022 badge
• 1.5.1: MCH2022 Badge Hardware
• 1.5.1.1: MCH2022 badge pinouts
• 1.5.1.2: Battery
• 1.5.1.3: MCH2022 Badge Hardware Hacking
• 1.5.2: Getting Help (and helping)
• 1.5.2.1: Troubleshooting & FAQ
• 1.5.3: Getting started
• 1.5.3.1: Inserting an SD Card
• 1.5.3.2: Installing Apps from "The Hatchery"
• 1.5.3.3: Using Your Badge
• 1.5.4: Software Development
• 1.5.4.1: Developing native Badge apps with the ESP-IDF
• 1.5.4.1.1: ESP-IDF getting started
• 1.5.4.1.2: A More Advanced Example
• 1.5.4.1.3: ESP-IDF fancy name tag
• 1.5.4.2: FPGA Development
• 1.5.4.2.1: FPGA Getting Started explained by a Badger with a Very Small Brain
• 1.5.4.3: Developing Badge Apps with MicroPython
• 1.5.4.3.1: Getting started
• 1.5.4.3.2: Neopixels
• 1.5.4.4: RISC-V Playground
• 1.5.4.5: Developing for the RP2040 Coprocessor
• 1.5.4.6: Publishing your App in The Hatchery
• 1.5.4.7: Getting Started with TinyGo
• 1.5.4.8: ESP Native APIs
• 1.5.4.8.1: APIs: Graphics
• 1.5.4.8.2: Board Support Package
• 1.5.4.8.3: WS2812
• 1.5.4.9: App gallery
• 1.5.4.10: Rust development for the ESP32
• 1.5.4.11: Using Arduino to Develop Badge Apps
• 1.6: CampZone 2020
• 1.7: Disobey 2020
• 1.8: Hackerhotel 2020
• 1.8.1: Connecting on Linux
• 1.8.2: Connecting on Mac
• 1.8.3: Connecting on Windows
• 1.8.4: Playing after the event
• 1.9: CampZone 2019
• 1.10: Disobey 2019
• 1.11: ETH0 2019
• 1.12: Hackerhotel 2019
• 1.13: SHA2017
• 1.13.1: Getting started
• 1.13.2: Driver installation
• 1.13.3: Hardware
• 1.13.4: Troubleshooting
• 2: Hatchery
• 2.1: API
• 2.2: API (MCH2022)
• 3: BadgeHub
• 3.1: Overview
• 4: Standards
• 4.1: SAO: Standardized Add-On
• 4.1.1: Binary SAO descriptor
• 5: BadgePython
• 5.1: API reference
• 5.1.1: Display
• 5.1.2: Buttons
• 5.1.3: mch22
• 6: ESP32 platform firmware
• 6.1: ESP32: app development
• 6.1.1: Getting started
• 6.1.1.1: Your first egg
• 6.1.2: USB-serial connection
• 6.1.3: API reference
• 6.1.3.1: Display
• 6.1.3.2: Buttons
• 6.1.3.3: System
• 6.1.3.4: Appconfig
• 6.1.3.5: Audio
• 6.1.3.6: HID Keyboard & Mouse
• 6.1.3.7: Keypad
• 6.1.3.8: MIDI Music Controller
• 6.1.3.9: Touchpads
• 6.1.3.10: ugTTS Text-to-Speech
• 6.1.3.11: WiFi
• 6.1.3.12: Terminal
• 6.1.3.13: Machine
• 6.1.3.13.1: Non Volatile Storage
• 6.1.3.13.2: The I2C bus
• 6.1.3.13.3: Pin: direct GPIO control
• 6.1.3.14: _buttons
• 6.1.3.15: consts
• 6.1.3.16: eink
• 6.1.3.17: erc12864
• 6.1.3.18: esp32_ulp
• 6.1.3.19: espnow
• 6.1.3.20: hub75
• 6.1.3.21: keyboard
• 6.1.3.22: mpu6050
• 6.1.3.23: neopixel
• 6.1.3.24: opus
• 6.1.3.25: rgb
• 6.1.3.26: samd
• 6.1.3.27: sndmixer
• 6.1.3.28: ssd1306
• 6.1.3.29: umqtt
• 6.1.3.30: ussl
• 6.1.3.31: voltages
• 6.1.4: Jupyter Notebook
• 6.2: ESP32: firmware development
• 6.2.1: Getting started
• 6.2.1.1: Menuconfig
• 6.2.2: Adding support
• 6.2.2.1: Adding drivers
• 6.2.3: Factory tests and provisioning
• 6.2.4: Device status

1 - Badges

Badge.Team badges

These are the badges where Badge.Team volunteers were involved in during their creation, either by helping with hardware development or by providing firmware. You can click on each of the badges to go the corresponding documentation section.

ESP32 based

Other badges

The CCC camp 2019 “CARD10” badge

The CARD10 uses the hatchery as its app repository. For all other details about this project (the hardware, firmware and API) please have a look at the CARD10 project over at the CCC website.

1.1 - Bornhack 2026 badge

Introduction

The BornHack 2026 badge is the Cyber Ægg: an egg-shaped, low-power hacker badge inspired by the 90’s Tamagotchi. It is designed to run for the entire duration of the BornHack camp on a single battery charge, while keeping you connected to everyone else on the field over a long-range LoRa mesh.

Under the playful shell it is a serious little radio computer. A Nordic nRF52840 drives a 1.54 inch black/red/white e-paper display, talks Bluetooth Low Energy to your phone, emulates an NFC tag on its back, and reaches the wider MeshCore network through a dedicated SX1262 LoRa radio. To keep you entertained between messages there is BornPets, a virtual pet with a handful of mini-games.

Front (display and buttons) and back (nRF52840, USB-C connectors, NFC coil).

Features

• Egg-shaped badge inspired by the classic Tamagotchi
• Nordic nRF52840 microcontroller (BLE + USB + NFC)
• 1.54" 152 × 152 black/red/white e-paper display
• SX1262 LoRa radio, part of the MeshCore mesh network
• Bluetooth Low Energy companion connection to the MeshCore app
• NFC tag on the back for location-based games and station taps
• 5-way joystick, Select / Execute / Cancel buttons, RGB LED and a piezo buzzer
• USB-C for charging and drag-and-drop file transfer

New to the badge? Start with the Getting started guide. Curious about the virtual pet? See Games. Want to know what is inside? See the Hardware page.

Source code

The Cyber Ægg is open source. Both the hardware design and the firmware live on Codeberg:

• Hardware (KiCad) — Ranzbak/bornhack2026-hardware
• Firmware (Rust / Embassy) — Ranzbak/bornhack-firmware-2026

The Flash page also offers four alternative images, each with its own home:

• Community Edition — ShadowSquad-org/BornHack-Cyberegg, a fork with extra BornPets mechanics
• DOOM — rarenerd/cyberaegg-doom, a bare-metal port of the DOOM engine
• CircuitPython — rarenerd/cyberaegg-circuitpython, for programming the badge in Python
• Bad Apple!! — annejan/aegg-apple, the animation on the e-paper panel with the tune on the buzzer

Hardware sponsors

• Nordic Semiconductor sponsored their low power yet very capable and fast NRF52840 microcontroller with Bluetooth Low Energy and NFC, making it possible for us to build a device that runs on one battery charge, the whole camp long!
• ALLNET China is our production partner, they take care of sourcing most components and oversee the production process in China, saving us a lot of work and potential headaches and allowing us to focus on the product!
• Procolix sponsored the SX1262 LoRa radio chips, converting the badge into a capable LoRa communications device. Check out their managed hosting solutions for a truely sovereign cloud built on European open source solutions!
• deFEEST sponsored part of the badge hardware, helping us get the components we needed to build it. Find out more at defeest.nl!
• Mollerup Automation sponsored the 3D printed housing for the badge. They are automation, robotics and PLC specialists from Odense, Denmark — see mollerup.info!

1.1.1 - Getting started

Welcome to the BornHack 2026 Cyber Ægg badge. This guide takes you from “unbox” to “actually playing with it” in a few minutes.

First power-on

A fresh badge runs a built-in factory self-test on the very first boot. You will see a FACTORY TEST screen with a small PASS/FAIL grid, followed by ALL PASS. After that the badge goes straight to the application on every boot; the self-test never runs again unless the firmware is wiped.

The very first boot then plays a short one-time sponsor slideshow (the event logos, then the badge-sponsor logos, a couple of seconds each) before dropping you on the Main screen. It only runs once per badge — you can replay it any time from Main → Badge sponsors.

The LED sequence at every boot is:

1. Pulsing orange — hardware initialisation
2. Pulsing blue — display and LoRa radio coming up (about 13 seconds)
3. A single green flash — ready

You then land on the Main screen.

Controls

The badge has a 5-way joystick on the left and two thumb buttons on the right:

Top-level screens

The interface is a carousel — Left / Right cycles through the top-level screens:

Pair with the MeshCore app

The badge speaks the MeshCore companion protocol over Bluetooth Low Energy. Install the MeshCore app on Android / iOS, or open https://app.meshcore.nz/ in a browser that supports Web Bluetooth (Chrome / Edge on desktop or Android).

1. Make sure Bluetooth is on — Main → Settings → Bluetooth should read BLE: ON.
2. In the app, scan for devices. Your badge advertises as Cyber Ægg XXYY, where XXYY is four hex characters unique to your badge.
3. The phone shows a passkey prompt and the badge shows a 6-digit passkey on its display. Type that number into the phone.
4. Once bonded, the app can set the clock, manage contacts, send and receive mesh messages, change the LoRa preset and more.

Set the time

The badge has no battery-backed real-time clock, so the clock resets to “not set” on every reboot. There are two ways to set it:

• MeshCore app — connect over Bluetooth and the app pushes your phone’s time to the badge.
• Near a synced repeater — a known-good mesh repeater advertises its time periodically and your badge picks it up automatically.

Set your timezone once under Main → Settings → Timezone — that setting persists.

Charging

Plug any USB-C cable into the badge to charge it. Charge state is shown on the on-screen battery icon (there is no dedicated charge LED).

Two things that look like faults but aren’t: the charge bolt disappearing while USB is still plugged means charging is complete (it returns by itself if the cell drains), and the battery icon can lag up to a minute behind reality — it is only re-sampled every 60 seconds.

USB drag-and-drop

When plugged in over USB-C the badge appears as a small drive named CYBR<4 hex>. You can drop these files into its root:

Reboot the badge after copying files (re-plug USB) for the changes to take effect.

LUT.CFG is an advanced tweak: it overrides the panel’s built-in display waveform with a calibrated one (e.g. faster refresh). If a custom LUT ever renders badly, hold Fire (joystick press) while booting to force the safe built-in waveform for that boot, then delete or fix the file. A malformed or wrong-panel LUT.CFG is rejected automatically.

Firmware update

The easiest route is the Flash page: it writes the firmware and the badge’s asset files straight from a Chromium-family browser, with no toolchain to install.

To do it by hand, slide the ON/OFF switch (top-left on the front of the badge) off and then back on while holding Execute to enter the bootloader (DFU) mode — the LED blinks red. (The battery keeps the badge running, so unplugging USB will not restart it.) You can then flash a new firmware image with dfu-util:

dfu-util -d 1915:521f -D cyber-aegg.bin

The firmware is open source and built with Rust / Embassy — see Ranzbak/bornhack-firmware-2026 for source, build instructions and pre-built images.

1.1.2 - Quick reference

A one-page cheat sheet for the Cyber Ægg. Print it and tuck it under the strap.

        ┌─────────────────────────────┐
        │      e-paper display        │
        ├─────────────────────────────┤
        │                             │
        │   [UP]                      │
        │ [L][F][R]      [CAN] [EXE]  │
        │   [DN]                      │
        │                             │
        └─────────────────────────────┘
            5-way joystick   2 buttons
            (F = press in)

Buttons

Top-level screens

Left / Right cycles through them:

Game → Main → PMs → Channel → Adverts → Tokens → Clock → Calendar → Name → My QR

LED meanings

Power-on combos

Hold these while powering on — slide the ON/OFF switch (top-left on the front) off, then back on (the battery keeps the badge running, so unplugging USB will not restart it):

If the app slot is blank the badge enters DFU on its own.

USB drag-and-drop

Plug in USB-C — the badge mounts as the CYBR<4 hex> drive.

Reboot the badge after dropping files.

Firmware update (DFU)

dfu-util -d 1915:521f -D cyber-aegg.bin

Bootloader LEDs in DFU: red blink (idle) → solid blue (flashing) → solid green (done — power-cycle).

Charging

USB-C in any port charges the badge. There is no separate charge LED — the battery icon on the watch / status bar shows the level.

1.1.3 - Mesh & messaging

The badge has a LoRa SX1262 radio and speaks the MeshCore mesh protocol. Other badges, MeshCore phones and standalone repeaters all appear as peers. Four carousel screens are mesh-related: PMs, Channel, Adverts and My QR, backed by the Contacts list.

Getting on the same network

Three things must match across every badge in the local mesh:

1. LoRa preset — frequency, bandwidth and spreading factor. The default is BornHack 2026 (baked into the firmware). Change it under Main → Settings → LoRa Radio.
2. Public channel key — shared automatically via the preset.
3. Antenna — make sure the LoRa antenna is connected.

If you can’t see anyone else’s adverts after a minute, check the preset first.

Adverts

Every badge, phone or repeater on the mesh periodically broadcasts an advert — its public name, identity hash and capabilities. Your badge logs these on the Adverts screen as they arrive.

Private messages (PMs)

The PMs screen is your private inbox — each row is a peer who has messaged you.

Use Up / Down to scroll, Execute / Fire to open a thread or start a reply, and Cancel to go back. Replies use the on-screen keyboard (joystick to pick a character, Execute to commit, Cancel to backspace) with about 70 emoji available.

Channels (group chat)

The Channel screen is group / room chat — the same protocol with a broadcast scope. Each row is a channel (for example the default Public channel that ships with the preset). Controls match the PMs screen; everyone on the same preset hears every message in a public channel.

My QR

The My QR screen renders your mesh identity as a QR code. Show it to someone else’s MeshCore phone or badge for instant pairing — no need to wait for an advert to be heard first.

Contacts

The Contacts list (Main → Bornagotchi → Contacts, or jump there from the Adverts screen) shows everyone the badge has heard or knows: nearby strangers, saved friends, repeaters and rooms.

Popup actions:

• PM — open the message thread.
• Info — hex identity prefix, last-heard time, advert capabilities.
• Add / Save — persist the contact in flash so it survives a reboot.
• Unsave — drop it from flash (stays in the discovery cache until reboot).
• Forget — remove it immediately, even from the discovery cache.

Pinging & visibility

When another badge pings you with the mesh blinkme command your LED briefly flashes in the requested colour — a fun way to find friends in a crowd. Your badge also sends its own adverts so others can see you.

Battery note

The LoRa radio is the single largest battery drain. To save power, Main → Settings → MeshCore lets you mute notification sounds. (The e-paper display itself draws no power once an image is shown.)

Using your phone instead

Prefer to chat from your phone? Install MeshCore on Android / iOS or open https://app.meshcore.nz/, then pair over Bluetooth — see Getting started. Once bonded, contacts, chat and settings are all reachable from the app.

1.1.4 - NFC & tokens

The back of the badge has an NFC antenna. Tap a phone or a station reader against it to interact — you don’t have to do anything on the badge, it is always ready.

Two things happen on a tap

A phone reads your broadcast profile

Any standard NFC reader (the built-in Android reader, iOS) sees whatever you have set as your broadcast profile — by default the badge’s own docs page https://badge.team/docs/badges/bornhack-2026/, but you can replace it with your own vanity URL, a vCard and more (see Set your own broadcast data). Tapping with the OS reader simply reads it. Harmless.

BadgeCtl runs a station command

A phone running the BadgeCtl companion app, loaded with the matching event key, can send signed commands when held to the badge. These are used at event stations, where you boost your BornPet’s stats:

A short toast on the badge confirms what happened. Each command has a 5-minute cooldown — tapping twice in quick succession does nothing the second time.

Station commands need an active game: pick a pet first (the egg countdown already counts). If your pet has left, start a new egg — a tap with no active pet is silently ignored.

Tokens

Tokens you collect from station taps (and from other badges) land on the Tokens carousel screen. The badge collects many tokens and keeps them until the next reboot, so it is a running record of the stations and badges you tapped during the camp.

When someone pushes a token: onto your badge it shows for about 10 seconds, then the badge reverts to broadcasting your own profile — a pushed token can’t overwrite it.

Set your own broadcast data

The default docs-page URL is not fixed — you can make the badge hand out anything you like. Use any NFC-writer app on your phone (e.g. NFC Tools) and write to the back of the badge:

• Vanity URL — write a URL / URI record (e.g. annejan.com). A Text record set:https://your.link also works for writer apps that only emit text.
• vCard — write a Contact / vCard record; phones tapping you then get your contact card.
• Wi-Fi, or any other record — served verbatim.

The rule is simple: anything you write sticks and survives a reboot — except a token:, which lands on your Tokens screen instead. Keep it short; records are capped at ~127 bytes (fine for a URL or a compact vCard). Long URLs sent via the set: text form are additionally clamped to ~118 characters after the scheme — for anything longer, write a plain URI record instead, or use a link shortener.

There is no NFC “erase” back to the factory default: an empty write (or a writer app’s “format tag”) doesn’t restore the built-in docs URL — it just leaves your current profile in place (or stores the empty record). To change what you broadcast, simply write the new record over it.

Setting this is unauthenticated — anyone who can physically tap your badge with a writer app can change it. It is your badge in your pocket; treat physical access accordingly.

What the reader side needs

The badge is always ready; the reader needs:

• The BadgeCtl app installed.
• The matching Ed25519 private key bundled in — BornHack staff hold this for the official stations.

Third-party NFC reader apps can’t issue these commands because they don’t have the key; they only ever see the public URL.

Running your own station

Want your own station? Rebuild the badge firmware with your own Ed25519 public key, then sign the matching commands with your private key in your reader app. The protocol spec, wire format and a signing recipe (Kotlin / Python / Rust) are in the firmware’s NFC_README.md.

How it works (hardware)

The nRF52840 includes an NFC tag PHY driving an on-PCB coil (~2.8 µH) tuned with capacitors to 13.56 MHz. It supports tag mode only (not reader mode) — see the Hardware page.

1.1.5 - Clock, alarm & calendar

Three apps share the “watch” carousel slots: Clock, Alarm (opened from the Clock) and Calendar.

Clock

Two switchable watch faces — digital and analog. A small bell icon in the header lights up when an alarm is armed.

Open: push Left / Right until you land on the Clock screen.

Setting the time

The badge has no backup battery for its real-time clock, so the wall clock resets to None on every boot and reads “Clock not set” until you set it. Two ways:

• MeshCore app over Bluetooth — the phone pushes its time. The easy path.
• Mesh time advert — stand near a synced LoRa repeater and the badge picks the time up over the air. On-air time is only accepted from a trusted source: a signature-verified repeater / companion advert or a channel you hold the key for. A crowd of other badges won’t set your clock.

Set the timezone once under Main → Settings → Timezone — it persists across reboots (default +2, CEST for BornHack).

Alarm

Push Execute / Fire on the Clock screen to open the alarm editor.

The Days field cycles: Daily · Weekdays · Weekends · None · Custom. The Tone field offers ten built-in tunes: Beep, Imperial March, Rickroll, Pink Panther, Sandstorm, Startup, Trololo, Daisy Bell, Nokia, Samsung.

When an alarm fires the buzzer plays the chosen tone up to five times, 8 seconds apart. Any button press silences it; if you ignore it, it stops itself after about 32 seconds.

Calendar

A month grid with a per-day timeline of imported iCalendar events.

Open: Left / Right to the Calendar screen (right of Clock). The grid is shown without a cursor; push Execute / Fire to enter active mode.

Active mode:

Day detail (timeline):

Loading events

The badge imports events at boot from a file named ALARMS.ICS in the root of the USB drive:

1. Plug the USB-C cable into your computer.
2. Open the drive labelled CYBR<4 hex>.
3. Drop your .ics file in the root, renamed to ALARMS.ICS.
4. Eject the drive.
5. Reboot the badge — slide the ON/OFF switch (top-left on the front) off, then back on.

You can use the official BornHack programme .ics straight from https://bornhack.dk/.

Import limits & quirks

The parser is deliberately minimal. If events are missing or look odd, one of these is usually why:

• File size: 16 KiB max. Anything past that is silently cut off mid-event. A full conference programme easily exceeds this — trim it first with the firmware’s scripts/strip_ics.py (drops DESCRIPTION/UID/etc. and supports --from / --to / --max to select a range).
• 31 events max. Import stops quietly at the cap; later events in the file never appear.
• No recurrence. RRULE is ignored — a repeating event imports as its first occurrence only. Export “expanded” per-occurrence ICS instead (the BornHack programme already is).
• No all-day events. A DATE-only DTSTART is dropped without warning. Give the event a real start time.
• ASCII only. Non-ASCII characters in titles are stripped, not transliterated (Æ, accents and emoji simply vanish).
• Timezones. Only Z-suffixed (UTC) timestamps are shifted to local time — always by the built-in default of UTC+2 (right for BornHack), because the import runs before your persisted timezone setting is applied. Floating and TZID=-zoned times are taken as-is. When in doubt, export in UTC.
• Fired events disappear from the Calendar until reboot. Imported events are one-shot alarms: once one has fired it no longer shows on the grid or day view. Rebooting re-imports everything.
• Edits apply at boot only. Replace ALARMS.ICS, eject the drive properly, then power-cycle the badge.

1.1.6 - Games

The Game screen runs BornPets — a virtual pet inspired by the 90’s Tamagotchi — plus a set of mini-games you launch from the pet’s Play menu.

BornPets

Hatch a snail or a cat, then keep it fed, healthy, rested and entertained.

Hatching

The first time you open the Game screen you see the hatchery. Push Execute / Fire to start, pick a pet from the roster (the built-ins are Bartholomeus, Cat and Slug), then wait about a minute for the egg to hatch. After hatching you name your pet — up to 12 characters via the on-screen keyboard. The save persists across reboots. You can rename the roster or add your own pets — see Custom pet roster below.

Stats

Your pet has decaying stats — the higher they get, the worse off the pet is. Watch out for:

Stats interact: when several stats are bad the pet becomes miserable faster, and miserable makes everything else worse. Stay ahead of the spiral.

Controls

Hibernate

Putting the badge away for more than a few hours? Open the action menu and choose Hibernate — stats freeze until you wake the pet. Forget to hibernate before storing the badge and the pet keeps decaying, so it may have starved by the time you find it again.

Game modes

Two difficulty presets, picked via Main → Bornagotchi → Mode:

• Classic — the original balance the badge ships with.
• Casual — roughly half the decay speed and more relief per action, for people who don’t want to baby-sit.

The setting persists in flash. A * next to the mode name means the change is queued — reboot the badge for it to take effect.

Turning the pet off

Not a pet person? Main → Bornagotchi → Disable Game hides the whole Game screen from the carousel. The toggle persists across reboots (the label flips to Enable Game once off) and, while disabled, an NFC station tap can no longer jump you into the pet. Flip it back to Enable Game to bring the pet screen back.

Mini-games

Open the bottom-row Play menu in BornPets and pick a game. Each win reduces the drained stat without raising hunger, so they are free entertainment. Cancel always exits a mini-game.

Inside a game: the joystick moves the cursor, Execute / Fire places or selects, and Cancel quits back to the Play menu.

Make your own pet

Want a companion that isn’t a snail or a cat? The CyberÆgg Pet Maker is a browser-based sprite and animation editor for BornPets:

scene.rs/pets/

With it you can:

• Start from a preset (Bartholomeus, Cat, Slug) or a Blank canvas.
• Draw each animation frame with the badge’s palette — black, red, white and transparent (white is the e-paper background; transparent means “not drawn”).
• Preview animation states (e.g. Idle) with speed and onion-skin controls.
• Optionally tune the game balance (BORNPETS.CFG) — how fast stats decay and recover.
• Download ZIP to get everything packaged for the badge.

Installing a custom pet

The badge exposes a USB drive when plugged in over USB-C (see Getting started). Unzip the export from the Pet Maker and copy the sprite files — plus PETS.CFG, and BORNPETS.CFG if you made one — into the root of the CYBR<4 hex> drive, then reboot the badge.

Hand-editing sprites (GIMP etc.)

The badge only accepts a very specific PCX flavour (2 bits-per-pixel, single plane, RLE). Editors like GIMP happily export 16- or 256-colour PCX instead, which the badge silently skips. The firmware’s scripts/ folder has helpers for exactly this:

• fix_badge_pcx.py — re-packs a wrong-depth PCX (e.g. a 4bpp/8bpp GIMP export) back to the badge’s 2bpp format, preserving dimensions.
• png_to_badge_pcx.py — converts a PNG straight to a 152×152 badge PCX.
• check_badge_pcx.py — validates a file before you copy it over, so you catch a bad export on your computer instead of on the badge.

Custom pet roster: PETS.CFG

PETS.CFG is the pet roster shown in “Choose your Pet”. It is a plain-text file with one PREFIX=NAME per line, editable without reflashing the firmware:

# --- current pets (rename if you like) ---
0=Bartholomeus
1=Cat
2=Slug

# --- add your own (needs 05xxxx.PCX / 06xxxx.PCX sprites) ---
5=Dragon
6=Ghost

• PREFIX is the pet’s sprite-prefix byte (decimal):
  • 0, 1, 2 — the built-in pets (listing them just renames them)
  • 3, 4 — reserved (sponsors, menu icons) and ignored
  • 5–7 — your own custom pets
• NAME is up to 16 ASCII characters.

A pet’s sprites are the matching PPAAFF.PCX files on the badge — PP is the prefix, AA the animation part, FF the frame. The firmware just counts the PCX files present (for example 050100…050104 = five idle frames), so there is no fixed frame count or header to maintain. Export sprites at the pet’s prefix from the Pet Maker and drop them next to PETS.CFG on the drive. Lines beginning with #, and reserved or malformed rows, are ignored.

Custom balance: BORNPETS.CFG

If you only want to change the difficulty (not the sprites), drop a plain-text BORNPETS.CFG in the root of the badge’s USB drive with one KEY=VALUE per line:

# speed up hunger decay, slow down the drained stat
HUNGER_RATE=4
DRAINED_INTERVAL=180

Eject the drive and reboot. When a config is active a small * appears after the pet’s name. Delete the file and reboot to return to a preset. The Pet Maker can generate this file for you, and the firmware’s USER_GAMES.md documents every supported key and its range.

A few gotchas:

• Edits apply at boot only. Eject the drive properly (so the write is flushed), then power-cycle. No * after the pet name = no override was applied.
• The parser is silent. Unknown keys are skipped, and a value that isn’t a plain whole number (no units, decimals or minus sign) drops the whole line without any on-screen error.
• The documented “reasonable range” is advice, not a limit. Values are only clamped to the raw integer type — HUNGER_RATE=1000 really does make hunger fill ~300× faster, and your pet will be starving before you’ve unplugged the cable. If a wild value wrecked your pet, delete the file and reboot to fall back to the preset.

1.1.7 - Hardware

The Cyber Ægg is a low-power LoRa badge built around a Nordic nRF52840 microcontroller. The design goal is to run for the entire week of BornHack on a single battery charge, so a lot of care goes into keeping the power consumption down in both hardware and firmware.

The full KiCad design is open source at Ranzbak/bornhack2026-hardware.

Overview

Display

The badge uses a 1.54 inch tri-colour (black / red / white) e-paper display with a resolution of 152 × 152 pixels, driven by an SSD1675 / SSD1675B controller. E-paper keeps the badge readable in bright camp sunlight and draws no power to hold an image, which is a big help for the week-long battery goal.

By default the panel is driven with the waveform LUT stored in its own OTP. Advanced users can override this with a calibrated waveform (for example a faster refresh) by dropping a LUT.CFG file on the USB drive — see the firmware’s LUT.md. You can generate one with the ssd1675-calibration tool. Holding Fire while booting always forces the safe built-in waveform.

Manual input

Because the Cyber Ægg is inspired by the 90’s Tamagotchi egg-shaped toy, the buttons carry the same names:

To make navigation more intuitive, the Select button is implemented as a 5-way joystick with a press action.

Bluetooth

Bluetooth Low Energy is provided directly by the nRF52840. It operates in the 2.4 GHz band and uses an on-PCB antenna based on a Texas Instruments reference design (included in the standard KiCad 9 library). See the TI application note SWRA228 for details.

LoRa

Long-range connectivity is provided by a dedicated Semtech SX1262 radio with the matching/balun circuit specified in the Semtech application note AN1200.54. The LoRa antenna is a Texas Instruments design documented in SWRA416. On the network side the badge speaks MeshCore, so it can join the wider camp mesh out of the box.

NFC

The nRF52840 includes an NFC PHY, used here to drive a resonant circuit consisting of an on-PCB coil (roughly 2.8 µH) and tuning capacitors, forming a tank circuit matched to 13.56 MHz. The nRF52840 only supports tag functionality (not reader mode), which the firmware uses for location-based games and station taps.

Expansion connector

There is a QWIIC like I2C expansion connector on the board. Be aware that we made a small design mistake: the 3.3v and GND signals have been swapped around. Make sure to use a modified cable before connecting any QWIIC peripherals.

The badge carries a connector that should have been QWIIC compatible. QWIIC is a standardised I²C connector used by a large range of SparkFun and third-party breakout boards. Two 10 kΩ pull-up resistors are fitted on the board, and the nRF52840’s internal pull-ups can be enabled as well when the bus capacitance is high.

The firmware can also drive an optional Nicolai-Electronics I²C keyboard on this bus for typing names and mesh messages — plug it in (with the corrected cable) and text entry uses the physical keys, with Shift / Alt one-shot toggles and an alt-symbol layer matching the silkscreen. Without a keyboard the badge falls back to the on-screen joystick picker automatically.

Power

The badge is powered by a LiPo battery and charged over USB-C. An ON/OFF slide switch (top-left on the front) cuts battery power — sliding it off and back on is how you power-cycle the badge, since the battery otherwise keeps it running even with USB unplugged. Hold Execute while switching on to enter DFU mode for flashing.

1.1.8 - FAQ & troubleshooting

Quick answers to the things people most often hit with the Cyber Ægg. If none of these help, file a bug (see the bottom of the page).

General

The badge won’t wake / the display stays blank. Plug in USB-C. If the LED never blinks, hold Execute while plugging in and re-flash the firmware with dfu-util — see Getting started → Firmware update.

A fresh flash (or factory reset) shows the factory test, then a “ready to ship” screen — and hangs there. By design. After an all-pass self-test the badge stamps its pass flag, draws the ship screen and halts (green LED pulsing). Power-cycle once more; the second boot skips the test and starts the app.

“Battery voltage critical” screen at boot, the badge goes no further. The cell measured below 3.0 V at power-on, so the firmware halts to protect it. Charging is hardware-controlled and continues anyway — leave USB plugged in for a while, then power-cycle manually (the badge does not reboot itself off this screen).

The clock keeps resetting on every reboot. Expected — there is no battery-backed RTC. Pair over Bluetooth with the MeshCore app once per boot, or wait until you are near a synced mesh repeater. Note that on-air time is only accepted from a trusted source — a signature-verified repeater / companion advert or a channel you hold the key for. A crowd of other badges won’t set your clock; a phone pairing always will.

Bluetooth isn’t visible / I can’t pair. Check that Bluetooth wasn’t switched off in Main → Settings → Bluetooth — the toggle persists across reboots, so set it back to BLE: ON.

My alarm never fired. The clock hasn’t been set yet this boot — alarms only fire once the time is known. If the clock is set, check the alarm’s Days field — None never fires, and a Weekdays / Weekends / Custom mask only fires on matching days (the header bell shows for any enabled alarm regardless of its day mask).

No mesh peers show up. Walk around — LoRa range varies with terrain and antenna orientation. Also check your LoRa preset under Main → Settings → LoRa Radio; it must match the rest of the local mesh. See Mesh.

I reformatted the badge’s USB drive and everything is gone. Don’t reformat. The badge only understands its own FAT12 layout; if boot finds anything else (exFAT, NTFS, odd sector sizes) it silently re-formats the whole partition — wiping every file. To clear files, delete them normally instead. If it already happened: copy your .PCX / .ICS / .CFG files back on and reboot.

The charge bolt disappeared while USB is still plugged in. Charging is complete — the bolt returns by itself if the cell drains. Also, the battery icon can lag up to a minute behind reality; it is only re-sampled every 60 seconds.

The red LED keeps flashing, especially on the BornPet screen. The LED does a short one-shot flash every time the e-paper repaints. Most screens are static so this is rare — but the pet has a slow idle animation, so the badge repaints (and flashes) every few seconds even when the frames look almost identical. It’s not a fault and usually not an incoming message. Note the Ignore blink setting (under MeshCore) only mutes the flash for incoming mesh messages — it does not stop the per-repaint flash. To stop it, sit on a static screen.

Which screen makes the battery last longest? The e-paper costs almost nothing to hold an image — the power goes into repaints. So the thriftiest screens are the ones that never repaint on their own: My QR, Name, Tokens and Calendar sit idle until you press a button. Main and Watch repaint once a minute for the clock; BornPet repaints every few seconds for its animation (most power). To stretch a charge, park on My QR or Name — idle, no flashing, and My QR is the handy one to leave up so people can scan you into the mesh.

Display (e-paper)

Red only shows up sometimes — e.g. after switching screens. Working as designed. Staying on one screen uses fast black/white refreshes that don’t repaint the red plane; red repaints on a full refresh (a screen switch, or periodically). It isn’t disabled — it just refreshes less often than black/white.

The whole screen looks inverted (colours swapped) and stays that way. A full refresh briefly cycles the whole panel; if it gets cut short the image can latch inverted. Flip to another screen and back to force a clean redraw. Persistent inversion on the red-capable (“B”) panels was a firmware bug — make sure you are on current firmware.

No red at all / washed-out screen after adding a custom LUT. Your LUT.CFG is a fast waveform that skips red. Delete LUT.CFG from the badge’s USB drive, or hold Fire (joystick press) while booting to force the built-in tri-colour waveform for that boot. See Hardware → Display.

Blinking white LED / won’t finish booting after dropping a LUT.CFG. A bad or wrong-panel LUT.CFG is rejected automatically, but if the screen is unreadable, hold Fire while booting to force the safe built-in waveform, then delete or fix the file.

The badge boots fine but ignores my LUT.CFG. Rejection is silent. Common causes: wrong variant letter for your panel, the wrong key copied from the ssd1675-calibration tool (it wants the flat band_lut hex field, not stage_luts), or bad hex length (each LUT value must be exactly 214 hex characters). File size is not a limit — the file is streamed off flash, so a full 16-band export (~3.7 KB, comments and all) loads fine. Holding Fire at boot also forces the built-in waveform for that boot. Details in the firmware’s LUT.md.

Mesh / Bluetooth

The MeshCore app says “connected” but nothing works — can’t set the clock, no contacts, messages won’t send. Stale pairing. The phone forgot the bond (you removed it in Bluetooth settings, or switched phones) but the badge still has it, so every command is rejected as unauthenticated. Fix: Main → Settings → Bluetooth → Clear pairings (wipes all bonds and reboots the badge), then pair fresh. The badge keeps at most 4 bonds — pairing a fifth phone silently doesn’t stick.

The Channel screen shows “BLE client connected” and the buttons are dead. By design: while the phone app is connected the on-badge channel browser locks (only Left / Right / Cancel work). Close or disconnect the app and the screen unlocks immediately.

My PMs and the peers I’d heard are gone after a reboot. The PM inbox and the recently-heard list live in RAM only. Saved contacts persist — when you meet someone you want to message later, open their entry and save them before powering off.

NFC

My vanity URL / vCard doesn’t stick. Write it with an NFC-writer app as a normal URL/URI, vCard or Wi-Fi record — anything you write (except a token:) becomes your broadcast profile and persists across reboots. See NFC & tokens → Set your own broadcast data.

A token I received disappeared / a URL I tapped reverted. A token: write is intentionally transient — it lands on the Tokens screen (kept until reboot) and the broadcast reverts to your own profile after about 10 seconds. A pushed token can’t overwrite your profile.

A station tap did nothing — no toast, pet unaffected. Station commands only apply while you have an active game: pick a pet first (the egg countdown already counts), or start a new egg if your pet has left. Also: station commands come through the signed BadgeCtl reader — writing the phrase (e.g. more food) as a plain text record with a generic NFC app doesn’t feed your pet; it just becomes your broadcast profile, and your badge now proudly hands out “more food” to every phone that taps it. Write a new URL / vCard to fix that.

Game / BornPets

The pet area shows “No sprites on flash”. The boot scan found zero .PCX files — typical after a factory reset, a drive reformat, or a fresh flash without the asset set. Copy the sprite .PCX files back onto the CYBR<hex> drive and reboot.

A sprite I made shows wrong colours / doesn’t show at all. The badge needs a very specific PCX flavour: 2 bits-per-pixel, single plane, RLE, with the fixed palette order 0 = black, 1 = red, 2 = white, 3 = transparent (the file’s own palette is ignored). A normal 256-colour or 24-bit export is silently skipped. The Pet Maker and the firmware’s asset tool get all of this right. If you hand-edited a sprite in GIMP, re-pack it with the firmware’s scripts/fix_badge_pcx.py (or check it first with check_badge_pcx.py) — see Games → Hand-editing sprites.

BORNPETS.CFG / a mode change seems to have no effect. Both apply at boot only — eject the drive properly (so the file is flushed) and power-cycle. No * after the pet name = no override was applied. See Games.

Where to file bugs

Found something broken? Open an issue on the firmware repository:

https://codeberg.org/Ranzbak/bornhack-firmware-2026/issues

1.1.9 - Flash your badge

Flash firmware onto your badge straight from this page — no toolchain, no drivers, no command line. The browser talks to the badge over USB and writes the image itself, and it can install the badge’s asset files in the same sitting.

If something goes wrong

The device chooser is empty. The badge is not in DFU mode. Put it in the bootloader first (for the Cyber Ægg: slide the ON/OFF switch — top-left on the front of the badge — off, then back on while holding Execute, and the LED blinks red), then click Connect again. The battery keeps the badge running, so unplugging USB does not restart it.

It connects but says “application firmware (CDC)”. Same cause: you reached the running firmware rather than the bootloader. Power-cycle into DFU mode.

“Failed to open the device” on Linux. A udev rule is missing. The badge’s own repository ships one — install it, replug, and retry.

The flash stopped part-way. Nothing is bricked. The bootloader writes directly to the application partition, so an interrupted write just leaves the badge sitting in DFU mode. Reconnect and flash again.

Checksum mismatch. The download did not match the hash published alongside it and was refused before anything was written. Reload the page and retry; if it persists, report it.

The badge says “No sprites on flash”. The firmware is installed but the asset files are not. Do step 5 above, then power-cycle.

I flashed DOOM and nothing happens / it asks for game data. Flashing DOOM is only half of it. DOOM ignores the USB drive entirely: its game data goes into the badge’s QSPI flash over a serial connection, so you need to upload a WAD before there is anything to play.

Sprites are missing or wrong after switching edition. Each firmware image ships its own asset set, and the Community Edition draws a good deal more than the standard one. Install the assets that belong to the image you flashed — step 5 follows your choice in step 3 automatically.

No drive appears to copy assets onto. The badge only exposes its USB drive in DFU mode, the same mode you flash from. If you already power-cycled to boot the new firmware, go back into DFU mode.

The copy finished but the badge still looks empty. Eject the drive in your file manager before unplugging. Until you do, the writes may still be sitting in your operating system’s cache rather than on the badge.

Flashing without a browser

Every image offered here is a plain .bin for the application partition, so dfu-util takes it directly:

dfu-util -d 1915:521f -D cyber-aegg.bin

Adding a badge or a firmware image

The flasher is driven entirely by data/firmwares.toml in the website repository. Add the image under static/firmware/<badge-id>/, record it in that file together with its sha256sum, and it appears here — there is no backend to deploy.

Asset payloads work the same way. Build the archive with flat, deflate-compressed entries, drop it in static/assets/<badge-id>/, and point the badge’s assets entry at it:

cd assets/to-badge && zip -rX -9 cyber-aegg-assets.zip .

Two constraints worth knowing:

• Images must be hosted on this site. A cross-origin download needs CORS headers, and release assets on Codeberg and GitHub do not send them.
• Only application images. A combined image that includes the bootloader (for the Cyber Ægg, cyber-aegg-full.bin) starts at address 0x00000000 and is meant for SWD / J-Link recovery. DFU writes the application partition, so publishing a combined image here would brick badges.

1.1.10 - DOOM

Yes, it runs DOOM. E1M1 — Knee-Deep in the Dead — renders on the badge’s e-paper panel at a couple of frames per second, in four levels of grey, with the level’s music picked out on the piezo buzzer.

It is a slideshow, and it is genuinely playable.

How to install it

Getting DOOM running takes two steps, because the game data is far too big to sit on the badge’s little USB drive. The firmware goes into the badge’s program memory over USB; the game data goes into the separate 2 MB QSPI flash chip over a serial connection.

1. Flash the DOOM firmware on the Flash page, the same way as any other image, then power-cycle the badge.
2. Upload a WAD with the loader below.

Upload a WAD

Controls

If something goes wrong

The browser never shows a serial port. The badge only presents its serial console in WAD upload mode. Reset it while holding Cancel and try again.

“Timed out waiting for the badge to ask for data”. The badge is connected but not in upload mode, so nothing is asking for a transfer. Reset holding Cancel.

The upload fails part-way. Nothing is damaged — the badge simply has no usable WAD and drops back into upload mode. Reconnect and send it again.

DOOM boots but complains about missing game data. The firmware is installed and the WAD is not, which is exactly what you get after a fresh flash. Upload it above.

Firefox or Safari show no Connect button. Neither ships Web Serial. Use a Chromium-family browser, or send the blob from a terminal with a YMODEM tool:

sb --ymodem-1k e1m1.blob < /dev/ttyACM0 > /dev/ttyACM0

About the game data

Only one level fits: the blob offered above is about 1.8 MiB, roughly 92% of the badge’s QSPI flash. It is built from the freely distributable shareware doom1.wad, trimmed and compressed by the asset pipeline in the cyberaegg-doom repository. DOOM and its game data remain the property of id Software.

To build your own from a copy of doom1.wad you already have:

bash tools/build_assets.sh    # doom1.wad -> build/e1m1.blob

Then pick that file in the loader instead of the prepared one.

Source

The port lives at rarenerd/cyberaegg-doom. It is a fork of next-hack/nRF52840Doom (of prBoom and GBADoom lineage), re-fitted to the badge’s e-paper display, buttons and power budget. The DOOM engine is licensed under the GPL.

1.1.11 - CircuitPython

There is a CircuitPython build for the Cyber Ægg, which turns the badge into something you program in Python with no toolchain at all. Flash it once and the badge mounts as a CIRCUITPY drive: drop a code.py on it, and it runs the moment you save.

The display, buttons, joystick, LEDs, buzzer, battery, LoRa radio and NFC are all reachable from ordinary CircuitPython modules.

Install it

1. Flash the CircuitPython image from the Flash page, then reset the badge with no button held.
2. The badge appears as a CIRCUITPY drive, plus a serial console for the REPL (/dev/ttyACM0 on Linux, a usbmodem device on macOS, a COM port on Windows).
3. Copy the library and an example onto the drive, as below.

Install the libraries

None of the examples run without the support libraries — importing cyberaegg_epd or the LoRa driver fails until they are in CIRCUITPY/lib. Put them there first:

Your first program

With the libraries installed, save this as CIRCUITPY/code.py:

import cyberaegg_epd

display = cyberaegg_epd.get_display()

get_display() returns a standard displayio.EPaperDisplay. Build a displayio group as usual, assign it to display.root_group and refresh.

The example epd_hello.py draws a bordered white field with a black and a red square; hwtest.py walks through the LED, buzzer, charger, battery, I²C and all the buttons.

→ Browse all the examples · the libraries

Copy any of them into the console below with Paste, or save one as code.py on the drive.

For text, the firmware includes terminalio and fontio, so adafruit_display_text can draw labels — it is bundled in the repository’s lib/.

The serial console

CircuitPython prints print() output and tracebacks to a USB serial console, and offers a REPL there. That console is where you find out why a program did not run — errors never appear on the display.

You can open it right here, without installing a terminal program:

Ctrl-C interrupts whatever is running and gives you the >>> prompt, where you can poke at the hardware a line at a time. Ctrl-D restarts code.py from the top, which is the quickest way to re-run after an edit.

The console is only available while CircuitPython is installed — it is the firmware that provides it, not the bootloader.

Working with the e-paper display

E-paper is the one part that does not behave like a normal screen, and most first-time surprises come from it.

The badge shows whatever was drawn last. E-ink holds its image with no power, and creating an EPaperDisplay does not touch the glass. To start from a clean panel:

import cyberaegg_epd

cyberaegg_epd.clear()          # white panel, one full refresh

If your program clears the screen and then exits rather than staying running, call displayio.release_displays() afterwards — otherwise CircuitPython draws its own boot logo over your freshly cleared panel.

Refreshes are slow and finite. A tri-colour full refresh takes around twenty seconds, and every refresh wears the panel a little. So:

• Prefer one refresh per boot, showing your final image with the white background baked into the same frame, over clearing and then drawing as two separate refreshes.
• Do not refresh more often than roughly every 180 seconds.
• Use full refreshes only — this panel does not do partial updates.
• If the badge will sit unused for a long time, leave it cleared to white to avoid image retention.

Refreshing does not block. display.refresh() returns straight away while the panel keeps updating for about six seconds. Read display.busy if you need to wait, or call cyberaegg_epd.refresh(display), which waits out the panel’s minimum interval first and blocks until the refresh finishes.

LoRa

The SX1262 radio has a driver in the repository’s lib/, configured for MeshCore-compatible EU settings: 869.618 MHz, SF8, 62.5 kHz bandwidth, coding rate 4/5, sync word 0x1424, no TCXO.

The driver and the SX126x files it needs are part of the library set installed above, so there is nothing more to copy:

import cyberaegg_lora

radio = cyberaegg_lora.LoRa()
radio.send("hello")
data, err = radio.receive(timeout_ms=5000)

examples/lora_tx.py sends a counter and lora_rx.py receives, printing each packet’s size and signal strength. The receiver works both against a second badge running lora_tx.py and left listening to live MeshCore traffic. lora_dashboard.py shows live packet statistics on the e-paper display.

NFC

NFC is built into the firmware, so there is nothing to copy into lib/. The badge serves a read-only tag, so tapping a phone against it opens a URL. See examples/nfc_tag.py and the repository’s docs/NFC.md.

What is not included

Bluetooth. CircuitPython’s Bluetooth support needs Nordic’s S140 SoftDevice, which has to live at flash address 0x1000 — inside the region owned by the badge’s own bootloader. The DFU bootloader only writes the application area from 0x10000 upwards and cannot overwrite itself, so Bluetooth would mean reflashing the bootloader over SWD. This firmware does not do that.

That also means the MeshCore companion app cannot talk to the badge while CircuitPython is installed.

If something goes wrong

No CIRCUITPY drive appears. The badge is probably still in the bootloader or was rebooted by the flashing tool rather than reset. Reset it with no button held.

My code did not run. CircuitPython runs code.py from the root of the drive. Check the filename, and open the serial console — syntax errors and tracebacks are printed there, not on the display.

The display shows the CircuitPython logo over my drawing. Your program cleared the panel and then exited. Call displayio.release_displays() before finishing, or keep the program running.

The screen did not change. Refreshes are rate-limited: too soon after the last one and the request is ignored. Wait out the interval, or use cyberaegg_epd.refresh(display), which handles the waiting for you.

Source

The firmware, library and examples live at rarenerd/cyberaegg-circuitpython — go straight to the examples or the libraries. The image offered on the Flash page is that repository’s prebuilt binary, byte for byte — its checksum matches the SHA256SUMS published alongside it. Build instructions are in the repository’s docs/BUILDING.md.

1.2 - Konsool badge

Introduction

The device will be the portable computer you wish you had in the 80s. Complete with on-device programming environment, a high resolution 60Hz screen and a full QWERTY keyboard this device is all the computing power you will need on a hand held hackable device!

The connectivity of this device is unparalleled, since the SHA badge WIFI and Bluetooth connectivity have been the norm, this badge adds long range low speed connectivity (LoRa) allowing for long range mesh networking! Who doesn’t want to talk to chat with friends over a kilometer away, no infrastructure needed!

Did we mention the dual core 400MHz Risc-V ESP32-P4 CPU?

Tanmatsu or Konsool?

The open-source badge design is released under the CERN-OHL-P license. This applies to both Konsool and Tanmatsu, which are essentially the same device.

• Konsool is an open design, freely available for anyone to modify, extend, and use as they see fit.
• Tanmatsu is the pre-assembled version sold by Nicolai Electronics, eliminating the hassle of sourcing components and manufacturing the PCB.

Selling electronic devices involves additional requirements, such as safety and environmental certifications. Badge.Team appreciates that Nicolai Electronics takes on these responsibilities, offering the badge practically at cost.

By providing both an open design and ready-to-use devices, we aim to foster a thriving ecosystem, ensuring ongoing support and updates for the community.

The Konsool hardware

​The Konsool is powered by the ESP32-P4 which is a high-performance system-on-chip (SoC) from Espressif, featuring a dual-core RISC-V CPU running up to 400 MHz with AI instruction extensions. It integrates high-speed peripherals, including USB OTG 2.0 HS and Ethernet. The ESP32-P4 is tailored for applications requiring rich human-machine interfaces and power efficient computing. Making it (in our humble opinion) a good choice for a battery held device that humans interact with.

Additionally, an ESP32-C6 module provides WiFi, Bluetooth Low Energy, and IEEE802.15.4 wireless connectivity. This allows for internet access as well as compatibility with local mesh networks like Thread and ZigBee, ideal for developers and enthusiasts.

A LoRa radio module enables communication over LoRa networks, including long-range mesh services and classic (G)FSK modulation at either 433, 868 or 915MHz, depending on the module installed.

The device includes 16MB of built-in flash storage for firmware and applications, expandable via a micro SD card slot. This slot supports SD cards at both standard and high-speed (SDIO 3.0).

User interaction is provided through a QWERTY keyboard and a MIPI DSI display.

The expansion port enhance Konsool’s versatility by supporting expansion an board on the back of the the device. Exposing SPI, I2C, USB (2.0) and GPIO to the expansion board provides ample connectivity options for expansion board designs.

The side-facing CATT port provides connectivity to a JTAG debugger, and various PMOD and SAO-compatible accessories.

A QWIIC compatible connector allows the device to interface with numerous sensors from manufacturers like Sparkfun and Adafruit.

The ESP32-P4 also includes hardware-accelerated encoding of h264 video through its MIPI DSI and CSI interfaces. This powerful CPU can record video from devices such as a Raspberry Pi camera, encode it, and stream it wirelessly over WiFi.

Custom front panels are feasible using the provided information, and 3D printable case designs are also available for those interested in additional customization. (A Case design in FreeCAD format coming soon)

The team

The Konsool would not have been possible without the help of our amazing volunteers.

1.2.1 - Konsool quick start

Quick start

Peripherals

Navigation

Powering on the badge

Keep the power button pressed for ~2 seconds, until the power button turns red.

Powering off is done in the same manner.

Moving around in the launcher

• Navigation is done using the arrow keys to navigate the menus.
• An item can be activated by pressing the ’enter’ key.

Returning back to the launcher

Exiting an application back to the launcher should be done using: the red ‘X’ function button, which is located next to the escape.

When a program is started, basically a new firmware image is loaded into the ESP32-P4 so this will not work for all applications. Applications that behave well should support this though, and should return to the launcher.

Charging the badge

The badge is charged via the USB-C connector at the top left of the device. Note that the badge only charges the battery when turned on.

Since no handshake is done the amount of power a device is allowed to pull from the USB port is 0.5A, this means the battery at this time won’t charge quickly.

1.2.2 - Compatibility

1.2.2.1 - Camera

Software

Konsool applications can use the esp_cam_sensor driver to read frames from a MIPI CSI camera module.

The camera connector on Konsool has the same pinout as the 22 pin MIPI CSI connector found on the Raspberry Pi Zero and Raspberry Pi 5.

Supported sensors

1.2.3 - Konsool FAQ

Questions and Answers

1.2.4 - konsool hardware

1.2.4.1 - Konsool specifications

1.2.4.1.1 - Konsool battery

Battery

Specifications

1.2.4.1.2 - Konsool ESP-C6

Specifications

Datasheet

For detailed specifications please look at the datasheet

1.2.4.1.3 - Konsool ESP-P4

#Specifications

For more details please look at the datasheet

1.2.4.1.4 - Konsool keyboard

#Specifications

QWERTY dome keyboard by Arturo

1.2.4.1.5 - Konsool screen

1.2.4.2 - Camera

Camera Compatibility List

Not compatible

The new IMX519 based camera modules from Raspberry Pi are currently not supported. For a list of supported sensors see supported sensors.

1.2.4.3 - Konsool connectors

Diagram

1.2.4.4 - Konsool pinouts

In this section you can find the pinout of the chips and connectors of the device.

1.2.4.4.1 - Konsool connectors

1.2.4.4.1.1 - CATT pinout

Description

The CATT connector combines several different connectors in one.

• Special Addon (SAO)
• JTAG
• PMOD

Because of this multi functional nature, the name for the connector is CATT (Connect all the things), even though there are more kind of things to connect.

SAO

• *DET: Detect, when pulled down during power up, JTAG functionality is provided
• *3V3: Not connected by default, jumper on the PCB needs to be closed to supply 3V3

Schematic

1.2.4.4.1.2 - QWIIC pinout

Description

The QWIIC connector combines I2C and I3C in one connector. Information about this connector and all of it’s versatile uses can be found on https://www.sparkfun.com/qwiic

For this connector sparkfun advices to use the standard cable so all modules you connect to this connector will work without any issues.

1.2.4.4.1.3 - Internal expansion port

Back Expansion layout

Back expansion port

This port is not exposed by default, and a modified back cover needs to be used to make it accessible. For this reason the port is also named the “internal expansion port”.

Limitations & warnings

• Total for all 3.3v outputs must not exceed 1A of current. It is generally adviced to stay well below this figure.
• Do not exceed a current of 1.5A from the battery when the battery is connected to the internal battery connector
• Do not charge the battery via the internal add-on port

1.2.4.4.2 - IC pinouts

IC pinout mapping to functions on the board.

1.2.4.4.2.1 - CH32V203 pinout

CH32V203

1.2.4.4.2.2 - ESP32C6 pinout

Schematic

ESP32 Pin table

1.2.4.4.2.3 - ESP32-P4 pinout

ESP32-P4 (U8)

LDO

GPIO

1.2.4.5 - Frontpanel

This page describes how to design and order a Konsool badge frontpanel.

Designing a frontpanel using Inkscape, svg2shenzhen and KiCad

The first step of designing a frontpanel is creating artwork that can be converted into a KiCad footprint. For this Inkscape and the Inkscape plugin svg2shenzhen are used.

Of course it is also possible to use any other method which allows you to import a footprint into KiCad so if you’re using a different method then you can skip ahead to the KiCad section.

Instructions on how to install svg2shenzhen can be found in the readme of the repository.

After opening the design file in Inkscape you will notice that multiple layers are used. Each of the layers in the design corresponds with a KiCad layer, this allows you to define how a shape should appear on the circuit board.

The most important layers are:

• Edge.Cuts: this is the outline of the board, the PCB manufacturer will use a CNC mill to cut the board following the edges of the object on this layer.
• F.Cu and B.Cu: these layers define where to place copper on the front and back of the circuit board.
• F.Mask and B.Mask: all shapes drawn on this layer are cut out of the colored soldermask layer of the board.
• F.SilkS and B.SilkS: these layers are printed on the front and back silkscreen layer respectively. The silkscreen layer is a non-conductive layer of ink usually used to add reference designators and text to a circuit board.

Export the design to KiCad by navigating to Extensions > Svg2Shenzhen > 2. Export to Kicad...

KiCad

…

1.2.4.5.1 - Konsool artwork

1.2.5 - Konsool software

(work in progress, please check this page again later)

1.2.5.1 - Konsool apps

1.2.5.1.1 - Konsool local apps

1.2.5.1.2 - Software Hub for Konsool

#Uploading, Downloading, Creating, Contributing

1.2.5.1.2.1 - Creating apps

1.2.5.1.2.2 - Downloading Apps

1.2.5.1.2.3 - Uploading apps

1.2.5.2 - Konsool settings

1.2.5.2.1 - Konsool LoRa

#Meshtastic (work in progress, please check this page again later)

1.2.5.2.2 - Konsool Software Hub settings

(work in progress, please check this page again later)

1.2.5.2.3 - Konsool wifi

(work in progress, please check this page again later)

1.2.5.3 - Konsool updating

(work in progress, please check this page again later)

1.2.5.3.1 - Konsool apps

(work in progress, please check this page again later)

1.2.5.3.2 - Konsool firmware

(work in progress, please check this page again later)

1.2.6 - Konsool expansion boards

1.2.6.1 - 18650 extension

18650 Extension

Introduction

Simple extension that attaches to the extension port at the back, and contains 2 18650 cells. This extends the battery time for the Konsool / Tanmatsu badge with several hours.

The extension features protection IC’s for both cells individually, to minimize risks related to the lithium batteries.

Features

• Protection IC per 18650 CELL
• On/Off switch
• Charges off the USB-C power from the Konsool/Tanmatsu
• M2 mounting holes to fasten the battery holder securely

Project

The project can be found here on Github.

Maturity

A prototype run has been done, and the hardware has been tested on a Tanmatsu V4 prototype (See pictures below).

Real life pictures

1.2.6.2 - Zero expansion boards

Zero expansion board

Introduction

The Konsool has al lot of capabilities already in a pretty handy form factor. To take advantage of the keyboard, powerful CPU to for example play with technologies like NFC, RFID and sub GHz radio extra circuitry is required. Even though this idea is not my own (thanks Renze) I do feel motivated to make this board given my interest in lock picking sports.

Disclaimer

It is important that this device is used for educational purposes only, the only locks that should be opened are either your own or with express permission of the owner of said lock.

The goal of this device is to improve security and educate, not do enable illegal activities.

I the designer do not take any responsibility for the how this device is used, if you manage to get into trouble using this device the responsibility is your own.

Planned Features

• 100 - 150 kHz RFID tag reading and writing
• Sub GHz radio capabilities using CC1101
• RFID receiver (The Konsool board has the transmitter LED on the PCB)
• IButton

Project

Main project

• PCB project: konsool-zero
• Software is not yet started

Intermediate

• RFID test board project: 125kHz-zero-proto

Most circuitry on the expansion is based on the Flipper zero schematics, as they are published on their website.

For the RFID circuitry this was not enough for me to understand the OpAMP circuits, here the creating RFID reader from scratch helped understanding the design.

Maturity

As for 2025-03-22:

This project in it’s early stages of development where major milestones still need to be reached.

Milestones:

• Create RFID prototype board
  • Troubleshoot RFID analog circuit make stable
  • Create proof of concept to read RFID tag
  • Create proof of concept to write RFID tag
• Choose type of microcontroller (STM32 / CH32)
• Choose antenna type PCB coil vs wire coil
• Integrate RFID prototype into expansion
• Create sub 1GHz radio module prototype board
  • Troubleshoot design to get a stable circuit
  • Create a proof of concept sending data
  • Create a proof of concept receiving data
• Create Konsool prototype board for development (Some work done)
• Create firmware for the MCU on the extension board
• Create software on the Konsool

At the moment of writing work needs to be done stabilizing the RFID analog circuitry.

• The RC circuit introduces DC offset, that prevents the carrier circuit from working correctly
• The Oscillator circuit is unstable an has a low frequency wobble
• The output does show a consistent bit stream when a RFID card is presented to the coil.

Findings:

• The schematic circuitry uses envelope detector circuits to decode the RFID signal.
• The idea of prototyping on a breadboard is not going to work as the cross talk of signals on a breadboard is too big which drowns out the RFID signals.

Contributors

Work in progress pictures

1.3 - Hackerhotel 2024

The Telegraph badge made for the event Hackerhotel 2024 is an interactive badge with puzzles themed telegraphs and the Victorian historical setting they were developed in. It is inspired from the Cooke and Wheatstone telegraph for the rather unusual input system.

Hardware

• ESP32-C6 microcontroller module with WiFi 6, BLE and 802.15.4 mesh networking
• Epaper screen with 296 x 128 resolution and both red and black ink
• Five three way switches for control
• LED matrix for telegraph style keyboard interface
• SAO connector
• QWIIC connector
• Addressable LED used as status indicator

Handbook

First steps

First turn the badge by sliding the switch down on the left hand side or plugging in a cable in the USB C port (this also recharges the battery).

⚠️ The display is e-paper and its behavior can be confusing under some conditions:

• The screen state does not change when turned off, so it will show its current screen until it is powered up again.
• When sliding the switch down to turn the device on (while unplugged) the top right corner LED should flash. If it does not then the battery is discharged and the screen will remained unchanged.
• The screen will sometimes cycle the ink before displaying the image, this can be changed for most menus in the “engine room”.

Using the input system

The inputs consist of 5 switches located at the bottom of the badge, each having 3 actions: rotate left, rotate right and press in. The effect of those actions is often described by the boxes at the bottom of the screen.

If you enter the typing mode, the device then functions as a Cooke & Wheatstone telegraph: Each switch represent one of the needles, and the led line shows the needle orientation. when 2 needles point towards the same letter, it is registered.

Navigating the apps

All the different applications and games are accessible via the map menu, rotate the left switch to change “location” (aka apps) on the map, and select by pressing in the right switch in:

Hardware sponsors

• ALLNET China was our production partner, for which we are more than grateful. They took care of sourcing most components and oversaw the production process in China, saving us a lot of work and potential headaches and allowing us to focus on the product!
• Espressif was very generous to donate us all of the ESP32-C6 modules we needed. The ESP32 series of WiFi capable microcontrollers has proven itself to be a solid basis for badges in the past. Espressifs continued support means a lot to us as it allows us to continue expanding our existing ESP32-based ecosystem!

Resources

• Repository of hardware design files
• Repository of ESP32-C6 firmware
• Repository of CH32V003 firmware
• Repository of SAO designs
• 3D printable case

The team

The HackerHotel 2024 badge would not have been possible without the help of the following amazing volunteers:

• Nikolett
• Guru-san
• Renze
• Tom Clement
• CH23
• Norbert
• Zac
• SqyD
• Martijn
• Julian
• Dimitri
• Yvo

Reporting bugs

If you find any bug, help us by filling in an issue.

Ready, set, hack!

Hack your badge and build cool applications on the ESP32-C6! Here are some basic instructions to get you started:

Main firmware/ESP32-C6

Follow the instructions on the ESP32-C6, we recommand VScode as an IDE.

CH32V003 co-processor

Follow the instructions on the CH32V003 repo, the J5 contains all the pins necessary to connect to a WCH link.

Add and display an image

First the convert your image (input.png) by running convert using the mascot.png in the ressource folder as a reference, example:

convert input.png -map mascot.png output.png

Then open main/CMakeLists.txt and add your new file:

EMBED_FILES ${project_dir}/resources/output.png

Add in your file:

extern const uint8_t output_png_start[] asm("_binary_output_png_start");
extern const uint8_t output_png_end[] asm("_binary_output_png_end");

And use pax_insert_png_buf in your code to add the image to the screen buffer:

pax_insert_png_buf(&gfx, output_png_start, output_png_end - output_png_start, 0, 0, 0);

Updating the badge firmware

OTA update over WiFi

Use the left most switch to enter the Map by pushing the first switch (from the left) Push the left most switch to the right, until you see Engine Room appear in the display Push the fifth button to select the engine room Select the OTA menu using the fourth button The badge will try and connect to wifi and update if an update is available

OTA Dev update over WiFi

Use the left most switch to enter the Map by pushing the first switch (from the left) Push the left most switch to the right, until you see Engine Room appear in the display Push the fifth button to select the engine room Select the OTA menu using the fifth button The badge will try and connect to wifi and update if an update is available

1.3.1 - Hackerhotel 2024 photos

The badge:

During the event a dot-matrix printer was busy printing all of the messages sent via the billboard messaging system.

Preparation for the event happened at Bitlair, where we flashed and tested all of the badges:

1.3.2 - Software Development

Introduction …

The Badge is basically an ESP32C6 development platform and features the following methods for developing software:

• Stock firmware build-IDF : native EPS apps using the IDF (IoT Development Framework)
• ESP-IDF with Platformio : Use the HH2024 badge as a generic dev board.
• EspHome: The easy way to program devices for Home-Assistant.

The badge also has a coprossor for extra IO.

See more information below.

Linux permissions

Regardless of the way you’re going to program the badge, to connect to the badge over USB from Linux, do the following.

Create /etc/udev/rules.d/99-mch2022.rules with the following contents:

SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0f9a", MODE="0666"

Then run the following commands to apply the new rule:

sudo udevadm control --reload-rules
sudo udevadm trigger

Windows installation

Not tested.

Software Platforms

Badge Team default firmware

You can find the official firmware here: https://github.com/badgeteam/hackerhotel-2024-firmware-esp32c6 You can build and upload the original firmware by cloning the archive and using the following commands:

make prepare
make build
make install

If you want to make some modifications check out this page on modifying the standard firmware. To try as a first hack.

ESP-IDF with Platformio

Jhaand ported the Hello World application for ESP-IDF to Platformio and made it easy to put your own program on the HH2024 badge with ESP-IDF.

https://gitlab.com/jhaand/hh2024_hello_platformio

This will only put some information on the UART /dev/ttyACM0 at 115200 and restart.

ESPHome

SqyD started integrating the HH2024 badge into ESPhome. Which makes things easy to integrate with Home-Assistant domotics.

You can find the yaml file for the HH2024 badge here:
https://gist.github.com/SqyD/d33b034c42dbc277ebb928ae45663476

It displays a Hello Badge Team! on the display.

More information on install EspHome you can find here:
https://esphome.io/guides/getting_started_command_line

CH32V003 co-processor

Follow the instructions on the CH32V003 repo, the J5 contains all the pins necessary to connect to a WCH link.

1.3.2.1 - Modify Standard Firmware

Ready, set, hack!

Hack your badge and build cool applications on the ESP32-C6! Here are some basic instructions to get you started:

Main firmware/ESP32-C6

Follow the instructions on the ESP32-C6, we recommand VScode as an IDE.

CH32V003 co-processor

Follow the instructions on the CH32V003 repo, the J5 contains all the pins necessary to connect to a WCH link.

Add and display an image

First the convert your image (input.png) by running convert using the mascot.png in the ressource folder as a reference, example:

convert input.png -map mascot.png output.png

Then open main/CMakeLists.txt and add your new file:

EMBED_FILES ${project_dir}/resources/output.png

Add in your file:

extern const uint8_t output_png_start[] asm("_binary_output_png_start");
extern const uint8_t output_png_end[] asm("_binary_output_png_end");

And use pax_insert_png_buf in your code to add the image to the screen buffer:

pax_insert_png_buf(&gfx, output_png_start, output_png_end - output_png_start, 0, 0, 0);

1.4 - Hackerhotel 2023

The team

• Pim: Team lead, hardware and software development
• Sake: Challenges
• Nikolett S.: Artwork

1.5 - MCH2022 badge

The MCH2022 badge is our most advanced badge yet. Shaped like a game console this badge is a powerhouse filled with cool technology.

Once assembled, you can use the badge to display your name, write Python code and maybe play a game or find an Easter Egg, but don’t forget: the real fun starts when you hack it to make it your own!

Getting Started

We’ve assembled some resources to quickly get started.

Getting Help (and helping …)

Reread the instructions if something isn’t working. Then go to our Troubleshooting Guide

Check out these resources if you run into trouble.

Case and frontpanel

You can find a 3D printable case and a lasercuttable frontpanel in this GIT repository.

The Hardware

The badge contains an Espressif ESP32 Wrover-e WiFi module with 16MB of flash storage and 8MB of PSRAM, an Raspberry Pi RP2040 microcontroller chip for advanced USB communication and board management and a Lattice ICE40UP5K FPGA for hardware accelerated graphics.

It also contains a bunch of stuff (TODO elaborate “stuff”).

The hardware is described in more detail in the hardware section.

The Software

The ESP32 loads an application chooser menu when you first power it on. Once loaded, you can launch a number of preinstalled applications:

• the Name-Tag app
• a Micropython scripting environment
• a sensor playground for the Bosch sensors
• The Hatchery where you can load more apps!

and the app contains a link to the Hatchery an app store you can use to load more apps. And more importantly, where you can publish app you write yourself.

The software is still in active development, more information will be published here soon.

Hardware sponsors

• ALLNET China was our production partner, for which we are more than grateful. They took care of sourcing most components and oversaw the production process in China, saving us a lot of work and potential headaches and allowing us to focus on the product!
• Espressif was very generous to donate us all of the ESP32-WROVER-E modules we needed. The ESP32 has proven itself to be a solid basis for badges in the past, and for related projects such as the PocketSprite. Espressifs continued support means a lot to us as it allows us to continue expanding our existing ESP32-based ecosystem!
• Lattice Semiconductor provided us with 4000 pieces of their awesome ICE40UP5K low-power FPGA. With this donation, they enabled us to explore and provide a new dimension of hardware capabilities and user-created applications. We shipped the first FPGA-equipped event badge in the world. Thanks Lattice!
• Bosch Sensortec let us put two of their advanced sensors on the badge: the BNO055 9-axis Absolute Orientation Sensor, and their new BME680 Air-Quality (And More) Sensor. These sensors enable a range of uses for the badge off-the-shelf, allowing developers to develop more engaging games and expanding the range of potential uses for the badge after the event.
• The Raspberry Pi Foundation helped us out with a discount when another chip which we tried to source became unavailable. On the badge, the RP2040 enables a wide range of USB capabilities, allowing us to work on bridging the gap between embedded development and everyday computing.

All of our sponsors helped us out in a time when sourcing capable chips was a near-impossible task. Without them, this project would not have been possible. We are grateful to all of them for their help and sponsorship, and we hope to work with them again in future badge projects!

The team

The MCH2022 badge would not have been possible without the help of these amazing volunteers.

Teamlead

• Reinier van der Leer

Hardware

• Renze Nicolai: Circuit diagram and PCB routing
• Nikolett S.: Artwork

With the help of Anne Jan Brouwer, Kliment Yanev, Kuristian, Martin Ling, Paul Honig, Sylvain Munaut, Tom Clement, Fuchsia (f0x) and Sander de Haan.

Launcher firmware

• Renze Nicolai
• Julian Scheffers (Robotman2412)
• Sylvain “tnt” Munaut
• Frans Faase
• Joris W. (jorisplusplus)
• Reinier van der Leer (Pwuts)
• Jeroen Domburg (spritetm)
• Arnold (Alt4arnold)
• Pepijn de Vos
• Andrejs Bondarevs (abondarevs)

FPGA examples and tools

• Sylvain “tnt” Munaut
• Matthias Koch Mecrisp
• Frans Faase
• Carlos Venegas @cavearr
• Sylvain Lefebvre @sylefeb

BadgePython

• Joris W. (jorisplusplus)
• Renze Nicolai
• Tom Clement
• Sylvain “tnt” Munaut
• Jorai Rijsdijk (Erackron)
• Pepijn de Vos
• Julian Scheffers (Robotman2412)

RP2040 co-processor firmware

• Renze Nicolai
• Sylvain “tnt” Munaut
• Reinier van der Leer (Pwuts)
• Jana Marie Hemsing

Documentation

• Tim Becker (a2800276)
• Matthias Koch (Mecrisp)
• Pepijn de Vos
• Julian Scheffers (Robotman2412)
• Sylvain “tnt” Munaut
• TheRealProcyon
• Pieter Vander Vennet
• Jenny List
• Oskar Roesler (bionade24)
• Dominik (dloidolt)
• Manuel Dipolt (xeniter)
• p2mate
• Sietse Ringers
• Yvo de Haas
• Marble (cyber-murmel)

1.5.1 - MCH2022 Badge Hardware

Block diagram

The badge contains a huge amount of awesome chips, so many that a block diagram is necessary to explain how everything is interconnected.

The ESP32 is at the center of the operation. It has access to almost all the peripherals on the badge and using its WiFi connectivity it can load new firmware and applications from the internet.

The RP2040 microcontroller provides USB connectivity consisting of two serial ports (for the ESP32 and the FPGA), WebUSB for managing the badge using your browser and HID for acting like a keyboard, mouse or joystick. It also drives the SK6812-EC15 addressable LEDs, giving the badge a lot of bling and eyecandy. To top it off a lot of the I/O pins of the RP2040 have been broken out, both as the IO pins of the SAO connector and as testpads next to the prototyping areas on the back of the badge.

The ICE40UP5K FPGA is programmed over an SPI connection by the ESP32. Using this connection the FPGA can also communicate with the application running on the ESP32. Our goal is to enable people to learn about HDL programming so new bitstreams can easily be loaded into the FPGA by user applications, to provide any function you want ranging from a simple LED blinker to a RISC-V SoC. To accomodate more advanced designs the FPGA is connected to the LCD display via a parallel bus, enabling it to update the display at high refresh rates, as well as 8MB of PSRAM via a Quad-SPI bus. 8 of the I/O pins of the FPGA have been broken out as an industry standard PMOD header, allowing users to connect standard expansion modules or their own creations.

Resources

• Check here for pinout tables describing how all the wonderful toyes are connected to each other.
• The board schematics download or view online at github

Datasheets and Resources

• ESP32 datasheet the datasheet for the main processor
• ESP32 technical reference technical reference for the main processor. This contains information about the features of the chip, so technically, it belongs in the firmware section, but … whatever.
• WROVER datasheet datasheet of the module. The processor is packed together with peripherals necessary for operations in a module (WROVER) nuder a metallic can.
• RP2040 documentation site and datasheet
• Lattice ICE40UP5K - iCE40UltraPlus documentation site and datasheet
• BME680 4 in 1 gas sensor. (temperature, humidity, air pressure and volatile organic compounds (VOC)
• BNO055 accelerometer, gyroscope, magnetometer sensor
• Display also have a look here
• SK6812-EC15 addressable RGB - LEDs (aka Neopixel)
• MS4344 Audio DAC

1.5.1.1 - MCH2022 badge pinouts

Connectors

SAO (Shitty AddOn)

Addon connector following the SHITTY ADD-ON V1.69BIS standard.

PMOD (peripheral module interface)

The PMOD connector is wired up to the iCE40 FPGA. Note that while the connector is physically located on the backside of the badge, it has been wired up such that the PMOD’s top side must be pointed in the same direction as the badge’s top.

Chips

ESP32

RP2040

¹: Set to input normally and force low to activate

ICE40 FPGA

1.5.1.2 - Battery

The MCH2022 badge uses the JST S2B-ZR-SM4A-TF connector for the battery. This connector has two pins at 1.5mm pitch.

Pinout

Photos

1.5.1.3 - MCH2022 Badge Hardware Hacking

The badge is made for hacking, and the hardware is no exception. There are several intended ways to extend the badge, next to unlimited unintented ones.

If you have access to a 3D printer, an easy and worthwile hardware mod is to print a knob for the joystick, such as this one or a case.

Shitty Add-on

The badge has a SAO header, which can provide power, I2C, and 2 GPIOs to small accessories that can be plugged in.

Qwiic

At the back of the badge there is a Qwiic connector hooked up to the ESP32 that is compatible with a large family of modules from Sparkfun, Adafruit and others.

PMOD

On the side of the badge there is a PMOD connector hooked up to the FPGA that is compatible with a large family of modules from Digilent and others.

May Contain Hardware Area

On the back of the badge there is a prototyping area with a grid of pads, as well as pads the expose I2C, power, and GPIOs.

Across the rest of the PCB are labeled pads that expose things like the LED serial data, audio signal, IR signal, various debug pads, and more.

1.5.2 - Getting Help (and helping)

You’re on the main documentation site for The Badge.

We hope that we’ll be able to centralize all documentation efforts here, but who knows what happens at camps.

We would be very happy to accept pull request (TODO link to how to make a good PR) if you find the documentation lacking and feel you are able to make improvements. The documentation project lives in this github repository

If you feel your Badge is broken, go HERE first!

Random Resources for Getting Help

• During the MCH2022 Event, please visit us at the Badge Tent in case you have any questions!
• Mastodon Badge.team
• MCH2022 Wiki Badge Page

Overview of the main github Repos you can contribute to …

You can find the sources and hardware files for all Badge artefacts files under the Badge.team organization:

• mch2022-badge-hardware The KiCad design files, look here for schematics, etc.
• mch2022-firmware-esp32 The main launcher firmware.
• Hatchery
• mch2022-firmware-rp2040 The loader firmware running on the RP2040 used to enable USB connectivity.
• badgePython The Micropython application you can use to write badge scripts.
• mch2022-firmware-ice40 code for the built in FPGA

Non-Specific Resources

(TODO)

• ESP32.com
• reddit/r/esp32
• rp2040 (todo)
• micropython
• lattice
• yosys fpga getting started general

1.5.2.1 - Troubleshooting & FAQ

This page is intended to collect answers to questions that pop up frequently and solutions to common problems…

MicroPython crashes every time I connect to it …

Apparently I’m disturbing the Guru’s Meditation

In case you are trying some Python samples and the firmware crashes … like this:

Guru Meditation Error: Core  0 panic'ed (Interrupt wdt timeout on CPU0).

Core  0 register dump:
PC      : 0x40084b56  PS      : 0x00050035  A0      : 0x400d7fde  A1      : 0x3ffbe990
A2      : 0x00040040  A3      : 0x3ffb27e0  A4      : 0xc0000000  A5      : 0x3ffbe970
A6      : 0x3ff40000  A7      : 0x3ffbf074  A8      : 0x800d7fde  A9      : 0x40090908
A10     : 0x00000000  A11     : 0xa6000000  A12     : 0x00000000  A13     : 0x00000473
A14     : 0x3f403a98  A15     : 0xffffffff  SAR     : 0x0000001f  EXCCAUSE: 0x00000005
EXCVADDR: 0x00000000  LBEG    : 0x4000c2e0  LEND    : 0x4000c2f6  LCOUNT  : 0xffffffff
Core  0 was running in ISR context:
EPC1    : 0x400d3f03  EPC2    : 0x400d7fde  EPC3    : 0x00000000  EPC4    : 0x00000000


Backtrace:0x40084b53:0x3ffbe9900x400d7fdb:0x3ffb27e0 0x401d505f:0x3ffb2800

We are working on it:

• make sure you’ve updated your BadgePython to the newest version. Use the AppUpdate menu item…
• try deleting Python from the Apps menu and reinstalling it from The Hatchery (Hatchery->ESP32->Utilities)

If none of this helps, here’s an easy work around … Connect to the serial console before you start Python. While you’re still in the launcher, connect, you will see some of the logging of the launcher application, when you start Python, you will see the boot messages. If the serial console is already attached when Python starts, it doesn’t crash. WTF!? ¯\_ (ツ)_/¯

I keep getting 419 errors in the Hatchery!

If you can’t log in to the Hatchery (or create an account) or whatever because you are getting 419 Expired errors, you need to either clear all cookies for the Hatchery, use incognito mode to connect or try a different browser. Please also report your experience, inlcuding time of occurance in the issue concerning this behavior to help figure this out.

My SD-Card is not being recognized

Try formatting the card as FAT32. Unfortunately exFAT is currently not supported.

The wifi doesn’t work!

Your battery is probably too close to the ESP32 “tin can”. Try moving it over :) The black strip on top of the can is the wifi antenna, you need to make sure that bit is not covered by anything.

The kite in the front is flashing RED!? Am I in danger!?

You’re probably fine. But be sure to drink plenty of water. But you will need to:

• Download the the RP2040 coprocessor firmware U2F
• Turn the Badge off ( with the switch labeled ON-OFF)
• Hold the SELECT button while turning the switch back to ON
• Make sure a USB cable is connected to your computer
• The Badge will mount as a mass storage device (MSD, a.k.a USB thumbdrive)
• Drag-n-drop (or whatever it is you Linux-from-Scratch folks do …) the U2F firmware onto the drive

This sounds way more complicated than it is, you’ll figure it out. In case you don’t that means we msessed up something else as well, please bring your Badge to the Badge tent so we can have a look to see what went wrong.

The badge doesn’t connect to the computer

If you have followed the instructions concerning udev rules, you may have a bad USB cable. Or a charging only cable. Did you make sure to connect one end of the cable into the computer and the other into The Badge? Try running lsusb, it should contain an entry like the one below:

$ lsusb
...
Bus 002 Device 025: ID 16d0:0f9a MCS MCH2022 badge
...

If instead, you see a line like this:

Bus 002 Device 027: ID 2e8a:0003 Raspberry Pi RP2 Boot

You may be having some issues with the Bootloader, have a look here for some hints.

Try running lsusb without a badge and see if you get different messages when a Badge is connected.

If this is not the case, try out a friend’s cable.

Button presses are glitching/bouncing‽

Your badge is probably not broken. Try updating the OS first. Choose “OS Update” in the main menu.

OMGWTFBBQ “FAIL”!?

In case you see this when first booting your Badge:

Don’t worry, that just means one of the elves in Santa’s workshop forgot to confirm that the self-test passed. Plug it into USB, and press A.

1.5.3 - Getting started

Congratulations, you’re the proud owner of a shiny new MCH badge! It’s a fully-functional computer, and while you (can do stuff with it) out of the box, the real fun starts when you start hacking it. The badge has two processors, an FPGA and a ton of sensors and toys to play with all in the palm of your hand! And we’ve done what we could to make using it as friendly and intuitive as possible. We had a lot of fun making it, and we hope you’ll have a lot of fun using it.

No fluff! I wanna get started!

Hook up the battery to the badge, the connector only allows it to be connected the right way around. Set the labeled on/off switch to ON. Things should quickly start up, display works and it makes a sound.

If this is the case everything works and you’re good to go. Attach the battery to the badge using the included velcro, slap on the lanyard (and possibly insert an SD-Card) and Start Hacking!

Don’t forget to update the OS and preinstalled apps. And have a look at some general tips for Using the Badge.

The rest of this page contains more detailed instructions in case you run into problems.

In the pack

If you are reading this at MCH, you received the unassembled badge in a bag when you entered the camp. Inside the bag are the following items:

(These will obviously change subject to what is in the pack)

• The badge itself
• A lithium-polymer battery for the badge
• A self-adhesive Velcro patch for attaching the battery
• A printed badge lanyard
• A leaflet containing basic information about the badge

Fitting the battery

The battery is a silver pouch with a short cable terminated in a trailing socket connector. This mates with a PCB mounted plug which you’ll find on the component side of the badge. Place your badge screen side down with the USB-C connector facing towards you, and you’ll find the on-board battery connector at the bottom right next to a field of gold squares (the prototyping area -> link to hardware).

The trailing plug on the battery has a small lug on one side that interfaces with a notch in the on-board socket. With the lug facing upwards, carefully slot the two connectors together.

Now turn the badge on. The switch is labeled ON OFF and located just below the battery connector. It will boot up, the display will start displaying things and the speaker will make some noise.

The battery should now be attached to the badge via the connector. We’ve provided velcro so you can affix it to the badge more firmly. One side of the battery tends to buldge, so try out which side lies most snugly against the badge. Find a good spot on the back of the battery and the reverse of the badge to attach the velcro.

Inserting an SD-Card

The SD-Card holder is a bit fiddly. We’ve assembled an illustrated guide to inserting an SD-Card.

Now what?

You should now have a working badge. We strongly suggest that you hook it up to a live USB power source to fully charge the battery. You’ll need a cable with a USB-C at the Badge end.

While the battery is charging, it’s time to explore the badge a little. When you turn it on it will start with a splash screen and details of all the sponsors who have made the event and the badge possible. You’ll then see the badge menu screen, so now’s a good time to move along to the next step in this introduction: using the MCH 2022 badge.

• learn to program The Badge
• find a 3D printer print a case for The Badge

Also, as with all security critical devices, make sure you update the Badge software and any of the apps you installed. There’s a menu item for that, which will probably save you a lot of grief from bugs we’ve already fixed!

1.5.3.1 - Inserting an SD Card

I inserted the card correctly, but it doesn’t work.

Format the card as FAT32 not exFAT, please. And if you are using a humongous 12TB Super SD Card, maybe try a cheap, small one from the grocery store :)

Oh Noes! I broke off the little metal thingie of the SD Card holder!

Oh well, better luck next time! Don’t feel bad, you’re not alone.

You can probably stick it back into the little grey plastic thingie.

I almost broke off the little metal thingie of the SD Card holder, WTF!?

Lucky you! You’ve come to the right place.

The trick is to:

• insert a fingernail into the SD-Cardholder manipulation slot and pull DOWN! (DOWN is in the direction of the arrow in the picture.)

• Somehow I never realized the metal thingie actually has “OPEN->” embossed in it until I uploaded the picture for the documenation. Don’t I feel stupid …

• fiddle around with your SD-Card to somehow get the alignment slot of the grey plastic thingie to align with the alignment notch in the card.

• find a small-fingered nerd to hold the SD-Card in place while you flip the metal fastener over the card and insert a fingernail into the SD-Cardholder manipulation slot and push UP! (UP is the direction of the arrow in the picture)

1.5.3.2 - Installing Apps from "The Hatchery"

WTF is a Hatchery!?

The Hatchery is an app store for The Badge!

You can also sort through the apps other people have published there. If you do so, please be aware that we don’t check for malware and will NEVER ask for your credit card number or home banking password (just kidding, off course we will.)

BTW, it’s called Hatchery because it (used to) contain “eggs” because previously the Hatchery was limited to Micropython apps and those are called eggs. And eggs hatch if you don’t eat them. Nowadays the Hatchery also supports native ESP Apps and FPGA bitstreams.

You can also use the Hatchery to publish your own apps and share them with friends. And unlike other App Stores, you don’t need a Dunn & Bradstreet Number, $1000 and don’t have to worry about your app being rejected because it contains malware.

A Word of Warning

Our crack team of Useability Experts are working around the clock to make the Hatchery even more intuitive and easy! So some of the information here, especially the screenshots may be out of date by the time you read this. Also, the documentation team is exceptionally lazy. Did we mention you can help update the documentation!? Go to the website project to create a Pull Request!

Better yet, check out the repo for The Hatchery itself and make improvements.

In case you are experiencing issues receiving 419 errors, clear cookies and try again.

Find an App

This will probably be the challenging part. We recommend you do this on a big computer, like a laptop. Something with a keyboard.

Go to mch20222.badge.team and sift through our fine offering of Hello World apps and super slow bitcoin miner malware.

If you go to the apps details page, you can download the app. But you don’t need to. Just remember the Category.

Now, go to the Hatchery app on the Badge.

Next you’ll be asked whether you want to install an ESP32 app, a Python egg or and FPGA bitstream. At the moment you kindof need to guess, here’s a heuristic:

If the details page contains:

• a file named main.bin it’s ESP32
• a bunch of Python files, it may be Python
• a file named bitstream.bin it’s an FPGA bitstream

In the next step, go to the Category remembered. Let’s pick “Safe Credit Card Detail Storage” (ESP->Utility). That sounds totally legit! Select it with the A button and you will see app details. As you can see, the app is, in fact, totally legit.

Now just press A to install. It will download for a while. Once it’s done, go to the “Apps” menu and your brand new app should be available to launch! Or … uninstall.

1.5.3.3 - Using Your Badge

Your MCH badge comes with installed software which allows you to select and run applications, install new applications from the online Hatchery, and configure Badge functions such as the Wi-Fi SSID and password (don’t worry, it can connect to camp Wifi out of the box).

This page is a high-level introduction to the installed software. If you came here looking for details on how to write software for the badge, then take a look at our software development guide.

Start at the menu screen

When you first turn on your badge, you’ll see a series of logos of the MCH2022 sponsors (Thanks again!) before finally a chime plays on the speaker and you find yourself at the main menu screen. It’s a graphical launcher with a series of icons for the different Badge functions. You can select a function with the joystick before launching it with the A button or by clicking the joystick.

When you are in an app the convention is that the A button is usually an action, the B button should take you one step back, and the Home button at the bottom left of the screen should take you out of the app and back to the menu.

As shipped, the badge has seven options on the main menu:

• Name Tag. This is the usual name tag app for an event Badge.
• Apps. This takes you to the user-installed apps on The Badge, including a Python launcher for backwards compatibility with previous Badge.team badges going back to the SHA 2017 badge.
• Hatchery. This is the app store for The Badge. Explore it to find new apps written by other MCH attendees.
• Tools. Here you can find a file browser, as well as infra-red remote control apps for some of the camp lighting.
• Settings. This takes you to a selection of badge configuration options. The badge ships pre-configured for the MCH2022 network, however it’s on this menu that you can find the tool to reconfigure it for your home network.
• App update. This option updates the apps on your badge to their latest versions from the hatchery.
• OS update. Here you can update the badge firmware.

1.5.4 - Software Development

Introduction …

This is a shameless placeholder for the software development section.

There are roughly 3 to 5 ways to develop for the Badge (depending on how you count:)

• Micropython : write apps in Python! This is the easiest way to get started, with the additional benefit that you probably don’t need to install anything (or much). Actually this should be the easiest way, but unfortunately has the fewest docs. Have a look here for documentation of the Python modules on the Badge.
• ESP-IDF : native EPS apps using the IDF (IoT Development Framework)
• FPGA : this is the special feature … not happy with the Tensilica CPU on the ESP? Just implement your own RISC-V core (or, to get started, connect all the buttons together with an AND gate…)

The other two plus (depending on how well you can count) :

• RP2040: aka Raspberry Pico. This is an onboard conprocessor that we are using as our USB Lifeline to the outside world. As such, if you break stuff here, you can easily brick your badge. Feel free to play around with it, but be aware: THIS VOIDS YOUR WARRANTY … and not in a fun way. It’s very unlikely we’ll have the resource to help you fix the badge during the camp.
• RISC-V and Forth: Because the badge contains an FPGA, you can turn it into anything you want. Technically the RISC-V and Forth projects are just FPGA projects, but the RISC-V CPU is powerful enough to run a Mandelbrot and Tricorn fractal explorer. A different RISC-V processor implementation with a focus on performance instead of readability can even run Doom! The Forth includes a custom stack processor and besides being useful for interactice experiments with freshly soldered additions on the PMOD connector, it can run a game of Snake.
• Rust: just a hint or two to get you started. Ask around the Telegram channel if you need support.
• TinyGo: Some hints on getting started with TinyGo on the Badge and some samples …
• Arduino: this was intended to be done and beautifully polished … but then we all got COVID and couldn’t finish. You can try to develop apps with Arduino if you think it will be easier, but it will probably cause some pain. Of course, we would be ecstatic if you help getting it work smoothly.

Linux permissions

Regardless of the way you’re going to program the badge, to connect to the badge over USB from Linux, do the following.

Create /etc/udev/rules.d/99-mch2022.rules with the following contents:

SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0f9a", MODE="0666"

Then run the following commands to apply the new rule:

sudo udevadm control --reload-rules
sudo udevadm trigger

Windows installation

To upload programs to the badge with the provided tools, python and pyusb are needed. The easiest way to install these on windows is by installing miniconda

After installation, open “Anaconda prompt” from the start menu. Then do the following

conda create -n badge -c conda-forge python pyusb
conda activate badge

Now you should be able to run commands like:

python ".\Desktop\mch2022-tools-master\webusb_fat_push.py" .\Desktop\my_test.py /flash/apps/python/button_tester/__init__.py

Micropython

The Badge comes with a preinstalled Micropython interpreter. Python should be the easiest way to control the device and the easiest mode to write apps for The Badge, especially if you are a beginner or don’t want to spend a lot of time downloading toolchains and debugging drivers.

Before the Camp and if you are afraid to break things…

Uri Shaked a.k.a Wokwi built an awesome emulation of the badge that runs in your browser. You can use it to test stuff out if you don’t yet have a Badge or your Badge is being used for something else. Or if you just feel more comfortable with a Badge that can’t catch on fire. It fantastic, you can click the buttons and everything! Try it.

On the device!

First, make sure Python is installed and that you didn’t accidentally delete it. Check in the apps menu. If it’s not there: install the Python app from the Hatchery by going to Hatchery -> ESP32 native binaries -> Utility -> Python and install it either onto the flash or onto an SD card.

This badge contains a common ESP32 firmware platform shared with other badges, so to learn more about the general platform and its components, start here. In addition there is also a mch22 module that offers a few badge-specific APIs.

While the above allows you to access the Python shell and install Python apps from the hatchery, here is how you upload custom apps to the badge over USB:

1. Download mch2022-tools
2. Write you Python code using the platform modules documented above
3. Use python3 webusb_fat_push.py __init__.py /sdcard/apps/python/myapp/__init__.py
4. Start your app in the Apps menu.

There’s a more detailled description on Micropython development here.

1.5.4.1 - Developing native Badge apps with the ESP-IDF

Introduction

Even though MicroPython is a quick and easy way to write apps for the Badge, you are limited both in terms of performance and functionality. If you need or want to write native applications, you have found the right place. This section describes how to develop Badge apps using the ESP-IDF, the development toolchain for native ESP32 apps.

Should I write a native app?

TLDR: OF COURSE YOU SHOULD! It’s fun! Hey, this Badge is for an event called “May Contain Hackers”, it was made for hacking in every possible way!

Native apps are amazing. The beautiful sponsors slideshow that you saw when you first booted your Badge was a native app. The BadgePython interpreter that runs all the BadgePython Eggs is a native app. Native apps are not launched within the Badge firmware - they are directly mapped to memory and then the Badge is rebooted. In other words: No walls, no fences around you. Ideally suited for writing Badge malware! Your code runs directly on the metal. This makes native apps the perfect option if you need full power and/or full access to all the MCU’s peripherals, not just the ones with a Python wrapper.

However, this comes at a (small) price: As native apps need to be directly accessible to the ESP32, their binaries reside in a special partition in the module’s internal Flash memory (if you’re interested in the magic behind it, have a look at the AppFS component). Because they are standalone firmwares, they tend to be larger than simple MicroPython apps. As a consequence, there is a limit to how many native apps can be installed on a Badge (five-to-ten-ish, depending on code size). If you run out of memory, you will have to uninstall others.

Getting Started

If you want to dive right in, here’s a short example walktrough to quickly get started writing a native ESP-IDF app.

Template App

The template app is a public template repository to use as a basis for your own app. It contains an application skeleton, an appropriate version of the ESP IDF and components for common Badge peripherals. You can find the template app on github. All examples here use this template. Basically: Clone, build, install, publish, fun. Incidentally, the template app has a button you can use to create a clone for your github user.

A More Advanced Example

Once you are familiar with the template and getting started example, it’s time to move a step further. The ESP-IDF has tons of features to offer. Here’s a more advanced app which turns your badge into a (crappy) bluetooth speaker.

1.5.4.1.1 - ESP-IDF getting started

Programming native applications on the Badge requires an ESP IDF to be installed. IDF stands for “IoT Development Framework” and is Expressif’s SDK which provides:

• convenient access to hardware functionality
• implementation of protocols such as TLS, HTTP and MQTT which are commonly used in IoT projects
• common utilities such as logging, error handling and JSON parsing
• infrastructure code for building, flashing and debugging.

The IDF will be installed automatically (via git submodules and make commands which we will point out) but it does require some dependencies to be installed.

Installing Prerequisites

How to install these prerequisites is described on the IDF documenttion page for:

• Linux
• Mac
• Windows

The instructions will (mainly) install git, cmake and python. Remember you DO NOT have to install the IDF!

In order to sideload the apps you develop, you will be using our webusb tools. These tools will get automatically installed, but require pyusb to be installed. This can be installed with pip install pyusb or apt install python3-usb

Download & build the “template app”

We created a basic Hello World template app that’s intended to be used as a basis for native badge apps you build. To allow you to get started quickly, the template app downloads the IDF in the required version, as well as some badge specific components you will.

To clone the template app, open a shell:

$ git clone https://github.com/badgeteam/mch2022-template-app my_fancy_app_name
$ cd my_fancy_app_name

The Makefile in the template app contains a number of targets for your convenience:

• prepare : Download all the ESP32 dependencies needed to build, you only need to run this once!
• build : compile the code
• install : install the app you just compiled (NOTE: if you have previously used the IDF to build ESP32 code, this is different from regular flashing! see below)
• monitor : connect to the ESP32 console and look at your log files.

$ make prepare # this downloads all the dependecies and may take a couple of minutes

$ make build   # this compile your app
$ make install # this installs the successfully compiled app to a connected badge.

# you really only need '$make install' because it depends on `install`. 

It will take a couple of minutes to download all the components. Once completed, a simple app showing “Hello, World!” will run on your badge.

Difference to “normal” IDF

If you have previously used the IDF, you may have noticed that we don’t use idf.py flash to install the app on the Badge. (And if you haven’t, you can safely skip this section. :)

The idf.py flash command assumes that the binary to flash is the main application for the device. This is not the case for the Badge, though. The main application is the launcher app, i.e. the app with the menu that starts by default. The make install target of the Makefile copies our newly created app into the appfs instead of overwrting the launch. Once copied to the appfs, the launcher can find it and the app should appear in the apps menu.

Obviously you can use idf.py flash but you’ll delete the launcher app and would need to reinstall it later.

Customizing the template app

Finally! Now that we have all the bureaucracy taken care of, we’ll start off by modifying the message printed to the screen. Have a look at this line of main.c, you can see the text shown on screen:

//...
        // This text is shown on screen.
        char             *text = "Hello, World!";
//...

This part is responsible for drawing the text to the screen. Go ahead and try to edit the text, here shown as “Fancy App!”:

Reading the buttons

The buttons on the Badge are not directly connected to the ESP32, instead they are read by the rp2040 coprocessor via I2C. Have a look in the esp32-component-mch2022-rp2040 component in case you are interested in the details.

The button handler starting on this line of main.c currently causes the app to exit and return to the launcher whenever the HOME button is pressed.:

        //...
        // Await any button press and do another cycle.
        // Structure used to receive data.
        rp2040_input_message_t message;
        // Await forever (because of portMAX_DELAY), a button press.
        xQueueReceive(buttonQueue, &message, portMAX_DELAY);
        
        // Is the home button currently pressed?
        if (message.input == RP2040_INPUT_BUTTON_HOME && message.state) {
            // If home is pressed, exit to launcher.
            exit_to_launcher();
        }
        // Is the home button currently pressed?
        if (message.input == RP2040_INPUT_BUTTON_HOME && message.state) {
            // If home is pressed, exit to launcher.
            exit_to_launcher();
        }
        //...

Let’s change this behaviour so the screen is briefly pink after pressing the A button. Graphics for the badge are handled by a library called Pax, if you want to dig deeper have a look at the docs here

Pax uses the same RGB (well, ARGB, to be precise) hex triplets as HTML. 0xeb34cf is beautiful MCH pink.

//...
        // Button handling.
        if (message.input == RP2040_INPUT_BUTTON_ACCEPT && message.state) {
                // Make a pink background.
                pax_background(&buf, 0xeb34cf);
                // Update the screen.
                disp_flush();
                // Wait for half a second.
                vTaskDelay(pdMS_TO_TICKS(500));
                // After this, it loops again with a new random background color.
        } else if (message.input == RP2040_INPUT_BUTTON_HOME && message.state) {
            // If home is pressed, exit to launcher.
            exit_to_launcher();
        }
//...

Using WiFi

The template app you’ve been playing with has a simple WiFi connection API.

First, empty the while loop so it looks like this:

//...
    while (1) {
        // Await any button press and do another cycle.
        // Structure used to receive data.
        rp2040_input_message_t message;
        // Await forever (because of portMAX_DELAY), a button press.
        xQueueReceive(buttonQueue, &message, portMAX_DELAY);
        
        // Is the home button currently pressed?
        if (message.input == RP2040_INPUT_BUTTON_HOME && message.state) {
            // If home is pressed, exit to launcher.
            exit_to_launcher();
        }
    }
//...

Instead of writing “Hello World” to the screen, we will modify the code to change the background color to indicate our Wifi connection status. Call wifi_connect_to_stored() to connect to WiFi and set the background color depending on whether the function returned successfully.

//...
    // Init (but not connect to) WiFi.
    wifi_init();
    // Now, connect to WiFi using the stored settings.
    bool success = wifi_connect_to_stored();
    if (success) {
        // Green color if connected successfully.
        pax_background(&buf, 0xff00ff00);
    } else {
        // Red color if not connected.
        pax_background(&buf, 0xffff0000);
    }
    disp_flush();
//...

What you want to do with WiFi varies a lot, so we can’t explain that here. But if you have other libraries that need WiFi (for example an MQTT client), you start them after this code.

Sharing is caring!

Now you’re ready to publish your app in the Hatchery. Follow these instructions to publish your app.

For further information:

• ESP-IDF WiFi and network API
• Tickets App using WiFi (example)
• ESP-IDF HTTP client API

1.5.4.1.2 - A More Advanced Example

If you have reached this page, you have probably already had a look at the template app and played through the getting started tutorial. If not, it might be a good idea to do it now - there’s a lot of information on getting the prerequisites installed.

You will need a computer with libusb, pyusb, git, cmake, make, python3, a terminal, a web browser and a text editor. This should be easily doable on Linux machines and Macs - if you’re on Windows, it’s probably easiest to work in a Linux wrapper but YMMV. Additionally, a github account is helpful but not strictly needed. Check here for details.

This journey assumes that you have some basic familiarity with shell, C and git (or a search engine of your choice). This is not a line-by-line tutorial, it just gives you the rough outline of writing an app and discusses some approaches and techniques along the way. If you want to cheat and download the finished project, go here

Starting

Start by cloning the template app - go there, click on “Use this template” and follow the instructions to make your own copy (or you can clone the repo and add a new remote manually). git clone the repo, cd to it and run make prepare. This should set up the ESP-IDF and all badge-specific components.

What should we do?

If you’re not sure what you want to hack, the ESP-IDF examples are an amazing starting point. They are already on your machine: ls esp-idf/examples. Hours of happy browsing. Besides covering many features of the ESP32, they are exceptionally well written and documented (usually).

We’ll use one of these app to build our app - something that can’t be done in the BadgePython world: Let’s turn the Badge into a bluetooth Boom Box. Speaker sound quality will most likely be worse than any smartphone on this planet, but with the headphone output, this thing might even be usable for something.

There’s a working example at esp-idf/examples/bluetooth/bluedroid/classic_bt/a2dp_sink. The code example already shows how to hook the audio stream to an I2S (Inter-IC Sound) DAC. And conveniently, the Badge’s audio outputs are connected to an I2S DAC! Almost like we’re done already before we even started.

Shameless Copying

To get started, copy the following files from the IDF project’s main directory: bt_app_av.h, bt_app_av.c, bt_app_core.h, bt_app_core.c into your own main folder (they are Public Domain, after all!). And while you’re at it, copy most of the contents of the main.c file over to the end of your main.c file and the includes to the top.

Actually Hacking Some Code …

Start by integrating the bluetooth initialization routine into your app. Rename the bluetooth example’s app_main to bt_init and call it within our app_mainfunction in place of the call to wifi_init ( we won’t be using WIFI in this example). bt_init must be declarated above app_main code. Either move the whole function up, or add a declaration.

Unfortunately, both app_main and bt_init call nvs_flash_init. And nvs_flash_init may only be called once. Get rid of the second call.

The example projects defines a number of constants using menuconfig. These are defined in Kconfig.projbuild, but we don’t need them. For example, this mechanism in the original IDF example allows you to redefine the I2S pins to use, but these are hardwired on the Badge, so configuring them adds unnecessary complexity. grep through main.c looking for CONFIG_EXAMPLE and replace them:

• CONFIG_EXAMPLE_A2DP_SINK_OUTPUT_INTERNAL_DAC : should be false, this option would route the audio to the ESP’s internal DAC, but the Badge has a dedicated audio DAC chip
• CONFIG_EXAMPLE_I2S_BCK_PIN
• CONFIG_EXAMPLE_I2S_LRCK_PIN
• CONFIG_EXAMPLE_I2S_DATA_PIN

We need to find the new values for the I2S pins CONFIG_EXAMPLE_I2S_BCK_PIN, CONFIG_EXAMPLE_I2S_LRCK_PIN and CONFIG_EXAMPLE_I2S_DATA_PIN in i2s_pin_config_t. Obviously, you can find the pins in the hardware schematics, but there’s an easier way: Have a look at components/mch2022-bsp/include/mch2022_badge.h. The Badge’s board support package has defines for all pins. (Note: At time of writing, this header had LRCLK and BCLK swapped, but hopefully this will be sorted out soon).

The components directory is generally a good place to look if you’re looking for Badge drivers. All items in this folder are independent components. You can imagine them as libraries. They are automatically added to the project by the ESP-IDF build system.

I2S has some sloppy signal naming rules, which may be confusing. LR is LRCLK (a word clock), CLK is BCK (a bit clock) and DATA is DATA. In addition, our DAC wants a MCLK (usually faster than the bit clock), so we add an entry: .mck_io_num = GPIO_I2S_MCLK. In the end, it should look something like this:

    i2s_pin_config_t pin_config = {
      .mck_io_num = GPIO_I2S_MCLK,
      .bck_io_num = 4, // should be GPIO_I2S_CLK
      .ws_io_num = 12, // should be GPIO_I2S_LR
      .data_out_num = GPIO_I2S_DATA,
      .data_in_num = -1 // not used
    };
    i2s_set_pin(0, &pin_config);

While you’re at it, you can tweak the I2S parameters to our needs (located directly above the pin_config code). I2S has half a dozen different dialects and each I2C peripheral speaks a different one. Getting the parameters right is not hard but tedious, requiring comparison of datasheets. Additionally, because the I2S peripheral will stream audio data via DMA, we can adjust buffer sizes. Here’s some settings that seem to work well:

    i2s_config_t i2s_config = {
      .mode = I2S_MODE_MASTER | I2S_MODE_TX, // TX only
      .sample_rate = 44100,
      .bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT,
      .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, // stereo
      .communication_format = I2S_COMM_FORMAT_STAND_I2S,
      .dma_buf_count = 6,
      .dma_buf_len = 128,
      .intr_alloc_flags = 0, // default interrupt priority
      .bits_per_chan = I2S_BITS_PER_SAMPLE_16BIT,
      .tx_desc_auto_clear = true // auto clear tx descriptor on underflow
    };
    i2s_driver_install(0, &i2s_config, 0, NULL);

Almost Ready to Try

We’re close to getting something working. Just four things before we try our first build:

• Change our app name: The projects Makefile contains an install target. It’s purpose is to push the project’s binary to the Badge during development. The name in quotes is the name shown on the Badge’s app chooser. Change it something unique.
• Change the Speaker’s name: There’s a #define that we copied over from the bluetooth example: LOCAL_DEVICE_NAME. This is the name broadcast via bluetooth. Change it to something unique.
• idf.py menuconfig: menuconfig allows you to enable and configure the components in your project. First, enable bluetooth. Start the tool with make menuconfig, go to Component config > Bluetooth and enable it. Go to Bluedroid Options and enable Classic Bluetooth and A2DP(Advanced Audio Distribution Profile = what bluetooth speakers do). Later on, menuconfig is a good place to disable unneeded software components. For now, we don’t care.
• Add files to compile: Remember that we added additional ‘*.c’ files, bt_app_av.c and bt_app_core.c? The project’s build process works roughly as follows: make build triggers idf.py build which in turn uses cmake. For now you don’t need to understand this in detail,you just have to tell the build system about the new files. We need to edit main/CMakeLists.txt. When you’re done, the SRCS section should look something like this:

    SRCS
        "main.c"
        "bt_app_core.c"
        "bt_app_av.c"

Now it’s time to make. Type make prepare, this downloads all the prerequisite tools and code. This process might take a while. It will fell like an eternity. Meanwhile, whistle the Jeopary theme song. Drink some water. Wash your hands. Give a polite, honest compliment to a stranger.

The make process should have finished by now. Now type make build. If this fails, you probably didn’t follow the steps properly (most likely the compliment part). No worries, subsequent builds will be faster.

Now, run make install. If there’s an error concerning missing USB, repeat the libusb and pyusb install steps. If you get a UnicodeEncodeError in printProgressBar, you’re using a Mac and you can solve this problem by editing tools/webusb.py: Replace the fill character with another character, e.g. *. Or fix it and create your first PR to the tools repo!

If everything went as expected, you should see a WebUSB screen on the Badge and a progress bar in the terminal. Once upload and verification completes, the Badge should reboot and show the “Hello world” screen of the template app. … Boring!

Take your phone or other bluetooth device, scan for new devices. Select BadgeBoomBox or whatever you chose for your speaker’s name and pair them. Make sure the speaker switch on your Badge is turned on. Play some music. Hear it? That amazing sound of no bass? Unbelievable.

Understand What’s Going On

Good work! Let’s take a short break and look at what the app is doing (hey, we didn’t write much of it yet). ESP-IDF has a logging facility that is used in the example code (look for ESP_LOGI, ESP_LOGE, ESP_LOGD etc.). We can monitor the logs with make monitor (if it does not work, you might want to set the PORT environment variable to the ESP’s /dev/tty* ). If you succeed, you will see bluetooth connection and disconnection events and all sorts of interesting things happening. For example:

• There are “volume change simulation” events. Too bad we didn’t look into the example before - the example code simulates volume controls and a user randomly turning the volume up and down to showcase the AVRC (Audio/Video Remote Control) features. This has to go. But just the “random volume change” part - we may want to hook the volume control to our buttons. The simulation is executed in a separate task, look for s_vcs_task_hdl in bt_app_av.c and surgically remove it from the source code along with volume_change_simulation.

• If you connected specific devices, e.g. an Android phone, you might be surprised to see that the phone will not only send connect/disconnect and play/pause events, but sometimes also track titles as well as album and artist names. Wouldn’t it be great to see this on the screen?

AVRC is not consistently used by all devices. Some features are used, some not. Anyway, let’s have some fun with it.

Another nice thing to have would be a dB-Meter. Our next task is to sift through the code to see where the audio stream passes by to analyze it.

Side note: Tasks, Events, FreeRTOS messaging and our threading approach

ESP-IDF makes heavy use of FreeRTOS. Two essential building blocks of FreeRTOS are Tasks and Queues. Tasks can be seen as threads: Independent, preemptively scheduled sequences of operation. Each application has a main thread (the one that executes app_main), a timer thread and possibly other threads (e.g. for bluetooth, Networking and other things). Queues are often used to pass events and other information from one task to another. They are basically thread-safe FIFO buffers. One task (or an interrupt) posts elements into the queue and another task can wait for elements to arrive in that queue.

The template app already uses one queue: The RP2040 firmware will post button presses into this queue. The application’s main loop waits for button press events to arrive and reacts to it by setting a new random color and redrawing the screen.

The bluetooth stack uses its own tasks. Our task, the main task, controls the screen and user interaction (and it’s a good idea to restrict this to a single task). So if we want to receive bluetooth information in the main task, it’s a good idea to use a queue. bluetooth event -> queue -> main task reacts.

But our main task is already blocked waiting for the button press queue! How can we receive our Bluethooth events? Could we use the button queue for our bluetooth events? Yes you could! But it’s not polite to push things into other’s queues without prior consent. So we don’t.

There’s another option: Queue sets are used to combine queues and (other things) and wait on several events simultaneously.

So we’ll create a new audioQueue to send us messages whenever there’s a relevant bluetooth and/or audio event. We also use this queue to send audio level updates regularly.

Queue entries can have data attached to them. This is often a struct with an event type and additional data, typically implemented as a union so that different events can have different data associated with them. It’s good practice to keep these entries short because queues will have to allocate several instances prior to usage (Real Time OSes prefer allocating a fixed amount of memory at start instead of dynamically allocating memory during runtime).

To keep the queued data short, we will not include the full audio stack state in the queue entries. Instead we’ll generate an event to notify that the state changed, but not what actually changed. For this, we use another mechanism to get data safely from one task to another: Semaphores used as mutexes / locks. The bluetooth stack will collect its own state in a struct. The main task can request a copy of that state struct. All accesses to members of that struct will be embedded in a lock, making sure that only one task has access to this struct at any instance in time.

Queues are good for pushing information from one task to another, mutexes are good for pulling. Admittedly, we could have used just queues in this case, but this example is supposed to be at least slightly educational…

In addition to the “something changed in the bluetooth audio state” event, we will have a dB-Meter-update event that should be sent in roughly 20-50Hz intervals so that we can have a smooth noise meter animation.

Who should manage the queue? The queue could be located either in the bt_app_*** part or in our main.c. Both are good options. We will add them to main.c, reasoning that the bt_app_*** is a generic service and should not make any assumptions about hosting application. As a consequence, the bt_app_*** part will just issue callbacks whenever something interesting happens. The code we’ll write in main.c takes care of queueing these events.

We will leave the well-paved path of documenting every changed part in the code here. The remaining document will show some examples. As said, the full code is in the repository.

Getting metadata

After some light reading, you’ll quickly get a better overview over the bluetooth app: naming suggest that bt_app_core.c seems to do the actual streaming while bt_app_av.c handles metadata and remote control. So the audio data is more likely to be found in bt_app_core.c. And metadata is most likely found in bt_app_av.c.

We need to decide: What data is useful for us? What could we want to display?

• Connection state: Whether we’re disconnected, connected, connecting or disconnecting
• Audio playback state: Whether we’re playing, stopped or suspended (which is, in effect, also stopped somehow)
• The current volume: A value between 0..127
• Our current sample rate (no idea if someone is interested but anyway, let’s collect it)
• Current title, artist and album (if available)

So a simple struct to hold that state should look something like this:

/** the full exposed audio state in a struct */
#define AUDIOSTATE_STRLEN 100
typedef struct BTAudioState_ {
  esp_a2d_connection_state_t connectionState;  // 0=disconnected, 1=connecting, 2=connected, 3=disconnecting
  esp_a2d_audio_state_t playState;  //0=suspended, 1=stopped, 2=playing
  uint8_t volume; //0..127
  int sampleRate;
  char title[AUDIOSTATE_STRLEN];
  char artist[AUDIOSTATE_STRLEN];
  char album[AUDIOSTATE_STRLEN];
} BTAudioState;

So what do we do now? Look into the logs (remember make monitor) for the data we’re interested in. Find the code that generated the log messsage. Insert code to update our state. Be sure to lock each access to the struct. After a change, push an entry to the event queue. It’s a good idea to clear the state when we get disconnected.

For example, we insert four lines to handle ESP_A2D_AUDIO_STATE_EVT, an event sent whenever the actual stream is started, stopped or suspended:

    case ESP_A2D_AUDIO_STATE_EVT: {
        a2d = (esp_a2d_cb_param_t *)(p_param);
        ESP_LOGI(BT_AV_TAG, "A2DP audio state: %s", s_a2d_audio_state_str[a2d->audio_stat.state]);
        s_audio_state = a2d->audio_stat.state;
        if (ESP_A2D_AUDIO_STATE_STARTED == a2d->audio_stat.state) {
            s_pkt_cnt = 0;
        }
        lockAudioState();
        audioState.playState = a2d->audio_stat.state;
        unlockAudioState();
        notifyAudioStateChange();
        break;
    }

There are other parts where the state is updated, but they all follow the same principle, so it would be boring to list them all here. Try yourself! Or have a look at the repo. lockAudioState()acquires the lock, unlockAudioState() releases it and notifyAudioStateChang() pushes an event to our queue.

Tapping the audio stream

bt_app_core.c has two tasks: The bt_app_task that responds to bluetooth stuff and the bt_i2s_task that seems to stream the audio data to the I2S peripheral. Bingo! That’s ideal!

Have a look at bt_i2s_task_handler: This function mainly consists of an endless loop waiting on a ring buffer to deliver sample data and pushes that data into the i2s peripheral. We can hack that! First, we want to implement volume control by scaling each sample. Second, we want to calculate the audio volume. Have a look:

static void bt_i2s_task_handler(void *arg) {
    uint8_t *data = NULL;
    size_t item_size = 0;
    size_t bytes_written = 0;
    static float leftSquares = 0;
    static float rightSquares = 0;
    static int sampleCount = 0;

    for (;;) {
        /* receive data from ringbuffer and write it to I2S DMA transmit buffer */
        data = (uint8_t *)xRingbufferReceive(s_ringbuf_i2s, &item_size, (portTickType)portMAX_DELAY);
        if (item_size != 0){
            int16_t *buf = (int16_t*)data;
            int numSamples = item_size / 2;
            uint8_t vol = getVolume();
            float volScale = volumeScale[vol] / 65536.0f;
            // Sample processing can go here. Right now, only volume scaling and RMS analysis
            for (int i=0; i<numSamples; i += 2) {
                float l = (float)buf[i];
                l *= volScale;
                leftSquares += l*l;
                buf[i] = l;
                float r = (float)buf[i+1];
                r *= volScale;
                rightSquares += r*r;
                buf[i+1] = r;
            }
            sampleCount += numSamples;
            i2s_write(0, data, item_size, &bytes_written, portMAX_DELAY);
            vRingbufferReturnItem(s_ringbuf_i2s, (void *)data);
            if (sampleCount >= 1500) {
              notifyAudioRMS(sqrtf(leftSquares / sampleCount), sqrtf(rightSquares / sampleCount));
              leftSquares = 0;
              rightSquares = 0;
              sampleCount = 0;
            }
        }
    }
}

This code is by no means elegant nor efficient. First, we cast the data buffer to an int16 array (we know that we have 16 bit samples and I2S has them typically interleaved, L/R/L/R/…). For each buffer, we request the current audio volume, get a scaling factor via a lookup table (perceived volume is logarithmic). Then we go through all left and right samples, convert each to float and multiply it with our volume factor. Then we convert the sample back to int and replace the sample in the buffer with our scaled value.

We also square each sample and sum the squares for the left and right channel. After 1500 samples (roughly every 30ms for 44KHz), we divide the the sum of squares by the number of samples, resulting in the mean square, and then take the square root, resulting in the Root of the Mean Square (RMS). That’s a good basis for a volume display. notifyAudioRMS() will push an audio RMS update to the event queue. After reporting, we reset the accumulators for the next interval.

Converting everything to float and back is terribly unneccessary and terribly slow. But the ESP is fast enough and this is a good starting point for further DSP (anyone?).

Bring it together

Now that we have extended the bluetooth audio code to give us callbacks whenever something happens, it’s time to bring it all to the main loop. Let’s see what we should do in the main loop:

• Audio state changed: Pull audio state, redraw screen
• Audio RMS levels changed: Remember levels, redraw just the level meter
• Home button pressed: Exit to launcher
• Joystick up or down: Increase or decrease volume, redraw all

First, write typedefs and structs that can hold audio events (state changes or RMS updates):

typedef enum BTAudioEventType_ {
  Event_StateChanged = 1, ///< audio state has changed, may be queried using getAudioState
  Event_RMSUpdate        ///< audio RMS update
} BTAudioEventType;

typedef struct BTAudioEvent_ {
  BTAudioEventType type;
  union {
    struct {
      float left;
      float right;
    } rms;
  } data;
} BTAudioEvent;

Next generate a queue to hold these events:

xQueueHandle audioQueue;

audioQueue = xQueueCreate( 10, sizeof(BTAudioEvent) );

Now we need callback functions to call from the bluetooth part (running in the the bluetooth task!). Their purpose is to push a BTAudioEvent into the audioQueue:

/** callback from bt_app_av: state has changed */
void audioStateChange() {
  BTAudioEvent evt = {
    .type = Event_StateChanged
  };
  xQueueSend(audioQueue, &evt, 0);  //evt is copied to queue
}

/** callback from bt_app_core: new volume measurement */
void audioRMSUpdate(float left, float right) {
  BTAudioEvent evt;
  evt.type = Event_RMSUpdate;
  evt.data.rms.left = left;
  evt.data.rms.right = right;
  xQueueSend(audioQueue, &evt, 0); //evt is copied to queue
}

Next, register the callbacks (not shown: They will just be stored in global variables and called when necessary)

  setAudioStateChangeCB(&audioStateChange);
  setAudioRmsCB(&audioRMSUpdate);

At this point, updates from the bluetooth stack will end up in our audioQueue. Time to combine the queues:

  QueueSetHandle_t queueSet = xQueueCreateSet(20);
  xQueueAddToSet(buttonQueue, queueSet);
  xQueueAddToSet(audioQueue, queueSet);

Finally, we can write our main event loop:

  while (1) { //handle events from both button and audio queue
    QueueSetMemberHandle_t queue = xQueueSelectFromSet(queueSet, portMAX_DELAY);
    if (queue == buttonQueue) {
      rp2040_input_message_t message;
      xQueueReceive(buttonQueue, &message, 0);
      if (message.state) {
        switch(message.input) {
          case RP2040_INPUT_BUTTON_HOME:
            exit_to_launcher();
            break;
          case RP2040_INPUT_JOYSTICK_UP:
            volume_set_by_local_host(audioState.volume < 122 ? (audioState.volume+5) : 127);
            drawAll();
            break;
          case RP2040_INPUT_JOYSTICK_DOWN:
            volume_set_by_local_host(audioState.volume > 5 ? (audioState.volume-5) : 0);
            drawAll();
            break;

        }
      }
    } else if (queue == audioQueue) { //audio event
      BTAudioEvent evt;
      xQueueReceive(audioQueue, &evt, 0);
      if (evt.type == Event_StateChanged) { //state changed: update main UI
        getAudioState(&audioState);
        drawAll();
      } else if (evt.type == Event_RMSUpdate) {  //RMS: Update bars
        float leftDB = 20 * log10(evt.data.rms.left);
        float rightDB = 20 * log10(evt.data.rms.right);
        leftDBMeter = (leftDB - DBMETER_MIN) / (DBMETER_MAX - DBMETER_MIN);
        rightDBMeter = (rightDB - DBMETER_MIN) / (DBMETER_MAX - DBMETER_MIN);
        drawDBMeter();
      }
    }
  }

The xQueueSelectFromSet will wait until am event arrives in one of the queues and return which queue was active. The rest is dispatch: If the origin was the button queue, react to button or joystick input. If it was an audio event, redraw the level meter or the whole screen. The RMS update will convert the RMS to dB by calculating the logarithm (as said above, perceived volume is logarithmic). Then, the values will be scaled to fill the screen. The values DBMETER_MIN and DBMETER_MAX are arbitrarily chosen so that the level meter shows something useful.

Show it!

We’ve put some effort into collecting and merging data to display. Now it’s time to visualize the data. The Badge comes with a convenient graphics package that allows us to draw shapes and write text. It draws to a bitmap and then transfers the bitmap to the screen. Currently, the transfer to screen is not very fast as it uses the MCU to control the transfer (anyone interested in implementing DMA transfers? Pull Request, plz!). Smooth fullscreen animations will be difficult. However, it’s possible to just transfer parts of the buffer. The only smooth animation we need is the level meter.

For simplicity, let’s draw that as a horizontal bar graph (expanding to the left and right from center for the left and right channel) at the bottom of the screen and put it in a separate drawing function, drawDBMeter(). The remaining screen is drawn in drawAll(), which will, in turn, call drawDBMeter(). This way we can either update the DB graph quickly or the whole screen slowly. Both functions will transfer their parts to the screen.

void drawDBMeter() {
  if ((audioState.connectionState != ESP_A2D_CONNECTION_STATE_CONNECTED) || (audioState.playState != ESP_A2D_AUDIO_STATE_STARTED)) {
    leftDBMeter = 0;
    rightDBMeter = 0;
  }
  int halfWidth = (ILI9341_WIDTH / 2);
  float l = (leftDBMeter < 0) ? 0 : (leftDBMeter > 1) ? 1 : leftDBMeter;
  float r = (rightDBMeter < 0) ? 0 : (rightDBMeter > 1) ? 1 : rightDBMeter;
  int leftPix = halfWidth * l;
  int rightPix = halfWidth * r;
  int p1 = halfWidth - leftPix;
  int p2 = halfWidth + rightPix;
  int y = ILI9341_HEIGHT-DBMETER_HEIGHT;
  pax_col_t bgCol = pax_col_rgb(0,0,0);
  pax_col_t fgCol = pax_col_rgb(255,255,255);
  pax_simple_rect(&screenBuf, bgCol, 0,  y, p1, DBMETER_HEIGHT);
  pax_simple_rect(&screenBuf, fgCol, p1, y, p2-p1, DBMETER_HEIGHT);
  pax_simple_rect(&screenBuf, bgCol, p2, y, ILI9341_WIDTH-p2, DBMETER_HEIGHT);
  int off = 2 * ILI9341_WIDTH * (ILI9341_HEIGHT-DBMETER_HEIGHT);
  ili9341_write_partial_direct(get_ili9341(), screenBuf.buf+off, 0, ILI9341_HEIGHT-DBMETER_HEIGHT, ILI9341_WIDTH, DBMETER_HEIGHT);
}

The code relies on the audioState struct and the leftDBMeter and rightDBMeter variables (all are local to the main task, so we don’t need to worry about threading here). DBMETER_HEIGHT is a global variable determining the height of the bar in pixels and ILI9341_WIDTH and ILI9341_HEIGHT are variables defined in the display driver component included with the template app. Drawing is pretty straightforward:

• If we’re currently not playing music, the meter should be at zero
• Levels are clamped and then scaled to screen size
• The bar graph always consists of a white rectangle in the middle and two black rectangles at the sides. It would be slightly easier to fill the whole area black and then a white rectangle over it, but that would touch some pixels twice. The three-rectangles-approach only sets each pixel once.
• In the end, the ili9341_write_partial_direct() call transfers the screen portion of the bar graph to the screen.

The drawAll() function is longer but even easier:

void drawAll() {
  static const char disconnected[] = "Disconnected";
  static const char connecting[] = "Connecting...";
  static const char disconnecting[] = "Disconnecting...";
  static const char stopped[] = "Stopped";
  static const char playing[] = "Playing";
  
  pax_col_t bgCol = pax_col_rgb(0,0,0);
  pax_background(&screenBuf, bgCol);

  pax_col_t fontColor = pax_col_rgb(255,255,255);
  const char *status = "?";
  switch (audioState.connectionState) {
    case ESP_A2D_CONNECTION_STATE_CONNECTING:
      status = connecting;
      break;
    case ESP_A2D_CONNECTION_STATE_DISCONNECTING:
      status = disconnecting;
      break;
    case ESP_A2D_CONNECTION_STATE_DISCONNECTED:
      status = disconnected;
      break;
    case ESP_A2D_CONNECTION_STATE_CONNECTED:
      status = (audioState.playState == ESP_A2D_AUDIO_STATE_STARTED) ? playing : stopped;
  }

  char volStr[30];
  snprintf(volStr, 30, "Volume: %i%%",audioState.volume * 100 / 127);

  pax_draw_text(&screenBuf, fontColor, pax_font_saira_condensed, pax_font_saira_condensed->default_size, 10, 10, status);
  pax_draw_text(&screenBuf, fontColor, pax_font_saira_regular, pax_font_saira_regular->default_size, 10, 90, audioState.title);
  pax_draw_text(&screenBuf, fontColor, pax_font_saira_regular, pax_font_saira_regular->default_size, 10, 115, audioState.artist);
  pax_draw_text(&screenBuf, fontColor, pax_font_saira_regular, pax_font_saira_regular->default_size, 10, 140, audioState.album);
  pax_draw_text(&screenBuf, fontColor, pax_font_saira_regular, pax_font_saira_regular->default_size, 10, 165, volStr);

  ili9341_write_partial_direct(get_ili9341(), screenBuf.buf, 0, 0, ILI9341_WIDTH, ILI9341_HEIGHT-DBMETER_HEIGHT);
  drawDBMeter();
}

The function just clears the screen and then writes some text to it. Most of the code just determines the message to draw. ili9341_write_partial_direct() transfers everything except for the volume meter and calls drawDBMeter() to update that part.

This should be it. Make and install again (and, if needed, debug, rinse, repeat). There should be awesome sound and an awesome user interface.

Publishing

The Badge.team hatchery also allows publishing native apps. Go to The Hatchery, register, login. There should be an option to publish native ESP32 apps. This tutorial is already way to long, though. Follow these instructions if you want to publish your app in The Hatchery

1.5.4.1.3 - ESP-IDF fancy name tag

There are endless games and apps to explore on the badge, but when going about your business on the camp, most likely its main function will be a name tag. So what better than writing a custom name tag to show off your style, identity, hacker skills, memes, or whatever you want.

After having completed the getting started you should have a template app that can draw a colored background and some text. Change the text to your name, and you have yourself a name tag… right? Let’s explore some ways in which you can spice up your name tag.

Other drawing functions

The pax-graphics documentation has quite a nice list of all the fonts and drawing primitives it contains.

Drawing lines and circles may sound a bit boring, but if you duck “line patterns” or “geometric pattern” or similar queries you can find quite some nice patterns to draw with those basic shapes.

In addition I’d like to draw your attention to the shaders documentation which has a nice example to draw rainbows on shapes, which you could easily adapt to do all sorts of nice gradients.

Drawing images

Geomeric patterns are nice, but if you want to show off your art, the logo of your favourite retrocomputer, a character from your favourite franchise, or your favourite meme, you’ll want to load images onto the screen.

The pax-graphics side of drawing images is well documented. But before you get to that point, there are a few things you need to do.

Of course first you need to find or make an image. This part is up to you. Keep in mind that the badge screen is 320x240 pixels, and that pax-graphics only loads png.

Next you’ll need to get the image onto the badge. Since internal flash space is extremely limited, it’s highly recommended to use a micro SD card. Be careful when inserting it! To push the png image to the SD card:

python3 tools/webusb_fat_push.py myimg.png /sdcard/myimg.png

To use the SD card, you need to include the component, and mount it. Then you can open the file.

#include "sdcard.h"

// image buffer
static pax_buf_t myimage;

// mount sd card
esp_err_t res  = mount_sd(GPIO_SD_CMD, GPIO_SD_CLK, GPIO_SD_D0, GPIO_SD_PWR, "/sd", false, 5);
if(res != ESP_OK) ESP_LOGE(TAG, "could not mount SD card");

// open file
FILE* fd = fopen("/sd/myimg.png", "rb");
if(fd == NULL) ESP_LOGE(TAG, "could not open file");

// store as a buffer for later use, best for animations
if(!pax_decode_png_fd(&myimage, fd, PAX_BUF_16_565RGB, 0)) ESP_LOGE(TAG, "could not parse png");
pax_draw_image(&buf, &myimage, x, y);

// or draw directly, simplest for static drawings
if(!pax_insert_png_fd(&buf, fd, x, y, 0)) ESP_LOGE(TAG, "could not parse png");