The converter outputs some cryptic diagnostic information when in use - it's especially useful to see what is happening when it starts up.
The hid_listen program (from PJRC) can display this output, which mostly just consists of bytes read from and written to the keyboard when things are working correctly.
Most of the output takes the form of a prefix code, followed by a hex value, followed by a space. For example, 'r4A '.
Prefixes used:
| Prefix | Description |
|---|---|
| r | byte read from keyboard |
| w | byte written to keyboard |
| R | read error |
| W | write error |
| + | HID code output from first translation stage (for key-press) |
| - | HID code output from first translation stage (for key-release) |
| d | HID code output (for key-press) v1.03+ |
| u | HID code output (for key-release) v1.03+ |
Error codes:
| Code | Error | Description |
|---|---|---|
| R03 | unknown | something bad happened! |
| R04 | clock | missed one edge of the clock signal, usually because of a short spike |
| R05 | timeout | started receiving clock from the board, but didn't receive enough for a full code |
| R06 | start bit | read a start bit, but it was incorrect |
| R07 | parity bit | failed to correctly read a parity bit |
| R08 | stop bit | failed to correctly read a stop bit |
| W005 | timeout | timeout while writing a command to the keyboard |
| W105 | timeout | timeout while writing the first byte of a 2-byte command |
| W205 | timeout | timeout while writing the second byte of a 2-byte command |
Usually, if you get error codes right after building your converter, it's because the wiring is incorrect. One fairly common error is to read the socket pinout diagrams backwards - they are drawn looking at the front of the socket, not the back.
As a side-project, I've posted a Simple Logic Analyzer on Deskthority. This can help to diagnose wiring problems or incompatibilities quickly and simply, whereas before you might've had to resort to trial and error, risking damage to the Teensy in the process.
This section is mostly only relevant to terminal keyboards. The converter uses the ID to decide between using scan code set 3 for terminal keyboards, or extended scan code set 2 for 'regular' keyboards.
By using hid_listen, you can see what ID your keyboard has by looking at the two bytes read back after the get ID command (wF2 rFA).
The ID and scan code set selected are also printed in a more readable way: v0.996+
Keyboard ID: BFBF
Code Set: 3Terminal keyboards often have DIP switches on the back panel, or alternatively a pin header on the PCB that you can fit jumpers to, which configure the keyboard's ID code. The ID is a 16-bit number, but commonly fewer than 16 switches/jumpers are fitted meaning it's not possible to select all of the bits. The default value with no jumpers fitted, or with all the DIP switches in the 'open' position, is BFBF.
If your terminal keyboard is not operating correctly, it might be because the wrong ID is set on the switches/jumpers. The first byte should not be AB.