Arnaud VALLEY / Mbed 2 deprecated Pinscape_Controller_V2_arnoz

Mirror with some correction

Dependencies:   mbed FastIO FastPWM USBDevice

USBProtocol.h@74:822a92bc11d2, 2017-01-27 (annotated)

Committer:
mjr
Date:
Fri Jan 27 23:47:15 2017 +0000
Revision:
74:822a92bc11d2
Parent:
73:4e8ce0b18915
Child:
75:677892300e7a
SBX/PBX extensions for multiple virtual LedWiz units on client; PWM GPIO update fixes; LedWiz pulse speed settings changed to match real LedWiz

Who changed what in which revision?

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