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
-----------

If `DEBUGY0' is defined,
the number of samples taken since the last HID report
is sent as Y axis on hat 0.
You can use the 
[included gamepad tester](gamepad.html),
to see the approximate number of samples as an integer.

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.

This number will not be very useful
unless you are polling the wammy bar,
since without that input,
updates are only sent when a button state changes.


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

Hats
----

I guess "hats" are what I would have called "joysticks and dpads".


### Hat 0: unknown

This doesn't appear to be sent or used.

### Hat 1: guitar analog controls

The X axis is the position of the wammy bar.

The Y axis is the pickup selector.
I believe this was a 5-position switch on some guitars.
Only Rock Band 1 seems to use this.

### Hat 2: navigation

Sent by the dpad on the controller,
as `hatAndConstant`.

Guitars send up/down for the up/down strum buttons.
Drums send up/down on the blue/yellow cymbal pads.

The position of this digital input is reported in only 3 bits:

    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)
----------------

The following USB PIDs are recognized by various things:

* 0x0003: XBox Drum
* 0x0004: Wii Guitar
* 0x0005: Wii Drums - Rock Band 1
* 0x3110: Wii Drums - Rock Band 2

There are some quirks to note:

* Rock Band 3 won't recognize cymbal hits on PID=0x0005,
  but the same program with PID=0x3110 works fine.
* Wii games don't appear to recognized PID=0x0003.
  Maybe Rock Band 3 does: I didn't test that one.


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.
Clone Hero also does not care.


Clone Hero
==========

Clone Hero wants Hat 2 up on yellow cymbal hit,
and Hat 2 down on blue cymbal hit.

If it doesn't see these while mapping drum pads,
then hitting any color bad will trigger both drum and cymbal for that color.


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)