// 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:
- A USB-C cable
- A computer with
gitand Python - PlatformIO Core:
pipx install platformio(orpip install platformioi guess) The ESP32 toolchain downloads on first build. - The group key (64 letters and numbers), ask virtualtack for it. Without it your badge will stop seeing everyone else's.
- The USB driver for the badge's CH340 serial chip:
- macOS: install
CH34xVCPDriver.dmgfrom WCH on GitHub- Run the app, click Install, then enable it in System Settings → General → Login Items & Extensions → Driver Extensions. Unplug and replug the badge.
- Linux: already built into the kernel.
- Add yourself to the
dialoutgroup (sudo usermod -aG dialout $USER, then log out and in).
- Add yourself to the
- Windows: get the CH340 driver from WCH (CH341SER).
- macOS: install
// 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.
- Clone the source:
git clone https://git.virtualshack.io/onlyn00bs-badge.git cd onlyn00bs-badge - Create the key file from its template:
Opencp firmware/src/secrets.h.example firmware/src/secrets.hfirmware/src/secrets.hand paste the key between the quotes on the#define GROUP_PSK_HEX ""line. - Check it is the right key. This prints a fingerprint of the key without revealing it:
It must printpython3 -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])'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:
- Use
oled_v3_prod- not
oledoroled_v3 - i mean, you can use those if you want to, but your badge won't work
- not
- Don't erase the badge.
- Erasing is for setting up brand-new badges and wipes everything first: including your handle, points and logs. A plain upload replaces only the firmware and keeps your data.
// verify that it worked
The update worked if the badge boots to HOME as you, with your handle and points intact.
- Badge Settings → Power → Deep sleep now exists.
- OPTIONS → Whoami shows
v1.10and a build code with no+on the end. - Near another badge, it shows up in FINDER within a minute.
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 brlttyif the port appears and vanishes. Permission deniedon the port (Linux)- Add yourself to
dialoutand log out and back in. - Build fails with an error about the group key
secrets.his missing, in the wrong place, or the key isn't pasted in whole. It must be atfirmware/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.