Arnaud VALLEY / Mbed 2 deprecated Pinscape_Controller_V2_arnoz

Mirror with some correction

Dependencies:   mbed FastIO FastPWM USBDevice

USBProtocol.h@53:9b2611964afc, 2016-04-22 (annotated)

Committer:
mjr
Date:
Fri Apr 22 17:58:35 2016 +0000
Revision:
53:9b2611964afc
Parent:
52:8298b2a73eb2
Child:
55:4db125cd11a0
Save some debugging instrumentation to be removed for release

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mjr 35:e959ffba78fd 1 // USB Message Protocol
mjr 35:e959ffba78fd 2 //
mjr 35:e959ffba78fd 3 // This file is purely for documentation, to describe our USB protocol.
mjr 35:e959ffba78fd 4 // We use the standard HID setup with one endpoint in each direction.
mjr 35:e959ffba78fd 5 // See USBJoystick.cpp/.h for our USB descriptor arrangement.
mjr 35:e959ffba78fd 6 //
mjr 35:e959ffba78fd 7
mjr 35:e959ffba78fd 8 // ------ OUTGOING MESSAGES (DEVICE TO HOST) ------
mjr 35:e959ffba78fd 9 //
mjr 47:df7a88cd249c 10 // General note: 16-bit and 32-bit fields in our reports are little-endian
mjr 47:df7a88cd249c 11 // unless otherwise specified.
mjr 47:df7a88cd249c 12 //
mjr 39:b3815a1c3802 13 // 1. Joystick reports
mjr 35:e959ffba78fd 14 // In most cases, our outgoing messages are HID joystick reports, using the
mjr 35:e959ffba78fd 15 // format defined in USBJoystick.cpp. This allows us to be installed on
mjr 35:e959ffba78fd 16 // Windows as a standard USB joystick, which all versions of Windows support
mjr 35:e959ffba78fd 17 // using in-the-box drivers. This allows a completely transparent, driverless,
mjr 39:b3815a1c3802 18 // plug-and-play installation experience on Windows. Our joystick report
mjr 39:b3815a1c3802 19 // looks like this (see USBJoystick.cpp for the formal HID report descriptor):
mjr 35:e959ffba78fd 20 //
mjr 39:b3815a1c3802 21 // ss status bits: 0x01 -> plunger enabled
mjr 40:cc0d9814522b 22 // 00 2nd byte of status (reserved)
mjr 40:cc0d9814522b 23 // 00 3rd byte of status (reserved)
mjr 39:b3815a1c3802 24 // 00 always zero for joystick reports
mjr 40:cc0d9814522b 25 // bb joystick buttons, low byte (buttons 1-8, 1 bit per button)
mjr 40:cc0d9814522b 26 // bb joystick buttons, 2nd byte (buttons 9-16)
mjr 40:cc0d9814522b 27 // bb joystick buttons, 3rd byte (buttons 17-24)
mjr 40:cc0d9814522b 28 // bb joystick buttons, high byte (buttons 25-32)
mjr 39:b3815a1c3802 29 // xx low byte of X position = nudge/accelerometer X axis
mjr 39:b3815a1c3802 30 // xx high byte of X position
mjr 39:b3815a1c3802 31 // yy low byte of Y position = nudge/accelerometer Y axis
mjr 39:b3815a1c3802 32 // yy high byte of Y position
mjr 39:b3815a1c3802 33 // zz low byte of Z position = plunger position
mjr 39:b3815a1c3802 34 // zz high byte of Z position
mjr 39:b3815a1c3802 35 //
mjr 39:b3815a1c3802 36 // The X, Y, and Z values are 16-bit signed integers. The accelerometer
mjr 39:b3815a1c3802 37 // values are on an abstract scale, where 0 represents no acceleration,
mjr 39:b3815a1c3802 38 // negative maximum represents -1g on that axis, and positive maximum
mjr 39:b3815a1c3802 39 // represents +1g on that axis. For the plunger position, 0 is the park
mjr 39:b3815a1c3802 40 // position (the rest position of the plunger) and positive values represent
mjr 39:b3815a1c3802 41 // retracted (pulled back) positions. A negative value means that the plunger
mjr 39:b3815a1c3802 42 // is pushed forward of the park position.
mjr 39:b3815a1c3802 43 //
mjr 39:b3815a1c3802 44 // 2. Special reports
mjr 35:e959ffba78fd 45 // We subvert the joystick report format in certain cases to report other
mjr 35:e959ffba78fd 46 // types of information, when specifically requested by the host. This allows
mjr 35:e959ffba78fd 47 // our custom configuration UI on the Windows side to query additional
mjr 35:e959ffba78fd 48 // information that we don't normally send via the joystick reports. We
mjr 35:e959ffba78fd 49 // define a custom vendor-specific "status" field in the reports that we
mjr 35:e959ffba78fd 50 // use to identify these special reports, as described below.
mjr 35:e959ffba78fd 51 //
mjr 39:b3815a1c3802 52 // Normal joystick reports always have 0 in the high bit of the 2nd byte
mjr 35:e959ffba78fd 53 // of the report. Special non-joystick reports always have 1 in the high bit
mjr 35:e959ffba78fd 54 // of the first byte. (This byte is defined in the HID Report Descriptor
mjr 35:e959ffba78fd 55 // as an opaque vendor-defined value, so the joystick interface on the
mjr 35:e959ffba78fd 56 // Windows side simply ignores it.)
mjr 35:e959ffba78fd 57 //
mjr 52:8298b2a73eb2 58 // 2A. Plunger sensor status report
mjr 52:8298b2a73eb2 59 // Software on the PC can request a detailed status report from the plunger
mjr 52:8298b2a73eb2 60 // sensor. The status information is meant as an aid to installing and
mjr 52:8298b2a73eb2 61 // adjusting the sensor device for proper performance. For imaging sensor
mjr 52:8298b2a73eb2 62 // types, the status report includes a complete current image snapshot
mjr 52:8298b2a73eb2 63 // (an array of all of the pixels the sensor is currently imaging). For
mjr 52:8298b2a73eb2 64 // all sensor types, it includes the current plunger position registered
mjr 52:8298b2a73eb2 65 // on the sensor, and some timing information.
mjr 52:8298b2a73eb2 66 //
mjr 52:8298b2a73eb2 67 // To request the sensor status, the host sends custom protocol message 65 3
mjr 52:8298b2a73eb2 68 // (see below). The device replies with a message in this format:
mjr 52:8298b2a73eb2 69 //
mjr 52:8298b2a73eb2 70 // bytes 0:1 = 0x87FF
mjr 52:8298b2a73eb2 71 // byte 2 = 0 -> first (currently only) status report packet
mjr 52:8298b2a73eb2 72 // (additional packets could be added in the future if
mjr 52:8298b2a73eb2 73 // more fields need to be added)
mjr 52:8298b2a73eb2 74 // bytes 3:4 = number of pixels to be sent in following messages, as
mjr 52:8298b2a73eb2 75 // an unsigned 16-bit little-endian integer. This is 0 if
mjr 52:8298b2a73eb2 76 // the sensor isn't an imaging type.
mjr 52:8298b2a73eb2 77 // bytes 5:6 = current plunger position registered on the sensor.
mjr 52:8298b2a73eb2 78 // For imaging sensors, this is the pixel position, so it's
mjr 52:8298b2a73eb2 79 // scaled from 0 to number of pixels - 1. For non-imaging
mjr 52:8298b2a73eb2 80 // sensors, this uses the generic joystick scale 0..4095.
mjr 52:8298b2a73eb2 81 // The special value 0xFFFF means that the position couldn't
mjr 52:8298b2a73eb2 82 // be determined,
mjr 52:8298b2a73eb2 83 // byte 7 = bit flags:
mjr 52:8298b2a73eb2 84 // 0x01 = normal orientation detected
mjr 52:8298b2a73eb2 85 // 0x02 = reversed orientation detected
mjr 52:8298b2a73eb2 86 // 0x04 = calibration mode is active (no pixel packets
mjr 52:8298b2a73eb2 87 // are sent for this reading)
mjr 52:8298b2a73eb2 88 // bytes 8:9:10 = average time for each sensor read, in 10us units.
mjr 52:8298b2a73eb2 89 // This is the average time it takes to complete the I/O
mjr 52:8298b2a73eb2 90 // operation to read the sensor, to obtain the raw sensor
mjr 52:8298b2a73eb2 91 // data for instantaneous plunger position reading. For
mjr 52:8298b2a73eb2 92 // an imaging sensor, this is the time it takes for the
mjr 52:8298b2a73eb2 93 // sensor to capture the image and transfer it to the
mjr 52:8298b2a73eb2 94 // microcontroller. For an analog sensor (e.g., an LVDT
mjr 52:8298b2a73eb2 95 // or potentiometer), it's the time to complete an ADC
mjr 52:8298b2a73eb2 96 // sample.
mjr 52:8298b2a73eb2 97 // bytes 11:12:13 = time it took to process the current frame, in 10us
mjr 52:8298b2a73eb2 98 // units. This is the software processing time that was
mjr 52:8298b2a73eb2 99 // needed to analyze the raw data read from the sensor.
mjr 52:8298b2a73eb2 100 // This is typically only non-zero for imaging sensors,
mjr 52:8298b2a73eb2 101 // where it reflects the time required to scan the pixel
mjr 52:8298b2a73eb2 102 // array to find the indicated plunger position. The time
mjr 52:8298b2a73eb2 103 // is usually zero or negligible for analog sensor types,
mjr 52:8298b2a73eb2 104 // since the only "analysis" is a multiplication to rescale
mjr 52:8298b2a73eb2 105 // the ADC sample.
mjr 52:8298b2a73eb2 106 //
mjr 52:8298b2a73eb2 107 // If the sensor is an imaging sensor type, this will be followed by a
mjr 52:8298b2a73eb2 108 // series of pixel messages. The imaging sensor types have too many pixels
mjr 52:8298b2a73eb2 109 // to send in a single USB transaction, so the device breaks up the array
mjr 52:8298b2a73eb2 110 // into as many packets as needed and sends them in sequence. For non-
mjr 52:8298b2a73eb2 111 // imaging sensors, the "number of pixels" field in the lead packet is
mjr 52:8298b2a73eb2 112 // zero, so obviously no pixel packets will follow. If the "calibration
mjr 52:8298b2a73eb2 113 // active" bit in the flags byte is set, no pixel packets are sent even
mjr 52:8298b2a73eb2 114 // if the sensor is an imaging type, since the transmission time for the
mjr 52:8298b2a73eb2 115 // pixels would intefere with the calibration process. If pixels are sent,
mjr 52:8298b2a73eb2 116 // they're sent in order starting at the first pixel. The format of each
mjr 52:8298b2a73eb2 117 // pixel packet is:
mjr 35:e959ffba78fd 118 //
mjr 35:e959ffba78fd 119 // bytes 0:1 = 11-bit index, with high 5 bits set to 10000. For
mjr 48:058ace2aed1d 120 // example, 0x8004 (encoded little endian as 0x04 0x80)
mjr 48:058ace2aed1d 121 // indicates index 4. This is the starting pixel number
mjr 48:058ace2aed1d 122 // in the report. The first report will be 0x00 0x80 to
mjr 48:058ace2aed1d 123 // indicate pixel #0.
mjr 47:df7a88cd249c 124 // bytes 2 = 8-bit unsigned int brightness level of pixel at index
mjr 47:df7a88cd249c 125 // bytes 3 = brightness of pixel at index+1
mjr 35:e959ffba78fd 126 // etc for the rest of the packet
mjr 35:e959ffba78fd 127 //
mjr 52:8298b2a73eb2 128 // Note that we currently only support one-dimensional imaging sensors
mjr 52:8298b2a73eb2 129 // (i.e., pixel arrays that are 1 pixel wide). The report format doesn't
mjr 52:8298b2a73eb2 130 // have any provision for a two-dimensional layout. The KL25Z probably
mjr 52:8298b2a73eb2 131 // isn't powerful enough to do real-time image analysis on a 2D image
mjr 52:8298b2a73eb2 132 // anyway, so it's unlikely that we'd be able to make 2D sensors work at
mjr 52:8298b2a73eb2 133 // all, but if we ever add such a thing we'll have to upgrade the report
mjr 52:8298b2a73eb2 134 // format here accordingly.
mjr 51:57eb311faafa 135 //
mjr 51:57eb311faafa 136 //
mjr 53:9b2611964afc 137 // 2B. Configuration report.
mjr 39:b3815a1c3802 138 // This is requested by sending custom protocol message 65 4 (see below).
mjr 39:b3815a1c3802 139 // In reponse, the device sends one report to the host using this format:
mjr 35:e959ffba78fd 140 //
mjr 35:e959ffba78fd 141 // bytes 0:1 = 0x8800. This has the bit pattern 10001 in the high
mjr 35:e959ffba78fd 142 // 5 bits, which distinguishes it from regular joystick
mjr 40:cc0d9814522b 143 // reports and from other special report types.
mjr 35:e959ffba78fd 144 // bytes 2:3 = total number of outputs, little endian
mjr 40:cc0d9814522b 145 // bytes 6:7 = plunger calibration zero point, little endian
mjr 40:cc0d9814522b 146 // bytes 8:9 = plunger calibration maximum point, little endian
mjr 52:8298b2a73eb2 147 // byte 10 = plunger calibration release time, in milliseconds
mjr 52:8298b2a73eb2 148 // byte 11 = bit flags:
mjr 40:cc0d9814522b 149 // 0x01 -> configuration loaded; 0 in this bit means that
mjr 40:cc0d9814522b 150 // the firmware has been loaded but no configuration
mjr 40:cc0d9814522b 151 // has been sent from the host
mjr 40:cc0d9814522b 152 // The remaining bytes are reserved for future use.
mjr 35:e959ffba78fd 153 //
mjr 53:9b2611964afc 154 // 2C. Device ID report.
mjr 40:cc0d9814522b 155 // This is requested by sending custom protocol message 65 7 (see below).
mjr 40:cc0d9814522b 156 // In response, the device sends one report to the host using this format:
mjr 40:cc0d9814522b 157 //
mjr 52:8298b2a73eb2 158 // bytes 0:1 = 0x9000. This has bit pattern 10010 in the high 5 bits
mjr 52:8298b2a73eb2 159 // to distinguish this from other report types.
mjr 53:9b2611964afc 160 // byte 2 = ID type. This is the same ID type sent in the request.
mjr 53:9b2611964afc 161 // bytes 3-12 = requested ID. The ID is 80 bits in big-endian byte
mjr 53:9b2611964afc 162 // order. For IDs longer than 80 bits, we truncate to the
mjr 53:9b2611964afc 163 // low-order 80 bits (that is, the last 80 bits).
mjr 53:9b2611964afc 164 //
mjr 53:9b2611964afc 165 // ID type 1 = CPU ID. This is the globally unique CPU ID
mjr 53:9b2611964afc 166 // stored in the KL25Z CPU.
mjr 35:e959ffba78fd 167 //
mjr 53:9b2611964afc 168 // ID type 2 = OpenSDA ID. This is the globally unique ID
mjr 53:9b2611964afc 169 // for the connected OpenSDA controller, if known. This
mjr 53:9b2611964afc 170 // allow the host to figure out which USB MSD (virtual
mjr 53:9b2611964afc 171 // disk drive), if any, represents the OpenSDA module for
mjr 53:9b2611964afc 172 // this Pinscape USB interface. This is primarily useful
mjr 53:9b2611964afc 173 // to determine which MSD to write in order to update the
mjr 53:9b2611964afc 174 // firmware on a given Pinscape unit.
mjr 53:9b2611964afc 175 //
mjr 53:9b2611964afc 176 // 2D. Configuration variable report.
mjr 52:8298b2a73eb2 177 // This is requested by sending custom protocol message 65 9 (see below).
mjr 52:8298b2a73eb2 178 // In response, the device sends one report to the host using this format:
mjr 52:8298b2a73eb2 179 //
mjr 52:8298b2a73eb2 180 // bytes 0:1 = 0x9800. This has bit pattern 10011 in the high 5 bits
mjr 52:8298b2a73eb2 181 // to distinguish this from other report types.
mjr 52:8298b2a73eb2 182 // byte 2 = Variable ID. This is the same variable ID sent in the
mjr 52:8298b2a73eb2 183 // query message, to relate the reply to the request.
mjr 52:8298b2a73eb2 184 // bytes 3-8 = Current value of the variable, in the format for the
mjr 52:8298b2a73eb2 185 // individual variable type. The variable formats are
mjr 52:8298b2a73eb2 186 // described in the CONFIGURATION VARIABLES section below.
mjr 52:8298b2a73eb2 187 //
mjr 53:9b2611964afc 188 // 2E. Software build information report.
mjr 53:9b2611964afc 189 // This is requested by sending custom protocol message 65 10 (see below).
mjr 53:9b2611964afc 190 // In response, the device sends one report using this format:
mjr 53:9b2611964afc 191 //
mjr 53:9b2611964afc 192 // bytes 0:1 = 0xA0. This has bit pattern 10100 in the high 5 bits
mjr 53:9b2611964afc 193 // to distinguish it from other report types.
mjr 53:9b2611964afc 194 // bytes 2:5 = Build date. This is returned as a 32-bit integer,
mjr 53:9b2611964afc 195 // little-endian as usual, encoding a decimal value
mjr 53:9b2611964afc 196 // in the format YYYYMMDD giving the date of the build.
mjr 53:9b2611964afc 197 // E.g., Feb 16 2016 is encoded as 20160216 (decimal).
mjr 53:9b2611964afc 198 // bytes 6:9 = Build time. This is a 32-bit integer, little-endian,
mjr 53:9b2611964afc 199 // encoding a decimal value in the format HHMMSS giving
mjr 53:9b2611964afc 200 // build time on a 24-hour clock.
mjr 53:9b2611964afc 201 //
mjr 52:8298b2a73eb2 202 //
mjr 35:e959ffba78fd 203 // WHY WE USE THIS HACKY APPROACH TO DIFFERENT REPORT TYPES
mjr 35:e959ffba78fd 204 //
mjr 35:e959ffba78fd 205 // The HID report system was specifically designed to provide a clean,
mjr 35:e959ffba78fd 206 // structured way for devices to describe the data they send to the host.
mjr 35:e959ffba78fd 207 // Our approach isn't clean or structured; it ignores the promises we
mjr 35:e959ffba78fd 208 // make about the contents of our report via the HID Report Descriptor
mjr 35:e959ffba78fd 209 // and stuffs our own different data format into the same structure.
mjr 35:e959ffba78fd 210 //
mjr 35:e959ffba78fd 211 // We use this hacky approach only because we can't use the official
mjr 35:e959ffba78fd 212 // mechanism, due to the constraint that we want to emulate the LedWiz.
mjr 35:e959ffba78fd 213 // The right way to send different report types is to declare different
mjr 35:e959ffba78fd 214 // report types via extra HID Report Descriptors, then send each report
mjr 35:e959ffba78fd 215 // using one of the types we declared. If it weren't for the LedWiz
mjr 35:e959ffba78fd 216 // constraint, we'd simply define the pixel dump and config query reports
mjr 35:e959ffba78fd 217 // as their own separate HID Report types, each consisting of opaque
mjr 35:e959ffba78fd 218 // blocks of bytes. But we can't do this. The snag is that some versions
mjr 35:e959ffba78fd 219 // of the LedWiz Windows host software parse the USB HID descriptors as part
mjr 35:e959ffba78fd 220 // of identifying a device as a valid LedWiz unit, and will only recognize
mjr 35:e959ffba78fd 221 // the device if it matches certain particulars about the descriptor
mjr 35:e959ffba78fd 222 // structure of a real LedWiz. One of the features that's important to
mjr 35:e959ffba78fd 223 // some versions of the software is the descriptor link structure, which
mjr 35:e959ffba78fd 224 // is affected by the layout of HID Report Descriptor entries. In order
mjr 35:e959ffba78fd 225 // to match the expected layout, we can only define a single kind of output
mjr 35:e959ffba78fd 226 // report. Since we have to use Joystick reports for the sake of VP and
mjr 35:e959ffba78fd 227 // other pinball software, and we're only allowed the one report type, we
mjr 35:e959ffba78fd 228 // have to make that one report type the Joystick type. That's why we
mjr 35:e959ffba78fd 229 // overload the joystick reports with other meanings. It's a hack, but
mjr 35:e959ffba78fd 230 // at least it's a fairly reliable and isolated hack, iun that our special
mjr 35:e959ffba78fd 231 // reports are only generated when clients specifically ask for them.
mjr 35:e959ffba78fd 232 // Plus, even if a client who doesn't ask for a special report somehow
mjr 35:e959ffba78fd 233 // gets one, the worst that happens is that they get a momentary spurious
mjr 35:e959ffba78fd 234 // reading from the accelerometer and plunger.
mjr 35:e959ffba78fd 235
mjr 35:e959ffba78fd 236
mjr 35:e959ffba78fd 237
mjr 35:e959ffba78fd 238 // ------- INCOMING MESSAGES (HOST TO DEVICE) -------
mjr 35:e959ffba78fd 239 //
mjr 35:e959ffba78fd 240 // For LedWiz compatibility, our incoming message format conforms to the
mjr 35:e959ffba78fd 241 // basic USB format used by real LedWiz units. This is simply 8 data
mjr 35:e959ffba78fd 242 // bytes, all private vendor-specific values (meaning that the Windows HID
mjr 35:e959ffba78fd 243 // driver treats them as opaque and doesn't attempt to parse them).
mjr 35:e959ffba78fd 244 //
mjr 35:e959ffba78fd 245 // Within this basic 8-byte format, we recognize the full protocol used
mjr 35:e959ffba78fd 246 // by real LedWiz units, plus an extended protocol that we define privately.
mjr 35:e959ffba78fd 247 // The LedWiz protocol leaves a large part of the potential protocol space
mjr 35:e959ffba78fd 248 // undefined, so we take advantage of this undefined region for our
mjr 35:e959ffba78fd 249 // extensions. This ensures that we can properly recognize all messages
mjr 35:e959ffba78fd 250 // intended for a real LedWiz unit, as well as messages from custom host
mjr 35:e959ffba78fd 251 // software that knows it's talking to a Pinscape unit.
mjr 35:e959ffba78fd 252
mjr 35:e959ffba78fd 253 // --- REAL LED WIZ MESSAGES ---
mjr 35:e959ffba78fd 254 //
mjr 35:e959ffba78fd 255 // The real LedWiz protocol has two message types, identified by the first
mjr 35:e959ffba78fd 256 // byte of the 8-byte USB packet:
mjr 35:e959ffba78fd 257 //
mjr 35:e959ffba78fd 258 // 64 -> SBA (64 xx xx xx xx ss uu uu)
mjr 35:e959ffba78fd 259 // xx = on/off bit mask for 8 outputs
mjr 35:e959ffba78fd 260 // ss = global flash speed setting (1-7)
mjr 35:e959ffba78fd 261 // uu = unused
mjr 35:e959ffba78fd 262 //
mjr 35:e959ffba78fd 263 // If the first byte has value 64 (0x40), it's an SBA message. This type of
mjr 35:e959ffba78fd 264 // message sets all 32 outputs individually ON or OFF according to the next
mjr 35:e959ffba78fd 265 // 32 bits (4 bytes) of the message, and sets the flash speed to the value in
mjr 35:e959ffba78fd 266 // the sixth byte. (The flash speed sets the global cycle rate for flashing
mjr 35:e959ffba78fd 267 // outputs - outputs with their values set to the range 128-132 - to a
mjr 35:e959ffba78fd 268 // relative speed, scaled linearly in frequency. 1 is the slowest at about
mjr 35:e959ffba78fd 269 // 2 Hz, 7 is the fastest at about 14 Hz.)
mjr 35:e959ffba78fd 270 //
mjr 35:e959ffba78fd 271 // 0-49 or 128-132 -> PBA (bb bb bb bb bb bb bb bb)
mjr 35:e959ffba78fd 272 // bb = brightness level/flash pattern for one output
mjr 35:e959ffba78fd 273 //
mjr 35:e959ffba78fd 274 // If the first byte is any valid brightness setting, it's a PBA message.
mjr 35:e959ffba78fd 275 // Valid brightness settings are:
mjr 35:e959ffba78fd 276 //
mjr 35:e959ffba78fd 277 // 0-48 = fixed brightness level, linearly from 0% to 100% intensity
mjr 35:e959ffba78fd 278 // 49 = fixed brightness level at 100% intensity (same as 48)
mjr 35:e959ffba78fd 279 // 129 = flashing pattern, fade up / fade down (sawtooth wave)
mjr 35:e959ffba78fd 280 // 130 = flashing pattern, on / off (square wave)
mjr 35:e959ffba78fd 281 // 131 = flashing pattern, on for 50% duty cycle / fade down
mjr 35:e959ffba78fd 282 // 132 = flashing pattern, fade up / on for 50% duty cycle
mjr 35:e959ffba78fd 283 //
mjr 35:e959ffba78fd 284 // A PBA message sets 8 outputs out of 32. Which 8 are to be set is
mjr 35:e959ffba78fd 285 // implicit in the message sequence: the first PBA sets outputs 1-8, the
mjr 35:e959ffba78fd 286 // second sets 9-16, and so on, rolling around after each fourth PBA.
mjr 35:e959ffba78fd 287 // An SBA also resets the implicit "bank" for the next PBA to outputs 1-8.
mjr 35:e959ffba78fd 288 //
mjr 35:e959ffba78fd 289 // Note that there's no special first byte to indicate the PBA message
mjr 35:e959ffba78fd 290 // type, as there is in an SBA. The first byte of a PBA is simply the
mjr 53:9b2611964afc 291 // first output setting. The way the LedWiz creators conceived this, an
mjr 53:9b2611964afc 292 // SBA message is distinguishable from a PBA because there's no such thing
mjr 53:9b2611964afc 293 // as a brightness level 64, hence 64 is never valid as a byte in an PBA
mjr 53:9b2611964afc 294 // message, hence a message starting with 64 must be something other than
mjr 53:9b2611964afc 295 // an PBA message.
mjr 35:e959ffba78fd 296 //
mjr 35:e959ffba78fd 297 // Our extended protocol uses the same principle, taking advantage of the
mjr 53:9b2611964afc 298 // many other byte values that are also invalid in PBA messages. To be a
mjr 53:9b2611964afc 299 // valid PBA message, the first byte must be in the range 0-49 or 129-132.
mjr 53:9b2611964afc 300 // As already mentioned, byte value 64 indicates an SBA message, so we
mjr 53:9b2611964afc 301 // can't use that one for private extensions. This still leaves many
mjr 53:9b2611964afc 302 // other byte values for us, though, namely 50-63, 65-128, and 133-255.
mjr 35:e959ffba78fd 303
mjr 35:e959ffba78fd 304
mjr 35:e959ffba78fd 305 // --- PRIVATE EXTENDED MESSAGES ---
mjr 35:e959ffba78fd 306 //
mjr 35:e959ffba78fd 307 // All of our extended protocol messages are identified by the first byte:
mjr 35:e959ffba78fd 308 //
mjr 35:e959ffba78fd 309 // 65 -> Miscellaneous control message. The second byte specifies the specific
mjr 35:e959ffba78fd 310 // operation:
mjr 35:e959ffba78fd 311 //
mjr 39:b3815a1c3802 312 // 0 -> No Op - does nothing. (This can be used to send a test message on the
mjr 39:b3815a1c3802 313 // USB endpoint.)
mjr 39:b3815a1c3802 314 //
mjr 35:e959ffba78fd 315 // 1 -> Set device unit number and plunger status, and save the changes immediately
mjr 35:e959ffba78fd 316 // to flash. The device will automatically reboot after the changes are saved.
mjr 35:e959ffba78fd 317 // The additional bytes of the message give the parameters:
mjr 35:e959ffba78fd 318 //
mjr 35:e959ffba78fd 319 // third byte = new unit number (0-15, corresponding to nominal unit numbers 1-16)
mjr 35:e959ffba78fd 320 // fourth byte = plunger on/off (0=disabled, 1=enabled)
mjr 35:e959ffba78fd 321 //
mjr 35:e959ffba78fd 322 // 2 -> Begin plunger calibration mode. The device stays in this mode for about
mjr 35:e959ffba78fd 323 // 15 seconds, and sets the zero point and maximum retraction points to the
mjr 35:e959ffba78fd 324 // observed endpoints of sensor readings while the mode is running. After
mjr 35:e959ffba78fd 325 // the time limit elapses, the device automatically stores the results in
mjr 35:e959ffba78fd 326 // non-volatile flash memory and exits the mode.
mjr 35:e959ffba78fd 327 //
mjr 51:57eb311faafa 328 // 3 -> Send pixel dump. The device sends one complete image snapshot from the
mjr 51:57eb311faafa 329 // plunger sensor, as as series of pixel dump messages. (The message format
mjr 51:57eb311faafa 330 // isn't big enough to allow the whole image to be sent in one message, so
mjr 53:9b2611964afc 331 // the image is broken up into as many messages as necessary.) The device
mjr 53:9b2611964afc 332 // then resumes sending normal joystick messages. If the plunger sensor
mjr 53:9b2611964afc 333 // isn't an imaging type, or no sensor is installed, no pixel messages are
mjr 53:9b2611964afc 334 // sent. Parameters:
mjr 48:058ace2aed1d 335 //
mjr 48:058ace2aed1d 336 // third byte = bit flags:
mjr 51:57eb311faafa 337 // 0x01 = low res mode. The device rescales the sensor pixel array
mjr 51:57eb311faafa 338 // sent in the dump messages to a low-resolution subset. The
mjr 51:57eb311faafa 339 // size of the subset is determined by the device. This has
mjr 51:57eb311faafa 340 // no effect on the sensor operation; it merely reduces the
mjr 51:57eb311faafa 341 // USB transmission time to allow for a faster frame rate for
mjr 51:57eb311faafa 342 // viewing in the config tool.
mjr 35:e959ffba78fd 343 //
mjr 53:9b2611964afc 344 // fourth byte = extra exposure time in 100us (.1ms) increments. For
mjr 53:9b2611964afc 345 // imaging sensors, we'll add this delay to the minimum exposure
mjr 53:9b2611964afc 346 // time. This allows the caller to explicitly adjust the exposure
mjr 53:9b2611964afc 347 // level for calibration purposes.
mjr 53:9b2611964afc 348 //
mjr 35:e959ffba78fd 349 // 4 -> Query configuration. The device sends a special configuration report,
mjr 40:cc0d9814522b 350 // (see above; see also USBJoystick.cpp), then resumes sending normal
mjr 40:cc0d9814522b 351 // joystick reports.
mjr 35:e959ffba78fd 352 //
mjr 35:e959ffba78fd 353 // 5 -> Turn all outputs off and restore LedWiz defaults. Sets output ports
mjr 35:e959ffba78fd 354 // 1-32 to OFF and LedWiz brightness/mode setting 48, sets outputs 33 and
mjr 35:e959ffba78fd 355 // higher to brightness level 0, and sets the LedWiz global flash speed to 2.
mjr 35:e959ffba78fd 356 //
mjr 35:e959ffba78fd 357 // 6 -> Save configuration to flash. This saves all variable updates sent via
mjr 35:e959ffba78fd 358 // type 66 messages since the last reboot, then automatically reboots the
mjr 35:e959ffba78fd 359 // device to put the changes into effect.
mjr 35:e959ffba78fd 360 //
mjr 53:9b2611964afc 361 // third byte = delay time in seconds. The device will wait this long
mjr 53:9b2611964afc 362 // before disconnecting, to allow the PC to perform any cleanup tasks
mjr 53:9b2611964afc 363 // while the device is still attached (e.g., modifying Windows device
mjr 53:9b2611964afc 364 // driver settings)
mjr 53:9b2611964afc 365 //
mjr 40:cc0d9814522b 366 // 7 -> Query device ID. The device replies with a special device ID report
mjr 40:cc0d9814522b 367 // (see above; see also USBJoystick.cpp), then resumes sending normal
mjr 40:cc0d9814522b 368 // joystick reports.
mjr 40:cc0d9814522b 369 //
mjr 53:9b2611964afc 370 // The third byte of the message is the ID index to retrieve:
mjr 53:9b2611964afc 371 //
mjr 53:9b2611964afc 372 // 1 = CPU ID: returns the KL25Z globally unique CPU ID.
mjr 53:9b2611964afc 373 //
mjr 53:9b2611964afc 374 // 2 = OpenSDA ID: returns the OpenSDA TUID. This must be patched
mjr 53:9b2611964afc 375 // into the firmware by the PC host when the .bin file is
mjr 53:9b2611964afc 376 // installed onto the device. This will return all 'X' bytes
mjr 53:9b2611964afc 377 // if the value wasn't patched at install time.
mjr 53:9b2611964afc 378 //
mjr 40:cc0d9814522b 379 // 8 -> Engage/disengage night mode. The third byte of the message is 1 to
mjr 40:cc0d9814522b 380 // engage night mode, 0 to disengage night mode. (This mode isn't stored
mjr 40:cc0d9814522b 381 // persistently; night mode is disengaged after a reset or power cycle.)
mjr 40:cc0d9814522b 382 //
mjr 52:8298b2a73eb2 383 // 9 -> Query configuration variable. The second byte is the config variable
mjr 52:8298b2a73eb2 384 // number (see the CONFIGURATION VARIABLES section below). For the array
mjr 52:8298b2a73eb2 385 // variables (button assignments, output ports), the third byte is the
mjr 52:8298b2a73eb2 386 // array index. The device replies with a configuration variable report
mjr 52:8298b2a73eb2 387 // (see above) with the current setting for the requested variable.
mjr 52:8298b2a73eb2 388 //
mjr 53:9b2611964afc 389 // 10 -> Query software build information. No parameters. This replies with
mjr 53:9b2611964afc 390 // the software build information report (see above).
mjr 53:9b2611964afc 391 //
mjr 35:e959ffba78fd 392 // 66 -> Set configuration variable. The second byte of the message is the config
mjr 35:e959ffba78fd 393 // variable number, and the remaining bytes give the new value for the variable.
mjr 53:9b2611964afc 394 // The value format is specific to each variable; see the CONFIGURATION VARIABLES
mjr 53:9b2611964afc 395 // section below for a list of the variables and their formats. This command
mjr 53:9b2611964afc 396 // only sets the value in RAM; it doesn't write the value to flash and doesn't
mjr 53:9b2611964afc 397 // put the change into effect. To save the new settings, the host must send a
mjr 53:9b2611964afc 398 // type 65 subtype 6 message (see above). That saves the settings to flash and
mjr 53:9b2611964afc 399 // reboots the device, which makes the new settings active.
mjr 35:e959ffba78fd 400 //
mjr 35:e959ffba78fd 401 // 200-228 -> Set extended output brightness. This sets outputs N to N+6 to the
mjr 35:e959ffba78fd 402 // respective brightness values in the 2nd through 8th bytes of the message
mjr 35:e959ffba78fd 403 // (output N is set to the 2nd byte value, N+1 is set to the 3rd byte value,
mjr 35:e959ffba78fd 404 // etc). Each brightness level is a linear brightness level from 0-255,
mjr 35:e959ffba78fd 405 // where 0 is 0% brightness and 255 is 100% brightness. N is calculated as
mjr 35:e959ffba78fd 406 // (first byte - 200)*7 + 1:
mjr 35:e959ffba78fd 407 //
mjr 35:e959ffba78fd 408 // 200 = outputs 1-7
mjr 35:e959ffba78fd 409 // 201 = outputs 8-14
mjr 35:e959ffba78fd 410 // 202 = outputs 15-21
mjr 35:e959ffba78fd 411 // ...
mjr 35:e959ffba78fd 412 // 228 = outputs 197-203
mjr 35:e959ffba78fd 413 //
mjr 53:9b2611964afc 414 // This message is the way to address ports 33 and higher. Original LedWiz
mjr 53:9b2611964afc 415 // protocol messages can't access ports above 32, since the protocol is
mjr 53:9b2611964afc 416 // hard-wired for exactly 32 ports.
mjr 35:e959ffba78fd 417 //
mjr 53:9b2611964afc 418 // Note that the extended output messages differ from regular LedWiz commands
mjr 35:e959ffba78fd 419 // in two ways. First, the brightness is the ONLY attribute when an output is
mjr 53:9b2611964afc 420 // set using this mode. There's no separate ON/OFF state per output as there
mjr 35:e959ffba78fd 421 // is with the SBA/PBA messages. To turn an output OFF with this message, set
mjr 35:e959ffba78fd 422 // the intensity to 0. Setting a non-zero intensity turns it on immediately
mjr 35:e959ffba78fd 423 // without regard to the SBA status for the port. Second, the brightness is
mjr 35:e959ffba78fd 424 // on a full 8-bit scale (0-255) rather than the LedWiz's approximately 5-bit
mjr 35:e959ffba78fd 425 // scale, because there are no parts of the range reserved for flashing modes.
mjr 35:e959ffba78fd 426 //
mjr 35:e959ffba78fd 427 // Outputs 1-32 can be controlled by EITHER the regular LedWiz SBA/PBA messages
mjr 35:e959ffba78fd 428 // or by the extended messages. The latest setting for a given port takes
mjr 35:e959ffba78fd 429 // precedence. If an SBA/PBA message was the last thing sent to a port, the
mjr 35:e959ffba78fd 430 // normal LedWiz combination of ON/OFF and brightness/flash mode status is used
mjr 35:e959ffba78fd 431 // to determine the port's physical output setting. If an extended brightness
mjr 35:e959ffba78fd 432 // message was the last thing sent to a port, the LedWiz ON/OFF status and
mjr 35:e959ffba78fd 433 // flash modes are ignored, and the fixed brightness is set. Outputs 33 and
mjr 35:e959ffba78fd 434 // higher inherently can't be addressed or affected by SBA/PBA messages.
mjr 53:9b2611964afc 435 //
mjr 53:9b2611964afc 436 // (The precedence scheme is designed to accommodate a mix of legacy and DOF
mjr 53:9b2611964afc 437 // software transparently. The behavior described is really just to ensure
mjr 53:9b2611964afc 438 // transparent interoperability; it's not something that host software writers
mjr 53:9b2611964afc 439 // should have to worry about. We expect that anyone writing new software will
mjr 53:9b2611964afc 440 // just use the extended protocol and ignore the old LedWiz commands, since
mjr 53:9b2611964afc 441 // the extended protocol is easier to use and more powerful.)
mjr 35:e959ffba78fd 442
mjr 35:e959ffba78fd 443
mjr 35:e959ffba78fd 444 // ------- CONFIGURATION VARIABLES -------
mjr 35:e959ffba78fd 445 //
mjr 35:e959ffba78fd 446 // Message type 66 (see above) sets one configuration variable. The second byte
mjr 35:e959ffba78fd 447 // of the message is the variable ID, and the rest of the bytes give the new
mjr 35:e959ffba78fd 448 // value, in a variable-specific format. 16-bit values are little endian.
mjr 35:e959ffba78fd 449 //
mjr 53:9b2611964afc 450 // 0 -> QUERY ONLY: Describe the configuration variables. The device
mjr 53:9b2611964afc 451 // sends a config variable query report with the following fields:
mjr 53:9b2611964afc 452 //
mjr 53:9b2611964afc 453 // byte 3 -> number of scalar (non-array) variables (these are
mjr 53:9b2611964afc 454 // numbered sequentially from 1 to N)
mjr 53:9b2611964afc 455 // byte 4 -> number of array variables (these are numbered
mjr 53:9b2611964afc 456 // sequentially from 256-N to 255)
mjr 53:9b2611964afc 457 //
mjr 53:9b2611964afc 458 // The description query is meant to allow the host to capture all
mjr 53:9b2611964afc 459 // configuration settings on the device without having to know what
mjr 53:9b2611964afc 460 // the variables mean or how many there are. This is useful for
mjr 53:9b2611964afc 461 // backing up the settings in a file on the PC, for example, or for
mjr 53:9b2611964afc 462 // capturing them to restore after a firmware update. This allows
mjr 53:9b2611964afc 463 // more flexible interoperability between unsynchronized versions
mjr 53:9b2611964afc 464 // of the firmware and the host software.
mjr 53:9b2611964afc 465 //
mjr 53:9b2611964afc 466 // 1 -> USB device ID. This sets the USB vendor and product ID codes
mjr 53:9b2611964afc 467 // to use when connecting to the PC. For LedWiz emulation, use
mjr 35:e959ffba78fd 468 // vendor 0xFAFA and product 0x00EF + unit# (where unit# is the
mjr 53:9b2611964afc 469 // nominal LedWiz unit number, from 1 to 16). If you have any
mjr 53:9b2611964afc 470 // REAL LedWiz units in your system, we recommend starting the
mjr 53:9b2611964afc 471 // Pinscape LedWiz numbering at 8 to avoid conflicts with the
mjr 53:9b2611964afc 472 // real LedWiz units. If you don't have any real LedWiz units,
mjr 53:9b2611964afc 473 // you can number your Pinscape units starting from 1.
mjr 35:e959ffba78fd 474 //
mjr 53:9b2611964afc 475 // If LedWiz emulation isn't desired or causes host conflicts,
mjr 53:9b2611964afc 476 // use our private ID: Vendor 0x1209, product 0xEAEA. (These IDs
mjr 53:9b2611964afc 477 // are registered with http://pid.codes, a registry for open-source
mjr 53:9b2611964afc 478 // USB devices, so they're guaranteed to be free of conflicts with
mjr 53:9b2611964afc 479 // other properly registered devices). The device will NOT appear
mjr 53:9b2611964afc 480 // as an LedWiz if you use the private ID codes, but DOF (R3 or
mjr 53:9b2611964afc 481 // later) will still recognize it as a Pinscape controller.
mjr 53:9b2611964afc 482 //
mjr 53:9b2611964afc 483 // bytes 3:4 -> USB Vendor ID
mjr 53:9b2611964afc 484 // bytes 5:6 -> USB Product ID
mjr 53:9b2611964afc 485 //
mjr 53:9b2611964afc 486 // 2 -> Pinscape Controller unit number for DOF. The Pinscape unit
mjr 53:9b2611964afc 487 // number is independent of the LedWiz unit number, and indepedent
mjr 53:9b2611964afc 488 // of the USB vendor/product IDs. DOF (R3 and later) uses this to
mjr 53:9b2611964afc 489 // identify the unit for the extended Pinscape functionality.
mjr 53:9b2611964afc 490 // For easiest DOF configuration, we recommend numbering your
mjr 53:9b2611964afc 491 // units sequentially starting at 1 (regardless of whether or not
mjr 53:9b2611964afc 492 // you have any real LedWiz units).
mjr 53:9b2611964afc 493 //
mjr 53:9b2611964afc 494 // byte 3 -> unit number, from 1 to 16
mjr 35:e959ffba78fd 495 //
mjr 35:e959ffba78fd 496 // 3 -> Enable/disable joystick reports. Byte 2 is 1 to enable, 0 to
mjr 35:e959ffba78fd 497 // disable. When disabled, the device registers as a generic HID
mjr 35:e959ffba78fd 498 / device, and only sends the private report types used by the
mjr 35:e959ffba78fd 499 // Windows config tool.
mjr 35:e959ffba78fd 500 //
mjr 35:e959ffba78fd 501 // 4 -> Accelerometer orientation. Byte 3 is the new setting:
mjr 35:e959ffba78fd 502 //
mjr 35:e959ffba78fd 503 // 0 = ports at front (USB ports pointing towards front of cabinet)
mjr 35:e959ffba78fd 504 // 1 = ports at left
mjr 35:e959ffba78fd 505 // 2 = ports at right
mjr 35:e959ffba78fd 506 // 3 = ports at rear
mjr 35:e959ffba78fd 507 //
mjr 35:e959ffba78fd 508 // 5 -> Plunger sensor type. Byte 3 is the type ID:
mjr 35:e959ffba78fd 509 //
mjr 35:e959ffba78fd 510 // 0 = none (disabled)
mjr 35:e959ffba78fd 511 // 1 = TSL1410R linear image sensor, 1280x1 pixels, serial mode
mjr 47:df7a88cd249c 512 // *2 = TSL1410R, parallel mode
mjr 35:e959ffba78fd 513 // 3 = TSL1412R linear image sensor, 1536x1 pixels, serial mode
mjr 47:df7a88cd249c 514 // *4 = TSL1412R, parallel mode
mjr 35:e959ffba78fd 515 // 5 = Potentiometer with linear taper, or any other device that
mjr 35:e959ffba78fd 516 // represents the position reading with a single analog voltage
mjr 47:df7a88cd249c 517 // *6 = AEDR8300 optical quadrature sensor, 75lpi
mjr 47:df7a88cd249c 518 // *7 = AS5304 magnetic quadrature sensor, 160 steps per 2mm
mjr 47:df7a88cd249c 519 //
mjr 47:df7a88cd249c 520 // * The sensor types marked with asterisks (*) are planned but not
mjr 47:df7a88cd249c 521 // currently implemented. Selecting these types will effectively
mjr 47:df7a88cd249c 522 // disable the plunger.
mjr 35:e959ffba78fd 523 //
mjr 35:e959ffba78fd 524 // 6 -> Plunger pin assignments. Bytes 3-6 give the pin assignments for
mjr 35:e959ffba78fd 525 // pins 1, 2, 3, and 4. These use the Pin Number Mappings listed
mjr 35:e959ffba78fd 526 // below. The meaning of each pin depends on the plunger type:
mjr 35:e959ffba78fd 527 //
mjr 35:e959ffba78fd 528 // TSL1410R/1412R, serial: SI (DigitalOut), CLK (DigitalOut), AO (AnalogIn), NC
mjr 35:e959ffba78fd 529 // TSL1410R/1412R, parallel: SI (DigitalOut), CLK (DigitalOut), AO1 (AnalogIn), AO2 (AnalogIn)
mjr 35:e959ffba78fd 530 // Potentiometer: AO (AnalogIn), NC, NC, NC
mjr 35:e959ffba78fd 531 // AEDR8300: A (InterruptIn), B (InterruptIn), NC, NC
mjr 35:e959ffba78fd 532 // AS5304: A (InterruptIn), B (InterruptIn), NC, NC
mjr 35:e959ffba78fd 533 //
mjr 35:e959ffba78fd 534 // 7 -> Plunger calibration button pin assignments. Byte 3 is the DigitalIn
mjr 35:e959ffba78fd 535 // pin for the button switch; byte 4 is the DigitalOut pin for the indicator
mjr 35:e959ffba78fd 536 // lamp. Either can be set to NC to disable the function. (Use the Pin
mjr 35:e959ffba78fd 537 // Number Mappins listed below for both bytes.)
mjr 35:e959ffba78fd 538 //
mjr 35:e959ffba78fd 539 // 8 -> ZB Launch Ball setup. This configures the ZB Launch Ball feature. Byte
mjr 35:e959ffba78fd 540 // 3 is the LedWiz port number (1-255) mapped to the "ZB Launch Ball" output
mjr 53:9b2611964afc 541 // in DOF. Set the port to 0 to disable the feature. Byte 4 is the key type
mjr 53:9b2611964afc 542 // and byte 5 is the key code for the key to send to the PC when a launch is
mjr 53:9b2611964afc 543 // triggered. These have the same meanings as for a regular key mapping. For
mjr 53:9b2611964afc 544 // example, set type=2 and code=0x28 for the keyboard Enter key. Bytes 6-7
mjr 35:e959ffba78fd 545 // give the "push distance" for activating the button by pushing forward on
mjr 53:9b2611964afc 546 // the plunger knob, in 1/1000 inch increments (e.g., 63 represents 0.063",
mjr 53:9b2611964afc 547 // or about 1/16", which is the recommended setting).
mjr 35:e959ffba78fd 548 //
mjr 35:e959ffba78fd 549 // 9 -> TV ON relay setup. This requires external circuitry implemented on the
mjr 35:e959ffba78fd 550 // Expansion Board (or an equivalent circuit as described in the Build Guide).
mjr 35:e959ffba78fd 551 // Byte 3 is the GPIO DigitalIn pin for the "power status" input, using the
mjr 35:e959ffba78fd 552 // Pin Number Mappings below. Byte 4 is the DigitalOut pin for the "latch"
mjr 35:e959ffba78fd 553 // output. Byte 5 is the DigitalOut pin for the relay trigger. Bytes 6-7
mjr 35:e959ffba78fd 554 // give the delay time in 10ms increments as an unsigned 16-bit value (e.g.,
mjr 35:e959ffba78fd 555 // 550 represents 5.5 seconds).
mjr 35:e959ffba78fd 556 //
mjr 35:e959ffba78fd 557 // 10 -> TLC5940NT setup. This chip is an external PWM controller, with 32 outputs
mjr 35:e959ffba78fd 558 // per chip and a serial data interface that allows the chips to be daisy-
mjr 35:e959ffba78fd 559 // chained. We can use these chips to add an arbitrary number of PWM output
mjr 35:e959ffba78fd 560 // ports for the LedWiz emulation. Set the number of chips to 0 to disable
mjr 35:e959ffba78fd 561 // the feature. The bytes of the message are:
mjr 35:e959ffba78fd 562 // byte 3 = number of chips attached (connected in daisy chain)
mjr 35:e959ffba78fd 563 // byte 4 = SIN pin - Serial data (must connect to SPIO MOSI -> PTC6 or PTD2)
mjr 35:e959ffba78fd 564 // byte 5 = SCLK pin - Serial clock (must connect to SPIO SCLK -> PTC5 or PTD1)
mjr 35:e959ffba78fd 565 // byte 6 = XLAT pin - XLAT (latch) signal (any GPIO pin)
mjr 35:e959ffba78fd 566 // byte 7 = BLANK pin - BLANK signal (any GPIO pin)
mjr 35:e959ffba78fd 567 // byte 8 = GSCLK pin - Grayscale clock signal (must be a PWM-out capable pin)
mjr 35:e959ffba78fd 568 //
mjr 35:e959ffba78fd 569 // 11 -> 74HC595 setup. This chip is an external shift register, with 8 outputs per
mjr 35:e959ffba78fd 570 // chip and a serial data interface that allows daisy-chaining. We use this
mjr 35:e959ffba78fd 571 // chips to add extra digital outputs for the LedWiz emulation. In particular,
mjr 35:e959ffba78fd 572 // the Chime Board (part of the Expansion Board suite) uses these to add timer-
mjr 35:e959ffba78fd 573 // protected outputs for coil devices (knockers, chimes, bells, etc). Set the
mjr 35:e959ffba78fd 574 // number of chips to 0 to disable the feature. The message bytes are:
mjr 35:e959ffba78fd 575 // byte 3 = number of chips attached (connected in daisy chain)
mjr 35:e959ffba78fd 576 // byte 4 = SIN pin - Serial data (any GPIO pin)
mjr 35:e959ffba78fd 577 // byte 5 = SCLK pin - Serial clock (any GPIO pin)
mjr 35:e959ffba78fd 578 // byte 6 = LATCH pin - LATCH signal (any GPIO pin)
mjr 35:e959ffba78fd 579 // byte 7 = ENA pin - ENABLE signal (any GPIO pin)
mjr 35:e959ffba78fd 580 //
mjr 53:9b2611964afc 581 // 12 -> Disconnect reboot timeout. The reboot timeout allows the controller software
mjr 51:57eb311faafa 582 // to automatically reboot the KL25Z after it detects that the USB connection is
mjr 51:57eb311faafa 583 // broken. On some hosts, the device isn't able to reconnect after the initial
mjr 51:57eb311faafa 584 // connection is lost. The reboot timeout is a workaround for these cases. When
mjr 51:57eb311faafa 585 // the software detects that the connection is no longer active, it will reboot
mjr 51:57eb311faafa 586 // the KL25Z automatically if a new connection isn't established within the
mjr 51:57eb311faafa 587 // timeout period. Bytes 3 give the new reboot timeout in seconds. Setting this
mjr 51:57eb311faafa 588 // to 0 disables the reboot timeout.
mjr 51:57eb311faafa 589 //
mjr 53:9b2611964afc 590 // 13 -> Plunger calibration. In most cases, the calibration is set internally by the
mjr 52:8298b2a73eb2 591 // device by running the calibration procedure. However, it's sometimes useful
mjr 52:8298b2a73eb2 592 // for the host to be able to get and set the calibration, such as to back up
mjr 52:8298b2a73eb2 593 // the device settings on the PC, or to save and restore the current settings
mjr 52:8298b2a73eb2 594 // when installing a software update.
mjr 52:8298b2a73eb2 595 //
mjr 52:8298b2a73eb2 596 // bytes 3:4 = rest position (unsigned 16-bit little-endian)
mjr 52:8298b2a73eb2 597 // bytes 5:6 = maximum retraction point (unsigned 16-bit little-endian)
mjr 52:8298b2a73eb2 598 // byte 7 = measured plunger release travel time in milliseconds
mjr 52:8298b2a73eb2 599 //
mjr 53:9b2611964afc 600 // 14 -> Expansion board configuration. This doesn't affect the controller behavior
mjr 52:8298b2a73eb2 601 // directly; the individual options related to the expansion boards (such as
mjr 52:8298b2a73eb2 602 // the TLC5940 and 74HC595 setup) still need to be set separately. This is
mjr 52:8298b2a73eb2 603 // stored so that the PC config UI can store and recover the information to
mjr 52:8298b2a73eb2 604 // present in the UI. For the "classic" KL25Z-only configuration, simply set
mjr 52:8298b2a73eb2 605 // all of the fields to zero.
mjr 52:8298b2a73eb2 606 //
mjr 53:9b2611964afc 607 // byte 3 = board set type. At the moment, the Pinscape expansion boards
mjr 53:9b2611964afc 608 // are the only ones supported in the software. This allows for
mjr 53:9b2611964afc 609 // adding new designs or independent designs in the future.
mjr 53:9b2611964afc 610 // 0 = Standalone KL25Z (no expansion boards)
mjr 53:9b2611964afc 611 // 1 = Pinscape expansion boards
mjr 53:9b2611964afc 612 //
mjr 53:9b2611964afc 613 // byte 4 = board set interface revision. This *isn't* the version number
mjr 53:9b2611964afc 614 // of the board itself, but rather of its software interface. In
mjr 53:9b2611964afc 615 // other words, this doesn't change every time the EAGLE layout
mjr 53:9b2611964afc 616 // for the board changes. It only changes when a revision is made
mjr 53:9b2611964afc 617 // that affects the software, such as a GPIO pin assignment.
mjr 53:9b2611964afc 618 //
mjr 53:9b2611964afc 619 // The remaining bytes depend on the board set type. Currently, only
mjr 53:9b2611964afc 620 // the Pinscape expansion boards are supported; for those, the bytes are
mjr 53:9b2611964afc 621 // used to store these values:
mjr 53:9b2611964afc 622 //
mjr 53:9b2611964afc 623 // byte 5 = number of main interface boards
mjr 53:9b2611964afc 624 // byte 6 = number of MOSFET power boards
mjr 53:9b2611964afc 625 // byte 7 = number of chime boards
mjr 53:9b2611964afc 626 //
mjr 53:9b2611964afc 627 // 15 -> Night mode setup.
mjr 53:9b2611964afc 628 //
mjr 53:9b2611964afc 629 // byte 3 = button number - 1..MAX_BUTTONS, or 0 for none. This selects
mjr 53:9b2611964afc 630 // a physically wired button that can be used to control night mode.
mjr 53:9b2611964afc 631 // The button can also be used as normal for PC input if desired.
mjr 53:9b2611964afc 632 // byte 4 = flags:
mjr 53:9b2611964afc 633 // 0x01 -> the wired input is an on/off switch; night mode will be
mjr 53:9b2611964afc 634 // active when the input is switched on. If this bit isn't
mjr 53:9b2611964afc 635 // set, the input is a momentary button; pushing the button
mjr 53:9b2611964afc 636 // toggles night mode.
mjr 53:9b2611964afc 637 // byte 5 = indicator output number - 1..MAX_OUT_PORTS, or 0 for none. This
mjr 53:9b2611964afc 638 // selects an output port that will be turned on when night mode is
mjr 53:9b2611964afc 639 // activated. Night mode activation overrides any setting made by
mjr 53:9b2611964afc 640 // the host.
mjr 53:9b2611964afc 641 //
mjr 53:9b2611964afc 642 //
mjr 53:9b2611964afc 643 // ARRAY VARIABLES: Each variable below is an array. For each get/set message,
mjr 53:9b2611964afc 644 // byte 3 gives the array index. These are grouped at the top end of the variable
mjr 53:9b2611964afc 645 // ID range to distinguish this special feature. On QUERY, set the index byte to 0
mjr 53:9b2611964afc 646 // to query the number of slots; the reply will be a report for the array index
mjr 53:9b2611964afc 647 // variable with index 0, with the first (and only) byte after that indicating
mjr 53:9b2611964afc 648 // the maximum array index.
mjr 53:9b2611964afc 649 //
mjr 53:9b2611964afc 650 // 254 -> Input button setup. This sets up one button; it can be repeated for each
mjr 53:9b2611964afc 651 // button to be configured. There are 32 button slots, numbered 1-32. Each
mjr 53:9b2611964afc 652 // slot can be configured as a joystick button, a regular keyboard key, or a
mjr 53:9b2611964afc 653 // media control key (mute, volume up, volume down).
mjr 53:9b2611964afc 654 //
mjr 53:9b2611964afc 655 // The bytes of the message are:
mjr 53:9b2611964afc 656 // byte 3 = Button number (1-32)
mjr 53:9b2611964afc 657 // byte 4 = GPIO pin to read for button input
mjr 53:9b2611964afc 658 // byte 5 = key type reported to PC when button is pushed:
mjr 53:9b2611964afc 659 // 0 = none (no PC input reported when button pushed)
mjr 53:9b2611964afc 660 // 1 = joystick button -> byte 6 is the button number, 1-32
mjr 53:9b2611964afc 661 // 2 = regular keyboard key -> byte 6 is the USB key code (see below)
mjr 53:9b2611964afc 662 // byte 6 = key code, which depends on the key type in byte 5
mjr 53:9b2611964afc 663 // byte 7 = flags - a combination of these bit values:
mjr 53:9b2611964afc 664 // 0x01 = pulse mode. This reports a physical on/off switch's state
mjr 53:9b2611964afc 665 // to the host as a brief key press whenever the switch changes
mjr 53:9b2611964afc 666 // state. This is useful for the VPinMAME Coin Door button,
mjr 53:9b2611964afc 667 // which requires the End key to be pressed each time the
mjr 53:9b2611964afc 668 // door changes state.
mjr 53:9b2611964afc 669 //
mjr 53:9b2611964afc 670 // 255 -> LedWiz output port setup. This sets up one output port; it can be repeated
mjr 53:9b2611964afc 671 // for each port to be configured. There are 128 possible slots for output ports,
mjr 53:9b2611964afc 672 // numbered 1 to 128. The number of ports atcually active is determined by
mjr 53:9b2611964afc 673 // the first DISABLED port (type 0). For example, if ports 1-32 are set as GPIO
mjr 53:9b2611964afc 674 // outputs and port 33 is disabled, we'll report to the host that we have 32 ports,
mjr 53:9b2611964afc 675 // regardless of the settings for post 34 and higher.
mjr 53:9b2611964afc 676 //
mjr 53:9b2611964afc 677 // The bytes of the message are:
mjr 53:9b2611964afc 678 // byte 3 = LedWiz port number (1 to MAX_OUT_PORTS)
mjr 53:9b2611964afc 679 // byte 4 = physical output type:
mjr 53:9b2611964afc 680 // 0 = Disabled. This output isn't used, and isn't visible to the
mjr 53:9b2611964afc 681 // LedWiz/DOF software on the host. The FIRST disabled port
mjr 53:9b2611964afc 682 // determines the number of ports visible to the host - ALL ports
mjr 53:9b2611964afc 683 // after the first disabled port are also implicitly disabled.
mjr 53:9b2611964afc 684 // 1 = GPIO PWM output: connected to GPIO pin specified in byte 5,
mjr 53:9b2611964afc 685 // operating in PWM mode. Note that only a subset of KL25Z GPIO
mjr 53:9b2611964afc 686 // ports are PWM-capable.
mjr 53:9b2611964afc 687 // 2 = GPIO Digital output: connected to GPIO pin specified in byte 5,
mjr 53:9b2611964afc 688 // operating in digital mode. Digital ports can only be set ON
mjr 53:9b2611964afc 689 // or OFF, with no brightness/intensity control. All pins can be
mjr 53:9b2611964afc 690 // used in this mode.
mjr 53:9b2611964afc 691 // 3 = TLC5940 port: connected to TLC5940 output port number specified
mjr 53:9b2611964afc 692 // in byte 5. Ports are numbered sequentially starting from port 0
mjr 53:9b2611964afc 693 // for the first output (OUT0) on the first chip in the daisy chain.
mjr 53:9b2611964afc 694 // 4 = 74HC595 port: connected to 74HC595 output port specified in byte 5.
mjr 53:9b2611964afc 695 // As with the TLC5940 outputs, ports are numbered sequentially from 0
mjr 53:9b2611964afc 696 // for the first output on the first chip in the daisy chain.
mjr 53:9b2611964afc 697 // 5 = Virtual output: this output port exists for the purposes of the
mjr 53:9b2611964afc 698 // LedWiz/DOF software on the host, but isn't physically connected
mjr 53:9b2611964afc 699 // to any output device. This can be used to create a virtual output
mjr 53:9b2611964afc 700 // for the DOF ZB Launch Ball signal, for example, or simply as a
mjr 53:9b2611964afc 701 // placeholder in the LedWiz port numbering. The physical output ID
mjr 53:9b2611964afc 702 // (byte 5) is ignored for this port type.
mjr 53:9b2611964afc 703 // byte 5 = physical output port, interpreted according to the value in byte 4
mjr 53:9b2611964afc 704 // byte 6 = flags: a combination of these bit values:
mjr 53:9b2611964afc 705 // 0x01 = active-high output (0V on output turns attached device ON)
mjr 53:9b2611964afc 706 // 0x02 = noisemaker device: disable this output when "night mode" is engaged
mjr 53:9b2611964afc 707 // 0x04 = apply gamma correction to this output
mjr 53:9b2611964afc 708 //
mjr 53:9b2611964afc 709 // Note that the on-board LED segments can be used as LedWiz output ports. This
mjr 53:9b2611964afc 710 // is useful for testing a new installation with DOF or other PC software without
mjr 53:9b2611964afc 711 // having to connect any external devices. Assigning the on-board LED segments to
mjr 53:9b2611964afc 712 // output ports overrides their normal status/diagnostic display use, so the normal
mjr 53:9b2611964afc 713 // status flash pattern won't appear when they're used this way.
mjr 52:8298b2a73eb2 714 //
mjr 35:e959ffba78fd 715
mjr 35:e959ffba78fd 716
mjr 35:e959ffba78fd 717 // --- PIN NUMBER MAPPINGS ---
mjr 35:e959ffba78fd 718 //
mjr 53:9b2611964afc 719 // In USB messages that specify GPIO pin assignments, pins are identified by
mjr 53:9b2611964afc 720 // 8-bit integers. The special value 0xFF means NC (not connected). All actual
mjr 53:9b2611964afc 721 // pins are mapped with the port number in the top 3 bits and the pin number in
mjr 53:9b2611964afc 722 // the bottom 5 bits. Port A=0, B=1, ..., E=4. For example, PTC7 is port C (2)
mjr 53:9b2611964afc 723 // pin 7, so it's represented as (2 << 5) | 7.
mjr 53:9b2611964afc 724
mjr 35:e959ffba78fd 725
mjr 35:e959ffba78fd 726 // --- USB KEYBOARD SCAN CODES ---
mjr 35:e959ffba78fd 727 //
mjr 53:9b2611964afc 728 // For regular keyboard keys, we use the standard USB HID scan codes
mjr 53:9b2611964afc 729 // for the US keyboard layout. The scan codes are defined by the USB
mjr 53:9b2611964afc 730 // HID specifications; you can find a full list in the official USB
mjr 53:9b2611964afc 731 // specs. Some common codes are listed below as a quick reference.
mjr 35:e959ffba78fd 732 //
mjr 53:9b2611964afc 733 // Key name -> USB scan code (hex)
mjr 53:9b2611964afc 734 // A-Z -> 04-1D
mjr 53:9b2611964afc 735 // top row 1!->0) -> 1E-27
mjr 53:9b2611964afc 736 // Return -> 28
mjr 53:9b2611964afc 737 // Escape -> 29
mjr 53:9b2611964afc 738 // Backspace -> 2A
mjr 53:9b2611964afc 739 // Tab -> 2B
mjr 53:9b2611964afc 740 // Spacebar -> 2C
mjr 53:9b2611964afc 741 // -_ -> 2D
mjr 53:9b2611964afc 742 // =+ -> 2E
mjr 53:9b2611964afc 743 // [{ -> 2F
mjr 53:9b2611964afc 744 // ]} -> 30
mjr 53:9b2611964afc 745 // \| -> 31
mjr 53:9b2611964afc 746 // ;: -> 33
mjr 53:9b2611964afc 747 // '" -> 34
mjr 53:9b2611964afc 748 // `~ -> 35
mjr 53:9b2611964afc 749 // ,< -> 36
mjr 53:9b2611964afc 750 // .> -> 37
mjr 53:9b2611964afc 751 // /? -> 38
mjr 53:9b2611964afc 752 // Caps Lock -> 39
mjr 53:9b2611964afc 753 // F1-F12 -> 3A-45
mjr 53:9b2611964afc 754 // F13-F24 -> 68-73
mjr 53:9b2611964afc 755 // Print Screen -> 46
mjr 53:9b2611964afc 756 // Scroll Lock -> 47
mjr 53:9b2611964afc 757 // Pause -> 48
mjr 53:9b2611964afc 758 // Insert -> 49
mjr 53:9b2611964afc 759 // Home -> 4A
mjr 53:9b2611964afc 760 // Page Up -> 4B
mjr 53:9b2611964afc 761 // Del -> 4C
mjr 53:9b2611964afc 762 // End -> 4D
mjr 53:9b2611964afc 763 // Page Down -> 4E
mjr 53:9b2611964afc 764 // Right Arrow -> 4F
mjr 53:9b2611964afc 765 // Left Arrow -> 50
mjr 53:9b2611964afc 766 // Down Arrow -> 51
mjr 53:9b2611964afc 767 // Up Arrow -> 52
mjr 53:9b2611964afc 768 // Num Lock/Clear -> 53
mjr 53:9b2611964afc 769 // Keypad / * - + -> 54 55 56 57
mjr 53:9b2611964afc 770 // Keypad Enter -> 58
mjr 53:9b2611964afc 771 // Keypad 1-9 -> 59-61
mjr 53:9b2611964afc 772 // Keypad 0 -> 62
mjr 53:9b2611964afc 773 // Keypad . -> 63
mjr 53:9b2611964afc 774 // Mute -> 7F
mjr 53:9b2611964afc 775 // Volume Up -> 80
mjr 53:9b2611964afc 776 // Volume Down -> 81
mjr 53:9b2611964afc 777 // Left Control -> E0
mjr 53:9b2611964afc 778 // Left Shift -> E1
mjr 53:9b2611964afc 779 // Left Alt -> E2
mjr 53:9b2611964afc 780 // Left GUI -> E3
mjr 53:9b2611964afc 781 // Right Control -> E4
mjr 53:9b2611964afc 782 // Right Shift -> E5
mjr 53:9b2611964afc 783 // Right Alt -> E6
mjr 53:9b2611964afc 784 // Right GUI -> E7
mjr 53:9b2611964afc 785 //
mjr 53:9b2611964afc 786 // Note that the Mute and Volume Up & Down keys are sent to the host as
mjr 53:9b2611964afc 787 // media control keys rather than regular keyboard keys.
mjr 35:e959ffba78fd 788