mockband/docs/tech-notes.md

Technical Notes
===============

It took me a lot of time digging around the Internet to find some of this stuff.
I'm writing down the highlights here,
so that when original sources fall off the net,
hopefully at least my notes will still be around.


Sample Rate
-----------

The number of samples taken since the last HID report
is sent as the second Y axis.
If you `#define DEBUG`,
you can use the 
[included gamepad tester](gamepad.html),
to see the approximate number of samples as an integer,
on the first X axis.

This is approximate,
because the browser encodes the value as a real number between -1 and 1.
We convert it back, but may lose a little precision.
It's close enough for me,
hopefully it's close enough for you.


Debouncing
----------

Using `millis()` time to debounce the switch
roughly halved my sample frequency.
So instead, I do some preprocessor arithmetic
to calculate how many samples to take after an edge,
in order to debounce switches.

The drum controller was a partcular pain:
in addition to the switch bouncing,
the stick was bouncing on the rubber pad.
I settled on a 40ms silence window as feeling pretty good.
You can adjust this if you want to.



USB Junk
========

Gamepad Buttons
---------------

The `buttons` struct member is a bitmap,
each bit mapping to one of the 12 buttons reported through HID.
Here's what each bit means:

* 0o00: Blue
* 0o01: Green
* 0o02: Red
* 0o03: Yellow
* 0o04: Orange
* 0o05: Tilt Switch / 2x kick
* 0o06: Solo modifier (second row of buttons on guitar)
* 0o07: ???
* 0o10: Minus
* 0o11: Plus
* 0o12: Drum pad modifier
* 0o13: Cymbal modifier
* 0o14: Select


hatAndConstant
--------------

The HAT switch reports its position like a clock.

    7   0   1

    6   8   2

    5   4   3

0 is up,
2 is right,
4 is down,
6 is left,
and 8 is centered.


velocity
--------

I don't know how I can verify that I'm setting this right,
but the `rbdrum2midi` program looks at these bytes to detect hits.
I set them to 127 when a hit is detected on the digital pin.

Sending these values does not seem to cause problems with my Wii games.


Product ID (PID)
----------------

Nicholas,
who did the initial work on the guitar,
suggested that PID 0x0005 would get the sketch working as drums.
And that was correct:
this works great on 
Wii Rock Band 1 and 
Wii LEGO Rock Band.

But it fails in frustrating ways on
Wii Rock Band 3:
the yellow and blue pads don't navigate menus,
and cymbals aren't detected.

The fix was setting the USB PID to 0x3110.


Drum Velocity
--------

I split the 12 "reserved" bytes from Nicholas's 
`struct InstrumentButtonState`
into 4 bytes of I-Don't-Know, 4 bytes of velocity,
and 4 more bytes of I-Don't-Know.
Whenever a pad is hit,
I send 127 on the corresponding velocity.

I did this because a program called `rbdrum2midi`
ignores the button press events,
and looks only at the velocity values.

None of the Wii games I have
seem to care what these values are set to.


References
=========

The most valuable sources of information I found were:

* [Nicholas Angle's reverse-engineering write-up](https://www.niangames.com/articles/reverse-engineering-rockband-guitar-controllers)
* [Nicholas Angle's guitar controller program](https://github.com/NianZo/WiiGuitarController)
* [Clone Hero Wiki: Drum Mapping Guide](https://wiki.clonehero.net/books/guitars-drums-controllers/page/drum-mapping-guide)
* [rbdrum2midi source code](https://github.com/rbdrum2midi/rbdrum2midi)