mockband

tech-notes.md

  1Technical Notes
  2===============
  3
  4It took me a lot of time digging around the Internet to find some of this stuff.
  5I'm writing down the highlights here,
  6so that when original sources fall off the net,
  7hopefully at least my notes will still be around.
  8
  9
 10USB data rate
 11-------------
 12
 13Unlike the Santroller
 14(which is much easier to install for beginners),
 15this firmware does not send continuous updates over USB,
 16unless it has to.
 17
 18Because the only analog input is the wammy bar,
 19if you don't include that input,
 20the controller can stay silent until a button is pressed or released.
 21This allows 4 controllers to connect to a USB hub,
 22with no concern for overwhelming the hub.
 23Since the amount of data is about the same as a keyboard,
 24and a little less than a mouse,
 25I would expect that a 7-port USB 2 hub would also handle 7 instruments,
 26no problem.
 27I just don't know of any games that can use mor than 4 instruments.
 28
 29If you do use the wammy bar,
 30an update is sent every 20 milliseconds.
 31The firmware still attempts to reduce lag
 32by sending button change events as soon as possible.
 33I haven't played with this much,
 34so if you have a wammy bar set up,
 35please reach out to me and let me know how it works.
 36
 37
 38
 39Sample Rate
 40-----------
 41
 42If `DEBUGY0' is defined,
 43the number of samples taken since the last HID report
 44is sent as Y axis on hat 0.
 45You can use the 
 46[included gamepad tester](gamepad.html),
 47to see the approximate number of samples as an integer.
 48
 49This is approximate,
 50because the browser encodes the value as a real number between -1 and 1.
 51We convert it back, but may lose a little precision.
 52It's close enough for me,
 53hopefully it's close enough for you.
 54
 55This number will not be very useful
 56unless you are polling the wammy bar,
 57since without that input,
 58updates are only sent when a button state changes.
 59
 60
 61Debouncing
 62----------
 63
 64Using `millis()` time to debounce the switch
 65roughly halved my sample frequency.
 66So instead, I do some preprocessor arithmetic
 67to calculate how many samples to take after an edge,
 68in order to debounce switches.
 69
 70The drum controller was a partcular pain:
 71in addition to the switch bouncing,
 72the stick was bouncing on the rubber pad.
 73I settled on a 40ms silence window as feeling pretty good.
 74You can adjust this if you want to.
 75
 76
 77
 78USB Junk
 79========
 80
 81Gamepad Buttons
 82---------------
 83
 84The `buttons` struct member is a bitmap,
 85each bit mapping to one of the 12 buttons reported through HID.
 86Here's what each bit means:
 87
 88* 0o00: Blue
 89* 0o01: Green
 90* 0o02: Red
 91* 0o03: Yellow
 92* 0o04: Orange
 93* 0o05: Tilt Switch / 2x kick
 94* 0o06: Solo modifier (second row of buttons on guitar)
 95* 0o07: ???
 96* 0o10: Minus
 97* 0o11: Plus
 98* 0o12: Drum pad modifier
 99* 0o13: Cymbal modifier
100* 0o14: Select
101
102Hats
103----
104
105I guess "hats" are what I would have called "joysticks and dpads".
106
107
108### Hat 0: unknown
109
110This doesn't appear to be sent or used.
111
112### Hat 1: guitar analog controls
113
114The X axis is the position of the wammy bar.
115
116The Y axis is the pickup selector.
117I believe this was a 5-position switch on some guitars.
118Only Rock Band 1 seems to use this.
119
120### Hat 2: navigation
121
122Sent by the dpad on the controller,
123as `hatAndConstant`.
124
125Guitars send up/down for the up/down strum buttons.
126Drums send up/down on the blue/yellow cymbal pads.
127
128The position of this digital input is reported in only 3 bits:
129
130    7   0   1
131
132    6   8   2
133
134    5   4   3
135
1360 is up,
1372 is right,
1384 is down,
1396 is left,
140and 8 is centered.
141
142
143velocity
144--------
145
146I don't know how I can verify that I'm setting this right,
147but the `rbdrum2midi` program looks at these bytes to detect hits.
148I set them to 127 when a hit is detected on the digital pin.
149
150Sending these values does not seem to cause problems with my Wii games.
151
152
153Product ID (PID)
154----------------
155
156The following USB PIDs are recognized by various things:
157
158* 0x0003: XBox Drum
159* 0x0004: Wii Guitar
160* 0x0005: Wii Drums - Rock Band 1
161* 0x3110: Wii Drums - Rock Band 2
162
163There are some quirks to note:
164
165* Rock Band 3 won't recognize cymbal hits on PID=0x0005,
166  but the same program with PID=0x3110 works fine.
167* Wii games don't appear to recognized PID=0x0003.
168  Maybe Rock Band 3 does: I didn't test that one.
169
170
171Drum Velocity
172--------
173
174I split the 12 "reserved" bytes from Nicholas's 
175`struct InstrumentButtonState`
176into 4 bytes of I-Don't-Know,
1774 bytes of velocity,
178and 4 more bytes of I-Don't-Know.
179Whenever a pad is hit,
180I send 127 on the corresponding velocity.
181
182I did this because a program called `rbdrum2midi`
183ignores the button press events,
184and looks only at the velocity values.
185
186None of the Wii games I have
187seem to care what these values are set to.
188Clone Hero also does not care.
189
190
191Clone Hero
192==========
193
194Clone Hero wants Hat 2 up on yellow cymbal hit,
195and Hat 2 down on blue cymbal hit.
196
197If it doesn't see these while mapping drum pads,
198then hitting any color bad will trigger both drum and cymbal for that color.
199
200
201References
202==========
203
204The most valuable sources of information I found were:
205
206* [Nicholas Angle's reverse-engineering write-up](https://www.niangames.com/articles/reverse-engineering-rockband-guitar-controllers)
207* [Nicholas Angle's guitar controller program](https://github.com/NianZo/WiiGuitarController)
208* [Clone Hero Wiki: Drum Mapping Guide](https://wiki.clonehero.net/books/guitars-drums-controllers/page/drum-mapping-guide)
209* [rbdrum2midi source code](https://github.com/rbdrum2midi/rbdrum2midi)
210