<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Usb on Tiziano Basile | Software Engineer</title><link>https://bstz.it/tags/usb/</link><description>Recent content in Usb on Tiziano Basile | Software Engineer</description><generator>Hugo -- gohugo.io</generator><language>en</language><copyright>Tiziano Basile</copyright><lastBuildDate>Sat, 21 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://bstz.it/tags/usb/index.xml" rel="self" type="application/rss+xml"/><item><title>Bonooru Devlog #0: Teaching a Switch 2 to play the ocarina</title><link>https://bstz.it/p/bonooru-devlog-0/</link><pubDate>Sat, 21 Nov 2026 00:00:00 +0000</pubDate><guid>https://bstz.it/p/bonooru-devlog-0/</guid><description>&lt;img src="https://bstz.it/p/bonooru-devlog-0/bonooru-setup.jpg" alt="Featured image of post Bonooru Devlog #0: Teaching a Switch 2 to play the ocarina" /&gt;&lt;p&gt;I want Link to play anything I give him on his ocarina, whether it&amp;rsquo;s a MIDI file, a tune I type in, &lt;em&gt;Ode to Joy&lt;/em&gt; or the theme of some other game, and I want him to do it on my own Switch 2, in the real game, with no mods and without me pressing a single button; this is the first post about how I&amp;rsquo;m building that.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;The Legend of Zelda: Ocarina of Time&lt;/em&gt; came out again on Switch 2, and in this version the ocarina is played with buttons: five buttons give five notes, and the D-pad and the left stick bend them up or down, which turns it into a 19-note chromatic instrument, from B4 to F6, that you play with a controller. &lt;a class="link" href="https://github.com/basteez/bonooru" target="_blank" rel="noopener"
&gt;Bonooru&lt;/a&gt; is my side project that plays that instrument for you, and it&amp;rsquo;s made of a desktop app, which turns a score into a timeline of button presses, and two tiny RP2040-Zero boards, which pretend to be a wired Pro Controller and press the buttons on time. It doesn&amp;rsquo;t play the game for you, it deliberately leaves the 12 official songs alone, and it doesn&amp;rsquo;t touch the console or the game; it&amp;rsquo;s offline, single player, and just for fun.&lt;/p&gt;
&lt;p&gt;The name comes from the game itself: Bonooru is one of the two scarecrows in &lt;em&gt;Ocarina of Time&lt;/em&gt;, the one at Lake Hylia who listens to a melody Link makes up on the ocarina and remembers it, which, for a project about teaching Link songs he doesn&amp;rsquo;t know, felt like a fairly obvious choice.&lt;/p&gt;
&lt;p&gt;The idea isn&amp;rsquo;t entirely mine, either. &lt;a class="link" href="https://riidraw.com" target="_blank" rel="noopener"
&gt;RiiDraw&lt;/a&gt; already uses two RP2040-Zero boards to draw pictures automatically in another Switch game, and I had it running on my console, which was a fairly strong hint that the same two boards could press ocarina buttons just as well as they draw pictures.&lt;/p&gt;
&lt;h2 id="two-boards-and-three-wires"&gt;Two boards and three wires
&lt;/h2&gt;&lt;p&gt;The hardware is two RP2040-Zero boards (a Raspberry Pi RP2040 chip on a board the size of a stamp), three jumper wires and two USB-C data cables, and that&amp;rsquo;s really all of it, with no soldering involved.&lt;/p&gt;
&lt;p&gt;&lt;img src="https://bstz.it/p/bonooru-devlog-0/bonooru-setup.jpg"
width="1280"
height="960"
srcset="https://bstz.it/p/bonooru-devlog-0/bonooru-setup_hu_a23855c855ed734.jpg 480w, https://bstz.it/p/bonooru-devlog-0/bonooru-setup_hu_cf736281e3958a5c.jpg 1024w"
loading="lazy"
alt="The two RP2040-Zero boards on a breadboard, wired to a MacBook and to a Switch 2 in handheld mode resting on the keyboard"
class="gallery-image"
data-flex-grow="133"
data-flex-basis="320px"
&gt;
&lt;em&gt;My setup: the two boards on the breadboard, one cable to the Mac and one to the Switch 2. The Mac screen is blurred, and the Arduino Uno underneath isn&amp;rsquo;t part of it.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src="https://bstz.it/p/bonooru-devlog-0/bonooru-wiring.png"
width="1600"
height="907"
srcset="https://bstz.it/p/bonooru-devlog-0/bonooru-wiring_hu_bd85fbb6d6cc54b2.png 480w, https://bstz.it/p/bonooru-devlog-0/bonooru-wiring_hu_7a275ae71387dbf4.png 1024w"
loading="lazy"
alt="Wiring diagram: PC to bridge RP2040-Zero over USB-C, bridge GP0 TX to controller GP1 RX, controller GP0 TX to bridge GP1 RX, GND to GND, controller to Switch 2 over USB-C"
class="gallery-image"
data-flex-grow="176"
data-flex-basis="423px"
&gt;
&lt;em&gt;The wiring: TX to RX, RX to TX, ground to ground, while 5V and 3V3 stay unconnected. (A schematic: pins are drawn by name, not where they sit on the board.)&lt;/em&gt;&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;flowchart LR
subgraph PC[&amp;#34;PC (Windows / Linux / macOS)&amp;#34;]
APP[&amp;#34;Bonooru app&amp;lt;br/&amp;gt;Rust + egui&amp;#34;]
end
APP -- &amp;#34;USB-CDC&amp;lt;br/&amp;gt;(virtual serial port)&amp;#34; --&amp;gt; BR[&amp;#34;RP2040-Zero #1&amp;lt;br/&amp;gt;bridge&amp;#34;]
BR -- &amp;#34;UART 3.3 V, 460800 baud&amp;lt;br/&amp;gt;GP0/GP1 crossed + GND&amp;#34; --&amp;gt; CT[&amp;#34;RP2040-Zero #2&amp;lt;br/&amp;gt;controller&amp;#34;]
CT -- &amp;#34;USB HID&amp;lt;br/&amp;gt;wired Pro Controller&amp;#34; --&amp;gt; SW[&amp;#34;Switch 2&amp;lt;br/&amp;gt;Ocarina of Time&amp;#34;]&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;The whole system: the app on the PC, the bridge board, the controller board and the console&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;The RP2040-Zero has exactly one USB port, which has to act as a USB &lt;em&gt;device&lt;/em&gt; towards the Switch 2, and since the PC needs a data link of its own, the work is split between two boards: the &lt;em&gt;bridge&lt;/em&gt; talks USB to the PC and UART to the other board, and the &lt;em&gt;controller board&lt;/em&gt; talks UART to the bridge and USB to the console. UART here is just two data wires at 3.3 V plus a common ground, and it&amp;rsquo;s the same layout RiiDraw and its firmware, 2wiCC, use, so I knew it worked on my console before writing a line of code. A USB-to-serial adapter, or a second USB port bit-banged in software with &lt;a class="link" href="https://github.com/sekigon-gonnoc/Pico-PIO-USB" target="_blank" rel="noopener"
&gt;Pico-PIO-USB&lt;/a&gt;, would also work; the second might come back later as an experiment.&lt;/p&gt;
&lt;p&gt;The console also has to accept the controller board as a controller, and there were three candidates: a HORI Pokkén pad (0F0D:0092), which is plain HID with no handshake but which I&amp;rsquo;d only seen in community reports on Switch 2; a Switch 2 Pro Controller (057E:2069), whose handshake includes a key exchange that one open-source project handles; and the wired Switch 1 Pro Controller (057E:2009), which RiiDraw and 2wiCC already use on my console. I went with the last one, the only one I&amp;rsquo;d actually seen working, even if it needs &amp;ldquo;Pro Controller Wired Communication&amp;rdquo; turned on in the system settings and a small handshake that I&amp;rsquo;ll write from public reverse-engineering notes. The firmware keeps the profile behind one interface, so if Nintendo ever drops it another profile can take its place without touching the protocol or the app.&lt;/p&gt;
&lt;p&gt;The firmware for both boards is my own, in C on &lt;a class="link" href="https://github.com/raspberrypi/pico-sdk" target="_blank" rel="noopener"
&gt;pico-sdk&lt;/a&gt; and &lt;a class="link" href="https://github.com/hathach/tinyusb" target="_blank" rel="noopener"
&gt;TinyUSB&lt;/a&gt;. 2wiCC has no licence, so I only use its published binaries for early experiments and read its sources to understand the behaviour, without copying any code, and everything in the repo is MIT.&lt;/p&gt;
&lt;h2 id="keeping-time"&gt;Keeping time
&lt;/h2&gt;&lt;p&gt;What the ocarina cares about is when each button goes down, and since the game runs at 60 frames per second, the goal is to start every note within one frame (16.7 ms) of where it should be, without drifting over a whole song. A PC can&amp;rsquo;t really promise that, because Windows can delay a thread by 1 to 15 ms, USB serial buffers data, and any pause in the app ends up in the music; RiiDraw, which sends its picture frame by frame, ran into desync problems on big drawings.&lt;/p&gt;
&lt;p&gt;The way around it is that the PC doesn&amp;rsquo;t keep time at all: the app compiles the whole piece into a list of events, each one saying &amp;ldquo;at time &lt;em&gt;t&lt;/em&gt;, in microseconds from the start, the controller state becomes &lt;em&gt;s&lt;/em&gt;&amp;rdquo;, and streams them ahead of time to the controller board, which buffers them and applies each one from a 1 MHz hardware timer. All the app has to do is keep that buffer from running empty, with credit-based flow control, where the controller board tells the app how much room it has left.&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;flowchart TB
UART[&amp;#34;UART RX&amp;#34;] --&amp;gt; DEC[&amp;#34;Frame decoder&amp;lt;br/&amp;gt;COBS + CRC, sequence numbers&amp;#34;]
DEC --&amp;gt; MODE[&amp;#34;Modes: IDLE / DIRECT / PLAYING&amp;#34;]
MODE --&amp;gt;|SET_STATE| RT[&amp;#34;Real-time state&amp;lt;br/&amp;gt;(virtual gamepad)&amp;#34;]
MODE --&amp;gt;|QUEUE_EVENT| Q[&amp;#34;Event queue&amp;#34;]
TMR[&amp;#34;1 MHz timer&amp;#34;] --&amp;gt; SCH[&amp;#34;Scheduler&amp;#34;]
Q --&amp;gt; SCH
SCH --&amp;gt; MASK[&amp;#34;Safety mask&amp;lt;br/&amp;gt;ocarina inputs only&amp;#34;]
RT --&amp;gt; CUR[&amp;#34;Current state&amp;#34;]
MASK --&amp;gt; CUR
CUR --&amp;gt; PRF[&amp;#34;Pro Controller profile&amp;lt;br/&amp;gt;builds the USB report&amp;#34;]
PRF --&amp;gt; USB[&amp;#34;TinyUSB HID&amp;#34;]
WD[&amp;#34;Watchdog:&amp;lt;br/&amp;gt;link lost, app silent, USB events&amp;#34;] --&amp;gt;|go neutral| MODE&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;Planned controller firmware: frames in from the UART, events out to USB on a hardware clock&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;The one rule in the spec that outranks everything else is not to hurt the console. The wiring is only GP0, GP1 and GND, never 5 V or 3.3 V, and the firmware never touches the power path; while a song plays, the controller board only lets through the inputs the ocarina needs (L, R, A, X, Y, the D-pad and the left stick), never Home, Capture, + or −, and it refuses any controller firmware-update request from the console. If the link drops mid-song, because I trip over the cable or the app crashes, a watchdog on the controller board releases every button on its own within 100 ms, since a stuck note is merely annoying, while a button held down in a system menu is something I&amp;rsquo;d rather not find out about.&lt;/p&gt;
&lt;p&gt;The app and the controller board speak one small binary protocol, and the bridge in the middle doesn&amp;rsquo;t understand it: it&amp;rsquo;s a frame-aware pipe that forwards whole frames from USB to UART, plus a heartbeat of its own so the controller board knows the bridge is still alive. Frames are COBS-encoded (Consistent Overhead Byte Stuffing, which guarantees that &lt;code&gt;0x00&lt;/code&gt; never appears inside a frame, so it can mark the end of one and the receiver resyncs at the next zero after any garbage), and each one carries a CRC-16 checksum to catch corrupted bytes:&lt;/p&gt;
&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;
&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;
&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;
&lt;td class="lntd"&gt;
&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-fallback" data-lang="fallback"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;type:u8 | seq:u8 | len:u8 | body[len] | crc16:u16le
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;
&lt;/div&gt;
&lt;/div&gt;&lt;p&gt;A controller state is 8 bytes, with 16 button bits, the D-pad as a hat value, two sticks and a flags byte, and those 8 bytes are the same for every profile, with only the profile module turning them into a USB report. The main messages are &lt;code&gt;HELLO&lt;/code&gt; and &lt;code&gt;INFO&lt;/code&gt; to start a session and check versions, &lt;code&gt;SET_STATE&lt;/code&gt; for real-time input from the on-screen gamepad, &lt;code&gt;QUEUE_EVENT&lt;/code&gt; to buffer timed states, &lt;code&gt;START&lt;/code&gt; and &lt;code&gt;STOP&lt;/code&gt; for playback, and &lt;code&gt;STATUS&lt;/code&gt; so the app can show what&amp;rsquo;s going on. I chose binary over a text protocol like 2wiCC&amp;rsquo;s because it&amp;rsquo;s smaller and the CRC catches errors, even if an ASCII line is easier to type in a terminal; for debugging, the app will get a hidden panel that shows and sends raw frames.&lt;/p&gt;
&lt;h2 id="from-a-score-to-button-presses"&gt;From a score to button presses
&lt;/h2&gt;&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;flowchart TB
MID[&amp;#34;.mid file&amp;#34;] --&amp;gt; NRM
TXT[&amp;#34;text score&amp;#34;] --&amp;gt; NRM[&amp;#34;Note list&amp;lt;br/&amp;gt;(pitch, start, duration)&amp;#34;]
NRM --&amp;gt; MONO[&amp;#34;One voice&amp;lt;br/&amp;gt;pick a track, chords → top note&amp;#34;]
MONO --&amp;gt; FIT[&amp;#34;Fit the range&amp;lt;br/&amp;gt;transpose to B4–F6&amp;#34;]
FIT --&amp;gt; FING[&amp;#34;Fingering&amp;lt;br/&amp;gt;cheapest path&amp;#34;]
FING --&amp;gt; QNT[&amp;#34;Timing rules&amp;lt;br/&amp;gt;frame grid, min press and gap&amp;#34;]
QNT --&amp;gt; TL[&amp;#34;Timeline&amp;lt;br/&amp;gt;(t_us, state)&amp;#34;]
PROF[(&amp;#34;Mapping profile&amp;lt;br/&amp;gt;TOML per game version&amp;#34;)] --&amp;gt; FIT &amp;amp; FING &amp;amp; QNT&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;The score pipeline in the app&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;The ocarina plays one note at a time and covers 19 semitones, so most music has to be squeezed into it: one voice, transposed to fit, and whatever still doesn&amp;rsquo;t fit is shown note by note so the user can decide what to do with it. Many pitches can be played in more than one way, with a button plus some modifiers, so the fingering step uses dynamic programming to find the sequence that changes modifiers the least. All the game-specific numbers, which button plays which pitch, how long a press has to be, how long a note can last, live in a mapping profile, a TOML file per game version, so if a game update ever changes the mapping it will take a new file rather than new code. When I wrote the plan most of those numbers came from community guides and were marked &lt;code&gt;HYPOTHESIS&lt;/code&gt;, and measuring them is what the first epic is about.&lt;/p&gt;
&lt;p&gt;The app is written in Rust with &lt;a class="link" href="https://github.com/emilk/egui" target="_blank" rel="noopener"
&gt;egui&lt;/a&gt;/eframe, one native binary per OS (Windows, Linux and macOS), with no toolchain or runtime to install and no terminal to open: you import a song, see it on a piano roll with the fingering of every note, listen to a preview on the PC and then play it on the console. There&amp;rsquo;s also an on-screen gamepad to walk Link to a quiet spot and take out the ocarina, three status lights for the three links, and a wizard that flashes both boards, where you hold BOOT, plug the board in and pick its role. The look evokes the game without borrowing anything from it, so no logos, no character art and no screenshots.&lt;/p&gt;
&lt;p&gt;My first plan was actually Python, but before committing to it I had an agent build a throwaway Rust + egui spike, with device discovery, a piano roll, an audio preview and the flasher logic, and measure it on my Mac:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;Rust + egui spike&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Release binary&lt;/td&gt;
&lt;td&gt;10.9 MB (4.8 MB zipped)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cold start to first frame&lt;/td&gt;
&lt;td&gt;~115 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Frame time with ~2,000 notes on screen&lt;/td&gt;
&lt;td&gt;p95 1.5 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Idle CPU&lt;/td&gt;
&lt;td&gt;0.2 %&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The Python + PySide6 option would have shipped about 113 MB, with LGPL obligations and antivirus false positives from the packager, so the choice turned out to be an easy one.&lt;/p&gt;
&lt;h2 id="where-its-going"&gt;Where it&amp;rsquo;s going
&lt;/h2&gt;&lt;p&gt;The roadmap tackles the hardware risks first. Before I wrote any code, the Switch 2 had already accepted an RP2040-Zero pressing A, through RiiDraw, and I&amp;rsquo;d settled on the wired Pro Controller; next comes measuring the ocarina, then my own controller and bridge firmware, the app with its status lights and gamepad, a first song on the console, timing checks on three operating systems, flashing from the app and, eventually, a 1.0, with a live MIDI keyboard and a calibration wizard as optional extras. What worried me most was that the ocarina wouldn&amp;rsquo;t behave the way the community chart says, and that the scope was too big for a fun project, with the first real song only arriving halfway through; the answer to both is to check the ocarina by hand before writing any code and to get a script playing a whole melody through existing firmware as early as possible, what&amp;rsquo;s usually called a walking skeleton. I&amp;rsquo;ll consider 1.0 done when someone who isn&amp;rsquo;t me can wire two boards, flash both from the app and play a one-minute piece covering all 19 pitches with zero wrong notes.&lt;/p&gt;
&lt;p&gt;I plan and build Bonooru with the &lt;a class="link" href="https://github.com/bmad-code-org/BMAD-METHOD" target="_blank" rel="noopener"
&gt;BMad Method&lt;/a&gt; and AI agents (Claude). It started as a set of notes in my org-roam vault inside Emacs, which became a spec with eight ADRs, then 21 architecture decisions, a UX spec with HTML mockups (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/1" target="_blank" rel="noopener"
&gt;PR #1&lt;/a&gt;) and finally 12 epics and 79 stories (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/2" target="_blank" rel="noopener"
&gt;PR #2&lt;/a&gt;, &lt;a class="link" href="https://github.com/basteez/bonooru/pull/4" target="_blank" rel="noopener"
&gt;PR #4&lt;/a&gt;). Every story then goes through the same loop, a story file with acceptance criteria, a dev agent that implements it, a code review and fixes I approve, and whatever needs the console I run at the console myself. The project was called &amp;ldquo;Ocarina Bot&amp;rdquo; until the end of the first epic, so some early files still carry that name.&lt;/p&gt;
&lt;p&gt;Before writing any firmware, the next step is to grab a real controller, a tuner and a microphone and find out how the ocarina actually behaves, and, without spoiling too much, the community chart turns out to be right about the buttons and wrong about something else.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;This is an unofficial fan project for personal, offline fun. It is not affiliated with, endorsed or sponsored by Nintendo. The Legend of Zelda and Nintendo Switch are trademarks of Nintendo. No game code, assets or console modifications are involved.&lt;/em&gt;&lt;/p&gt;</description></item></channel></rss>