// update the firmware

latest firmware: v1.10 · released 2026-09-26

virtualshack.io / badge / update

Updating takes about 15 minutes over USB: you build the firmware from source and flash it with PlatformIO. Your handle, points, friends and encounter log are kept. No OTA (yet).

// before you start

If your badge has Badge Settings → Power → Deep sleep, you already have the latest firmware (v1.10, released 2026-09-26). Badges flashed before 2026-08-05 do not have that menu and need this update.

To see your exact build, open OPTIONS → Whoami; it shows something like v1.10 32c3255 ch1 (version, build commit, channel).

You need:

// download the latest firmware

Clone the public source and drop the group key into it. The key never goes in git, so it stays only on your machine.

  1. Clone the source:
    git clone https://git.virtualshack.io/onlyn00bs-badge.git
    cd onlyn00bs-badge
  2. Create the key file from its template:
    cp firmware/src/secrets.h.example firmware/src/secrets.h
    Open firmware/src/secrets.h and paste the key between the quotes on the #define GROUP_PSK_HEX "" line.
  3. Check it is the right key. This prints a fingerprint of the key without revealing it:
    python3 -c 'import re,hashlib;k=re.search(r"#define GROUP_PSK_HEX \"(.*)\"",open("firmware/src/secrets.h").read()).group(1);print(hashlib.sha256(bytes.fromhex(k)).hexdigest()[:16])'
    It must print a4dc586d0276fa51. Anything else means the wrong file: stop and ask for the right one.

Don't generate a new key with openssl rand. If you do your badge will be on its own private network, and it will quietly find nobody.

// connect the badge

No button presses are needed - the flasher resets the badge into update mode. Find its port:

macOS
ls /dev/cu.wchusbserial* → PORT looks like /dev/cu.wchusbserial10
Linux
ls /dev/ttyUSB* → PORT looks like /dev/ttyUSB0
Windows
Device Manager → Ports (COM & LPT) → PORT looks like COM3 ("USB-SERIAL CH340")

// flash the firmware

One command builds and flashes. From the onlyn00bs-badge folder, replace PORT with your port:

pio run -d firmware -e oled_v3_prod -t upload --upload-port PORT

The first run takes several minutes while PlatformIO downloads the ESP32 toolchain. Later runs take about 45 seconds. It is done when you see Hash of data verified. followed by [SUCCESS]. Then the badge restarts by itself.

Two things to get right:

// verify that it worked

The update worked if the badge boots to HOME as you, with your handle and points intact.

For a closer look, watch the boot log with pio device monitor -p PORT -b 115200 (Ctrl-C to exit). It should show build : v1.10 … and mode : DISCOVERY with your handle.

// troubleshooting

No port appears
Try a different cable (most likely charge-only). On macOS, check the CH34x driver is enabled in Driver Extensions. On Ubuntu, sudo apt remove brltty if the port appears and vanishes.
Permission denied on the port (Linux)
Add yourself to dialout and log out and back in.
Build fails with an error about the group key
secrets.h is missing, in the wrong place, or the key isn't pasted in whole. It must be at firmware/src/secrets.h, with all 64 characters of the key between the quotes and nothing else.
Failed to connect to ESP32
Unplug, replug, and run the command again. Close any serial monitor that has the port open.
Upload stopped partway
Run it again. A half-written firmware can't brick the badge, because the bootloader is never touched.
FINDER shows nobody after the update
Rerun the key fingerprint check. A wrong key looks exactly like "nobody in range". Then compare Whoami with a friend's badge.

Still stuck? Send virtualtack the output of pio run.

← back to the badge