# VT1200 keyboard & mouse serial protocol — distilled specification

Everything here is attributed to a source in `SOURCES.md`, and each fact is tagged
**[confirmed]**, **[probable]** or **[unknown]**.

## 0. Bottom line

There is **no VT1200-specific protocol document**. What exists is documentation for the
**LK201 keyboard** (and its successor the **LK401**) and for the **VSXXX-AA/-GA mouse /
VSXXX-AB tablet**. The evidence that these *are* the VT1200's parts — and therefore that
their protocols apply — is strong and is laid out in §1. The two facts the level-1
Keyboard/Mouse tests need (the self-test command and its reply) **are** covered by public
sources: it is `FD` → `01 00 00 00` for the keyboard and `T` → a 4-byte report for the mouse.
See §3.5 and §4.4.

Status of the question in the brief: **closest-part-only**. The VT1200's own manuals never
describe the wire protocol.

---

## 1. Which parts the VT1200 uses — the evidence

| Fact | Value | Confidence | Source |
|---|---|---|---|
| Keyboard family | **LK400 series**; `LK401-XX` standard, `LK402-XX` word-processing | **[confirmed]** | `EK-V1000-SV-002_service-guide.txt` §1.1.3 |
| Keyboard, ROM side | Terminal firmware source file is named **`LK401.C`**; ROM strings *"The keyboard ROM reported a fault at power-up"*, *"A key was held down during power-up"* | **[confirmed]** | `../rom-strings.txt` (offsets 0x0E4AB9, 0x0E4B2A, 0x0E4B58) |
| Keyboard, model designation | `LK401 Keyboard` appears as a heading in the VT1200 user guide | **[confirmed]** | `../../docs/EK-V1200-UG-001_installing-VT1200.txt` (TOC §"The Keyboard") |
| LK401 electrical/firmware relation to LK201 | "not intended to be a direct replacement for the LK201, but is **electrically and firmware functionally compatible**" | **[confirmed]** | `vt100net-lk401.txt` line 239 |
| LK401 host protocol = LK201 protocol | LK401 spec says the terminal→keyboard protocol "can be found in the LK400 Keyboard Firmware Requirements"; `lkkbd.c` and `elkay` implement one driver for both, and `lkkbd.c` enables extra LK401 keys with one added command | **[probable]** | `vt100net-lk401.txt` line 678; `linux-lkkbd.c` lines 39–46; `elkay/docs/protocol.md` |
| Mouse / tablet | 3-button pointing device; service guide calls the device test "mouse **or tablet**"; a `VSXXX-AB` tablet is the optional alternative | **[confirmed]** device type / **[probable]** exact model `VSXXX-AA` | `EK-V1000-SV-002_service-guide.txt`; `vcb02-az-glgab-mn-feb86-text.txt` App. C/D |

So: **keyboard = LK401, which speaks the LK201 serial protocol; mouse = VSXXX-AA
(hockey-puck), with the VSXXX-AB tablet as the alternate the firmware also supports.**

---

## 2. Topology — separate ports, NOT daisy-chained

This is the one place the VT1200 differs from the common LK201/VSXXX picture (where the
mouse hangs off the keyboard).

* The terminal ROM's own test list names **two separate DUART2 channels**:
  `H - DUART2, CHANNEL A (KEYBOARD)` and `I - DUART2, CHANNEL B (MOUSE)`. **[confirmed]**
  (`../rom-strings.txt`, offsets 0x179795 / nearby; `../level1-test-sequence.md`).
* The service guide tells the technician to "Disconnect the keyboard, mouse, or printer
  **from the rear of the system box**"; the VT1200 user guide says "The keyboard cable
  connects to the system box" and "The mouse connects to the system box". **[confirmed]**
* The service guide provides a **separate mouse-port loopback connector** (12-25628-01) and a
  distinct *Mouse Port Test* (19) vs *Keyboard Port Test* (18). **[confirmed]**
* The VCB02 (the architectural ancestor, same Q-bus/DUART design) likewise keeps the keyboard
  on DUART **channel A** and the pointing device on **channel B**, with "the other port …
  for any other serial device, probably a mouse or a tablet". **[confirmed]**
  (`vcb02-az-glgab-mn-feb86-text.txt` lines ~9635, and the DUART reset-default table.)

**Conclusion [confirmed]: on the VT1200 the keyboard is on DUART2-A and the mouse is on
DUART2-B, as two independent serial links. The mouse is NOT daisy-chained through the
keyboard.** This matches the already-wired MAME SCN2681 at both DUART windows.

---

## 3. Keyboard (LK401, LK201 protocol)

### 3.1 Wire parameters

| Parameter | Value | Confidence | Source |
|---|---|---|---|
| Baud | **4800** | **[confirmed]** | `netbsd-lk201-interface.html`; `vt100net-lk401.txt` §3.5.4 "4800 baud only"; MAME `lk201.cpp` `set_rate(4800)` |
| Data bits | **8** | **[confirmed]** | LK401 §3.5.5 "start bit, 8 data bits, stop bit"; `vt100net-lk401.txt` |
| Parity | **none** | **[confirmed]** | LK401 §3.5.5 has no parity element (8N1); `netbsd-lk201-interface.html` ("8N1"); MAME `set_data_frame(1, 8, PARITY_NONE, STOP_BITS_1)` |
| Stop bits | **1** | **[confirmed]** | as above |
| Levels | **EIA RS-423**, ±5 V, powered from +12 V | **[confirmed]** | `netbsd-lk201-interface.html`; `elkay/docs/protocol.md` |
| Connector | 4P4C modular: 1=host TX→kbd, 2=GND, 3=+12 V, 4=kbd→host RX | **[probable]** (pin order differs between write-ups; verify at the cable) | `linux-lkkbd.c` header; `elkay/docs/protocol.md` |

### 3.2 Framing / command encoding

Host→keyboard: a command is one or more bytes. **Bit 7 of the last byte of every command is
set** (the "PARAMS" flag); bit 7 of a non-final byte is clear, and byte bit 0 is the
"TYPE" flag (0 = transmission command, 1 = peripheral command). **[confirmed]**
(`vcb02-az-glgab-mn-feb86-text.txt` §B.5.5.1–B.5.5.2.) Keyboard→host: single bytes.

### 3.3 Host → keyboard command set (VCB02 Table B-7, cross-checked against drivers)

| Bytes | Meaning | Conf. | Source |
|---|---|---|---|
| `FD` | **Jump to Power-Up / Reinitiate Keyboard** — keyboard runs its self-test and sends the 4-byte power-up sequence (§3.5) | **[confirmed]** | VCB02 B.5.5.3 "The jump to power-up command is FD (hexadecimal)"; `linux-lkkbd.c` `LK_CMD_POWERCYCLE_RESET 0xfd`; `vt100net-lk201-keyboard.html` trace |
| `AB` | Request keyboard ID — returns the 2-byte ID, does not jump to power-up | **[confirmed]** | VCB02 Table B-7; `linux-lkkbd.c`; `netbsd-lk201-interface.html` |
| `D3` | Reinstate defaults | **[confirmed]** | VCB02 Table B-7; `linux-lkkbd.c` |
| `CB` | Jump to test mode (factory) → replies `B8` | **[confirmed]** | VCB02 Table B-7; `netbsd-lk201-interface.html` |
| `13 p` / `11 p` | LEDs on / off; `p` bitmask: `01` Wait, `02` Compose, `04` Lock, `08` Hold Screen (parameter high bit set, e.g. `8F` = all) | **[confirmed]** | VCB02 Table B-7 + Fig. B-11; `netbsd-lk201-interface.html` |
| `99` | Disable keyclick | **[confirmed]** | VCB02 Table B-7 |
| `1B v` | Enable keyclick, volume `v` (`0x80`\|0–7, 0 = loudest) | **[confirmed]** | VCB02 Table B-7 + Fig. B-13 |
| `B9` | Disable Ctrl-key click | **[confirmed]** | VCB02 Table B-7 |
| `BB v` | Enable Ctrl-key click | **[confirmed]** | VCB02 Table B-7 |
| `9F` | Sound a keyclick | **[confirmed]** | VCB02 Table B-7 |
| `A1` | Disable bell | **[confirmed]** | VCB02 Table B-7 |
| `23 v` | Enable bell, volume | **[confirmed]** | VCB02 Table B-7 |
| `A7` | Sound bell | **[confirmed]** | VCB02 Table B-7 |
| `D1` | Temporary auto-repeat inhibit | **[confirmed]** | VCB02 Table B-7 |
| `E3` / `E1` | Enable / disable auto-repeat across keyboard | **[confirmed]** | VCB02 Table B-7 |
| `D9` | Change all auto-repeat to down-only | **[confirmed]** | VCB02 Table B-7 |
| `8B` | Resume keyboard transmission | **[confirmed]** | VCB02 Table B-7 |
| `89` (VCB02 OCR) / `B9` (NetBSD) | Inhibit keyboard transmission | **[unknown]** — the two sources disagree (`89` vs `B9`); treat as unresolved | VCB02 Table B-7; `netbsd-lk201-interface.html` |
| `0x86 \| d<<3` | Set division *d* (1–14) to a mode: low bits `00` down, `10` auto-down, `11` down/up | **[confirmed]** | VCB02 B.5.5.4; `netbsd-lk201-interface.html`; `elkay/docs/protocol.md` |
| `E9` | **LK401 mode**: enables the extra keys (LAlt, RAlt, RCompose, RShift). LK401-only. | **[confirmed]** | `linux-lkkbd.c` `LK_CMD_ENABLE_LK401`; `elkay/docs/protocol.md` |

> ⚠ The level-0 I/O data-path anomaly recorded in `../level1-test-sequence.md` says the
> firmware writes `0xE1` to DUART2-A and expects a **10-byte** reply. `0xE1` is documented as
> "disable auto-repeat across keyboard", which has **no reply** in any source here. So either
> that level-0 write is not what it looks like, or `0xE1` is a transcription error. **[unknown]**
> — flag it for the ROM/Ghidra side; it is not the keyboard *self-test*.

### 3.4 Keyboard → host special codes (single bytes)

`B3` All-Up (last down/up key released) · `B4` Metronome/auto-repeat tick · `B5` Output Error
(buffer overflow) · `B6` Input Error (bad command) · `B7` KBD-locked ACK · `B8` Test-mode ACK ·
`B9` Prefix-to-keys-down · `BA` Mode-change ACK · `7F` reserved. **[confirmed]**
(VCB02 Table B-4; `netbsd-lk201-interface.html`; `linux-lkkbd.c`.) Ordinary keycodes are
single bytes `> 0x40`; every key has one unique code, no shift/ctrl variants. **[confirmed]**
Full keycode table: `netbsd-lk201-keycodes.html` (14 divisions).

### 3.5 Power-up / self-test — **what the level-1 Keyboard Test (error 27) exercises**

On power-up, **or on receiving `FD`**, the keyboard runs a self-test in ≤70 ms and sends a
**4-byte** result. **[confirmed]** (VCB02 §B.5.4.3; NetBSD; LK401 §3.3.4.6; and the captured
VT320 trace in `vt100net-lk201-keyboard.html`.)

| Byte | Meaning | Value |
|---|---|---|
| 1 | Keyboard ID — firmware | `01` (`lkkbd.c` also accepts `02` = LK401 from the `AB` reply) |
| 2 | Keyboard ID — hardware | `00` |
| 3 | **Error code** | `00` = OK · `3D` = key held down at power-up · `3E` = ROM/RAM self-test failure |
| 4 | Keycode of the key held down, else `00` | e.g. `AE` in the stuck-shift trace |

* Healthy reply: **`01 00 00 00`**. Captured live on a VT320/LK201 in
  `vt100net-lk201-keyboard.html`; emulated identically by `lk201emu` (`resetkb()` sends
  `1,0,0,0`) and expected by `linux-lkkbd.c`. **[confirmed]**
* On a stuck key the reply becomes `01 00 3D <keycode>` and the terminal re-issues `FD`.
  **[confirmed]** (`vt100net-lk201-keyboard.html`.)
* "If the self-test fails and the error is fatal, the keyboard is unable to transmit."
  **[confirmed]** (VCB02 §B.5.4.3.)

**⇒ Implement the device-test model to: on receiving `FD`, reply `01 00 00 00`.** The
terminal's own display of the error code (message *"Keyboard Error - 27"*) comes from its
interpretation of byte 3; "any error code" from the device is what the service guide means by
"display any error code".

### 3.6 Wire parameters under test — does the terminal's test override them?

No source shows the Keyboard/Mouse tests changing baud/parity. The self-test is a normal
command on the already-configured port. **[probable]** — the VCB02 DUART reset-default table
sets channel A to "8 data, parity Off, 4800" and channel B to "8 data, parity **Odd**, 4800"
(`vcb02-az-glgab-mn-feb86-text.txt` §5.5.2.5, Table 5-9). Treat 4800/8N1 (kbd) and 4800/8O1
(mouse) as the port defaults; the VT1200's SCN2681 should be programmed the same way. **[probable]**

---

## 4. Mouse / tablet (VSXXX-AA / VSXXX-AB)

### 4.1 Wire parameters

| Parameter | Value | Confidence | Source |
|---|---|---|---|
| Baud | **4800** | **[confirmed]** | VCB02 §C.4; `linux-vsxxxaa.c` |
| Data bits | **8** | **[confirmed]** | VCB02 §C.6.1 |
| Parity | **ODD** | **[confirmed]** | VCB02 §C.6.1; `allpinouts-dec-7pin.html`; `linux-vsxxxaa.c` ("4800, 8o1") |
| Stop bits | **1** | **[confirmed]** | VCB02 §C.6.1 |
| Levels | RS-232-compatible (mark < −6 V, space > +4.6 V) | **[confirmed]** | VCB02 §C.5 |
| Connector | 7-pin micro-DIN: 1 GND, 2 TxD(mouse out), 3 RxD(into mouse), 4 −12 V, 5 +5 V, 6 n/c, 7 device-present→pin1 | **[confirmed]** | VCB02 Table C-1; `vaxarchive-vsxxx.html` |
| Duplex | half-duplex; a host byte during a mouse transmission aborts it | **[confirmed]** | VCB02 §C.6.1 |

### 4.2 Host → mouse commands (printable ASCII)

`R` (0x52) incremental stream mode · `D` (0x44) prompt mode (power-up default) · `P` (0x50)
request position (also enters prompt mode) · **`T` (0x54) self-test & identify** ·
`S` (0x53) select report format · `Z` (0x5A) reserved. Invalid commands are ignored.
**[confirmed]** (VCB02 Table C-2; `linux-vsxxxaa.c`; `vaxarchive-vsxxx.html`.)

### 4.3 Mouse → host position report (3 bytes, incremental mode)

```
bit  7   6   5   4   3   2   1   0
    1   0   0   SX  SY   L   M   R     byte 1   (header 100)
    0   X6  X5  X4  X3  X2  X1  X0     byte 2
    0   Y6  Y5  Y4  Y3  Y2  Y1  Y0     byte 3
```
`SX/SY` sign (1 = positive), `L/M/R` buttons (1 = depressed), X/Y in resolution units since
last report. **[confirmed]** (VCB02 Fig. C-4; `linux-vsxxxaa.c`; `vaxarchive-vsxxx.html`.)

### 4.4 Power-up / self-test — **what the level-1 Mouse Test (error 26) exercises**

On power-up, **or on receiving `T`**, the device sends a **4-byte self-test report**, starting
bits `101` (0xA0). **[confirmed]** (VCB02 §C.6.5 and Fig. C-5; `linux-vsxxxaa.c`; captured in
`vaxarchive-vsxxx.html`.)

```
byte 1:  1 0 1 0  R3 R2 R1 R0      revision
byte 2:  0 M2 M1 M0 D3 D2 D1 D0    M = manufacturer loc.; device code D: 0010 = mouse, 0100 = tablet
byte 3:  0 E6 E5 E4 E3 E2 E1 E0    error code
byte 4:  0 0 0 0 0  L  M  R        button state, or the failed button if byte 3 = 3D
```
* Byte-3 error codes: `00` = OK; **`3E` = ROM/RAM checksum error**; **`3D` = button error**;
  **codes ≥ 0x20 are fatal, < 0x20 non-fatal**. **[confirmed]** (VCB02 §C.6.5; `vsxxxaa.c`
  treats ≤0x1f as "no serious error".)
* Self-test leaves the device in the reset/power-up state; data sent during self-test is
  ignored. Self-test completes within 500 ms (power-up within 1 s). **[confirmed]** (VCB02 §C.6.4/§C.6.7.)
* Recommended host init (VCB02 §C.7.1): configure port for `4800 8O1`; read the power-up
  self-test report; if none within 1 s, send `T`; then `S`; then `R` (or `D`). **[confirmed]**

**⇒ Implement the device-test model to: on receiving `T`, reply a well-formed self-test
report (e.g. header `0xA0|rev`, device byte `0x02`, error `00`, buttons `00`).** This is
exactly "firmware requests that the mouse do its self-test and display any error code".

### 4.5 Tablet (VSXXX-AB) — for completeness

Same connector, same serial parameters, same command set plus extras; power-up self-test differs
only in device code (`0100`) and a 5-byte absolute-position report (header `110`/0xC0).
**[confirmed]** (VCB02 App. D, §C.7.4; `linux-vsxxxaa.c` ABS branch.) Not needed for the level-1
mouse test unless a tablet is what's attached.

**Coordinate range:** the absolute position spans **`0..2199`** over the active area
(VCB02 App. D.1). **[confirmed]**

**How the terminal chooses** — there is no separate command and no setup record. The **device
code in the `T` reply is the whole discriminator**, and the host then frames **3-byte relative**
reports for a mouse (`0010`) or **5-byte absolute** ones for a tablet (`0100`). **[confirmed]**
against the running OS in the harness: it sends `T`, reads `A0 04 00 00` from a tablet, and then
reads RHRB in **groups of 5** — groups of 3 with a mouse.

---

## 5. How a device failure is reported back (both devices)

The terminal displays an error code it derived from the device's self-test reply: keyboard
error byte 3 (`3E`/`3D`), mouse error byte 3 (`3E`/`3D`, or ≥0x20 fatal). The service guide's
troubleshooting table then says, for **error 27**, "Replace the keyboard"; for **error 26**,
"run the Mouse Port Test with external loopback … otherwise replace the mouse". **[confirmed]**
(`EK-V1000-SV-002_service-guide.txt` Table 3-1.)

---

## 6. MAME relevance (drop-in candidates)

* **Keyboard: MAME already has a DEC LK201 device.** `DECLARE_DEVICE_TYPE(LK201, lk201_device)`,
  device name `"lk201"`, "DEC LK201 Keyboard", in
  `src/mame/dec/lk201.h` / `src/mame/dec/lk201.cpp`. It is a
  `device_t + device_serial_interface`, i.e. **it expects a DUART-style serial channel** — it
  would attach to the same SCN2681 channel A we already wired. It models the 68HC05 keyboard
  MCU and **executes the real keyboard firmware ROM** (`23-001s9-00.bin`), so the protocol
  behaviour (including the `FD` self-test reply) comes from that ROM, not from C. It wires as
  `m_lk201->tx_handler()...`/`m_lk201->rx_w()` (see `src/mame/dec/vt240.cpp`, which places it
  behind an i8251). **It does NOT model the mouse.**
* **Mouse: no DEC mouse device exists in MAME** (checked `src/mame/dec/` and the tree; no
  `vsxxx*`). We would need a small HLE model, but §4 gives the complete protocol, so this is
  low-risk.
* **Caveat / gap:** MAME's `lk201` wants the **6805** LK201 ROM `23-001s9-00.bin`, which is
  **not** in the bitsavers zip we have (that is the **8051** `23-004M2`). Running MAME's device
  therefore needs that ROM sourced first; otherwise implement a HLE keyboard that answers `FD`
  with `01 00 00 00` (and optionally honours `AB`, `13/11`, mode-set `BA` ACKs). For merely
  passing level-1 tests 26/27, an HLE keyboard + HLE mouse driven off DUART2-A/B is the
  smallest sufficient model and needs no ROMs at all.

---

## 7. Confidence summary

| Item | Status |
|---|---|
| VT1200 uses LK401 keyboard / VSXXX-AA mouse | **confirmed** (service guide + ROM) |
| Keyboard LK401 speaks LK201 protocol | **probable** (LK401 spec: "firmware functionally compatible"; shared drivers) |
| Keyboard wire: 4800 8N1, RS-423 | **confirmed** |
| Keyboard self-test command `FD` → `01 00 00 00` (+ `3D`/`3E` errors) | **confirmed** |
| Mouse wire: 4800 8O1, RS-232, 7-pin DIN | **confirmed** |
| Mouse self-test command `T` → 4-byte report (`3D`/`3E`, ≥0x20 fatal) | **confirmed** |
| Separate ports (DUART2-A kbd, DUART2-B mouse); no daisy chain | **confirmed** |
| Exact LK401 firmware protocol (LK400 Firmware Requirements) | **unknown** — document not public |
| `0xE1`+10-byte level-0 anomaly | **unknown** — not explained by any source here |
| Inhibit-transmission opcode (`89` vs `B9`) | **unknown** — sources disagree |
| 4P4C keyboard pin order | **probable** — verify at cable |