Pinscape_Controller_V2_arnoz

Users » arnoz » Code » Pinscape_Controller_V2_arnoz

Arnaud VALLEY / Mbed 2 deprecated Pinscape_Controller_V2_arnoz

Dependencies: mbed FastIO FastPWM USBDevice

USBProtocol.h@82:4f6209cb5c33, 2017-04-13 (annotated)

Committer:: mjr
Date:: Thu Apr 13 23:20:28 2017 +0000
Revision:: 82:4f6209cb5c33
Parent:: 79:682ae3171a08
Child:: 85:3c28aee81cde

Plunger refactoring; AEDR-8300 added; TSL1401CL in progress; VL6180X added

Who changed what in which revision?

User	Revision	Line number	New contents of line
mjr	35:e959ffba78fd	1	// USB Message Protocol
mjr	35:e959ffba78fd	2	//
mjr	74:822a92bc11d2	3	// This file is purely for documentation, to describe our USB protocol
mjr	74:822a92bc11d2	4	// for incoming messages (host to device). We use the standard HID setup
mjr	74:822a92bc11d2	5	// with one endpoint in each direction. See USBJoystick.cpp and .h for
mjr	74:822a92bc11d2	6	// the USB descriptors.
mjr	74:822a92bc11d2	7	//
mjr	74:822a92bc11d2	8	// Our incoming message protocol is an extended version of the protocol
mjr	74:822a92bc11d2	9	// used by the LedWiz. Our protocol is designed to be 100% backwards
mjr	74:822a92bc11d2	10	// compatible with clients using the original LedWiz wire protocol, as long
mjr	74:822a92bc11d2	11	// as they only send well-formed messages in the original protocol. The
mjr	74:822a92bc11d2	12	// "well-formed" part is an important condition, because our extensions to
mjr	74:822a92bc11d2	13	// the original protocol all consist of messages that aren't defined in the
mjr	74:822a92bc11d2	14	// original protocol and are meaningless to a real LedWiz.
mjr	35:e959ffba78fd	15	//
mjr	74:822a92bc11d2	16	// The protocol compatibility ensures that all original LedWiz clients can
mjr	74:822a92bc11d2	17	// also transparently access a Pinscape unit. Clients will simply think the
mjr	74:822a92bc11d2	18	// Pinscape unit is an LedWiz, thus they'll be able to operate 32 of our
mjr	74:822a92bc11d2	19	// ports. We designate the first 32 ports (ports 1-32) as the ones accessible
mjr	74:822a92bc11d2	20	// through the LedWiz protocol.
mjr	74:822a92bc11d2	21	//
mjr	74:822a92bc11d2	22	// In addition the wire-level protocol compatibility, we can provide legacy
mjr	74:822a92bc11d2	23	// LedWiz clients with access to more than 32 ports by emulating multiple
mjr	74:822a92bc11d2	24	// virtual LedWiz units. We can't do this across the wire protocol, since
mjr	74:822a92bc11d2	25	// the KL25Z USB interface constrains us to a single VID/PID (which is how
mjr	74:822a92bc11d2	26	// LedWiz clients distinguish units). However, virtuall all legacy LedWiz
mjr	74:822a92bc11d2	27	// clients access the device through a shared library, LEDWIZ.DLL, rather
mjr	74:822a92bc11d2	28	// than directly through USB. LEDWIZ.DLL is distributed by the LedWiz's
mjr	74:822a92bc11d2	29	// manufacturer and has a published client interface. We can thus provide
mjr	74:822a92bc11d2	30	// a replacement DLL that contains the logic needed to recognize a Pinscape
mjr	74:822a92bc11d2	31	// unit and represent it to clients as multiple LedWiz devices. This allows
mjr	74:822a92bc11d2	32	// old clients to access our full complement of ports without any changes
mjr	74:822a92bc11d2	33	// to the clients. We define some extended message types (SBX and PBX)
mjr	74:822a92bc11d2	34	// specifically to support this DLL feature.
mjr	74:822a92bc11d2	35	//
mjr	74:822a92bc11d2	36
mjr	35:e959ffba78fd	37
mjr	35:e959ffba78fd	38	// ------ OUTGOING MESSAGES (DEVICE TO HOST) ------
mjr	35:e959ffba78fd	39	//
mjr	47:df7a88cd249c	40	// General note: 16-bit and 32-bit fields in our reports are little-endian
mjr	47:df7a88cd249c	41	// unless otherwise specified.
mjr	47:df7a88cd249c	42	//
mjr	39:b3815a1c3802	43	// 1. Joystick reports
mjr	35:e959ffba78fd	44	// In most cases, our outgoing messages are HID joystick reports, using the
mjr	35:e959ffba78fd	45	// format defined in USBJoystick.cpp. This allows us to be installed on
mjr	35:e959ffba78fd	46	// Windows as a standard USB joystick, which all versions of Windows support
mjr	35:e959ffba78fd	47	// using in-the-box drivers. This allows a completely transparent, driverless,
mjr	39:b3815a1c3802	48	// plug-and-play installation experience on Windows. Our joystick report
mjr	39:b3815a1c3802	49	// looks like this (see USBJoystick.cpp for the formal HID report descriptor):
mjr	35:e959ffba78fd	50	//
mjr	55:4db125cd11a0	51	// ss status bits:
mjr	55:4db125cd11a0	52	// 0x01 -> plunger enabled
mjr	55:4db125cd11a0	53	// 0x02 -> night mode engaged
mjr	73:4e8ce0b18915	54	// 0x04,0x08,0x10 -> power sense status: meaningful only when
mjr	73:4e8ce0b18915	55	// the TV-on timer is used. Figure (ss>>2) & 0x07 to
mjr	73:4e8ce0b18915	56	// isolate the status bits. The resulting value is:
mjr	73:4e8ce0b18915	57	// 1 -> latch was on at last check
mjr	73:4e8ce0b18915	58	// 2 -> latch was off at last check, SET pin high
mjr	73:4e8ce0b18915	59	// 3 -> latch off, SET pin low, ready to check status
mjr	73:4e8ce0b18915	60	// 4 -> TV timer countdown in progress
mjr	73:4e8ce0b18915	61	// 5 -> TV relay is on
mjr	77:0b96f6867312	62	// 6 -> sending IR signals designated as TV ON signals
mjr	77:0b96f6867312	63	// 0x20 -> IR learning mode in progress
mjr	79:682ae3171a08	64	// 0x40 -> configuration saved successfully (see below)
mjr	40:cc0d9814522b	65	// 00 2nd byte of status (reserved)
mjr	40:cc0d9814522b	66	// 00 3rd byte of status (reserved)
mjr	39:b3815a1c3802	67	// 00 always zero for joystick reports
mjr	40:cc0d9814522b	68	// bb joystick buttons, low byte (buttons 1-8, 1 bit per button)
mjr	40:cc0d9814522b	69	// bb joystick buttons, 2nd byte (buttons 9-16)
mjr	40:cc0d9814522b	70	// bb joystick buttons, 3rd byte (buttons 17-24)
mjr	40:cc0d9814522b	71	// bb joystick buttons, high byte (buttons 25-32)
mjr	39:b3815a1c3802	72	// xx low byte of X position = nudge/accelerometer X axis
mjr	39:b3815a1c3802	73	// xx high byte of X position
mjr	39:b3815a1c3802	74	// yy low byte of Y position = nudge/accelerometer Y axis
mjr	39:b3815a1c3802	75	// yy high byte of Y position
mjr	39:b3815a1c3802	76	// zz low byte of Z position = plunger position
mjr	39:b3815a1c3802	77	// zz high byte of Z position
mjr	39:b3815a1c3802	78	//
mjr	39:b3815a1c3802	79	// The X, Y, and Z values are 16-bit signed integers. The accelerometer
mjr	39:b3815a1c3802	80	// values are on an abstract scale, where 0 represents no acceleration,
mjr	39:b3815a1c3802	81	// negative maximum represents -1g on that axis, and positive maximum
mjr	39:b3815a1c3802	82	// represents +1g on that axis. For the plunger position, 0 is the park
mjr	39:b3815a1c3802	83	// position (the rest position of the plunger) and positive values represent
mjr	39:b3815a1c3802	84	// retracted (pulled back) positions. A negative value means that the plunger
mjr	39:b3815a1c3802	85	// is pushed forward of the park position.
mjr	39:b3815a1c3802	86	//
mjr	79:682ae3171a08	87	// Status bit 0x40 is set after a successful configuration update via special
mjr	79:682ae3171a08	88	// command 65 6 (save config to flash). The device always reboots after this
mjr	79:682ae3171a08	89	// command, so if the host wants to receive a status update verifying the
mjr	79:682ae3171a08	90	// save, it has to request a non-zero reboot delay in the message to allow
mjr	79:682ae3171a08	91	// us time to send at least one of these status reports after the save.
mjr	79:682ae3171a08	92	// This bit is only sent after a successful save, which means that the flash
mjr	79:682ae3171a08	93	// write succeeded and the written sectors verified as correct.
mjr	82:4f6209cb5c33	94	// NOTE: older firmware versions didn't support this status bit, so clients
mjr	82:4f6209cb5c33	95	// can't interpret the lack of a response as a failure for older versions.
mjr	82:4f6209cb5c33	96	// To determine if the flag is supported, check the config report feature
mjr	82:4f6209cb5c33	97	// flags.
mjr	82:4f6209cb5c33	98	//
mjr	79:682ae3171a08	99	//
mjr	39:b3815a1c3802	100	// 2. Special reports
mjr	35:e959ffba78fd	101	// We subvert the joystick report format in certain cases to report other
mjr	35:e959ffba78fd	102	// types of information, when specifically requested by the host. This allows
mjr	35:e959ffba78fd	103	// our custom configuration UI on the Windows side to query additional
mjr	35:e959ffba78fd	104	// information that we don't normally send via the joystick reports. We
mjr	35:e959ffba78fd	105	// define a custom vendor-specific "status" field in the reports that we
mjr	35:e959ffba78fd	106	// use to identify these special reports, as described below.
mjr	35:e959ffba78fd	107	//
mjr	39:b3815a1c3802	108	// Normal joystick reports always have 0 in the high bit of the 2nd byte
mjr	35:e959ffba78fd	109	// of the report. Special non-joystick reports always have 1 in the high bit
mjr	35:e959ffba78fd	110	// of the first byte. (This byte is defined in the HID Report Descriptor
mjr	35:e959ffba78fd	111	// as an opaque vendor-defined value, so the joystick interface on the
mjr	35:e959ffba78fd	112	// Windows side simply ignores it.)
mjr	35:e959ffba78fd	113	//
mjr	52:8298b2a73eb2	114	// 2A. Plunger sensor status report
mjr	52:8298b2a73eb2	115	// Software on the PC can request a detailed status report from the plunger
mjr	52:8298b2a73eb2	116	// sensor. The status information is meant as an aid to installing and
mjr	52:8298b2a73eb2	117	// adjusting the sensor device for proper performance. For imaging sensor
mjr	52:8298b2a73eb2	118	// types, the status report includes a complete current image snapshot
mjr	52:8298b2a73eb2	119	// (an array of all of the pixels the sensor is currently imaging). For
mjr	52:8298b2a73eb2	120	// all sensor types, it includes the current plunger position registered
mjr	52:8298b2a73eb2	121	// on the sensor, and some timing information.
mjr	52:8298b2a73eb2	122	//
mjr	52:8298b2a73eb2	123	// To request the sensor status, the host sends custom protocol message 65 3
mjr	52:8298b2a73eb2	124	// (see below). The device replies with a message in this format:
mjr	52:8298b2a73eb2	125	//
mjr	52:8298b2a73eb2	126	// bytes 0:1 = 0x87FF
mjr	52:8298b2a73eb2	127	// byte 2 = 0 -> first (currently only) status report packet
mjr	52:8298b2a73eb2	128	// (additional packets could be added in the future if
mjr	52:8298b2a73eb2	129	// more fields need to be added)
mjr	52:8298b2a73eb2	130	// bytes 3:4 = number of pixels to be sent in following messages, as
mjr	52:8298b2a73eb2	131	// an unsigned 16-bit little-endian integer. This is 0 if
mjr	52:8298b2a73eb2	132	// the sensor isn't an imaging type.
mjr	52:8298b2a73eb2	133	// bytes 5:6 = current plunger position registered on the sensor.
mjr	52:8298b2a73eb2	134	// For imaging sensors, this is the pixel position, so it's
mjr	52:8298b2a73eb2	135	// scaled from 0 to number of pixels - 1. For non-imaging
mjr	52:8298b2a73eb2	136	// sensors, this uses the generic joystick scale 0..4095.
mjr	52:8298b2a73eb2	137	// The special value 0xFFFF means that the position couldn't
mjr	52:8298b2a73eb2	138	// be determined,
mjr	52:8298b2a73eb2	139	// byte 7 = bit flags:
mjr	52:8298b2a73eb2	140	// 0x01 = normal orientation detected
mjr	52:8298b2a73eb2	141	// 0x02 = reversed orientation detected
mjr	52:8298b2a73eb2	142	// 0x04 = calibration mode is active (no pixel packets
mjr	52:8298b2a73eb2	143	// are sent for this reading)
mjr	52:8298b2a73eb2	144	// bytes 8:9:10 = average time for each sensor read, in 10us units.
mjr	52:8298b2a73eb2	145	// This is the average time it takes to complete the I/O
mjr	52:8298b2a73eb2	146	// operation to read the sensor, to obtain the raw sensor
mjr	52:8298b2a73eb2	147	// data for instantaneous plunger position reading. For
mjr	52:8298b2a73eb2	148	// an imaging sensor, this is the time it takes for the
mjr	52:8298b2a73eb2	149	// sensor to capture the image and transfer it to the
mjr	52:8298b2a73eb2	150	// microcontroller. For an analog sensor (e.g., an LVDT
mjr	52:8298b2a73eb2	151	// or potentiometer), it's the time to complete an ADC
mjr	52:8298b2a73eb2	152	// sample.
mjr	52:8298b2a73eb2	153	// bytes 11:12:13 = time it took to process the current frame, in 10us
mjr	52:8298b2a73eb2	154	// units. This is the software processing time that was
mjr	52:8298b2a73eb2	155	// needed to analyze the raw data read from the sensor.
mjr	52:8298b2a73eb2	156	// This is typically only non-zero for imaging sensors,
mjr	52:8298b2a73eb2	157	// where it reflects the time required to scan the pixel
mjr	52:8298b2a73eb2	158	// array to find the indicated plunger position. The time
mjr	52:8298b2a73eb2	159	// is usually zero or negligible for analog sensor types,
mjr	52:8298b2a73eb2	160	// since the only "analysis" is a multiplication to rescale
mjr	52:8298b2a73eb2	161	// the ADC sample.
mjr	52:8298b2a73eb2	162	//
mjr	52:8298b2a73eb2	163	// If the sensor is an imaging sensor type, this will be followed by a
mjr	52:8298b2a73eb2	164	// series of pixel messages. The imaging sensor types have too many pixels
mjr	52:8298b2a73eb2	165	// to send in a single USB transaction, so the device breaks up the array
mjr	52:8298b2a73eb2	166	// into as many packets as needed and sends them in sequence. For non-
mjr	52:8298b2a73eb2	167	// imaging sensors, the "number of pixels" field in the lead packet is
mjr	52:8298b2a73eb2	168	// zero, so obviously no pixel packets will follow. If the "calibration
mjr	52:8298b2a73eb2	169	// active" bit in the flags byte is set, no pixel packets are sent even
mjr	52:8298b2a73eb2	170	// if the sensor is an imaging type, since the transmission time for the
mjr	52:8298b2a73eb2	171	// pixels would intefere with the calibration process. If pixels are sent,
mjr	52:8298b2a73eb2	172	// they're sent in order starting at the first pixel. The format of each
mjr	52:8298b2a73eb2	173	// pixel packet is:
mjr	35:e959ffba78fd	174	//
mjr	35:e959ffba78fd	175	// bytes 0:1 = 11-bit index, with high 5 bits set to 10000. For
mjr	48:058ace2aed1d	176	// example, 0x8004 (encoded little endian as 0x04 0x80)
mjr	48:058ace2aed1d	177	// indicates index 4. This is the starting pixel number
mjr	48:058ace2aed1d	178	// in the report. The first report will be 0x00 0x80 to
mjr	48:058ace2aed1d	179	// indicate pixel #0.
mjr	47:df7a88cd249c	180	// bytes 2 = 8-bit unsigned int brightness level of pixel at index
mjr	47:df7a88cd249c	181	// bytes 3 = brightness of pixel at index+1
mjr	35:e959ffba78fd	182	// etc for the rest of the packet
mjr	35:e959ffba78fd	183	//
mjr	52:8298b2a73eb2	184	// Note that we currently only support one-dimensional imaging sensors
mjr	52:8298b2a73eb2	185	// (i.e., pixel arrays that are 1 pixel wide). The report format doesn't
mjr	52:8298b2a73eb2	186	// have any provision for a two-dimensional layout. The KL25Z probably
mjr	52:8298b2a73eb2	187	// isn't powerful enough to do real-time image analysis on a 2D image
mjr	52:8298b2a73eb2	188	// anyway, so it's unlikely that we'd be able to make 2D sensors work at
mjr	52:8298b2a73eb2	189	// all, but if we ever add such a thing we'll have to upgrade the report
mjr	52:8298b2a73eb2	190	// format here accordingly.
mjr	51:57eb311faafa	191	//
mjr	51:57eb311faafa	192	//
mjr	53:9b2611964afc	193	// 2B. Configuration report.
mjr	39:b3815a1c3802	194	// This is requested by sending custom protocol message 65 4 (see below).
mjr	39:b3815a1c3802	195	// In reponse, the device sends one report to the host using this format:
mjr	35:e959ffba78fd	196	//
mjr	35:e959ffba78fd	197	// bytes 0:1 = 0x8800. This has the bit pattern 10001 in the high
mjr	35:e959ffba78fd	198	// 5 bits, which distinguishes it from regular joystick
mjr	40:cc0d9814522b	199	// reports and from other special report types.
mjr	74:822a92bc11d2	200	// bytes 2:3 = total number of configured outputs, little endian. This
mjr	74:822a92bc11d2	201	// is the number of outputs with assigned functions in the
mjr	74:822a92bc11d2	202	// active configuration.
mjr	75:677892300e7a	203	// byte 4 = Pinscape unit number (0-15), little endian
mjr	75:677892300e7a	204	// byte 5 = reserved (currently always zero)
mjr	40:cc0d9814522b	205	// bytes 6:7 = plunger calibration zero point, little endian
mjr	40:cc0d9814522b	206	// bytes 8:9 = plunger calibration maximum point, little endian
mjr	52:8298b2a73eb2	207	// byte 10 = plunger calibration release time, in milliseconds
mjr	52:8298b2a73eb2	208	// byte 11 = bit flags:
mjr	40:cc0d9814522b	209	// 0x01 -> configuration loaded; 0 in this bit means that
mjr	40:cc0d9814522b	210	// the firmware has been loaded but no configuration
mjr	40:cc0d9814522b	211	// has been sent from the host
mjr	74:822a92bc11d2	212	// 0x02 -> SBX/PBX extension features: 1 in this bit means
mjr	74:822a92bc11d2	213	// that these features are present in this version.
mjr	78:1e00b3fa11af	214	// 0x04 -> new accelerometer features supported (adjustable
mjr	78:1e00b3fa11af	215	// dynamic range, auto-centering on/off, adjustable
mjr	78:1e00b3fa11af	216	// auto-centering time)
mjr	82:4f6209cb5c33	217	// 0x08 -> flash write status flag supported (see flag 0x40
mjr	82:4f6209cb5c33	218	// in normal joystick status report)
mjr	73:4e8ce0b18915	219	// bytes 12:13 = available RAM, in bytes, little endian. This is the amount
mjr	73:4e8ce0b18915	220	// of unused heap (malloc'able) memory. The firmware generally
mjr	73:4e8ce0b18915	221	// allocates all of the dynamic memory it needs during startup,
mjr	73:4e8ce0b18915	222	// so the free memory figure doesn't tend to fluctuate during
mjr	73:4e8ce0b18915	223	// normal operation. The dynamic memory used is a function of
mjr	73:4e8ce0b18915	224	// the set of features enabled.
mjr	35:e959ffba78fd	225	//
mjr	53:9b2611964afc	226	// 2C. Device ID report.
mjr	40:cc0d9814522b	227	// This is requested by sending custom protocol message 65 7 (see below).
mjr	40:cc0d9814522b	228	// In response, the device sends one report to the host using this format:
mjr	40:cc0d9814522b	229	//
mjr	52:8298b2a73eb2	230	// bytes 0:1 = 0x9000. This has bit pattern 10010 in the high 5 bits
mjr	52:8298b2a73eb2	231	// to distinguish this from other report types.
mjr	53:9b2611964afc	232	// byte 2 = ID type. This is the same ID type sent in the request.
mjr	53:9b2611964afc	233	// bytes 3-12 = requested ID. The ID is 80 bits in big-endian byte
mjr	53:9b2611964afc	234	// order. For IDs longer than 80 bits, we truncate to the
mjr	53:9b2611964afc	235	// low-order 80 bits (that is, the last 80 bits).
mjr	53:9b2611964afc	236	//
mjr	53:9b2611964afc	237	// ID type 1 = CPU ID. This is the globally unique CPU ID
mjr	53:9b2611964afc	238	// stored in the KL25Z CPU.
mjr	35:e959ffba78fd	239	//
mjr	53:9b2611964afc	240	// ID type 2 = OpenSDA ID. This is the globally unique ID
mjr	53:9b2611964afc	241	// for the connected OpenSDA controller, if known. This
mjr	53:9b2611964afc	242	// allow the host to figure out which USB MSD (virtual
mjr	53:9b2611964afc	243	// disk drive), if any, represents the OpenSDA module for
mjr	53:9b2611964afc	244	// this Pinscape USB interface. This is primarily useful
mjr	53:9b2611964afc	245	// to determine which MSD to write in order to update the
mjr	53:9b2611964afc	246	// firmware on a given Pinscape unit.
mjr	53:9b2611964afc	247	//
mjr	53:9b2611964afc	248	// 2D. Configuration variable report.
mjr	52:8298b2a73eb2	249	// This is requested by sending custom protocol message 65 9 (see below).
mjr	52:8298b2a73eb2	250	// In response, the device sends one report to the host using this format:
mjr	52:8298b2a73eb2	251	//
mjr	52:8298b2a73eb2	252	// bytes 0:1 = 0x9800. This has bit pattern 10011 in the high 5 bits
mjr	52:8298b2a73eb2	253	// to distinguish this from other report types.
mjr	52:8298b2a73eb2	254	// byte 2 = Variable ID. This is the same variable ID sent in the
mjr	52:8298b2a73eb2	255	// query message, to relate the reply to the request.
mjr	52:8298b2a73eb2	256	// bytes 3-8 = Current value of the variable, in the format for the
mjr	52:8298b2a73eb2	257	// individual variable type. The variable formats are
mjr	52:8298b2a73eb2	258	// described in the CONFIGURATION VARIABLES section below.
mjr	52:8298b2a73eb2	259	//
mjr	53:9b2611964afc	260	// 2E. Software build information report.
mjr	53:9b2611964afc	261	// This is requested by sending custom protocol message 65 10 (see below).
mjr	53:9b2611964afc	262	// In response, the device sends one report using this format:
mjr	53:9b2611964afc	263	//
mjr	73:4e8ce0b18915	264	// bytes 0:1 = 0xA000. This has bit pattern 10100 in the high 5 bits
mjr	77:0b96f6867312	265	// (and 10100000 in the high 8 bits) to distinguish it from
mjr	77:0b96f6867312	266	// other report types.
mjr	53:9b2611964afc	267	// bytes 2:5 = Build date. This is returned as a 32-bit integer,
mjr	53:9b2611964afc	268	// little-endian as usual, encoding a decimal value
mjr	53:9b2611964afc	269	// in the format YYYYMMDD giving the date of the build.
mjr	53:9b2611964afc	270	// E.g., Feb 16 2016 is encoded as 20160216 (decimal).
mjr	53:9b2611964afc	271	// bytes 6:9 = Build time. This is a 32-bit integer, little-endian,
mjr	53:9b2611964afc	272	// encoding a decimal value in the format HHMMSS giving
mjr	53:9b2611964afc	273	// build time on a 24-hour clock.
mjr	53:9b2611964afc	274	//
mjr	73:4e8ce0b18915	275	// 2F. Button status report.
mjr	73:4e8ce0b18915	276	// This is requested by sending custom protocol message 65 13 (see below).
mjr	73:4e8ce0b18915	277	// In response, the device sends one report using this format:
mjr	73:4e8ce0b18915	278	//
mjr	77:0b96f6867312	279	// bytes 0:1 = 0xA1. This has bit pattern 10100 in the high 5 bits (and
mjr	77:0b96f6867312	280	// 10100001 in the high 8 bits) to distinguish it from other
mjr	77:0b96f6867312	281	// report types.
mjr	73:4e8ce0b18915	282	// byte 2 = number of button reports
mjr	73:4e8ce0b18915	283	// byte 3 = Physical status of buttons 1-8, 1 bit each. The low-order
mjr	73:4e8ce0b18915	284	// bit (0x01) is button 1. Each bit is 0 if the button is off,
mjr	73:4e8ce0b18915	285	// 1 if on. This reflects the physical status of the button
mjr	73:4e8ce0b18915	286	// input pins, after debouncing but before any logical state
mjr	73:4e8ce0b18915	287	// processing. Pulse mode and shifting have no effect on the
mjr	73:4e8ce0b18915	288	// physical state; this simply indicates whether the button is
mjr	73:4e8ce0b18915	289	// electrically on (shorted to GND) or off (open circuit).
mjr	73:4e8ce0b18915	290	// byte 4 = buttons 9-16
mjr	73:4e8ce0b18915	291	// byte 5 = buttons 17-24
mjr	73:4e8ce0b18915	292	// byte 6 = buttons 25-32
mjr	73:4e8ce0b18915	293	// byte 7 = buttons 33-40
mjr	73:4e8ce0b18915	294	// byte 8 = buttons 41-48
mjr	73:4e8ce0b18915	295	//
mjr	77:0b96f6867312	296	// 2G. IR sensor data report.
mjr	77:0b96f6867312	297	// This is requested by sending custom protocol message 65 12 (see below).
mjr	77:0b96f6867312	298	// That command puts controller in IR learning mode for a short time, during
mjr	77:0b96f6867312	299	// which it monitors the IR sensor and send these special reports to relay the
mjr	77:0b96f6867312	300	// readings. The reports contain the raw data, plus the decoded command code
mjr	77:0b96f6867312	301	// and protocol information if the controller is able to recognize and decode
mjr	77:0b96f6867312	302	// the command.
mjr	52:8298b2a73eb2	303	//
mjr	77:0b96f6867312	304	// bytes 0:1 = 0xA2. This has bit pattern 10100 in the high 5 bits (and
mjr	77:0b96f6867312	305	// 10100010 in the high 8 bits to distinguish it from other
mjr	77:0b96f6867312	306	// report types.
mjr	77:0b96f6867312	307	// byte 2 = number of raw reports that follow
mjr	77:0b96f6867312	308	// bytes 3:4 = first raw report, as a little-endian 16-bit int. The
mjr	77:0b96f6867312	309	// value represents the time of an IR "space" or "mark" in
mjr	77:0b96f6867312	310	// 2us units. The low bit is 0 for a space and 1 for a mark.
mjr	77:0b96f6867312	311	// To recover the time in microseconds, mask our the low bit
mjr	77:0b96f6867312	312	// and multiply the result by 2. Received codes always
mjr	77:0b96f6867312	313	// alternate between spaces and marks. A space is an interval
mjr	77:0b96f6867312	314	// where the IR is off, and a mark is an interval with IR on.
mjr	77:0b96f6867312	315	// If the value is 0xFFFE (after masking out the low bit), it
mjr	77:0b96f6867312	316	// represents a timeout, that is, a time greater than or equal
mjr	77:0b96f6867312	317	// to the maximum that can be represented in this format,
mjr	77:0b96f6867312	318	// which is 131068us. None of the IR codes we can parse have
mjr	77:0b96f6867312	319	// any internal signal component this long, so a timeout value
mjr	77:0b96f6867312	320	// is generally seen only during a gap between codes where
mjr	77:0b96f6867312	321	// nothing is being transmitted.
mjr	77:0b96f6867312	322	// bytes 4:5 = second raw report
mjr	77:0b96f6867312	323	// (etc for remaining reports)
mjr	77:0b96f6867312	324	//
mjr	77:0b96f6867312	325	// If byte 2 is 0x00, it indicates that learning mode has expired without
mjr	77:0b96f6867312	326	// a code being received, so it's the last report sent for the learning
mjr	77:0b96f6867312	327	// session.
mjr	77:0b96f6867312	328	//
mjr	77:0b96f6867312	329	// If byte 2 is 0xFF, it indicates that a code has been successfully
mjr	77:0b96f6867312	330	// learned. The rest of the report contains the learned code instead
mjr	77:0b96f6867312	331	// of the raw data:
mjr	77:0b96f6867312	332	//
mjr	77:0b96f6867312	333	// byte 3 = protocol ID, which is an integer giving an internal code
mjr	77:0b96f6867312	334	// identifying the IR protocol that was recognized for the
mjr	77:0b96f6867312	335	// received data. See IRProtocolID.h for a list of the IDs.
mjr	77:0b96f6867312	336	// byte 4 = bit flags:
mjr	77:0b96f6867312	337	// 0x02 -> the protocol uses "dittos"
mjr	77:0b96f6867312	338	// bytes 5:6:7:8:9:10:11:12 = a little-endian 64-bit int containing
mjr	77:0b96f6867312	339	// the code received. The code is essentially the data payload
mjr	77:0b96f6867312	340	// of the IR packet, after removing bits that are purely
mjr	77:0b96f6867312	341	// structural, such as toggle bits and error correction bits.
mjr	77:0b96f6867312	342	// The mapping between the IR bit stream and our 64-bit is
mjr	77:0b96f6867312	343	// essentially arbitrary and varies by protocol, but it always
mjr	77:0b96f6867312	344	// has round-trip fidelity: using the 64-bit code value +
mjr	77:0b96f6867312	345	// protocol ID + flags to send an IR command will result in
mjr	77:0b96f6867312	346	// the same IR bit sequence being sent, modulo structural bits
mjr	77:0b96f6867312	347	// that need to be updates in the reconstruction (such as toggle
mjr	77:0b96f6867312	348	// bits or sequencing codes).
mjr	77:0b96f6867312	349	//
mjr	77:0b96f6867312	350	//
mjr	77:0b96f6867312	351	// WHY WE USE A HACKY APPROACH TO DIFFERENT REPORT TYPES
mjr	35:e959ffba78fd	352	//
mjr	35:e959ffba78fd	353	// The HID report system was specifically designed to provide a clean,
mjr	35:e959ffba78fd	354	// structured way for devices to describe the data they send to the host.
mjr	35:e959ffba78fd	355	// Our approach isn't clean or structured; it ignores the promises we
mjr	35:e959ffba78fd	356	// make about the contents of our report via the HID Report Descriptor
mjr	35:e959ffba78fd	357	// and stuffs our own different data format into the same structure.
mjr	35:e959ffba78fd	358	//
mjr	77:0b96f6867312	359	// We use this hacky approach only because we can't use the standard USB
mjr	77:0b96f6867312	360	// HID mechanism for varying report types, which is to provide multiple
mjr	77:0b96f6867312	361	// report descriptors and tag each report with a type byte that indicates
mjr	77:0b96f6867312	362	// which descriptor applies. We can't use that standard approach because
mjr	77:0b96f6867312	363	// we want to be 100% LedWiz compatible. The snag is that some Windows
mjr	77:0b96f6867312	364	// LedWiz clients parse the USB HID descriptors as part of identifying a
mjr	77:0b96f6867312	365	// USB HID device as a valid LedWiz unit, and will only recognize the device
mjr	77:0b96f6867312	366	// if certain properties of the HID descriptors match those of a real LedWiz.
mjr	77:0b96f6867312	367	// One of the features that's important to some clients is the descriptor
mjr	77:0b96f6867312	368	// link structure, which is affected by the layout of HID Report Descriptor
mjr	77:0b96f6867312	369	// entries. In order to match the expected layout, we can only define a
mjr	77:0b96f6867312	370	// single kind of output report. Since we have to use Joystick reports for
mjr	77:0b96f6867312	371	// the sake of VP and other pinball software, and we're only allowed the
mjr	77:0b96f6867312	372	// one report type, we have to make that one report type the Joystick type.
mjr	77:0b96f6867312	373	// That's why we overload the joystick reports with other meanings. It's a
mjr	77:0b96f6867312	374	// hack, but at least it's a fairly reliable and isolated hack, in that our
mjr	77:0b96f6867312	375	// special reports are only generated when clients specifically ask for
mjr	77:0b96f6867312	376	// them. Plus, even if a client who doesn't ask for a special report
mjr	77:0b96f6867312	377	// somehow gets one, the worst that happens is that they get a momentary
mjr	77:0b96f6867312	378	// spurious reading from the accelerometer and plunger.
mjr	35:e959ffba78fd	379
mjr	35:e959ffba78fd	380
mjr	35:e959ffba78fd	381
mjr	35:e959ffba78fd	382	// ------- INCOMING MESSAGES (HOST TO DEVICE) -------
mjr	35:e959ffba78fd	383	//
mjr	35:e959ffba78fd	384	// For LedWiz compatibility, our incoming message format conforms to the
mjr	35:e959ffba78fd	385	// basic USB format used by real LedWiz units. This is simply 8 data
mjr	35:e959ffba78fd	386	// bytes, all private vendor-specific values (meaning that the Windows HID
mjr	35:e959ffba78fd	387	// driver treats them as opaque and doesn't attempt to parse them).
mjr	35:e959ffba78fd	388	//
mjr	35:e959ffba78fd	389	// Within this basic 8-byte format, we recognize the full protocol used
mjr	35:e959ffba78fd	390	// by real LedWiz units, plus an extended protocol that we define privately.
mjr	35:e959ffba78fd	391	// The LedWiz protocol leaves a large part of the potential protocol space
mjr	35:e959ffba78fd	392	// undefined, so we take advantage of this undefined region for our
mjr	35:e959ffba78fd	393	// extensions. This ensures that we can properly recognize all messages
mjr	35:e959ffba78fd	394	// intended for a real LedWiz unit, as well as messages from custom host
mjr	35:e959ffba78fd	395	// software that knows it's talking to a Pinscape unit.
mjr	35:e959ffba78fd	396
mjr	35:e959ffba78fd	397	// --- REAL LED WIZ MESSAGES ---
mjr	35:e959ffba78fd	398	//
mjr	74:822a92bc11d2	399	// The real LedWiz protocol has two message types, "SBA" and "PBA". The
mjr	74:822a92bc11d2	400	// message type can be determined from the first byte of the 8-byte message
mjr	74:822a92bc11d2	401	// packet: if the first byte 64 (0x40), it's an SBA message. If the first
mjr	74:822a92bc11d2	402	// byte is 0-49 or 129-132, it's a PBA message. All other byte values are
mjr	74:822a92bc11d2	403	// invalid in the original protocol and have undefined behavior if sent to
mjr	74:822a92bc11d2	404	// a real LedWiz. We take advantage of this to extend the protocol with
mjr	74:822a92bc11d2	405	// our new features by assigning new meanings to byte patterns that have no
mjr	74:822a92bc11d2	406	// meaning in the original protocol.
mjr	35:e959ffba78fd	407	//
mjr	74:822a92bc11d2	408	// "SBA" message: 64 xx xx xx xx ss 00 00
mjr	74:822a92bc11d2	409	// xx = on/off bit mask for 8 outputs
mjr	74:822a92bc11d2	410	// ss = global flash speed setting (valid values 1-7)
mjr	74:822a92bc11d2	411	// 00 = unused/reserved; client should set to zero (not enforced, but
mjr	74:822a92bc11d2	412	// strongly recommended in case of future additions)
mjr	35:e959ffba78fd	413	//
mjr	35:e959ffba78fd	414	// If the first byte has value 64 (0x40), it's an SBA message. This type of
mjr	35:e959ffba78fd	415	// message sets all 32 outputs individually ON or OFF according to the next
mjr	35:e959ffba78fd	416	// 32 bits (4 bytes) of the message, and sets the flash speed to the value in
mjr	74:822a92bc11d2	417	// the sixth byte. The flash speed sets the global cycle rate for flashing
mjr	74:822a92bc11d2	418	// outputs - outputs with their values set to the range 128-132. The speed
mjr	74:822a92bc11d2	419	// parameter is in ad hoc units that aren't documented in the LedWiz API, but
mjr	74:822a92bc11d2	420	// observations of real LedWiz units show that the "speed" is actually the
mjr	74:822a92bc11d2	421	// period, each unit representing 0.25s: so speed 1 is a 0.25s period, or 4Hz,
mjr	74:822a92bc11d2	422	// speed 2 is a 0.5s period or 2Hz, etc., up to speed 7 as a 1.75s period or
mjr	74:822a92bc11d2	423	// 0.57Hz. The period is the full waveform cycle time.
mjr	74:822a92bc11d2	424	//
mjr	35:e959ffba78fd	425	//
mjr	74:822a92bc11d2	426	// "PBA" message: bb bb bb bb bb bb bb bb
mjr	74:822a92bc11d2	427	// bb = brightness level, 0-49 or 128-132
mjr	35:e959ffba78fd	428	//
mjr	74:822a92bc11d2	429	// Note that there's no prefix byte indicating this message type. This
mjr	74:822a92bc11d2	430	// message is indicated simply by the first byte being in one of the valid
mjr	74:822a92bc11d2	431	// ranges.
mjr	74:822a92bc11d2	432	//
mjr	74:822a92bc11d2	433	// Each byte gives the new brightness level or flash pattern for one part.
mjr	74:822a92bc11d2	434	// The valid values are:
mjr	35:e959ffba78fd	435	//
mjr	35:e959ffba78fd	436	// 0-48 = fixed brightness level, linearly from 0% to 100% intensity
mjr	35:e959ffba78fd	437	// 49 = fixed brightness level at 100% intensity (same as 48)
mjr	35:e959ffba78fd	438	// 129 = flashing pattern, fade up / fade down (sawtooth wave)
mjr	35:e959ffba78fd	439	// 130 = flashing pattern, on / off (square wave)
mjr	35:e959ffba78fd	440	// 131 = flashing pattern, on for 50% duty cycle / fade down
mjr	35:e959ffba78fd	441	// 132 = flashing pattern, fade up / on for 50% duty cycle
mjr	35:e959ffba78fd	442	//
mjr	74:822a92bc11d2	443	// This message sets new brightness/flash settings for 8 ports. There's
mjr	74:822a92bc11d2	444	// no port number specified in the message; instead, the port is given by
mjr	74:822a92bc11d2	445	// the protocol state. Specifically, the device has an internal register
mjr	74:822a92bc11d2	446	// containing the base port for PBA messages. On reset AND after any SBA
mjr	74:822a92bc11d2	447	// message is received, the base port is set to 0. After any PBA message
mjr	74:822a92bc11d2	448	// is received and processed, the base port is incremented by 8, resetting
mjr	74:822a92bc11d2	449	// to 0 when it reaches 32. The bytes of the message set the brightness
mjr	74:822a92bc11d2	450	// levels for the base port, base port + 1, ..., base port + 7 respectively.
mjr	35:e959ffba78fd	451	//
mjr	74:822a92bc11d2	452	//
mjr	35:e959ffba78fd	453
mjr	35:e959ffba78fd	454	// --- PRIVATE EXTENDED MESSAGES ---
mjr	35:e959ffba78fd	455	//
mjr	35:e959ffba78fd	456	// All of our extended protocol messages are identified by the first byte:
mjr	35:e959ffba78fd	457	//
mjr	35:e959ffba78fd	458	// 65 -> Miscellaneous control message. The second byte specifies the specific
mjr	35:e959ffba78fd	459	// operation:
mjr	35:e959ffba78fd	460	//
mjr	39:b3815a1c3802	461	// 0 -> No Op - does nothing. (This can be used to send a test message on the
mjr	39:b3815a1c3802	462	// USB endpoint.)
mjr	39:b3815a1c3802	463	//
mjr	35:e959ffba78fd	464	// 1 -> Set device unit number and plunger status, and save the changes immediately
mjr	35:e959ffba78fd	465	// to flash. The device will automatically reboot after the changes are saved.
mjr	35:e959ffba78fd	466	// The additional bytes of the message give the parameters:
mjr	35:e959ffba78fd	467	//
mjr	35:e959ffba78fd	468	// third byte = new unit number (0-15, corresponding to nominal unit numbers 1-16)
mjr	35:e959ffba78fd	469	// fourth byte = plunger on/off (0=disabled, 1=enabled)
mjr	35:e959ffba78fd	470	//
mjr	35:e959ffba78fd	471	// 2 -> Begin plunger calibration mode. The device stays in this mode for about
mjr	35:e959ffba78fd	472	// 15 seconds, and sets the zero point and maximum retraction points to the
mjr	35:e959ffba78fd	473	// observed endpoints of sensor readings while the mode is running. After
mjr	35:e959ffba78fd	474	// the time limit elapses, the device automatically stores the results in
mjr	35:e959ffba78fd	475	// non-volatile flash memory and exits the mode.
mjr	35:e959ffba78fd	476	//
mjr	51:57eb311faafa	477	// 3 -> Send pixel dump. The device sends one complete image snapshot from the
mjr	51:57eb311faafa	478	// plunger sensor, as as series of pixel dump messages. (The message format
mjr	51:57eb311faafa	479	// isn't big enough to allow the whole image to be sent in one message, so
mjr	53:9b2611964afc	480	// the image is broken up into as many messages as necessary.) The device
mjr	53:9b2611964afc	481	// then resumes sending normal joystick messages. If the plunger sensor
mjr	53:9b2611964afc	482	// isn't an imaging type, or no sensor is installed, no pixel messages are
mjr	53:9b2611964afc	483	// sent. Parameters:
mjr	48:058ace2aed1d	484	//
mjr	48:058ace2aed1d	485	// third byte = bit flags:
mjr	51:57eb311faafa	486	// 0x01 = low res mode. The device rescales the sensor pixel array
mjr	51:57eb311faafa	487	// sent in the dump messages to a low-resolution subset. The
mjr	51:57eb311faafa	488	// size of the subset is determined by the device. This has
mjr	51:57eb311faafa	489	// no effect on the sensor operation; it merely reduces the
mjr	51:57eb311faafa	490	// USB transmission time to allow for a faster frame rate for
mjr	51:57eb311faafa	491	// viewing in the config tool.
mjr	35:e959ffba78fd	492	//
mjr	53:9b2611964afc	493	// fourth byte = extra exposure time in 100us (.1ms) increments. For
mjr	53:9b2611964afc	494	// imaging sensors, we'll add this delay to the minimum exposure
mjr	53:9b2611964afc	495	// time. This allows the caller to explicitly adjust the exposure
mjr	53:9b2611964afc	496	// level for calibration purposes.
mjr	53:9b2611964afc	497	//
mjr	35:e959ffba78fd	498	// 4 -> Query configuration. The device sends a special configuration report,
mjr	40:cc0d9814522b	499	// (see above; see also USBJoystick.cpp), then resumes sending normal
mjr	40:cc0d9814522b	500	// joystick reports.
mjr	35:e959ffba78fd	501	//
mjr	74:822a92bc11d2	502	// 5 -> Turn all outputs off and restore LedWiz defaults. Sets all output
mjr	74:822a92bc11d2	503	// ports to OFF and LedWiz brightness/mode setting 48, and sets the LedWiz
mjr	74:822a92bc11d2	504	// global flash speed to 2.
mjr	35:e959ffba78fd	505	//
mjr	35:e959ffba78fd	506	// 6 -> Save configuration to flash. This saves all variable updates sent via
mjr	35:e959ffba78fd	507	// type 66 messages since the last reboot, then automatically reboots the
mjr	82:4f6209cb5c33	508	// device to put the changes into effect. If the flash write succeeds,
mjr	82:4f6209cb5c33	509	// we set the "flash write OK" bit in our status reports, which we
mjr	82:4f6209cb5c33	510	// continue sending between the successful write and the delayed reboot.
mjr	82:4f6209cb5c33	511	// We don't set the bit or reboot if the write fails.
mjr	35:e959ffba78fd	512	//
mjr	53:9b2611964afc	513	// third byte = delay time in seconds. The device will wait this long
mjr	82:4f6209cb5c33	514	// before disconnecting, to allow the PC to test for the success bit
mjr	82:4f6209cb5c33	515	// in the status report, and to perform any cleanup tasks while the
mjr	82:4f6209cb5c33	516	// device is still attached (e.g., modifying Windows device driver
mjr	82:4f6209cb5c33	517	// settings)
mjr	53:9b2611964afc	518	//
mjr	40:cc0d9814522b	519	// 7 -> Query device ID. The device replies with a special device ID report
mjr	40:cc0d9814522b	520	// (see above; see also USBJoystick.cpp), then resumes sending normal
mjr	40:cc0d9814522b	521	// joystick reports.
mjr	40:cc0d9814522b	522	//
mjr	53:9b2611964afc	523	// The third byte of the message is the ID index to retrieve:
mjr	53:9b2611964afc	524	//
mjr	53:9b2611964afc	525	// 1 = CPU ID: returns the KL25Z globally unique CPU ID.
mjr	53:9b2611964afc	526	//
mjr	53:9b2611964afc	527	// 2 = OpenSDA ID: returns the OpenSDA TUID. This must be patched
mjr	53:9b2611964afc	528	// into the firmware by the PC host when the .bin file is
mjr	53:9b2611964afc	529	// installed onto the device. This will return all 'X' bytes
mjr	53:9b2611964afc	530	// if the value wasn't patched at install time.
mjr	53:9b2611964afc	531	//
mjr	40:cc0d9814522b	532	// 8 -> Engage/disengage night mode. The third byte of the message is 1 to
mjr	55:4db125cd11a0	533	// engage night mode, 0 to disengage night mode. The current mode isn't
mjr	55:4db125cd11a0	534	// stored persistently; night mode is always off after a reset.
mjr	40:cc0d9814522b	535	//
mjr	52:8298b2a73eb2	536	// 9 -> Query configuration variable. The second byte is the config variable
mjr	52:8298b2a73eb2	537	// number (see the CONFIGURATION VARIABLES section below). For the array
mjr	52:8298b2a73eb2	538	// variables (button assignments, output ports), the third byte is the
mjr	52:8298b2a73eb2	539	// array index. The device replies with a configuration variable report
mjr	52:8298b2a73eb2	540	// (see above) with the current setting for the requested variable.
mjr	52:8298b2a73eb2	541	//
mjr	53:9b2611964afc	542	// 10 -> Query software build information. No parameters. This replies with
mjr	53:9b2611964afc	543	// the software build information report (see above).
mjr	53:9b2611964afc	544	//
mjr	73:4e8ce0b18915	545	// 11 -> TV ON relay manual control. This allows testing and operating the
mjr	73:4e8ce0b18915	546	// relay from the PC. This doesn't change the power-up configuration;
mjr	73:4e8ce0b18915	547	// it merely allows the relay to be controlled directly.
mjr	73:4e8ce0b18915	548	//
mjr	73:4e8ce0b18915	549	// 0 = turn relay off
mjr	73:4e8ce0b18915	550	// 1 = turn relay on
mjr	73:4e8ce0b18915	551	// 2 = pulse the relay as though the power-on delay timer fired
mjr	73:4e8ce0b18915	552	//
mjr	77:0b96f6867312	553	// 12 -> Learn IR code. The device enters "IR learning mode". While in
mjr	77:0b96f6867312	554	// learning mode, the device reports the raw signals read through
mjr	77:0b96f6867312	555	// the IR sensor to the PC through the special IR learning report
mjr	77:0b96f6867312	556	// (see "2G" above). If a signal can be decoded through a known
mjr	77:0b96f6867312	557	// protocol, the device sends a final "2G" report with the decoded
mjr	77:0b96f6867312	558	// command, then terminates learning mode. If no signal can be
mjr	77:0b96f6867312	559	// decoded within a timeout period, the mode automatically ends,
mjr	77:0b96f6867312	560	// and the device sends a final IR learning report with zero raw
mjr	77:0b96f6867312	561	// signals to indicate termination. After initiating IR learning
mjr	77:0b96f6867312	562	// mode, the user should point the remote control with the key to
mjr	77:0b96f6867312	563	// be learned at the IR sensor on the KL25Z, and press and hold the
mjr	77:0b96f6867312	564	// key on the remote for a few seconds. Holding the key for a few
mjr	77:0b96f6867312	565	// moments is important because it lets the decoder sense the type
mjr	77:0b96f6867312	566	// of auto-repeat coding the remote uses. The learned code can be
mjr	77:0b96f6867312	567	// written to an IR config variable slot to program the controller
mjr	77:0b96f6867312	568	// to send the learned command on events like TV ON or a button
mjr	77:0b96f6867312	569	// press.
mjr	77:0b96f6867312	570	//
mjr	78:1e00b3fa11af	571	// 13 -> Get button status report. The device sends one button status
mjr	78:1e00b3fa11af	572	// report in response (see section "2F" above).
mjr	78:1e00b3fa11af	573	//
mjr	78:1e00b3fa11af	574	// 14 -> Manually center the accelerometer. This sets the accelerometer
mjr	78:1e00b3fa11af	575	// zero point to the running average of readings over the past few
mjr	78:1e00b3fa11af	576	// seconds.
mjr	78:1e00b3fa11af	577	//
mjr	78:1e00b3fa11af	578	// 15 -> Set up ad hoc IR command, part 1. This sets up the first part
mjr	78:1e00b3fa11af	579	// of an IR command to transmit. The device stores the data in an
mjr	78:1e00b3fa11af	580	// internal register for later use in message 65 16. Send the
mjr	78:1e00b3fa11af	581	// remainder of the command data with 65 16.
mjr	78:1e00b3fa11af	582	//
mjr	78:1e00b3fa11af	583	// byte 3 = IR protocol ID
mjr	78:1e00b3fa11af	584	// byte 4 = flags (IRFlagXxx bit flags)
mjr	78:1e00b3fa11af	585	// byte 5-8 = low-order 32 bits of command code, little-endian
mjr	78:1e00b3fa11af	586	//
mjr	78:1e00b3fa11af	587	// 16 -> Finish and send an ad hoc IR command. Use message 65 15 first
mjr	78:1e00b3fa11af	588	// to set up the start of the command data, then send this message
mjr	78:1e00b3fa11af	589	// to fill in the rest of the data and transmit the command. Upon
mjr	78:1e00b3fa11af	590	// receiving this message, the device performs the transmission.
mjr	78:1e00b3fa11af	591	//
mjr	78:1e00b3fa11af	592	// byte 3-6 = high-order 32 bits of command code, little-endian
mjr	78:1e00b3fa11af	593	//
mjr	73:4e8ce0b18915	594	//
mjr	35:e959ffba78fd	595	// 66 -> Set configuration variable. The second byte of the message is the config
mjr	35:e959ffba78fd	596	// variable number, and the remaining bytes give the new value for the variable.
mjr	53:9b2611964afc	597	// The value format is specific to each variable; see the CONFIGURATION VARIABLES
mjr	53:9b2611964afc	598	// section below for a list of the variables and their formats. This command
mjr	53:9b2611964afc	599	// only sets the value in RAM; it doesn't write the value to flash and doesn't
mjr	53:9b2611964afc	600	// put the change into effect. To save the new settings, the host must send a
mjr	53:9b2611964afc	601	// type 65 subtype 6 message (see above). That saves the settings to flash and
mjr	53:9b2611964afc	602	// reboots the device, which makes the new settings active.
mjr	35:e959ffba78fd	603	//
mjr	74:822a92bc11d2	604	// 67 -> "SBX". This is an extended form of the original LedWiz SBA message. This
mjr	74:822a92bc11d2	605	// version is specifically designed to support a replacement LEDWIZ.DLL on the
mjr	74:822a92bc11d2	606	// host that exposes one Pinscape device as multiple virtual LedWiz devices,
mjr	74:822a92bc11d2	607	// in order to give legacy clients access to more than 32 ports. Each virtual
mjr	74:822a92bc11d2	608	// LedWiz represents a block of 32 ports. The format of this message is the
mjr	74:822a92bc11d2	609	// same as for the original SBA, with the addition of one byte:
mjr	74:822a92bc11d2	610	//
mjr	74:822a92bc11d2	611	// 67 xx xx xx xx ss pp 00
mjr	74:822a92bc11d2	612	// xx = on/off switches for 8 ports, one bit per port
mjr	74:822a92bc11d2	613	// ss = global flash speed setting for this bank of ports, 1-7
mjr	74:822a92bc11d2	614	// pp = port group: 0 for ports 1-32, 1 for ports 33-64, etc
mjr	74:822a92bc11d2	615	// 00 = unused/reserved; client should set to zero
mjr	74:822a92bc11d2	616	//
mjr	74:822a92bc11d2	617	// As with SBA, this sets the on/off switch states for a block of 32 ports.
mjr	74:822a92bc11d2	618	// SBA always addresses ports 1-32; SBX can address any set of 32 ports.
mjr	74:822a92bc11d2	619	//
mjr	74:822a92bc11d2	620	// We keep a separate speed setting for each group of 32 ports. The purpose
mjr	74:822a92bc11d2	621	// of the SBX extension is to allow a custom LEDWIZ.DLL to expose multiple
mjr	74:822a92bc11d2	622	// virtual LedWiz units to legacy clients, so clients will expect each unit
mjr	74:822a92bc11d2	623	// to have its separate flash speed setting. Each block of 32 ports maps to
mjr	74:822a92bc11d2	624	// a virtual unit on the client side, so each block needs its own speed state.
mjr	74:822a92bc11d2	625	//
mjr	74:822a92bc11d2	626	// 68 -> "PBX". This is an extended form of the original LedWiz PBA message; it's
mjr	74:822a92bc11d2	627	// the PBA equivalent of our SBX extension above.
mjr	74:822a92bc11d2	628	//
mjr	74:822a92bc11d2	629	// 68 pp ee ee ee ee ee ee
mjr	74:822a92bc11d2	630	// pp = port group: 0 for ports 1-8, 1 for 9-16, etc
mjr	74:822a92bc11d2	631	// qq = sequence number: 0 for the first 8 ports in the group, etc
mjr	74:822a92bc11d2	632	// ee = brightness/flash values, 6 bits per port, packed into the bytes
mjr	74:822a92bc11d2	633	//
mjr	74:822a92bc11d2	634	// The port group 'pp' selects a group of 8 ports. Note that, unlike PBA,
mjr	74:822a92bc11d2	635	// the port group being updated is explicitly coded in the message, which makes
mjr	74:822a92bc11d2	636	// the message stateless. This eliminates any possibility of the client and
mjr	74:822a92bc11d2	637	// host getting out of sync as to which ports they're talking about. This
mjr	74:822a92bc11d2	638	// message doesn't affect the PBA port address state.
mjr	74:822a92bc11d2	639	//
mjr	74:822a92bc11d2	640	// The brightness values are almost the same as in PBA, but not quite. We
mjr	74:822a92bc11d2	641	// remap the flashing state values as follows:
mjr	74:822a92bc11d2	642	//
mjr	74:822a92bc11d2	643	// 0-48 = brightness level, 0% to 100%, on a linear scale
mjr	74:822a92bc11d2	644	// 49 = brightness level 100% (redundant with 48)
mjr	74:822a92bc11d2	645	// 60 = PBA 129 equivalent, sawtooth
mjr	74:822a92bc11d2	646	// 61 = PBA 130 equivalent, square wave (on/off)
mjr	74:822a92bc11d2	647	// 62 = PBA 131 equivalent, on/fade down
mjr	74:822a92bc11d2	648	// 63 = PBA 132 equivalent, fade up/on
mjr	74:822a92bc11d2	649	//
mjr	74:822a92bc11d2	650	// We reassign the brightness levels like this because it allows us to pack
mjr	74:822a92bc11d2	651	// every possible value into 6 bits. This allows us to fit 8 port settings
mjr	74:822a92bc11d2	652	// into six bytes. The 6-bit fields are packed into the 8 bytes consecutively
mjr	74:822a92bc11d2	653	// starting with the low-order bit of the first byte. An efficient way to
mjr	74:822a92bc11d2	654	// pack the 'ee' fields given the brightness values is to shift each group of
mjr	74:822a92bc11d2	655	// four bytes into a uint, then shift the uint into three 'ee' bytes:
mjr	74:822a92bc11d2	656	//
mjr	74:822a92bc11d2	657	// unsigned int tmp1 = bri[0] \| (bri[1]<<6) \| (bri[2]<<12) \| (bri[3]<<18);
mjr	74:822a92bc11d2	658	// unsigned int tmp2 = bri[4] \| (bri[5]<<6) \| (bri[6]<<12) \| (bri[7]<<18);
mjr	74:822a92bc11d2	659	// unsigned char port_group = FIRST_PORT_TO_ADDRESS / 8;
mjr	74:822a92bc11d2	660	// unsigned char msg[8] = {
mjr	74:822a92bc11d2	661	// 68, pp,
mjr	74:822a92bc11d2	662	// tmp1 & 0xFF, (tmp1 >> 8) & 0xFF, (tmp1 >> 16) & 0xFF,
mjr	74:822a92bc11d2	663	// tmp2 & 0xFF, (tmp2 >> 8) & 0xFF, (tmp2 >> 16) & 0xFF
mjr	74:822a92bc11d2	664	// };
mjr	74:822a92bc11d2	665	//
mjr	35:e959ffba78fd	666	// 200-228 -> Set extended output brightness. This sets outputs N to N+6 to the
mjr	35:e959ffba78fd	667	// respective brightness values in the 2nd through 8th bytes of the message
mjr	35:e959ffba78fd	668	// (output N is set to the 2nd byte value, N+1 is set to the 3rd byte value,
mjr	35:e959ffba78fd	669	// etc). Each brightness level is a linear brightness level from 0-255,
mjr	35:e959ffba78fd	670	// where 0 is 0% brightness and 255 is 100% brightness. N is calculated as
mjr	35:e959ffba78fd	671	// (first byte - 200)*7 + 1:
mjr	35:e959ffba78fd	672	//
mjr	35:e959ffba78fd	673	// 200 = outputs 1-7
mjr	35:e959ffba78fd	674	// 201 = outputs 8-14
mjr	35:e959ffba78fd	675	// 202 = outputs 15-21
mjr	35:e959ffba78fd	676	// ...
mjr	35:e959ffba78fd	677	// 228 = outputs 197-203
mjr	35:e959ffba78fd	678	//
mjr	53:9b2611964afc	679	// This message is the way to address ports 33 and higher. Original LedWiz
mjr	53:9b2611964afc	680	// protocol messages can't access ports above 32, since the protocol is
mjr	53:9b2611964afc	681	// hard-wired for exactly 32 ports.
mjr	35:e959ffba78fd	682	//
mjr	53:9b2611964afc	683	// Note that the extended output messages differ from regular LedWiz commands
mjr	35:e959ffba78fd	684	// in two ways. First, the brightness is the ONLY attribute when an output is
mjr	53:9b2611964afc	685	// set using this mode. There's no separate ON/OFF state per output as there
mjr	35:e959ffba78fd	686	// is with the SBA/PBA messages. To turn an output OFF with this message, set
mjr	35:e959ffba78fd	687	// the intensity to 0. Setting a non-zero intensity turns it on immediately
mjr	35:e959ffba78fd	688	// without regard to the SBA status for the port. Second, the brightness is
mjr	35:e959ffba78fd	689	// on a full 8-bit scale (0-255) rather than the LedWiz's approximately 5-bit
mjr	35:e959ffba78fd	690	// scale, because there are no parts of the range reserved for flashing modes.
mjr	35:e959ffba78fd	691	//
mjr	35:e959ffba78fd	692	// Outputs 1-32 can be controlled by EITHER the regular LedWiz SBA/PBA messages
mjr	35:e959ffba78fd	693	// or by the extended messages. The latest setting for a given port takes
mjr	35:e959ffba78fd	694	// precedence. If an SBA/PBA message was the last thing sent to a port, the
mjr	35:e959ffba78fd	695	// normal LedWiz combination of ON/OFF and brightness/flash mode status is used
mjr	35:e959ffba78fd	696	// to determine the port's physical output setting. If an extended brightness
mjr	35:e959ffba78fd	697	// message was the last thing sent to a port, the LedWiz ON/OFF status and
mjr	35:e959ffba78fd	698	// flash modes are ignored, and the fixed brightness is set. Outputs 33 and
mjr	35:e959ffba78fd	699	// higher inherently can't be addressed or affected by SBA/PBA messages.
mjr	53:9b2611964afc	700	//
mjr	53:9b2611964afc	701	// (The precedence scheme is designed to accommodate a mix of legacy and DOF
mjr	53:9b2611964afc	702	// software transparently. The behavior described is really just to ensure
mjr	53:9b2611964afc	703	// transparent interoperability; it's not something that host software writers
mjr	53:9b2611964afc	704	// should have to worry about. We expect that anyone writing new software will
mjr	53:9b2611964afc	705	// just use the extended protocol and ignore the old LedWiz commands, since
mjr	53:9b2611964afc	706	// the extended protocol is easier to use and more powerful.)
mjr	35:e959ffba78fd	707
mjr	35:e959ffba78fd	708
mjr	35:e959ffba78fd	709	// ------- CONFIGURATION VARIABLES -------
mjr	35:e959ffba78fd	710	//
mjr	35:e959ffba78fd	711	// Message type 66 (see above) sets one configuration variable. The second byte
mjr	35:e959ffba78fd	712	// of the message is the variable ID, and the rest of the bytes give the new
mjr	35:e959ffba78fd	713	// value, in a variable-specific format. 16-bit values are little endian.
mjr	55:4db125cd11a0	714	// Any bytes at the end of the message not otherwise specified are reserved
mjr	55:4db125cd11a0	715	// for future use and should always be set to 0 in the message data.
mjr	35:e959ffba78fd	716	//
mjr	77:0b96f6867312	717	// Variable IDs:
mjr	77:0b96f6867312	718	//
mjr	53:9b2611964afc	719	// 0 -> QUERY ONLY: Describe the configuration variables. The device
mjr	53:9b2611964afc	720	// sends a config variable query report with the following fields:
mjr	53:9b2611964afc	721	//
mjr	53:9b2611964afc	722	// byte 3 -> number of scalar (non-array) variables (these are
mjr	53:9b2611964afc	723	// numbered sequentially from 1 to N)
mjr	53:9b2611964afc	724	// byte 4 -> number of array variables (these are numbered
mjr	53:9b2611964afc	725	// sequentially from 256-N to 255)
mjr	53:9b2611964afc	726	//
mjr	53:9b2611964afc	727	// The description query is meant to allow the host to capture all
mjr	53:9b2611964afc	728	// configuration settings on the device without having to know what
mjr	53:9b2611964afc	729	// the variables mean or how many there are. This is useful for
mjr	53:9b2611964afc	730	// backing up the settings in a file on the PC, for example, or for
mjr	53:9b2611964afc	731	// capturing them to restore after a firmware update. This allows
mjr	53:9b2611964afc	732	// more flexible interoperability between unsynchronized versions
mjr	53:9b2611964afc	733	// of the firmware and the host software.
mjr	53:9b2611964afc	734	//
mjr	53:9b2611964afc	735	// 1 -> USB device ID. This sets the USB vendor and product ID codes
mjr	53:9b2611964afc	736	// to use when connecting to the PC. For LedWiz emulation, use
mjr	35:e959ffba78fd	737	// vendor 0xFAFA and product 0x00EF + unit# (where unit# is the
mjr	53:9b2611964afc	738	// nominal LedWiz unit number, from 1 to 16). If you have any
mjr	53:9b2611964afc	739	// REAL LedWiz units in your system, we recommend starting the
mjr	53:9b2611964afc	740	// Pinscape LedWiz numbering at 8 to avoid conflicts with the
mjr	53:9b2611964afc	741	// real LedWiz units. If you don't have any real LedWiz units,
mjr	53:9b2611964afc	742	// you can number your Pinscape units starting from 1.
mjr	35:e959ffba78fd	743	//
mjr	53:9b2611964afc	744	// If LedWiz emulation isn't desired or causes host conflicts,
mjr	53:9b2611964afc	745	// use our private ID: Vendor 0x1209, product 0xEAEA. (These IDs
mjr	53:9b2611964afc	746	// are registered with http://pid.codes, a registry for open-source
mjr	53:9b2611964afc	747	// USB devices, so they're guaranteed to be free of conflicts with
mjr	53:9b2611964afc	748	// other properly registered devices). The device will NOT appear
mjr	53:9b2611964afc	749	// as an LedWiz if you use the private ID codes, but DOF (R3 or
mjr	53:9b2611964afc	750	// later) will still recognize it as a Pinscape controller.
mjr	53:9b2611964afc	751	//
mjr	53:9b2611964afc	752	// bytes 3:4 -> USB Vendor ID
mjr	53:9b2611964afc	753	// bytes 5:6 -> USB Product ID
mjr	53:9b2611964afc	754	//
mjr	53:9b2611964afc	755	// 2 -> Pinscape Controller unit number for DOF. The Pinscape unit
mjr	53:9b2611964afc	756	// number is independent of the LedWiz unit number, and indepedent
mjr	53:9b2611964afc	757	// of the USB vendor/product IDs. DOF (R3 and later) uses this to
mjr	53:9b2611964afc	758	// identify the unit for the extended Pinscape functionality.
mjr	53:9b2611964afc	759	// For easiest DOF configuration, we recommend numbering your
mjr	53:9b2611964afc	760	// units sequentially starting at 1 (regardless of whether or not
mjr	53:9b2611964afc	761	// you have any real LedWiz units).
mjr	53:9b2611964afc	762	//
mjr	53:9b2611964afc	763	// byte 3 -> unit number, from 1 to 16
mjr	35:e959ffba78fd	764	//
mjr	55:4db125cd11a0	765	// 3 -> Enable/disable joystick reports.
mjr	55:4db125cd11a0	766	//
mjr	55:4db125cd11a0	767	// byte 2 -> 1 to enable, 0 to disable
mjr	35:e959ffba78fd	768	//
mjr	55:4db125cd11a0	769	// When joystick reports are disabled, the device registers as a generic HID
mjr	55:4db125cd11a0	770	// device, and only sends the private report types used by the Windows config
mjr	55:4db125cd11a0	771	// tool. It won't appear to Windows as a USB game controller or joystick.
mjr	55:4db125cd11a0	772	//
mjr	55:4db125cd11a0	773	// Note that this doesn't affect whether the device also registers a keyboard
mjr	55:4db125cd11a0	774	// interface. A keyboard interface will appear if and only if any buttons
mjr	55:4db125cd11a0	775	// (including virtual buttons, such as the ZB Launch Ball feature) are assigned
mjr	55:4db125cd11a0	776	// to generate keyboard key input.
mjr	55:4db125cd11a0	777	//
mjr	77:0b96f6867312	778	// 4 -> Accelerometer settings
mjr	35:e959ffba78fd	779	//
mjr	55:4db125cd11a0	780	// byte 3 -> orientation:
mjr	55:4db125cd11a0	781	// 0 = ports at front (USB ports pointing towards front of cabinet)
mjr	55:4db125cd11a0	782	// 1 = ports at left
mjr	55:4db125cd11a0	783	// 2 = ports at right
mjr	55:4db125cd11a0	784	// 3 = ports at rear
mjr	77:0b96f6867312	785	// byte 4 -> dynamic range
mjr	78:1e00b3fa11af	786	// 0 = +/- 1G (2G hardware mode, but rescales joystick reports to 1G
mjr	78:1e00b3fa11af	787	// range; compatible with older versions)
mjr	77:0b96f6867312	788	// 1 = +/- 2G (2G hardware mode)
mjr	77:0b96f6867312	789	// 2 = +/- 4G (4G hardware mode)
mjr	77:0b96f6867312	790	// 3 = +/- 8G (8G hardware mode)
mjr	78:1e00b3fa11af	791	// byte 5 -> Auto-centering mode
mjr	78:1e00b3fa11af	792	// 0 = auto-centering on, 5 second timer (default, compatible
mjr	78:1e00b3fa11af	793	// with older versions)
mjr	78:1e00b3fa11af	794	// 1-60 = auto-centering on with the given time in seconds
mjr	78:1e00b3fa11af	795	// 61-245 = reserved
mjr	78:1e00b3fa11af	796	// 255 = auto-centering off; manual centering only
mjr	55:4db125cd11a0	797	//
mjr	55:4db125cd11a0	798	// 5 -> Plunger sensor type.
mjr	35:e959ffba78fd	799	//
mjr	55:4db125cd11a0	800	// byte 3 -> plunger type:
mjr	55:4db125cd11a0	801	// 0 = none (disabled)
mjr	82:4f6209cb5c33	802	// 1 = TSL1410R linear image sensor, 1280x1 pixels, serial mode, edge detection
mjr	82:4f6209cb5c33	803	// 3 = TSL1412R linear image sensor, 1536x1 pixels, serial mode, edge detection
mjr	55:4db125cd11a0	804	// 5 = Potentiometer with linear taper, or any other device that
mjr	55:4db125cd11a0	805	// represents the position reading with a single analog voltage
mjr	82:4f6209cb5c33	806	// 6 = AEDR8300 optical quadrature sensor, 75lpi
mjr	55:4db125cd11a0	807	// *7 = AS5304 magnetic quadrature sensor, 160 steps per 2mm
mjr	82:4f6209cb5c33	808	// 8 = TSL1401CL linear image sensor, 128x1 pixel, bar code detection
mjr	82:4f6209cb5c33	809	// 9 = VL6180X time-of-flight distance sensor
mjr	55:4db125cd11a0	810	//
mjr	55:4db125cd11a0	811	// * The sensor types marked with asterisks (*) are reserved for types
mjr	55:4db125cd11a0	812	// that aren't currently implemented but could be added in the future.
mjr	82:4f6209cb5c33	813	// Selecting these types will effectively disable the plunger. Note
mjr	82:4f6209cb5c33	814	// that sensor types 2 and 4 were formerly reserved for TSL14xx sensors
mjr	82:4f6209cb5c33	815	// in parallel wiring mode, but support for these is no longer planned,
mjr	82:4f6209cb5c33	816	// as the KL25Z's single ADC sampler makes it incapable of gaining any
mjr	82:4f6209cb5c33	817	// advantage from the parallel mode offered by the sensors. Those slots
mjr	82:4f6209cb5c33	818	// could be reassigned in the future for other sensors, since they were
mjr	82:4f6209cb5c33	819	// never enabled in any version of the firwmare.
mjr	55:4db125cd11a0	820	//
mjr	55:4db125cd11a0	821	// 6 -> Plunger pin assignments.
mjr	47:df7a88cd249c	822	//
mjr	55:4db125cd11a0	823	// byte 3 -> pin assignment 1
mjr	55:4db125cd11a0	824	// byte 4 -> pin assignment 2
mjr	55:4db125cd11a0	825	// byte 5 -> pin assignment 3
mjr	55:4db125cd11a0	826	// byte 6 -> pin assignment 4
mjr	55:4db125cd11a0	827	//
mjr	55:4db125cd11a0	828	// All of the pins use the standard GPIO port format (see "GPIO pin number
mjr	55:4db125cd11a0	829	// mappings" below). The actual use of the four pins depends on the plunger
mjr	55:4db125cd11a0	830	// type, as shown below. "NC" means that the pin isn't used at all for the
mjr	82:4f6209cb5c33	831	// corresponding plunger type. "GPIO" means that any GPIO pin will work.
mjr	82:4f6209cb5c33	832	// AnalogIn and InterruptIn means that only pins with the respective
mjr	82:4f6209cb5c33	833	// capabilities can be chosen.
mjr	35:e959ffba78fd	834	//
mjr	55:4db125cd11a0	835	// Plunger Type Pin 1 Pin 2 Pin 3 Pin 4
mjr	35:e959ffba78fd	836	//
mjr	82:4f6209cb5c33	837	// TSL1410R/1412R/1401CL SI (GPIO) CLK (GPIO) AO (AnalogIn) NC
mjr	55:4db125cd11a0	838	// Potentiometer AO (AnalogIn) NC NC NC
mjr	55:4db125cd11a0	839	// AEDR8300 A (InterruptIn) B (InterruptIn) NC NC
mjr	55:4db125cd11a0	840	// AS5304 A (InterruptIn) B (InterruptIn) NC NC
mjr	82:4f6209cb5c33	841	// VL6180X SDA (GPIO) SCL (GPIO) GPIO0/CE (GPIO) NC
mjr	55:4db125cd11a0	842	//
mjr	55:4db125cd11a0	843	// 7 -> Plunger calibration button pin assignments.
mjr	35:e959ffba78fd	844	//
mjr	55:4db125cd11a0	845	// byte 3 -> features enabled/disabled: bit mask consisting of:
mjr	55:4db125cd11a0	846	// 0x01 button input is enabled
mjr	55:4db125cd11a0	847	// 0x02 lamp output is enabled
mjr	55:4db125cd11a0	848	// byte 4 -> DigitalIn pin for the button switch
mjr	55:4db125cd11a0	849	// byte 5 -> DigitalOut pin for the indicator lamp
mjr	55:4db125cd11a0	850	//
mjr	55:4db125cd11a0	851	// Note that setting a pin to NC (Not Connected) will disable it even if the
mjr	55:4db125cd11a0	852	// corresponding feature enable bit (in byte 3) is set.
mjr	35:e959ffba78fd	853	//
mjr	55:4db125cd11a0	854	// 8 -> ZB Launch Ball setup. This configures the ZB Launch Ball feature.
mjr	55:4db125cd11a0	855	//
mjr	55:4db125cd11a0	856	// byte 3 -> LedWiz port number (1-255) mapped to "ZB Launch Ball" in DOF
mjr	55:4db125cd11a0	857	// byte 4 -> key type
mjr	55:4db125cd11a0	858	// byte 5 -> key code
mjr	55:4db125cd11a0	859	// bytes 6:7 -> "push" distance, in 1/1000 inch increments (16 bit little endian)
mjr	55:4db125cd11a0	860	//
mjr	55:4db125cd11a0	861	// Set the port number to 0 to disable the feature. The key type and key code
mjr	55:4db125cd11a0	862	// fields use the same conventions as for a button mapping (see below). The
mjr	55:4db125cd11a0	863	// recommended push distance is 63, which represents .063" ~ 1/16".
mjr	35:e959ffba78fd	864	//
mjr	35:e959ffba78fd	865	// 9 -> TV ON relay setup. This requires external circuitry implemented on the
mjr	35:e959ffba78fd	866	// Expansion Board (or an equivalent circuit as described in the Build Guide).
mjr	55:4db125cd11a0	867	//
mjr	55:4db125cd11a0	868	// byte 3 -> "power status" input pin (DigitalIn)
mjr	55:4db125cd11a0	869	// byte 4 -> "latch" output (DigitalOut)
mjr	55:4db125cd11a0	870	// byte 5 -> relay trigger output (DigitalOut)
mjr	55:4db125cd11a0	871	// bytes 6:7 -> delay time in 10ms increments (16 bit little endian);
mjr	55:4db125cd11a0	872	// e.g., 550 (0x26 0x02) represents 5.5 seconds
mjr	55:4db125cd11a0	873	//
mjr	55:4db125cd11a0	874	// Set the delay time to 0 to disable the feature. The pin assignments will
mjr	55:4db125cd11a0	875	// be ignored if the feature is disabled.
mjr	35:e959ffba78fd	876	//
mjr	77:0b96f6867312	877	// If an IR remote control transmitter is installed (see variable 17), we'll
mjr	77:0b96f6867312	878	// also transmit any IR codes designated as TV ON codes when the startup timer
mjr	77:0b96f6867312	879	// finishes. This allows TVs to be turned on via IR remotes codes rather than
mjr	77:0b96f6867312	880	// hard-wiring them through the relay. The relay can be omitted in this case.
mjr	77:0b96f6867312	881	//
mjr	35:e959ffba78fd	882	// 10 -> TLC5940NT setup. This chip is an external PWM controller, with 32 outputs
mjr	35:e959ffba78fd	883	// per chip and a serial data interface that allows the chips to be daisy-
mjr	35:e959ffba78fd	884	// chained. We can use these chips to add an arbitrary number of PWM output
mjr	55:4db125cd11a0	885	// ports for the LedWiz emulation.
mjr	55:4db125cd11a0	886	//
mjr	35:e959ffba78fd	887	// byte 3 = number of chips attached (connected in daisy chain)
mjr	35:e959ffba78fd	888	// byte 4 = SIN pin - Serial data (must connect to SPIO MOSI -> PTC6 or PTD2)
mjr	35:e959ffba78fd	889	// byte 5 = SCLK pin - Serial clock (must connect to SPIO SCLK -> PTC5 or PTD1)
mjr	35:e959ffba78fd	890	// byte 6 = XLAT pin - XLAT (latch) signal (any GPIO pin)
mjr	35:e959ffba78fd	891	// byte 7 = BLANK pin - BLANK signal (any GPIO pin)
mjr	35:e959ffba78fd	892	// byte 8 = GSCLK pin - Grayscale clock signal (must be a PWM-out capable pin)
mjr	35:e959ffba78fd	893	//
mjr	55:4db125cd11a0	894	// Set the number of chips to 0 to disable the feature. The pin assignments are
mjr	55:4db125cd11a0	895	// ignored if the feature is disabled.
mjr	55:4db125cd11a0	896	//
mjr	35:e959ffba78fd	897	// 11 -> 74HC595 setup. This chip is an external shift register, with 8 outputs per
mjr	35:e959ffba78fd	898	// chip and a serial data interface that allows daisy-chaining. We use this
mjr	35:e959ffba78fd	899	// chips to add extra digital outputs for the LedWiz emulation. In particular,
mjr	35:e959ffba78fd	900	// the Chime Board (part of the Expansion Board suite) uses these to add timer-
mjr	55:4db125cd11a0	901	// protected outputs for coil devices (knockers, chimes, bells, etc).
mjr	55:4db125cd11a0	902	//
mjr	35:e959ffba78fd	903	// byte 3 = number of chips attached (connected in daisy chain)
mjr	35:e959ffba78fd	904	// byte 4 = SIN pin - Serial data (any GPIO pin)
mjr	35:e959ffba78fd	905	// byte 5 = SCLK pin - Serial clock (any GPIO pin)
mjr	35:e959ffba78fd	906	// byte 6 = LATCH pin - LATCH signal (any GPIO pin)
mjr	35:e959ffba78fd	907	// byte 7 = ENA pin - ENABLE signal (any GPIO pin)
mjr	35:e959ffba78fd	908	//
mjr	55:4db125cd11a0	909	// Set the number of chips to 0 to disable the feature. The pin assignments are
mjr	55:4db125cd11a0	910	// ignored if the feature is disabled.
mjr	55:4db125cd11a0	911	//
mjr	53:9b2611964afc	912	// 12 -> Disconnect reboot timeout. The reboot timeout allows the controller software
mjr	51:57eb311faafa	913	// to automatically reboot the KL25Z after it detects that the USB connection is
mjr	51:57eb311faafa	914	// broken. On some hosts, the device isn't able to reconnect after the initial
mjr	51:57eb311faafa	915	// connection is lost. The reboot timeout is a workaround for these cases. When
mjr	51:57eb311faafa	916	// the software detects that the connection is no longer active, it will reboot
mjr	51:57eb311faafa	917	// the KL25Z automatically if a new connection isn't established within the
mjr	55:4db125cd11a0	918	// timeout period. Set the timeout to 0 to disable the feature (i.e., the device
mjr	55:4db125cd11a0	919	// will never automatically reboot itself on a broken connection).
mjr	55:4db125cd11a0	920	//
mjr	55:4db125cd11a0	921	// byte 3 -> reboot timeout in seconds; 0 = disabled
mjr	51:57eb311faafa	922	//
mjr	53:9b2611964afc	923	// 13 -> Plunger calibration. In most cases, the calibration is set internally by the
mjr	52:8298b2a73eb2	924	// device by running the calibration procedure. However, it's sometimes useful
mjr	52:8298b2a73eb2	925	// for the host to be able to get and set the calibration, such as to back up
mjr	52:8298b2a73eb2	926	// the device settings on the PC, or to save and restore the current settings
mjr	52:8298b2a73eb2	927	// when installing a software update.
mjr	52:8298b2a73eb2	928	//
mjr	52:8298b2a73eb2	929	// bytes 3:4 = rest position (unsigned 16-bit little-endian)
mjr	52:8298b2a73eb2	930	// bytes 5:6 = maximum retraction point (unsigned 16-bit little-endian)
mjr	52:8298b2a73eb2	931	// byte 7 = measured plunger release travel time in milliseconds
mjr	52:8298b2a73eb2	932	//
mjr	53:9b2611964afc	933	// 14 -> Expansion board configuration. This doesn't affect the controller behavior
mjr	52:8298b2a73eb2	934	// directly; the individual options related to the expansion boards (such as
mjr	52:8298b2a73eb2	935	// the TLC5940 and 74HC595 setup) still need to be set separately. This is
mjr	52:8298b2a73eb2	936	// stored so that the PC config UI can store and recover the information to
mjr	52:8298b2a73eb2	937	// present in the UI. For the "classic" KL25Z-only configuration, simply set
mjr	52:8298b2a73eb2	938	// all of the fields to zero.
mjr	52:8298b2a73eb2	939	//
mjr	53:9b2611964afc	940	// byte 3 = board set type. At the moment, the Pinscape expansion boards
mjr	53:9b2611964afc	941	// are the only ones supported in the software. This allows for
mjr	53:9b2611964afc	942	// adding new designs or independent designs in the future.
mjr	53:9b2611964afc	943	// 0 = Standalone KL25Z (no expansion boards)
mjr	53:9b2611964afc	944	// 1 = Pinscape expansion boards
mjr	53:9b2611964afc	945	//
mjr	53:9b2611964afc	946	// byte 4 = board set interface revision. This isn't the version number
mjr	53:9b2611964afc	947	// of the board itself, but rather of its software interface. In
mjr	53:9b2611964afc	948	// other words, this doesn't change every time the EAGLE layout
mjr	53:9b2611964afc	949	// for the board changes. It only changes when a revision is made
mjr	53:9b2611964afc	950	// that affects the software, such as a GPIO pin assignment.
mjr	53:9b2611964afc	951	//
mjr	55:4db125cd11a0	952	// For Pinscape expansion boards (board set type = 1):
mjr	55:4db125cd11a0	953	// 0 = first release (Feb 2016)
mjr	53:9b2611964afc	954	//
mjr	55:4db125cd11a0	955	// bytes 5:8 = additional hardware-specific data. These slots are used
mjr	55:4db125cd11a0	956	// to store extra data specific to the expansion boards selected.
mjr	55:4db125cd11a0	957	//
mjr	55:4db125cd11a0	958	// For Pinscape expansion boards (board set type = 1):
mjr	55:4db125cd11a0	959	// byte 5 = number of main interface boards
mjr	55:4db125cd11a0	960	// byte 6 = number of MOSFET power boards
mjr	55:4db125cd11a0	961	// byte 7 = number of chime boards
mjr	53:9b2611964afc	962	//
mjr	53:9b2611964afc	963	// 15 -> Night mode setup.
mjr	53:9b2611964afc	964	//
mjr	53:9b2611964afc	965	// byte 3 = button number - 1..MAX_BUTTONS, or 0 for none. This selects
mjr	53:9b2611964afc	966	// a physically wired button that can be used to control night mode.
mjr	53:9b2611964afc	967	// The button can also be used as normal for PC input if desired.
mjr	55:4db125cd11a0	968	// Note that night mode can still be activated via a USB command
mjr	55:4db125cd11a0	969	// even if no button is assigned.
mjr	55:4db125cd11a0	970	//
mjr	53:9b2611964afc	971	// byte 4 = flags:
mjr	66:2e3583fbd2f4	972	//
mjr	66:2e3583fbd2f4	973	// 0x01 -> The wired input is an on/off switch: night mode will be
mjr	53:9b2611964afc	974	// active when the input is switched on. If this bit isn't
mjr	66:2e3583fbd2f4	975	// set, the input is a momentary button: pushing the button
mjr	53:9b2611964afc	976	// toggles night mode.
mjr	55:4db125cd11a0	977	//
mjr	66:2e3583fbd2f4	978	// 0x02 -> Night Mode is assigned to the SHIFTED button (see Shift
mjr	66:2e3583fbd2f4	979	// Button setup at variable 16). This can only be used
mjr	66:2e3583fbd2f4	980	// in momentary mode; it's ignored if flag bit 0x01 is set.
mjr	66:2e3583fbd2f4	981	// When the shift flag is set, the button only toggles
mjr	66:2e3583fbd2f4	982	// night mode when you press it while also holding down
mjr	66:2e3583fbd2f4	983	// the Shift button.
mjr	66:2e3583fbd2f4	984	//
mjr	53:9b2611964afc	985	// byte 5 = indicator output number - 1..MAX_OUT_PORTS, or 0 for none. This
mjr	53:9b2611964afc	986	// selects an output port that will be turned on when night mode is
mjr	53:9b2611964afc	987	// activated. Night mode activation overrides any setting made by
mjr	53:9b2611964afc	988	// the host.
mjr	53:9b2611964afc	989	//
mjr	66:2e3583fbd2f4	990	// 16 -> Shift Button setup. One button can be designated as a "Local Shift
mjr	66:2e3583fbd2f4	991	// Button" that can be pressed to select a secondary meaning for other
mjr	78:1e00b3fa11af	992	// buttons. This isn't the same as the PC keyboard Shift keys; those can
mjr	66:2e3583fbd2f4	993	// be programmed using the USB key codes for Left Shift and Right Shift.
mjr	66:2e3583fbd2f4	994	// Rather, this applies a LOCAL shift feature in the cabinet button that
mjr	66:2e3583fbd2f4	995	// lets you select a secondary meaning. For example, you could assign
mjr	66:2e3583fbd2f4	996	// the Start button to the "1" key (VP "Start Game") normally, but have
mjr	66:2e3583fbd2f4	997	// its meaning change to the "5" key ("Insert Coin") when the shift
mjr	66:2e3583fbd2f4	998	// button is pressed. This provides access to more control functions
mjr	66:2e3583fbd2f4	999	// without adding more physical buttons.
mjr	66:2e3583fbd2f4	1000	//
mjr	78:1e00b3fa11af	1001	// byte 3 = button number - 1..MAX_BUTTONS, or 0 for none
mjr	78:1e00b3fa11af	1002	// byte 4 = mode (default is 0):
mjr	66:2e3583fbd2f4	1003	//
mjr	78:1e00b3fa11af	1004	// 0 -> Shift OR Key mode. In this mode, the Shift button doesn't
mjr	78:1e00b3fa11af	1005	// send its assigned key or IR command when initially pressed.
mjr	78:1e00b3fa11af	1006	// Instead, we wait to see if another button is pressed while
mjr	78:1e00b3fa11af	1007	// the Shift button is held down. If so, this Shift button
mjr	78:1e00b3fa11af	1008	// press ONLY counts as the Shift function, and its own assigned
mjr	78:1e00b3fa11af	1009	// key is NOT sent to the PC. On the other hand, if you press
mjr	78:1e00b3fa11af	1010	// the Shift button and then release it without having pressed
mjr	78:1e00b3fa11af	1011	// any other key in the meantime, this press counts as a regular
mjr	78:1e00b3fa11af	1012	// key press, so we send the assigned key to the PC.
mjr	78:1e00b3fa11af	1013	//
mjr	78:1e00b3fa11af	1014	// 1 -> Shift AND Key mode. In this mode, the Shift button sends its
mjr	78:1e00b3fa11af	1015	// assigned key when pressed, just like a normal button. If you
mjr	78:1e00b3fa11af	1016	// press another button while the Shift key is pressed, the
mjr	78:1e00b3fa11af	1017	// shifted meaning of the other key is used.
mjr	66:2e3583fbd2f4	1018	//
mjr	77:0b96f6867312	1019	// 17 -> IR Remote Control physical device setup. We support IR remotes for
mjr	77:0b96f6867312	1020	// both sending and receiving. On the receive side, we can read from a
mjr	77:0b96f6867312	1021	// sensor such as a TSOP384xx. The sensor requires one GPIO pin with
mjr	77:0b96f6867312	1022	// interrupt support, so any PTAxx or PTDxx pin will work. On the send
mjr	77:0b96f6867312	1023	// side, we can transmit through any IR LED. This requires one PWM
mjr	77:0b96f6867312	1024	// output pin. To enable send and/or receive, specify a valid pin; to
mjr	77:0b96f6867312	1025	// disable, set the pin NC (not connected). Send and receive can be
mjr	77:0b96f6867312	1026	// enabled and disabled independently; it's not necessary to enable
mjr	77:0b96f6867312	1027	// the transmit function to use the receive function, or vice versa.
mjr	77:0b96f6867312	1028	//
mjr	77:0b96f6867312	1029	// byte 3 = receiver input GPIO pin ID. Must be interrupt-capable.
mjr	77:0b96f6867312	1030	// byte 4 = transmitter pin. Must be PWM-capable.
mjr	77:0b96f6867312	1031	//
mjr	82:4f6209cb5c33	1032	// 18 -> Plunger auto-zeroing. This only applies to sensor types with
mjr	82:4f6209cb5c33	1033	// relative positioning, such as quadrature sensors. Other sensor
mjr	82:4f6209cb5c33	1034	// types simply ignore this.
mjr	82:4f6209cb5c33	1035	//
mjr	82:4f6209cb5c33	1036	// byte 3 = bit flags:
mjr	82:4f6209cb5c33	1037	// 0x01 -> auto-zeroing enabled
mjr	82:4f6209cb5c33	1038	// byte 4 = auto-zeroing time in seconds
mjr	82:4f6209cb5c33	1039	//
mjr	53:9b2611964afc	1040	//
mjr	74:822a92bc11d2	1041	// SPECIAL DIAGNOSTICS VARIABLES: These work like the array variables below,
mjr	74:822a92bc11d2	1042	// the only difference being that we don't report these in the number of array
mjr	74:822a92bc11d2	1043	// variables reported in the "variable 0" query.
mjr	74:822a92bc11d2	1044	//
mjr	74:822a92bc11d2	1045	// 220 -> Performance/diagnostics variables. Items marked "read only" can't
mjr	74:822a92bc11d2	1046	// be written; any SET VARIABLE messages on these are ignored. Items
mjr	74:822a92bc11d2	1047	// marked "diagnostic only" refer to counters or statistics that are
mjr	74:822a92bc11d2	1048	// collected only when the diagnostics are enabled via the diags.h
mjr	74:822a92bc11d2	1049	// macro ENABLE_DIAGNOSTICS. These will simply return zero otherwise.
mjr	74:822a92bc11d2	1050	//
mjr	74:822a92bc11d2	1051	// byte 3 = diagnostic index (see below)
mjr	74:822a92bc11d2	1052	//
mjr	74:822a92bc11d2	1053	// Diagnostic index values:
mjr	74:822a92bc11d2	1054	//
mjr	74:822a92bc11d2	1055	// 1 -> Main loop cycle time [read only, diagnostic only]
mjr	74:822a92bc11d2	1056	// Retrieves the average time of one iteration of the main
mjr	74:822a92bc11d2	1057	// loop, in microseconds, as a uint32. This excludes the
mjr	74:822a92bc11d2	1058	// time spent processing incoming messages, as well as any
mjr	74:822a92bc11d2	1059	// time spent waiting for a dropped USB connection to be
mjr	74:822a92bc11d2	1060	// restored. This includes all subroutine time and polled
mjr	74:822a92bc11d2	1061	// task time, such as processing button and plunger input,
mjr	74:822a92bc11d2	1062	// sending USB joystick reports, etc.
mjr	74:822a92bc11d2	1063	//
mjr	74:822a92bc11d2	1064	// 2 -> Main loop message read time [read only, diagnostic only]
mjr	74:822a92bc11d2	1065	// Retrieves the average time spent processing incoming USB
mjr	74:822a92bc11d2	1066	// messages per iteration of the main loop, in microseconds,
mjr	74:822a92bc11d2	1067	// as a uint32. This only counts the processing time when
mjr	74:822a92bc11d2	1068	// messages are actually present, so the average isn't reduced
mjr	74:822a92bc11d2	1069	// by iterations of the main loop where no messages are found.
mjr	74:822a92bc11d2	1070	// That is, if we run a million iterations of the main loop,
mjr	74:822a92bc11d2	1071	// and only five of them have messages at all, the average time
mjr	74:822a92bc11d2	1072	// includes only those five cycles with messages to process.
mjr	74:822a92bc11d2	1073	//
mjr	74:822a92bc11d2	1074	// 3 -> PWM update polling time [read only, diagnostic only]
mjr	74:822a92bc11d2	1075	// Retrieves the average time, as a uint32 in microseconds,
mjr	74:822a92bc11d2	1076	// spent in the PWM update polling routine.
mjr	74:822a92bc11d2	1077	//
mjr	74:822a92bc11d2	1078	// 4 -> LedWiz update polling time [read only, diagnostic only]
mjr	74:822a92bc11d2	1079	// Retrieves the average time, as a uint32 in microseconds,
mjr	74:822a92bc11d2	1080	// units, spent in the LedWiz flash cycle update routine.
mjr	74:822a92bc11d2	1081	//
mjr	74:822a92bc11d2	1082	//
mjr	53:9b2611964afc	1083	// ARRAY VARIABLES: Each variable below is an array. For each get/set message,
mjr	53:9b2611964afc	1084	// byte 3 gives the array index. These are grouped at the top end of the variable
mjr	53:9b2611964afc	1085	// ID range to distinguish this special feature. On QUERY, set the index byte to 0
mjr	53:9b2611964afc	1086	// to query the number of slots; the reply will be a report for the array index
mjr	53:9b2611964afc	1087	// variable with index 0, with the first (and only) byte after that indicating
mjr	53:9b2611964afc	1088	// the maximum array index.
mjr	53:9b2611964afc	1089	//
mjr	77:0b96f6867312	1090	// 250 -> IR remote control commands - code part 2. This stores the high-order
mjr	77:0b96f6867312	1091	// 32 bits of the remote control for each slot. These are combined with
mjr	77:0b96f6867312	1092	// the low-order 32 bits from variable 251 below to form a 64-bit code.
mjr	77:0b96f6867312	1093	//
mjr	77:0b96f6867312	1094	// byte 3 = Command slot number (1..MAX_IR_CODES)
mjr	77:0b96f6867312	1095	// byte 4 = bits 32..39 of remote control command code
mjr	77:0b96f6867312	1096	// byte 5 = bits 40..47
mjr	77:0b96f6867312	1097	// byte 6 = bits 48..55
mjr	77:0b96f6867312	1098	// byte 7 = bits 56..63
mjr	77:0b96f6867312	1099	//
mjr	77:0b96f6867312	1100	// 251 -> IR remote control commands - code part 1. This stores the protocol
mjr	77:0b96f6867312	1101	// identifier and low-order 32 bits of the remote control code for each
mjr	77:0b96f6867312	1102	// remote control command slot. The code represents a key press on a
mjr	77:0b96f6867312	1103	// remote, and is usually determined by reading it from the device's
mjr	77:0b96f6867312	1104	// actual remote via the IR sensor input feature. These codes combine
mjr	77:0b96f6867312	1105	// with variable 250 above to form a 64-bit code for each slot.
mjr	77:0b96f6867312	1106	// See IRRemote/IRProtocolID.h for the protocol ID codes.
mjr	77:0b96f6867312	1107	//
mjr	77:0b96f6867312	1108	// byte 3 = Command slot number (1..MAX_IR_CODES)
mjr	77:0b96f6867312	1109	// byte 4 = protocol ID
mjr	77:0b96f6867312	1110	// byte 5 = bits 0..7 of remote control command code
mjr	77:0b96f6867312	1111	// byte 6 = bits 8..15
mjr	77:0b96f6867312	1112	// byte 7 = bits 16..23
mjr	77:0b96f6867312	1113	// byte 8 = bits 24..31
mjr	77:0b96f6867312	1114	//
mjr	77:0b96f6867312	1115	// 252 -> IR remote control commands - control information. This stores
mjr	77:0b96f6867312	1116	// descriptive information for each remote control command slot.
mjr	77:0b96f6867312	1117	// The IR code for each slot is stored in the corresponding array
mjr	77:0b96f6867312	1118	// entry in variables 251 & 250 above; the information is split over
mjr	77:0b96f6867312	1119	// several variables like this because of the 8-byte command message
mjr	77:0b96f6867312	1120	// size in our USB protocol (which we use for LedWiz compatibility).
mjr	77:0b96f6867312	1121	//
mjr	77:0b96f6867312	1122	// byte 3 = Command slot number (1..MAX_IR_CODES)
mjr	77:0b96f6867312	1123	// byte 4 = bit flags:
mjr	77:0b96f6867312	1124	// 0x01 -> send this code as a TV ON signal at system start
mjr	77:0b96f6867312	1125	// 0x02 -> use "ditto" codes when sending the command
mjr	77:0b96f6867312	1126	// byte 5 = key type; same as the key type in an input button variable
mjr	77:0b96f6867312	1127	// byte 6 = key code; same as the key code in an input button variable
mjr	77:0b96f6867312	1128	//
mjr	77:0b96f6867312	1129	// Each IR command slot can serve three purposes:
mjr	77:0b96f6867312	1130	//
mjr	77:0b96f6867312	1131	// - First, it can be used as part of the TV ON sequence when the
mjr	77:0b96f6867312	1132	// system powers up, to turn on cabinet TVs that don't power up by
mjr	77:0b96f6867312	1133	// themselves. To use this feature, set the TV ON bit in the flags.
mjr	77:0b96f6867312	1134	//
mjr	77:0b96f6867312	1135	// - Second, when the IR sensor receives a command in a given slot, we
mjr	77:0b96f6867312	1136	// can translate it into a keyboard key or joystick button press sent
mjr	77:0b96f6867312	1137	// to the PC. This lets you use any IR remote to send commands to the
mjr	77:0b96f6867312	1138	// PC, allowing access to additional control inputs without any extra
mjr	77:0b96f6867312	1139	// buttons on the cabinet. To use this feature, assign the key to
mjr	77:0b96f6867312	1140	// send in the key type and key code bytes.
mjr	77:0b96f6867312	1141	//
mjr	77:0b96f6867312	1142	// - Third, we can send a given IR command when a physical cabinet
mjr	77:0b96f6867312	1143	// button is pressed. This lets you use cabinet buttons to send IR
mjr	77:0b96f6867312	1144	// commands to other devices in your system. For example, you could
mjr	77:0b96f6867312	1145	// assign cabinet buttons to control the volume on a cab TV. To use
mjr	77:0b96f6867312	1146	// this feature, assign an IR slot as a button function in the button
mjr	77:0b96f6867312	1147	// setup.
mjr	77:0b96f6867312	1148	//
mjr	66:2e3583fbd2f4	1149	// 253 -> Extended input button setup. This adds on to the information set by
mjr	66:2e3583fbd2f4	1150	// variable 254 below, accessing additional fields. The "shifted" key
mjr	66:2e3583fbd2f4	1151	// type and code fields assign a secondary meaning to the button that's
mjr	66:2e3583fbd2f4	1152	// used when the local Shift button is being held down. See variable 16
mjr	66:2e3583fbd2f4	1153	// above for more details on the Shift button.
mjr	66:2e3583fbd2f4	1154	//
mjr	77:0b96f6867312	1155	// byte 3 = Button number (1..MAX_BUTTONS)
mjr	66:2e3583fbd2f4	1156	// byte 4 = shifted key type (same codes as "key type" in var 254)
mjr	77:0b96f6867312	1157	// byte 5 = shifted key code (same codes as "key code" in var 254)
mjr	77:0b96f6867312	1158	// byte 6 = shifted IR command (see "IR command" in var 254)
mjr	66:2e3583fbd2f4	1159	//
mjr	53:9b2611964afc	1160	// 254 -> Input button setup. This sets up one button; it can be repeated for each
mjr	64:ef7ca92dff36	1161	// button to be configured. There are MAX_EXT_BUTTONS button slots (see
mjr	64:ef7ca92dff36	1162	// config.h for the constant definition), numbered 1..MAX_EXT_BUTTONS. Each
mjr	53:9b2611964afc	1163	// slot can be configured as a joystick button, a regular keyboard key, or a
mjr	53:9b2611964afc	1164	// media control key (mute, volume up, volume down).
mjr	53:9b2611964afc	1165	//
mjr	53:9b2611964afc	1166	// The bytes of the message are:
mjr	66:2e3583fbd2f4	1167	// byte 3 = Button number (1..MAX_BUTTONS)
mjr	64:ef7ca92dff36	1168	// byte 4 = GPIO pin for the button input; mapped as a DigitalIn port
mjr	53:9b2611964afc	1169	// byte 5 = key type reported to PC when button is pushed:
mjr	53:9b2611964afc	1170	// 0 = none (no PC input reported when button pushed)
mjr	53:9b2611964afc	1171	// 1 = joystick button -> byte 6 is the button number, 1-32
mjr	53:9b2611964afc	1172	// 2 = regular keyboard key -> byte 6 is the USB key code (see below)
mjr	67:c39e66c4e000	1173	// 3 = media key -> byte 6 is the USB media control code (see below)
mjr	53:9b2611964afc	1174	// byte 6 = key code, which depends on the key type in byte 5
mjr	53:9b2611964afc	1175	// byte 7 = flags - a combination of these bit values:
mjr	53:9b2611964afc	1176	// 0x01 = pulse mode. This reports a physical on/off switch's state
mjr	53:9b2611964afc	1177	// to the host as a brief key press whenever the switch changes
mjr	53:9b2611964afc	1178	// state. This is useful for the VPinMAME Coin Door button,
mjr	53:9b2611964afc	1179	// which requires the End key to be pressed each time the
mjr	53:9b2611964afc	1180	// door changes state.
mjr	77:0b96f6867312	1181	// byte 8 = IR command to transmit when unshifted button is pressed. This
mjr	77:0b96f6867312	1182	// contains an IR slot number (1..MAX_IR_CODES), or 0 if no code
mjr	77:0b96f6867312	1183	// is associated with the button.
mjr	53:9b2611964afc	1184	//
mjr	53:9b2611964afc	1185	// 255 -> LedWiz output port setup. This sets up one output port; it can be repeated
mjr	53:9b2611964afc	1186	// for each port to be configured. There are 128 possible slots for output ports,
mjr	53:9b2611964afc	1187	// numbered 1 to 128. The number of ports atcually active is determined by
mjr	53:9b2611964afc	1188	// the first DISABLED port (type 0). For example, if ports 1-32 are set as GPIO
mjr	53:9b2611964afc	1189	// outputs and port 33 is disabled, we'll report to the host that we have 32 ports,
mjr	53:9b2611964afc	1190	// regardless of the settings for post 34 and higher.
mjr	53:9b2611964afc	1191	//
mjr	53:9b2611964afc	1192	// The bytes of the message are:
mjr	53:9b2611964afc	1193	// byte 3 = LedWiz port number (1 to MAX_OUT_PORTS)
mjr	53:9b2611964afc	1194	// byte 4 = physical output type:
mjr	53:9b2611964afc	1195	// 0 = Disabled. This output isn't used, and isn't visible to the
mjr	53:9b2611964afc	1196	// LedWiz/DOF software on the host. The FIRST disabled port
mjr	53:9b2611964afc	1197	// determines the number of ports visible to the host - ALL ports
mjr	53:9b2611964afc	1198	// after the first disabled port are also implicitly disabled.
mjr	53:9b2611964afc	1199	// 1 = GPIO PWM output: connected to GPIO pin specified in byte 5,
mjr	53:9b2611964afc	1200	// operating in PWM mode. Note that only a subset of KL25Z GPIO
mjr	53:9b2611964afc	1201	// ports are PWM-capable.
mjr	53:9b2611964afc	1202	// 2 = GPIO Digital output: connected to GPIO pin specified in byte 5,
mjr	53:9b2611964afc	1203	// operating in digital mode. Digital ports can only be set ON
mjr	53:9b2611964afc	1204	// or OFF, with no brightness/intensity control. All pins can be
mjr	53:9b2611964afc	1205	// used in this mode.
mjr	53:9b2611964afc	1206	// 3 = TLC5940 port: connected to TLC5940 output port number specified
mjr	53:9b2611964afc	1207	// in byte 5. Ports are numbered sequentially starting from port 0
mjr	53:9b2611964afc	1208	// for the first output (OUT0) on the first chip in the daisy chain.
mjr	53:9b2611964afc	1209	// 4 = 74HC595 port: connected to 74HC595 output port specified in byte 5.
mjr	53:9b2611964afc	1210	// As with the TLC5940 outputs, ports are numbered sequentially from 0
mjr	53:9b2611964afc	1211	// for the first output on the first chip in the daisy chain.
mjr	53:9b2611964afc	1212	// 5 = Virtual output: this output port exists for the purposes of the
mjr	53:9b2611964afc	1213	// LedWiz/DOF software on the host, but isn't physically connected
mjr	53:9b2611964afc	1214	// to any output device. This can be used to create a virtual output
mjr	53:9b2611964afc	1215	// for the DOF ZB Launch Ball signal, for example, or simply as a
mjr	53:9b2611964afc	1216	// placeholder in the LedWiz port numbering. The physical output ID
mjr	53:9b2611964afc	1217	// (byte 5) is ignored for this port type.
mjr	53:9b2611964afc	1218	// byte 5 = physical output port, interpreted according to the value in byte 4
mjr	53:9b2611964afc	1219	// byte 6 = flags: a combination of these bit values:
mjr	53:9b2611964afc	1220	// 0x01 = active-high output (0V on output turns attached device ON)
mjr	53:9b2611964afc	1221	// 0x02 = noisemaker device: disable this output when "night mode" is engaged
mjr	53:9b2611964afc	1222	// 0x04 = apply gamma correction to this output
mjr	53:9b2611964afc	1223	//
mjr	53:9b2611964afc	1224	// Note that the on-board LED segments can be used as LedWiz output ports. This
mjr	53:9b2611964afc	1225	// is useful for testing a new installation with DOF or other PC software without
mjr	53:9b2611964afc	1226	// having to connect any external devices. Assigning the on-board LED segments to
mjr	53:9b2611964afc	1227	// output ports overrides their normal status/diagnostic display use, so the normal
mjr	53:9b2611964afc	1228	// status flash pattern won't appear when they're used this way.
mjr	52:8298b2a73eb2	1229	//
mjr	35:e959ffba78fd	1230
mjr	35:e959ffba78fd	1231
mjr	55:4db125cd11a0	1232	// --- GPIO PIN NUMBER MAPPINGS ---
mjr	35:e959ffba78fd	1233	//
mjr	53:9b2611964afc	1234	// In USB messages that specify GPIO pin assignments, pins are identified by
mjr	53:9b2611964afc	1235	// 8-bit integers. The special value 0xFF means NC (not connected). All actual
mjr	53:9b2611964afc	1236	// pins are mapped with the port number in the top 3 bits and the pin number in
mjr	53:9b2611964afc	1237	// the bottom 5 bits. Port A=0, B=1, ..., E=4. For example, PTC7 is port C (2)
mjr	53:9b2611964afc	1238	// pin 7, so it's represented as (2 << 5) \| 7.
mjr	53:9b2611964afc	1239
mjr	35:e959ffba78fd	1240
mjr	35:e959ffba78fd	1241	// --- USB KEYBOARD SCAN CODES ---
mjr	35:e959ffba78fd	1242	//
mjr	53:9b2611964afc	1243	// For regular keyboard keys, we use the standard USB HID scan codes
mjr	53:9b2611964afc	1244	// for the US keyboard layout. The scan codes are defined by the USB
mjr	53:9b2611964afc	1245	// HID specifications; you can find a full list in the official USB
mjr	53:9b2611964afc	1246	// specs. Some common codes are listed below as a quick reference.
mjr	35:e959ffba78fd	1247	//
mjr	53:9b2611964afc	1248	// Key name -> USB scan code (hex)
mjr	53:9b2611964afc	1249	// A-Z -> 04-1D
mjr	53:9b2611964afc	1250	// top row 1!->0) -> 1E-27
mjr	53:9b2611964afc	1251	// Return -> 28
mjr	53:9b2611964afc	1252	// Escape -> 29
mjr	53:9b2611964afc	1253	// Backspace -> 2A
mjr	53:9b2611964afc	1254	// Tab -> 2B
mjr	53:9b2611964afc	1255	// Spacebar -> 2C
mjr	53:9b2611964afc	1256	// -_ -> 2D
mjr	53:9b2611964afc	1257	// =+ -> 2E
mjr	53:9b2611964afc	1258	// [{ -> 2F
mjr	53:9b2611964afc	1259	// ]} -> 30
mjr	53:9b2611964afc	1260	// \\| -> 31
mjr	53:9b2611964afc	1261	// ;: -> 33
mjr	53:9b2611964afc	1262	// '" -> 34
mjr	53:9b2611964afc	1263	// `~ -> 35
mjr	53:9b2611964afc	1264	// ,< -> 36
mjr	53:9b2611964afc	1265	// .> -> 37
mjr	53:9b2611964afc	1266	// /? -> 38
mjr	53:9b2611964afc	1267	// Caps Lock -> 39
mjr	53:9b2611964afc	1268	// F1-F12 -> 3A-45
mjr	53:9b2611964afc	1269	// F13-F24 -> 68-73
mjr	53:9b2611964afc	1270	// Print Screen -> 46
mjr	53:9b2611964afc	1271	// Scroll Lock -> 47
mjr	53:9b2611964afc	1272	// Pause -> 48
mjr	53:9b2611964afc	1273	// Insert -> 49
mjr	53:9b2611964afc	1274	// Home -> 4A
mjr	53:9b2611964afc	1275	// Page Up -> 4B
mjr	53:9b2611964afc	1276	// Del -> 4C
mjr	53:9b2611964afc	1277	// End -> 4D
mjr	53:9b2611964afc	1278	// Page Down -> 4E
mjr	53:9b2611964afc	1279	// Right Arrow -> 4F
mjr	53:9b2611964afc	1280	// Left Arrow -> 50
mjr	53:9b2611964afc	1281	// Down Arrow -> 51
mjr	53:9b2611964afc	1282	// Up Arrow -> 52
mjr	53:9b2611964afc	1283	// Num Lock/Clear -> 53
mjr	53:9b2611964afc	1284	// Keypad / * - + -> 54 55 56 57
mjr	53:9b2611964afc	1285	// Keypad Enter -> 58
mjr	53:9b2611964afc	1286	// Keypad 1-9 -> 59-61
mjr	53:9b2611964afc	1287	// Keypad 0 -> 62
mjr	53:9b2611964afc	1288	// Keypad . -> 63
mjr	53:9b2611964afc	1289	// Mute -> 7F
mjr	53:9b2611964afc	1290	// Volume Up -> 80
mjr	53:9b2611964afc	1291	// Volume Down -> 81
mjr	53:9b2611964afc	1292	// Left Control -> E0
mjr	53:9b2611964afc	1293	// Left Shift -> E1
mjr	53:9b2611964afc	1294	// Left Alt -> E2
mjr	53:9b2611964afc	1295	// Left GUI -> E3
mjr	53:9b2611964afc	1296	// Right Control -> E4
mjr	53:9b2611964afc	1297	// Right Shift -> E5
mjr	53:9b2611964afc	1298	// Right Alt -> E6
mjr	53:9b2611964afc	1299	// Right GUI -> E7
mjr	53:9b2611964afc	1300	//
mjr	66:2e3583fbd2f4	1301	// Due to limitations in Windows, there's a limit of 6 regular keys
mjr	66:2e3583fbd2f4	1302	// pressed at the same time. The shift keys in the E0-E7 range don't
mjr	66:2e3583fbd2f4	1303	// count against this limit, though, since they're encoded as modifier
mjr	66:2e3583fbd2f4	1304	// keys; all of these can be pressed at the same time in addition to 6
mjr	67:c39e66c4e000	1305	// regular keys.
mjr	67:c39e66c4e000	1306
mjr	67:c39e66c4e000	1307	// --- USB MEDIA CONTROL SCAN CODES ---
mjr	67:c39e66c4e000	1308	//
mjr	67:c39e66c4e000	1309	// Buttons mapped to type 3 are Media Control buttons. These select
mjr	67:c39e66c4e000	1310	// a small set of common media control functions. We recognize the
mjr	67:c39e66c4e000	1311	// following type codes only:
mjr	67:c39e66c4e000	1312	//
mjr	67:c39e66c4e000	1313	// Mute -> E2
mjr	67:c39e66c4e000	1314	// Volume up -> E9
mjr	67:c39e66c4e000	1315	// Volume Down -> EA
mjr	67:c39e66c4e000	1316	// Next Track -> B5
mjr	67:c39e66c4e000	1317	// Previous Track -> B6
mjr	67:c39e66c4e000	1318	// Stop -> B7
mjr	67:c39e66c4e000	1319	// Play/Pause -> CD

Repository toolbox

Repository details

Type:	Program
Mbed OS support:	Mbed 2 deprecated
Created:	01 Oct 2021
Imports:	0
Forks:	0
Commits:	117
Dependents:	0
Dependencies:	4
Followers:	1

Important changes to repositories hosted on mbed.com

USBProtocol.h@82:4f6209cb5c33, 2017-04-13 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

USBProtocol.h@82:4f6209cb5c33, 2017-04-13 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning