<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Nintendo-Switch on Tiziano Basile | Software Engineer</title><link>https://bstz.it/tags/nintendo-switch/</link><description>Recent content in Nintendo-Switch on Tiziano Basile | Software Engineer</description><generator>Hugo -- gohugo.io</generator><language>en</language><copyright>Tiziano Basile</copyright><lastBuildDate>Sun, 22 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://bstz.it/tags/nintendo-switch/index.xml" rel="self" type="application/rss+xml"/><item><title>Bonooru Devlog #1: Measuring an ocarina before writing any firmware</title><link>https://bstz.it/p/bonooru-devlog-1/</link><pubDate>Sun, 22 Nov 2026 00:00:00 +0000</pubDate><guid>https://bstz.it/p/bonooru-devlog-1/</guid><description>&lt;img src="https://bstz.it/p/bonooru-devlog-1/bonooru-wiring.png" alt="Featured image of post Bonooru Devlog #1: Measuring an ocarina before writing any firmware" /&gt;&lt;p&gt;The Switch 2 just played &lt;em&gt;Ode to Joy&lt;/em&gt; on Link&amp;rsquo;s ocarina, 62 notes out of 62, three times in a row, without me touching the controller once and without a single line of my own firmware involved, which is an odd place for a firmware project to start; this post is about the two days of measuring that came before it.&lt;/p&gt;
&lt;p&gt;&lt;a class="link" href="https://github.com/basteez/bonooru" target="_blank" rel="noopener"
&gt;Bonooru&lt;/a&gt; is my side project to play arbitrary melodies on the ocarina in &lt;em&gt;The Legend of Zelda: Ocarina of Time&lt;/em&gt; on Switch 2 by pretending to be a wired controller, and &lt;a class="link" href="https://bstz.it/p/bonooru-devlog-0/" target="_blank" rel="noopener"
&gt;Devlog #0&lt;/a&gt; explains the idea, the two boards and the plan:&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;span class="lnt"&gt; 2
&lt;/span&gt;&lt;span class="lnt"&gt; 3
&lt;/span&gt;&lt;span class="lnt"&gt; 4
&lt;/span&gt;&lt;span class="lnt"&gt; 5
&lt;/span&gt;&lt;span class="lnt"&gt; 6
&lt;/span&gt;&lt;span class="lnt"&gt; 7
&lt;/span&gt;&lt;span class="lnt"&gt; 8
&lt;/span&gt;&lt;span class="lnt"&gt; 9
&lt;/span&gt;&lt;span class="lnt"&gt;10
&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;PC (desktop app)
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; │ USB
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; ▼
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;bridge (RP2040-Zero)
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; │ UART
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; ▼
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;controller (RP2040-Zero)
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; │ USB
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; ▼
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Switch 2
&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;Before this epic I had a spec, an architecture, a UX design and a backlog of 12 epics, all of it on paper, and on the hardware side two RP2040-Zero boards on a breadboard flashed with &lt;a class="link" href="https://github.com/knflrpn/2wiCC" target="_blank" rel="noopener"
&gt;2wiCC&lt;/a&gt; and &lt;a class="link" href="https://github.com/knflrpn/2wiCC_Comms" target="_blank" rel="noopener"
&gt;2wiCC_Comms&lt;/a&gt; by knflrpn, the two-board controller firmware that &lt;a class="link" href="https://riidraw.com" target="_blank" rel="noopener"
&gt;RiiDraw&lt;/a&gt; uses; the only thing I had actually checked was that a command typed in a terminal could press A on the console. (During this epic the project was still called &amp;ldquo;Ocarina Bot&amp;rdquo;, so some files linked below carry the old name.)&lt;/p&gt;
&lt;p&gt;&lt;img src="https://bstz.it/p/bonooru-devlog-1/bonooru-wiring.png"
width="1600"
height="907"
srcset="https://bstz.it/p/bonooru-devlog-1/bonooru-wiring_hu_bd85fbb6d6cc54b2.png 480w, https://bstz.it/p/bonooru-devlog-1/bonooru-wiring_hu_7a275ae71387dbf4.png 1024w"
loading="lazy"
alt="Wiring diagram of the two RP2040-Zero boards between the PC and the Switch 2"
class="gallery-image"
data-flex-grow="176"
data-flex-basis="423px"
&gt;
&lt;em&gt;The same two-board wiring as in Devlog #0. During Epic 1 the bridge ran 2wiCC_Comms and the controller board ran 2wiCC.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The whole plan rests on facts about the game that I had only read in community guides, which buttons play which notes, how the pitch modifiers work, how short a note can be and how long it can last, and if any of those were wrong the score compiler, the mapping file and the timing rules of my firmware would all rest on guesses. So Epic 1 meant no firmware of mine and no app yet, just measuring first on my own Switch 2 and getting a melody out early enough to hear the whole thing work end to end, what&amp;rsquo;s usually called a walking skeleton. It took six stories and seven PRs over two days.&lt;/p&gt;
&lt;h2 id="by-hand-with-a-tuner"&gt;By hand, with a tuner
&lt;/h2&gt;&lt;p&gt;The cheapest test needs no hardware at all, just a real Joy-Con 2, the game in ocarina free play and a tuner app on my phone, so that&amp;rsquo;s where I started (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/5" target="_blank" rel="noopener"
&gt;PR #5&lt;/a&gt;). The community chart says L, R, A, Y and X play D4, F4, A4, B4 and D5; the pairing was right, but every note sounded one octave higher, D5, F5, A5, B5, D6, and the same went for all 19 fingerings in the chart, so from then on the project uses the &lt;em&gt;sounding&lt;/em&gt; pitch everywhere (profile, UI, docs) and keeps the chart names only to cross-reference guides. The playable range is B4 to F6, 19 chromatic pitches, with the D-pad shifting a note by ±1 semitone, the left stick by ±2 and both together by ±3.&lt;/p&gt;
&lt;p&gt;The rest of the session was about how the ocarina behaves over time. Holding a button sustains the note, but it starts to waver after about 2 s and stops by itself at about 6 s; pressing a new button while one is held cuts the old note, and releasing the new one brings the first note back, so the old button has to be released; changing the D-pad while a note sounds steps the pitch at once, while the stick glides, so portamento is possible. Free play survived 100 notes in a row and a minute of idling without closing, and two of the answers changed actual decisions. D-pad ← is a toggle that both opens and closes the ocarina, and notes are only accepted about 2 s after opening, so the app won&amp;rsquo;t take the ocarina out by itself: it can&amp;rsquo;t see the screen, and an automatic press would close an ocarina the user had already opened. ZL, on the other hand, opens the song menu, ZR does nothing and the right stick moves the camera, which confirmed the allow-list for my firmware (only L, R, A, X, Y, the D-pad and the left stick reach the console while a song plays) and made masking ZL a feature rather than a restriction.&lt;/p&gt;
&lt;p&gt;The test I was most nervous about was row 1.8. The game has 12 official songs with in-game effects, and if a melody happens to contain one the song triggers and free play ends mid-piece; my hope was to dodge that by playing one note on an alternative fingering. I played Zelda&amp;rsquo;s Lullaby on natural notes and it was recognised, then with the first B as A + stick↑ and it was recognised again, then with the first D as Y + D↑ + stick↑, with the same result, so the game matches songs by pitch rather than by button, whatever the tempo, and the mitigation in the risk register went from &amp;ldquo;alternative fingering&amp;rdquo; to &amp;ldquo;warn only&amp;rdquo;: the score compiler will detect official song sequences and warn about them.&lt;/p&gt;
&lt;h2 id="a-sender-for-someone-elses-queue"&gt;A sender for someone else&amp;rsquo;s queue
&lt;/h2&gt;&lt;p&gt;Measuring timing by hand is hopeless, so I needed a script that sends timed controller states to the 2wiCC bridge (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/7" target="_blank" rel="noopener"
&gt;PR #7&lt;/a&gt;): a throwaway one-file Python spike, MIT like the rest of the repo, with the 2wiCC binaries used for testing only and never committed, since 2wiCC has no licence and I only read its README and sources to describe the behaviour in my own words. The wire format is ASCII lines at 460800 baud, 8N1:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+SPM BUF&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;switch to buffered playback (power-up mode is real-time)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+QD hhhhhh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;queue one 60 Hz frame, 3 digital bytes, sticks centred&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+QF hh…hh&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;queue one frame, 3 digital + 6 analog bytes (12-bit sticks)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+SPM RT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;back to real-time: the backlog is discarded&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;+QD 000000&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;neutral&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The 2wiCC queue holds 1024 frames and plays one per frame, and my input files are rows of &lt;code&gt;time buttons hat stick&lt;/code&gt; in the same canonical state my own firmware will use later, with a single &lt;code&gt;encode()&lt;/code&gt; function that knows the 2wiCC layout. Most of the thinking went into pacing, because if you fill the queue too much a Ctrl+C has a long backlog to throw away, and if you let it run empty 2wiCC keeps the last state, which on an ocarina means a note that never ends; so the pacer keeps the lead, frames sent minus frames played as estimated from the host clock, between 1 and 30 frames, and treats an empty queue as a hard error:&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;span class="lnt"&gt; 2
&lt;/span&gt;&lt;span class="lnt"&gt; 3
&lt;/span&gt;&lt;span class="lnt"&gt; 4
&lt;/span&gt;&lt;span class="lnt"&gt; 5
&lt;/span&gt;&lt;span class="lnt"&gt; 6
&lt;/span&gt;&lt;span class="lnt"&gt; 7
&lt;/span&gt;&lt;span class="lnt"&gt; 8
&lt;/span&gt;&lt;span class="lnt"&gt; 9
&lt;/span&gt;&lt;span class="lnt"&gt;10
&lt;/span&gt;&lt;span class="lnt"&gt;11
&lt;/span&gt;&lt;span class="lnt"&gt;12
&lt;/span&gt;&lt;span class="lnt"&gt;13
&lt;/span&gt;&lt;span class="lnt"&gt;14
&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-python" data-lang="python"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;first&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;max_lead&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="n"&gt;t0&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;clock&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;write&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lines_to_bytes&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="n"&gt;PREAMBLE&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="n"&gt;commands&lt;/span&gt;&lt;span class="p"&gt;[:&lt;/span&gt;&lt;span class="n"&gt;first&lt;/span&gt;&lt;span class="p"&gt;]]))&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;first&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="k"&gt;while&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;played&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;played&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;lead&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;played&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;lead&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="n"&gt;Underrun&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sa"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;host fell behind at frame &lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="s2"&gt; (lead &lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="n"&gt;lead&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;); stopping&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="n"&gt;target&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;played&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;max_lead&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;target&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;write&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;lines_to_bytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;commands&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;target&lt;/span&gt;&lt;span class="p"&gt;]))&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;target&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="bp"&gt;self&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;sleep&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;period&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&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;&lt;em&gt;Trimmed from &lt;a class="link" href="https://github.com/basteez/bonooru/blob/2f90b00/spikes/send_2wicc.py#L431-L454" target="_blank" rel="noopener"
&gt;&lt;code&gt;spikes/send_2wicc.py#L431-L454&lt;/code&gt;&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;sequenceDiagram
participant S as send_2wicc.py (Mac)
participant B as Bridge (2wiCC_Comms)
participant C as Controller (2wiCC)
participant N as Switch 2
S-&amp;gt;&amp;gt;B: +SPM BUF, then up to 30 × +QD/+QF
B-&amp;gt;&amp;gt;C: UART 460800 8N1
loop every 8.3 ms
C-&amp;gt;&amp;gt;N: one frame per 16.7 ms tick
S-&amp;gt;&amp;gt;B: top up so 0 &amp;lt; lead ≤ 30
end
Note over S: end of file, Ctrl+C, SIGTERM or error
S-&amp;gt;&amp;gt;B: +SPM RT (drop the backlog)
S-&amp;gt;&amp;gt;B: +QD 000000 (neutral)
C-&amp;gt;&amp;gt;N: all buttons released&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;One run of send_2wicc.py: preamble and prefill, top-ups every half frame, and the stop sequence on every exit path&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;The stop sequence has to run on every exit, and code review found two ways a second signal could skip it, so &lt;code&gt;play()&lt;/code&gt; now ignores SIGINT, SIGTERM and SIGHUP as the first statement of its &lt;code&gt;finally&lt;/code&gt;, before sending &lt;code&gt;+SPM RT&lt;/code&gt; and &lt;code&gt;+QD 000000&lt;/code&gt;, with a regression test that fails with the old order.&lt;/p&gt;
&lt;p&gt;In the first session commands from the PC mostly worked, but replies came back as &lt;code&gt;+2wicc��&lt;/code&gt; and &lt;code&gt;+GQS&amp;lt;&amp;lt;48&amp;lt;�&lt;/code&gt; and the stop probes were inconsistent; the culprit, a little embarrassingly, was the breadboard, where the two GND pins sat on power rails I hadn&amp;rsquo;t bridged, so the boards had no common ground. Once the rails were bridged (0.1 Ω measured from GND to GND) everything behaved, a ground continuity check became step one of every session in the test plan, and every result from before the fix went in the bin. After that the L R A Y X scale played in order, D5 F5 A5 B5 D6 on the tuner, and Ctrl+C in the middle of a note stopped it at once with exit code 130; the first run of the scale didn&amp;rsquo;t play at all, though, because the game was showing a &amp;ldquo;connect controller&amp;rdquo; prompt, and that turned out to be a pattern: after the controller is connected, powered on or re-plugged, the first injected input is ignored and the second one works, so from then on every session sacrificed its first A.&lt;/p&gt;
&lt;h2 id="the-stick-bends"&gt;The stick bends
&lt;/h2&gt;&lt;p&gt;I expected the left stick to work like a button with a threshold, where past some deflection it counts as &amp;ldquo;up&amp;rdquo; and the pitch jumps by 2 semitones, so I wrote trials to find that threshold (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/8" target="_blank" rel="noopener"
&gt;PR #8&lt;/a&gt;) and a helper, &lt;code&gt;listen_trial.py&lt;/code&gt;, that plays a trial file while recording the MacBook microphone and reports the pitch of every press. It turns out there&amp;rsquo;s no threshold at all: the stick bends the pitch gradually, close to linear in cents (1 cent = 1/100 of a semitone), about 25 cents per 0x10 step of the 8-bit stick value, with no dead zone, and reaches the full ±2 semitones only at full travel.&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;xychart-beta
title &amp;#34;Stick bend on A5&amp;#34;
x-axis &amp;#34;Vertical deflection (% of full travel)&amp;#34; [0, 12, 25, 38, 50, 62, 75, 88, 100]
y-axis &amp;#34;Bend (cents)&amp;#34; -220 --&amp;gt; 220
line [0, 24, 49, 78, 105, 134, 160, 185, 199]
line [0, -24, -50, -76, -105, -132, -159, -184, -197]&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;Pitch bend of A5 vs left stick deflection (test plan row 1.6, one note per step, cents vs the A5 at rest). The last down step is 99 % of travel (0xFF).&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;Half travel gives about ±105 cents, which a tuner happily reads as the next semitone but which is 5 cents away from being wrong. Diagonals were another surprise, because the stick at full travel in a corner gives about ±142 cents, the same as a diagonal on the circle, which fits the game clamping the stick vector to the unit circle and bending by its vertical component (0.707 × 200 ≈ 141); so the profile uses a pure vertical stick at full travel, &lt;code&gt;ly = 0x00&lt;/code&gt; up and &lt;code&gt;ly = 0xFF&lt;/code&gt; down with &lt;code&gt;lx&lt;/code&gt; centred.&lt;/p&gt;
&lt;p&gt;Then I tried all 45 combinations (5 buttons × D-pad none/↑/↓ × stick none/↑/↓), and every one gave the model pitch, button + D-pad ±1 + stick ±2, by nearest note. Nine modifier states give seven offsets, from −3 to +3, so the 45 inputs cover the 19 pitches with one to four fingerings each: G♯5, A♯5 and C6 can be played four ways, B4, C5, E6 and F6 only one. The game also isn&amp;rsquo;t tuned to A4 = 440 Hz, since A5 reads about 894 Hz, roughly 27 cents sharp, and on X the D-pad shifts by about ±115 cents instead of 100; every note still reads as the right note, so I wrote both down and moved on.&lt;/p&gt;
&lt;h3 id="then-the-microphone"&gt;Then the microphone
&lt;/h3&gt;&lt;p&gt;The first live calibration reported no sound for an A5 that was clearly there (894 Hz, +28 c), because two problems had stacked up: the signal-to-noise ratio was computed over the whole band, where sub-200 Hz room noise dominated, and the ffmpeg avfoundation capture was silently dropping about 9 % of the samples, so the analysis windows drifted late and the &amp;ldquo;noise before the press&amp;rdquo; window contained the note itself. In a later session the same capture delivered only 78 % of real time, so it was replaced by a lossless capture through PortAudio (&lt;code&gt;sounddevice&lt;/code&gt;) with its own self-test (a 1 kHz tone for 60 s, delivered-sample ratio 1.00000), and levels are now measured at the expected pitch instead of over the whole band. Something similar had already happened by hand, when one reading of the D-pad bend said 311 Hz instead of 932 Hz because the tuner had locked onto a subharmonic (932 / 3) during the change; holding both for 2 s fixed it, and in hindsight it was a fair warning of what automated pitch detection would do to me later.&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;flowchart LR
G[gen_trials_*.py&amp;lt;br/&amp;gt;trial files, committed] --&amp;gt; L[listen_trial.py]
L --&amp;gt; S[send_2wicc.py --announce]
S --&amp;gt;|USB CDC| B[bridge&amp;lt;br/&amp;gt;2wiCC_Comms]
B --&amp;gt;|UART| C[controller&amp;lt;br/&amp;gt;2wiCC]
C --&amp;gt;|USB| N[Switch 2&amp;lt;br/&amp;gt;free play]
N -.-&amp;gt;|speaker| M[MacBook mic&amp;lt;br/&amp;gt;PortAudio, lossless]
M --&amp;gt; L
L --&amp;gt; R[CSV + Markdown report&amp;lt;br/&amp;gt;git-ignored]&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;The measurement loop used from Story 1.3 on&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;h2 id="how-fast-it-can-play"&gt;How fast it can play
&lt;/h2&gt;&lt;p&gt;The next question was how fast the bot can play (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/9" target="_blank" rel="noopener"
&gt;PR #9&lt;/a&gt;), which comes down to four numbers, each defined as the smallest value that passes 20 out of 20 tries. The trial generator writes every time in frames, interleaves the steps in shuffled rounds so that a step isn&amp;rsquo;t always at the same phase of the game&amp;rsquo;s frame, and adds a warm-up press and controls to every file: blanks, which must stay silent, a gap of 0 frames, which must read as one held note, and a gap of 30 frames, which must clearly read as two.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;th&gt;Detail&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Shortest press that always sounds&lt;/td&gt;
&lt;td&gt;2 frames (33.3 ms)&lt;/td&gt;
&lt;td&gt;20/20 on all five buttons; 1 frame sounds only 16 to 18 of 20, and a 1-frame press still sounds for 0.1 to 0.2 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shortest release between two presses of the same button&lt;/td&gt;
&lt;td&gt;5 frames (83.3 ms), my choice&lt;/td&gt;
&lt;td&gt;20/20 at 4 frames on A, L and Y; R and X not fully resolved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;How early a modifier must be set&lt;/td&gt;
&lt;td&gt;0 frames&lt;/td&gt;
&lt;td&gt;set in the same frame as the button, no wrong pitch longer than about 35 ms, 20/20 at every lead from 0 to 5&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Frame rate while playing&lt;/td&gt;
&lt;td&gt;60 Hz (16.67 ms)&lt;/td&gt;
&lt;td&gt;240 fps phone video of the screen, median run of 4 identical capture frames&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The retrigger gap turned out not to be a clean yes or no: while the button is up the note decays, and the dip between the two notes deepens smoothly with the gap.&lt;/p&gt;
&lt;figure class="mermaid-figure"&gt;
&lt;pre class="mermaid"&gt;xychart-beta
title &amp;#34;Same-button retrigger on A&amp;#34;
x-axis &amp;#34;Release gap (frames)&amp;#34; [1, 2, 3, 4, 5, 6]
y-axis &amp;#34;Retriggers out of 20&amp;#34; 0 --&amp;gt; 20
bar [0, 4, 19, 20, 20, 20]&lt;/pre&gt;
&lt;figcaption class="mermaid-caption"&gt;Same-button retrigger on A: retriggers detected out of 20 per gap (test plan row 2.2; threshold 11.8 dB from the pooled controls)&lt;/figcaption&gt;
&lt;/figure&gt;
&lt;p&gt;So &amp;ldquo;retrigger&amp;rdquo; is a threshold on a continuous dip, and the threshold depends on the button; X (D6) is quiet at the microphone, with a full dip only about 13 dB above the noise, so 4 frames gave 18/20 and I couldn&amp;rsquo;t tell the game apart from the microphone. I picked 5 frames for the profile and wrote down that it&amp;rsquo;s a choice rather than a measured limit.&lt;/p&gt;
&lt;p&gt;For jitter I played a 30 s passage of sixteenth notes at 120 BPM, 240 notes, through the 2wiCC queue three times: 237 to 240 notes matched each run, the error on the interval between two note starts had a σ of 8.07 to 11.67 ms (0.48 to 0.70 of a frame), p95 between 18.8 and 21.1 ms and a worst case of 22.9 ms, always under the one-frame target, with a median latency of 123 to 139 ms from the scheduled press to the sound. The per-note latency fell into two clusters one frame apart, which is what you&amp;rsquo;d expect if the game samples input once per 60 Hz frame and my host-clocked sender isn&amp;rsquo;t phase-locked to it. Keep in mind that this measures 2wiCC&amp;rsquo;s queue and my Mac&amp;rsquo;s clock rather than my own firmware&amp;rsquo;s scheduler, which gets its turn in Epic 2.&lt;/p&gt;
&lt;h3 id="when-the-analysers-were-wrong"&gt;When the analysers were wrong
&lt;/h3&gt;&lt;p&gt;Most of what I learned in this story was about measuring rather than about the game, because three of my analysers kept producing numbers that looked plausible and were wrong. The broadband signal-to-noise ratio made room noise &amp;ldquo;sound&amp;rdquo; at 5 to 14 dB and made the quiet X fail, while measured at the expected pitch X notes are 14 to 23 dB and blanks at most 6.8 dB; short-window YIN, a common pitch detector, locked onto f/2, f/3 or 2f on noisy notes, so X read as G4 or D5 and lead errors of over 1000 cents appeared out of nowhere until I switched to spectral peaks searched near the expected pitch; and generic onset detection found about 385 onsets for 240 notes, with a latency search that locked onto the wrong offsets and invented a drift, until per-button envelopes with one latency per run fixed it. Each fix has a synthetic test for its trap, and there&amp;rsquo;s a caveat I also kept in the profile: these numbers come from analysers I revised after seeing the recordings, so the borderline values (1-frame presses, 2 to 3 frame gaps, the jitter σ) should be confirmed later, in the timing epic, on fresh recordings with a frozen analyser.&lt;/p&gt;
&lt;h2 id="a-whole-melody"&gt;A whole melody
&lt;/h2&gt;&lt;p&gt;All of the above went into the bundled mapping profile, &lt;code&gt;app/profiles/oot-switch2-1.1.1.toml&lt;/code&gt; (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/10" target="_blank" rel="noopener"
&gt;PR #10&lt;/a&gt;), with the buttons, the modifiers, the stick bytes, the range, the timing, the fingering cost weights and all 45 fingerings, and with a tag on every value saying where it came from (&lt;code&gt;MEASURED&lt;/code&gt;, &lt;code&gt;MARGIN&lt;/code&gt; for a measured value plus a safety margin, &lt;code&gt;OWNER CHOICE&lt;/code&gt;, &lt;code&gt;ESTIMATE&lt;/code&gt; or &lt;code&gt;DESIGN DEFAULT&lt;/code&gt;) plus the test plan row, so that nothing ends up labelled as measured unless it actually was.&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;span class="lnt"&gt; 2
&lt;/span&gt;&lt;span class="lnt"&gt; 3
&lt;/span&gt;&lt;span class="lnt"&gt; 4
&lt;/span&gt;&lt;span class="lnt"&gt; 5
&lt;/span&gt;&lt;span class="lnt"&gt; 6
&lt;/span&gt;&lt;span class="lnt"&gt; 7
&lt;/span&gt;&lt;span class="lnt"&gt; 8
&lt;/span&gt;&lt;span class="lnt"&gt; 9
&lt;/span&gt;&lt;span class="lnt"&gt;10
&lt;/span&gt;&lt;span class="lnt"&gt;11
&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-toml" data-lang="toml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;timing&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# MARGIN: measured 2 frames (33.3 ms), profile 3 frames (50 ms), margin +1 frame (test plan row 2.1, U7).&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;min_press_frames&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# OWNER CHOICE: 5 frames (83.3 ms), NOT a measured limit (test plan row 2.2, U2).&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;min_gap_same_button_frames&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# MARGIN: measured 0 frames, profile 1 frame (16.7 ms), margin +1 frame (test plan row 2.3, U5).&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;modifier_lead_frames&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# MARGIN: measured 6500 ms, profile 6000 ms, margin 500 ms (test plan row 1.10, U1; Story 1.6).&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;max_sustain_ms&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;6000&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="c"&gt;# DESIGN DEFAULT (not measured): lead before the first event of a timeline.&lt;/span&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nx"&gt;start_lead_ms&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt;
&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;&lt;em&gt;Comments shortened; full file: &lt;a class="link" href="https://github.com/basteez/bonooru/blob/2f90b00/app/profiles/oot-switch2-1.1.1.toml#L68-L95" target="_blank" rel="noopener"
&gt;&lt;code&gt;app/profiles/oot-switch2-1.1.1.toml#L68-L95&lt;/code&gt;&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The 45 fingerings were transcribed from the measured table rather than generated from the model, and a test checks them against the model, so the two stay independent; pitches are MIDI numbers of the sounding pitch (A = 81 = A5), and the profile is tied to a game version, so if a patch ever changes the mapping I&amp;rsquo;ll write a new file rather than new code. The &lt;code&gt;max_sustain_ms&lt;/code&gt; value came at the very end of the epic, from timing held notes on A five times per length: up to 6.5 s the note lasted until the release every time, at 7 s it stopped by itself three times out of five, and the 10 s controls stopped between 6599 and 7157 ms, so the profile takes 6000 ms. I didn&amp;rsquo;t measure L, R, Y and X and decided to assume they behave like A, which the profile comment says, and the session had an extra noise source, an air fryer running in the room, so any odd pitches in those recordings were dinner.&lt;/p&gt;
&lt;p&gt;The last story was about playing a whole melody, from a hand-written note list through the measured profile to the console (&lt;a class="link" href="https://github.com/basteez/bonooru/pull/11" target="_blank" rel="noopener"
&gt;PR #11&lt;/a&gt;). I picked the &lt;em&gt;Ode to Joy&lt;/em&gt; theme (Beethoven, public domain) and transposed it to G major at G5 so it fits the range, 62 notes and 64 beats from D5 to D6, and a generator reads every value from the TOML, picks the chart fingering for each note and applies the timing rules.&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;span class="lnt"&gt;2
&lt;/span&gt;&lt;span class="lnt"&gt;3
&lt;/span&gt;&lt;span class="lnt"&gt;4
&lt;/span&gt;&lt;span class="lnt"&gt;5
&lt;/span&gt;&lt;span class="lnt"&gt;6
&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;# A (bars 1-4): 3 3 4 5 | 5 4 3 2 | 1 1 2 3 | 3. 2 2
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;B5 1
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;B5 1
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;C6 1
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;D6 1
&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;...
&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;&lt;em&gt;&lt;a class="link" href="https://github.com/basteez/bonooru/blob/2f90b00/spikes/samples/story-1-6/ode-to-joy.melody" target="_blank" rel="noopener"
&gt;&lt;code&gt;spikes/samples/story-1-6/ode-to-joy.melody&lt;/code&gt;&lt;/a&gt;: sounding pitch and length in beats&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The first run at 60 BPM sounded generally good, with some notes missing; the analyser said 56 of 62 notes were audible and every audible note was at the right pitch, and the second run was the same, except that this time I watched the screen and saw that during the silent notes nothing happened at all, as if the button hadn&amp;rsquo;t been pressed. So I started cutting the melody into pieces. With notes 1 to 16 shifted 4 s later and everything 2wiCC sent back logged, note 7 was cut short and note 8 was missing, the event moved with the notes rather than with the elapsed time, and the firmware said nothing at all; notes 6 to 8 on their own played fine three times out of three, while notes 1 to 8 failed in the same way twice out of two. Seventeen identical A5 notes all sounded, but I heard a longer pause after the 7th and the 14th, and I heard it before the analyser did. Then I capped every press at 400 ms, with a neutral gap before every note, and notes 1 to 8 played 8 out of 8, and the full melody 62 out of 62 after re-analysis.&lt;/p&gt;
&lt;p&gt;As far as I can tell, with long (legato) presses the game ends a held note 0.54 to 0.91 s after it starts roughly every seventh sounded note, then ignores input for up to about a second, so a note that follows by hand-over (the next button pressed as the old one is released) gets lost. The audio really is silent, the later notes stay on schedule and 2wiCC reports nothing; I have no idea what the mechanism is, so for now it stays a hypothesis, and the workaround for the spike is staccato, every press capped at 400 ms. For the real pipeline I&amp;rsquo;d rather split long notes into repeated short presses so durations stay audible, but that&amp;rsquo;s a follow-up I haven&amp;rsquo;t tested yet.&lt;/p&gt;
&lt;p&gt;There was one more missing note, and that one was on me, or rather on Beethoven. At 90 BPM, with the cap, I heard the second note of the last phrase go missing, while the analyser said every note sounded and the recording showed both B5 presses at full level: the file used Beethoven&amp;rsquo;s syncopated entry, where the B5 starts on beat 4 and is tied over the bar line, and with a 400 ms cap that becomes a short early B5 followed by almost a second of silence over the downbeat, which my ear heard as a hole. I switched to the simplified rhythm most people know, with two B attacks on beats 1 and 2, the same 62 notes and 64 beats, and it finally sounded the way I remember it.&lt;/p&gt;
&lt;p&gt;The three official runs at 90 BPM with the final file were 62 out of 62 audible and in tune each time, within −3 to +2 cents, and they sounded fine to me (the third has one raw &amp;ldquo;cut&amp;rdquo; flag on a D6 that faded to 300 of its 400 ms, which reads as the quiet X note fading rather than a drop). I haven&amp;rsquo;t shown 60 BPM with the final file, the 120 BPM stress run or legato playing, and of everything in this epic, the times my ear and the analyser disagreed were the most useful: once the ear was right, with the pause after the seventh note, and once the score was &amp;ldquo;wrong&amp;rdquo;, with the syncopation, and recording both side by side is the only reason I found out.&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), and the spike stories were split in two: the generators, the sender, the analysers and the tests need no console, so an agent wrote them alone, while everything that needs the Switch I ran at the console myself, with the agent preparing the trial files and recording the numbers exactly as measured. At the end of the epic &lt;code&gt;spikes/&lt;/code&gt; had 570 tests, none of which needs hardware, and all the measurements live in &lt;a class="link" href="https://github.com/basteez/bonooru/blob/2f90b00/docs/test-plan.md" target="_blank" rel="noopener"
&gt;&lt;code&gt;docs/test-plan.md&lt;/code&gt;&lt;/a&gt; and &lt;a class="link" href="https://github.com/basteez/bonooru/blob/2f90b00/docs/ocarina-input-mechanics.md" target="_blank" rel="noopener"
&gt;&lt;code&gt;docs/ocarina-input-mechanics.md&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Everything in &lt;code&gt;spikes/&lt;/code&gt; will be thrown away; what I keep from Epic 1 is the profile and the measurements, along with the slightly uncomfortable feeling of having spent two days on someone else&amp;rsquo;s firmware, which is why the next devlog is about my own controller firmware on the RP2040 and the first time the Switch 2 accepts it as a controller.&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><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>