index.html (9005B)
1 <!DOCTYPE html> 2 <html lang="en"> 3 <head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width, initial-scale=1"> 6 <title>onlyn00bs badge · update the firmware</title> 7 <meta name="description" content="Update an OnlyN00bs badge to the latest firmware over USB, keeping your handle, points and log."> 8 <meta name="color-scheme" content="dark light"> 9 <meta property="og:title" content="onlyn00bs badge · update the firmware"> 10 <meta property="og:description" content="Update an OnlyN00bs badge to the latest firmware over USB, keeping your handle, points and log."> 11 <meta property="og:type" content="website"> 12 <meta property="og:site_name" content="virtualshack"> 13 <meta property="og:url" content="https://badge.virtualshack.io/update/"> 14 <meta property="og:image" content="https://badge.virtualshack.io/assets/img/og-badge.jpg"> 15 <meta property="og:image:width" content="1200"> 16 <meta property="og:image:height" content="630"> 17 <meta name="twitter:card" content="summary_large_image"> 18 <meta name="twitter:image" content="https://badge.virtualshack.io/assets/img/og-badge.jpg"> 19 <!-- ?v= must match CACHE in ../sw.js — same rule as index.html --> 20 <link rel="stylesheet" href="../assets/badge.css?v=48"> 21 <link rel="icon" type="image/svg+xml" href="../assets/icon.svg"> 22 <link rel="manifest" href="../manifest.webmanifest"> 23 <meta name="theme-color" content="#212121"> 24 </head> 25 <body class="theme-purple"> 26 <main class="wrapper" id="top"> 27 28 <h1>// update the firmware</h1> 29 <p class="tagline">latest firmware: v1.10 · released 2026-09-26</p> 30 <p class="small muted"><a href="https://virtualshack.io/">virtualshack.io</a> / 31 <a href="../">badge</a> / update</p> 32 33 <p>Updating takes about 15 minutes over USB: you build the firmware from source and flash it 34 with PlatformIO. Your handle, points, friends and encounter log are kept. No OTA (yet).</p> 35 36 <nav class="toc"> 37 <ul> 38 <li><a href="#before">// before you start</a></li> 39 <li><a href="#get">// download the latest firmware</a></li> 40 <li><a href="#connect">// connect the badge</a></li> 41 <li><a href="#flash">// flash the firmware</a></li> 42 <li><a href="#check">// verify that it worked</a></li> 43 <li><a href="#trouble">// troubleshooting</a></li> 44 </ul> 45 </nav> 46 47 <h2 id="before">// before you start</h2> 48 <p>If your badge has <b>Badge Settings → Power → Deep sleep</b>, you already have the latest 49 firmware (v1.10, released 2026-09-26). Badges flashed before 2026-08-05 do not have that 50 menu and need this update.</p> 51 <p>To see your exact build, open <b>OPTIONS → Whoami</b>; it shows something like 52 <code>v1.10 32c3255 ch1</code> (version, build commit, channel).</p> 53 54 <p>You need:</p> 55 <ul> 56 <li><b>A USB-C cable</b></li> 57 <li><b>A computer</b> with <code>git</code> and Python</li> 58 <li><b>PlatformIO Core:</b> <code>pipx install platformio</code> (or 59 <code>pip install platformio</code> i guess) The ESP32 toolchain downloads on first 60 build.</li> 61 <li><b>The group key</b> (64 letters and numbers), ask virtualtack for it. Without it 62 your badge will stop seeing everyone else's.</li> 63 <li><b>The USB driver</b> for the badge's CH340 serial chip: 64 <ul> 65 <li><b>macOS:</b> install <code>CH34xVCPDriver.dmg</code> from 66 <a href="https://github.com/WCHSoftGroup/ch34xser_macos" target="_blank" rel="noopener">WCH on GitHub</a> 67 <ul> 68 <li>Run the app, click Install, then enable it in System Settings → General → Login 69 Items & Extensions → Driver Extensions. Unplug and replug the badge.</li> 70 </ul> 71 </li> 72 <li><b>Linux:</b> already built into the kernel. 73 <ul> 74 <li>Add yourself to the <code>dialout</code> group 75 (<code>sudo usermod -aG dialout $USER</code>, then log out and in).</li> 76 </ul> 77 </li> 78 <li><b>Windows:</b> get the CH340 driver from WCH (CH341SER).</li> 79 </ul> 80 </li> 81 </ul> 82 83 <h2 id="get">// download the latest firmware</h2> 84 <p>Clone the public source and drop the group key into it. The key never goes in git, so it 85 stays only on your machine.</p> 86 <ol> 87 <li>Clone the source: 88 <pre><code>git clone https://git.virtualshack.io/onlyn00bs-badge.git 89 cd onlyn00bs-badge</code></pre></li> 90 <li>Create the key file from its template: 91 <pre><code>cp firmware/src/secrets.h.example firmware/src/secrets.h</code></pre> 92 Open <code>firmware/src/secrets.h</code> and paste the key between the quotes on the 93 <code>#define GROUP_PSK_HEX ""</code> line.</li> 94 <li>Check it is the right key. This prints a fingerprint of the key without revealing it: 95 <pre><code>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])'</code></pre> 96 It must print <code>a4dc586d0276fa51</code>. Anything else means the wrong file: stop and 97 ask for the right one.</li> 98 </ol> 99 <div class="note stop"> 100 <p><b>Don't generate a new key with <code>openssl rand</code>.</b> If you do your badge will 101 be on its own private network, and it will quietly find nobody.</p> 102 </div> 103 104 <h2 id="connect">// connect the badge</h2> 105 <p>No button presses are needed - the flasher resets the badge into update mode. Find its 106 port:</p> 107 <dl> 108 <dt>macOS</dt> 109 <dd><code>ls /dev/cu.wchusbserial*</code> → PORT looks like <code>/dev/cu.wchusbserial10</code></dd> 110 <dt>Linux</dt> 111 <dd><code>ls /dev/ttyUSB*</code> → PORT looks like <code>/dev/ttyUSB0</code></dd> 112 <dt>Windows</dt> 113 <dd>Device Manager → Ports (COM & LPT) → PORT looks like <code>COM3</code> ("USB-SERIAL CH340")</dd> 114 </dl> 115 116 <h2 id="flash">// flash the firmware</h2> 117 <p>One command builds and flashes. From the <code>onlyn00bs-badge</code> folder, replace 118 <code>PORT</code> with your port:</p> 119 <pre><code>pio run -d firmware -e oled_v3_prod -t upload --upload-port PORT</code></pre> 120 <p>The first run takes several minutes while PlatformIO downloads the ESP32 toolchain. Later 121 runs take about 45 seconds. It is done when you see <code>Hash of data verified.</code> 122 followed by <code>[SUCCESS]</code>. Then the badge restarts by itself.</p> 123 <p>Two things to get right:</p> 124 <ul> 125 <li><b>Use <code>oled_v3_prod</code></b> 126 <ul> 127 <li><b>not <code>oled</code> or <code>oled_v3</code></b></li> 128 <li>i mean, you can use those if you want to, but your badge won't work</li> 129 </ul> 130 </li> 131 <li><b>Don't erase the badge.</b> 132 <ul> 133 <li>Erasing is for setting up brand-new badges and wipes everything first: including 134 your handle, points and logs. A plain upload replaces only the firmware and keeps 135 your data.</li> 136 </ul> 137 </li> 138 </ul> 139 140 <h2 id="check">// verify that it worked</h2> 141 <p>The update worked if the badge boots to HOME as you, with your handle and points 142 intact.</p> 143 <ul> 144 <li><b>Badge Settings → Power → Deep sleep</b> now exists.</li> 145 <li><b>OPTIONS → Whoami</b> shows <code>v1.10</code> and a build code with no 146 <code>+</code> on the end.</li> 147 <li>Near another badge, it shows up in <b>FINDER</b> within a minute.</li> 148 </ul> 149 <p>For a closer look, watch the boot log with 150 <code>pio device monitor -p PORT -b 115200</code> (Ctrl-C to exit). It should show 151 <code>build : v1.10 …</code> and <code>mode : DISCOVERY</code> with your handle.</p> 152 153 <h2 id="trouble">// troubleshooting</h2> 154 <dl> 155 <dt>No port appears</dt> 156 <dd>Try a different cable (most likely charge-only). On macOS, check the CH34x driver is 157 enabled in Driver Extensions. On Ubuntu, <code>sudo apt remove brltty</code> if the port 158 appears and vanishes.</dd> 159 <dt><code>Permission denied</code> on the port (Linux)</dt> 160 <dd>Add yourself to <code>dialout</code> and log out and back in.</dd> 161 <dt>Build fails with an error about the group key</dt> 162 <dd><code>secrets.h</code> is missing, in the wrong place, or the key isn't pasted in 163 whole. It must be at <code>firmware/src/secrets.h</code>, with all 64 characters of the 164 key between the quotes and nothing else.</dd> 165 <dt><code>Failed to connect to ESP32</code></dt> 166 <dd>Unplug, replug, and run the command again. Close any serial monitor that has the port 167 open.</dd> 168 <dt>Upload stopped partway</dt> 169 <dd>Run it again. A half-written firmware can't brick the badge, because the bootloader is 170 never touched.</dd> 171 <dt>FINDER shows nobody after the update</dt> 172 <dd>Rerun the key fingerprint check. A wrong key looks exactly like "nobody in range". Then 173 compare <b>Whoami</b> with a friend's badge.</dd> 174 </dl> 175 <p>Still stuck? Send virtualtack the output of <code>pio run</code>.</p> 176 177 <p style="text-align:center"><a class="totop" href="../">← back to the badge</a></p> 178 179 </main> 180 </body> 181 </html>