---------------------------------------------------
 MSX-HID device hardware fingerprints

The real hardware fingerprints are three 6bit values sent on each border of the
clock, as listed bellow. The megadrive 6-button joypad outputs five additional
6bit values if you need to differentiate it from the 3-button controller.


In HIDlib, for performance reasons, the first two 6-bit values of the
fingerprint are condensed into a single byte "DEVID" with some bit juggling
that reuses some otherwise illegal ranges, and the 3rd 6-bit value is
supplied only for PWM devices, as the "PWM mask" return value. If any driver
need additional bytes to differentiate between devices of the same family
(same DEVID), they must implement it themselves. I.e.: This is the case of the
Megadrive controller.

Always remember that the system is based in the following premisses:

1) The devices shall be accessed at most once per frame, where all needed data
   must be transferred at once.
2) While the detection is being done, the device must be centered/idle and all
   buttons must be released.
3) Fingerprints can only use values that a standard MSX 2-button joystick cannot
   produce during normal use. (a joystick controller cannot have opposite
   directions pressed, for example).
4) There must be a way for the driver to know that the device was disconnected.
   Usually this is some fixed bit at some specific byte of the data it sends.
5) During detection, the pins 6 and 7 must be left high (value=1).
6) The 1st value read from the device on each frame starts a session, and must
   always be obtained with the clock line set to low. As many bytes as needed
   might be transferred in a session, and the clock line must be set back to low
   at the end of each communication session.
7) The device data-transfer state must auto-reset after ~8ms without receiving
   any clock transition
8) The formula to detect time Encoded analog channels from the fingerprint is
   (byte1 xor byte3 and byte3). All bits that result in 1 are analog channels.
9) The first two bytes of the fingerprint are used to compose a unique ID for a
   device type. Extra bytes beyond that are used to differentiate variations
   within that device family. The formula for the unique ID byte is:
   HIDID=(byte1<<4|0xF)&(byte2|0xC0)&(byte1<<2|0x3F)&0xFF


Additional recommendations

- It's more reliable to detect the devices only upon connection.
- When the device is being connected, since not all pins of the DE-9 connector get
  a proper electric contact at the same time, the programmer must discard spurious
  reads by confirming that the same fingerprint values are received for at least a second.


==Fingerprints of MSX devices==
Unconnected or MSX joystick	: 3Fh,3Fh,3Fh
Mouse				: 30h,30h,30h
Trackball			; 38h,38h,38h
Touchpad			; 39h,3Dh,39h
Touchpad on turbo machines	; 3Dh,3Dh,3Dh
Lightgun			; 2Fh,2Fh,2Fh
Arkanoid Vaus Paddle		; 3Eh,3Eh,3Eh
PWM devices			; xxh,3Fh,3Fh, where each bit of "xx"
 				; is zero for each analog channel present
  MSX Paddle			; 3Eh,3Fh,3Fh
  Yamaha MMP-01	 music pad	; 3Ch,3Fh,3Fh
  IBM PC DA-15 analog joystick	; 3Ah,3Fh,3Fh 
  Atari dual-paddle adapter	; 36h,3Fh,3Fh
  Dual-axis joypad		; 30h,3Fh,3Fh

==Fingerprints of Sega devices that are compatible with the MSX-HID==
Megadrive 3-button joypad	: 3Fh,33h,3Fh
Megadrive 6-button joypad	: 3Fh,33h,3Fh,33h,3Fh,30h
Megadrive Multi-Tap		: 33h,3Fh,33h
Saturn digital joypad		: 3Ch,3Fh,3Ch
Saturn Mouse			: 30h,3Bh,30h
Sega 3line-handshake device	: 31h,31h,31h

==Fingerprints of devices that conflict with MSX-HID devices==
Micomsoft XE1-AP analog mode	: 2Fh,2Fh,2Fh (same as the Light gun)
Sega-Mouse (Megadrive)		: 30h,30h,30h (unconfirmed)
Sega Menacer			: 30h,30h,30h (unconfirmed)

===Homebrew devices===
Ninja-tap			: 3Fh,1Fh,3Fh
Port2 Light-pen adapter		: 33h,35h,33h 
3D glasses			: 3Fh,37h,3Fh
3D glasses + light gun		: 2Fh,27h,2Fh
Passive PS/2 mouse adapter	: 3Fh,3Eh,3Fh 

===Reserved fingerprints - Do not use ===
Any fingerprints that set both the pin-6 and pin-7 to 0 simultaneously
on any the two first bytes

==Devices that don't conform to the MSX-HID standard will be read as bogus
fingerprints when used, like the ones listed below=
Micomsoft XE-1AP digital mode	; 3Fh,3Bh,3Fh (C button pressed)
 Note: combinations of these	; 3Fh,37h,3Fh (D button pressed)
 buttons will result in invalid ; 3Fh,2Fh,3Fh (E1 button pressed)
 fingerprints.			; 3Fh,1Fh,3Fh (E2 button pressed)
				; 33h,33h,33h (START button pressed)
				; 3Ch,3Ch,3Ch (SELECT button pressed)
				; 3Fh,3Eh,3Fh (Throttle up)
				; 3Fh,3Dh,3Fh (Throttle down)
X68000 6-button joypad		: 3Fh,3Eh,3Fh (R button pressed)
				: 3Fh,3Dh,3Fh (Y button pressed)
				: 3Fh,3Bh,3Fh (X button pressed)
				: 3Fh,37h,3Fh (SELECT button pressed)
				: 3Fh,2Fh,3Fh (L button pressed)
				: 3Fh,1Fh,3Fh (START button pressed)
FS-JH1 (when non-idle)		: 35h,35h,35h (DOWN+RIGHT)
				: 36h,36h,36h (UP+RIGHT)
				: 37h,37h,37h (RIGHT)
				: 39h,39h,39h (DOWN+LEFT)
				: 3Ah,3Ah,3Ah (UP+LEFT)
				: 3Bh,3Bh,3Bh (LEFT) = MSX-Touchpad
				: 3Dh,3Dh,3Dh (DOWN)
				: 3Eh,3Eh,3Eh (UP)   = Arkanoid paddle
FM-Towns joypad UP/DOWN/LEFT/RIGHT: same as JS-JH1 UP/DOWN/LEFT/RIGHT
FM-Towns joypad SELECT button	: 3Ch,3Ch,3Ch
FM-Towns joypad RUN button	: 33h,33h,33h

Such devices cannot be supported nor detected by HIDlib and will require you to
write specific code to handle it and to do the manual selection.


Notes:
- Sega Japan only started supporting the MSX-HID standard since the Megadrive.
  This means that any controller that fits in the following categories
  won't respect the standard:
  - Any controllers for the SG-1000
  - Any controllers for the Master System
  - Any controller designed by Sega of America (like the Sega Menacer)

- The MSX standard supports PWM encoding to receive analog bytes since its
  inception. Some fingerprints are specific to known devices and were listed in
  this document, and the others should be dealt as generic PWM devices.
  As a side note, this interface seems heavily inspired in the legacy IBM PC
  DA-15 gameport. In fact, it's perfectly possible to build an adapter to
  connect such devices to the MSX general-purpose joystick ports. This is why
  the PC joystick is listed here amongst the devices.
  To make the life of hw and sw developers easier, channel0 and channel2 will
  always be the Y-axis and X-axis,respectivelly.
  The remaining channels may vary per device. They can be used to add any
  feature that can be encoded in PWM, like more axis, extra potentiometers
  or even sensors of temperature or light.
- The Microsoft Sidewinder 3D Pro obviously wasn't designed for the MSX,
  but it was included here both because it will be possible to connect it
  with the same adapter used for the IBM-PC DA15 joysticks, and because I found
  it's protocol have very curious similarities to the one use on the Dempa
  XE-1AP & Sharp CZ-8NJ1.


