onlyn00bs-badge

OnlyN00bs: a DEF CON 34 friend-finder badge. ESP32 firmware, Web Bluetooth setup app, printable case
git clone https://git.virtualshack.io/onlyn00bs-badge.git
Log | Files | Refs | README | LICENSE

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 &amp; 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 &amp; 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>