vt1200/reference/keyboard-mouse/SOURCES.md

# Keyboard / mouse protocol — sources

Retrieval date for everything below: **2026-10-16** (all fetched by this session).
Originals are preserved in this directory; text/OCR extractions are kept alongside
where they were produced. Nothing here is VT1200-specific — see the note at the end.

## Primary DEC documents

| Source | Local file | What it covers |
|---|---|---|
| VCB02 Video Subsystem Technical Manual, **EK-104AA-TM-001**, DEC Educational Services, Feb 1987 (per `vt100.net`). Appendix B = LK201 Keyboard Spec, Appendix C = Mouse Spec, Appendix D = Digitizing Tablet. | `vcb02-technical-manual-ek-104aa-tm-001.pdf` (scanned, 26 MB, **no text layer**) + `vcb02-ek-104aa-tm-001-archive-djvu.txt` (archive.org OCR of the same item, useful but noisy) | The authoritative DEC spec for the LK201 keyboard protocol, the VSXXX-AA/-GA mouse, and the VSXXX-AB tablet. URL: <https://vt100.net/dec/ek-104aa-tm-001.pdf> (mirror of archive.org item `104aatm1`). |
| VCB02 Video Subsystem Technical Manual, **AZ-GLGAB-MN**, DEC Educational Services, Feb 1986 (the edition Dan McMahill credits with "cleaning out the remaining mysteries"). | `vcb02-az-glgab-mn-feb86-text.pdf` + `vcb02-az-glgab-mn-feb86-text.txt` (pdftotext -layout) | Same appendices, cleaner OCR. Appendix B (LK201) and Appendix C (Mouse) tables are readable here — this is the copy the facts in `PROTOCOL.md` are quoted from. URL: <https://archive.org/download/bitsavers_decqbusvcbhnicalManualFeb86_19080378/AZ-GLGAB-MN_VCB02_Technical_Manual_Feb86_text.pdf> |
| **LK401 Keyboard Product Specification**, DEC PS 3032041-0-0, 17 Jan 1990 (rev CX01). | `vt100net-lk401.pdf` + `vt100net-lk401.txt` | The keyboard the VT1200 actually ships. States LK401 is "electrically and firmware functionally compatible" with the LK201, frame format (start + 8 data + stop), 4800 baud, self-test 4-byte result, key matrix/divisions. URL: <https://vt100.net/mirror/antonio/lk401.pdf> |
| LK201 schematic, **MP01395**, Oct 1983. | `bitsavers-MP01395_LK201_Schematic_Oct83.pdf` (scanned, no text layer) | Hardware reference for the keyboard matrix / serial driver. URL: <http://bitsavers.trailing-edge.com/pdf/dec/terminal/lk201/MP01395_LK201_Schematic_Oct83.pdf> |
| LK201-AA 8051 firmware, part **23-004M2-00**. | `bitsavers-23-004M2-00_LK201AA_Firmware.zip` (`23-004M2-00.BIN`, `.hex`) | Firmware image for the **older 8051** LK201. Note: MAME's `lk201` device emulates the **6805** LK201 and wants `23-001s9-00.bin`, which is **not** in this zip. URL: <http://bitsavers.trailing-edge.com/pdf/dec/terminal/lk201/23-004M2-00_LK201AA_Firmware.zip> |
| VT330/VT340 Programmer Reference Manual, Chapter 15 "Using a Mouse or Tablet". | `vt100net-vt3xx-gp-chapter15.html` | Corroborates the VSXXX-AA mouse and VSXXX-AB tablet as DEC terminal locator devices on a dedicated "locator port" with the micro-DIN connector. URL: <https://vt100.net/docs/vt3xx-gp/chapter15.html> |

## Reverse-engineered / driver sources (usable as documentation)

| Source | Local file | What it covers |
|---|---|---|
| Dan McMahill, "LK201 Keyboard Interface" (NetBSD docs). | `netbsd-lk201-interface.html` | The single best public write-up of the LK201 protocol: 4800 8N1, connector pinout, all host→keyboard commands, the 4-byte power-up self-test result and error codes, key modes/divisions, autorepeat. URL: <https://www.netbsd.org/docs/Hardware/Machines/DEC/lk201.html> |
| NetBSD, LK201 keycode/division table. | `netbsd-lk201-keycodes.html` | Complete keycode→key map, grouped by the 14 divisions. URL: <https://www.netbsd.org/docs/Hardware/Machines/DEC/lk201_keycodes.html> |
| Paul Flo Williams, vt100.net "LK201 Keyboard". | `vt100net-lk201-keyboard.html` | A **real captured VT320↔LK201 POST exchange** (hex), including the `FD` self-test request and the `01 00 00 00` reply, and the stuck-key variant `01 00 3D AE`. URL: <https://vt100.net/keyboard.html> |
| Linux `drivers/input/keyboard/lkkbd.c`. | `linux-lkkbd.c` | Working LK201/LK401 driver. Command bytes (`FD AB D3 E9`, modes, LEDs, bell/keyclick), error codes `3D`/`3E`, and the `AB` ID reply distinguishing LK201 (byte=1) from LK401 (byte=2). URL: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/drivers/input/keyboard/lkkbd.c> |
| Linux `drivers/input/mouse/vsxxxaa.c`. | `linux-vsxxxaa.c` | Working VSXXX-AA/-GA/AB driver: `4800 8o1`, `'T'` self-test trigger, POR/REL/ABS packet layouts, error-code semantics. URL: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/drivers/input/mouse/vsxxxaa.c> |
| `elkay` (issinoho), a modern LK401→USB adapter. | `elkay/` (git clone, shallow) | `docs/protocol.md` and `firmware/include/lk.h` — a clean, implementation-grade restatement of the LK201/LK401 protocol including the `E9` LK401-mode command. URL: <https://github.com/issinoho/elkay> |
| `lk201emu` (pkoning2), LK201 emulator firmware. | `lk201emu/` (git clone, shallow) | Arduino firmware that *impersonates* an LK201: shows exactly what to reply to `FD` (`01 00 00 00`) and `AB`. URL: <https://github.com/pkoning2/lk201emu> |
| `vtbt` (tsowell), Bluetooth→LK201 bridge. | `vtbt/` (git clone, shallow) | Another independent LK201 host implementation (ESP32), useful for cross-checking timing/sequence. URL: <https://github.com/tsowell/vtbt> |
| `libgii` man page "LK201/LK401 keyboard input". | `libgii-input-lk201.7.html` | States LK201 and LK401 share the connector and serial format. URL: <https://www.ibiblio.org/ggicore/documentation/libgii/1.0.x/input-lk201.7.html> |
| comp.sys.dec post "The DEC round mouse VSXXX-AA" (Fred Kleinsorge, 1998). | `vaxarchive-vsxxx.html` | Mouse pinout, `4800 8o1`, command set, REL and self-test byte layouts. URL: <https://vaxarchive.org/hardware/vsxxx.html> |
| AllPinouts, "Mouse / Digitizer DEC 7-pin". | `allpinouts-dec-7pin.html` | Connector pinout and the "4800, 8 data bits, odd parity, 1 stop bit" figure for VSXXX-AA/-GA/AB. URL: <https://allpinouts.org/pinouts/connectors/input_device/mouse-digitizer-dec-7-pin/> |

## Our own repository (cross-checks)

* `../EK-V1000-SV-002_service-guide.txt` — VT1000/VT1200 service guide. Says the terminal uses the
  **LK400 series** keyboard (LK401 standard, LK402 word-processing); lists the *Keyboard Test* (27)
  and *Mouse Test* (26) as "firmware requests that the keyboard/mouse do its self-test and display
  any error code"; shows a **separate mouse port** with its own loopback connector (12-25628-01).
* `../../docs/EK-V1200-UG-001_installing-VT1200.txt` — "The keyboard cable connects to the system
  box" and "The mouse connects to the system box"; lists a dedicated *Pointing Device Connector*
  (Table C-2).
* `../rom-strings.txt` — terminal ROM names **`LK401.C`**, and carries the messages
  *"The keyboard ROM reported a fault at power-up"* and *"A key was held down during power-up"*,
  matching the LK201/LK401 error codes `3E`/`3D`.

## Found but NOT retrieved (visible gaps)

| Source | Why | Note |
|---|---|---|
| **LK400 Keyboard Firmware Requirements** | Not located publicly. | The LK401 spec (line 678) points at this document as *the* definition of the terminal→keyboard command protocol. This is the one document that would make LK401 coverage first-class rather than "inherited from LK201". |
| **VT1200-specific keyboard/mouse protocol** | Does not appear to exist. | No VT1000/VT1200/VXT2000 manual documents the wire protocol; the manuals only say "uses the LK400 series keyboard / a 3-button mouse". |
| MAME keyboard ROM `23-001s9-00.bin` (6805 LK201) | Not in the bitsavers zip we have (that zip is the 8051 `23-004M2`). | Needed if we want to run MAME's `lk201` device rather than a HLE model. |
| `bitsavers.org/pdf/dec/terminal/lk201/` directory listing | 403 to our fetcher; used the `trailing-edge` HTTP mirror instead. | Functional equivalent retrieved. |
| `vaxarchive.org/hardware/vsxxx.html` over plain HTTP | 406 (ModSecurity). | Retrieved over HTTPS with a browser UA. |
| `github.com/.../raw/...` for the two Linux drivers | GitHub raw returned a 429 rate-limit stub. | Re-fetched from `git.kernel.org` instead (identical drivers). |