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