From 62d277e5d65f961560a8eee13646ea0867e2c870 Mon Sep 17 00:00:00 2001 From: lyrathorpe Date: Mon, 6 Jul 2026 21:42:36 +0100 Subject: [PATCH] docs(inventory): add reverse-engineered WL2 init sequence + default Symbol2 param block --- code/inventory/SCANNER-API.md | 68 ++++++++++++++++++++++++++++------- 1 file changed, 56 insertions(+), 12 deletions(-) diff --git a/code/inventory/SCANNER-API.md b/code/inventory/SCANNER-API.md index 9f84c82..419bb36 100644 --- a/code/inventory/SCANNER-API.md +++ b/code/inventory/SCANNER-API.md @@ -101,20 +101,64 @@ Recorded so they are not retried: the intelligent-reader escape commands (`-y1J` / `-y1K`), not reading one byte at a time. The integral laser's decoded data is not on `TTY:D`. -## Open gap (not yet solved) +## Initialisation sequence (reverse-engineered from the ROM) -Opening `WL2:D` succeeds, but the scanner does not start scanning on a bare open — -it requires an **initialisation sequence** (set decoder type, write the 11-byte -parameter block as decoder commands, enable the engine) before a read returns -data. That sequence is the function-code / control protocol of the `WL2` driver -and is implemented in the binary `SCANNER.DYL`; it is **not** present in any ROM -strings or in the SDK. +Opening `WL2:D` is not enough — the scanner must be configured and enabled first. +The sequence was recovered by disassembling `SCANNER.DYL` in the v7.20f ROM +(around file offset `0xD7AA4`). It uses the SIBO I/O executive **`int 0xCF`**, +whose convention here is: **`CL` = I/O function code, `BX` = channel handle, +`DX` = argument (by value)**, result in `AX`. From C this is the `p_iow(chan, +func, ...)` layer. -To close it, one of: -1. The **Workabout MX C SDK** scanner header / `SCANNER.DYL` category definition - (what `SCANAPP` was built against) — the clean answer. -2. Disassembly of `SCANNER.DYL` / `SCANAPP` from the ROM to extract the `WL2` - init sequence — large, uncertain effort. +Function codes observed on the `WL2` channel (from `p_file.h`, plus WL2-specific +ones above the standard range): + +| CL | Meaning | +| --- | --- | +| 6 | (`P_FDETACH` slot) used as a scanner enable/control op | +| 7 | (`P_FSET`) used as a scanner enable/control op | +| 8 | `P_FSENSE` | +| 9 | `P_FFLUSH` | +| 0x0C (12) | **WL2-specific: write a config/command byte** (byte passed in `DX`) | + +The driver keeps a per-channel structure; the param block sits at **channel+4**, +with the **decoder type at offset +6** (dispatch values 1..4) and the **11-byte +parameter block at +8..+0x12**. Configuration is pushed to the engine as a series +of `cl=0x0C` writes (one command byte per call in `DX`), then enable ops +(`cl=6`, `cl=7`). + +### Default Symbol2 parameter block (from the ROM) + +The routine at `0xD7AB3` fills the 11-byte block with these defaults for the +Workabout MX (Symbol2) scanner: + +| Byte | Param | Value | +| --- | --- | --- | +| +8 | Param0 Decode security | `0x04` | +| +9 | Param1 Code type | `0x3F` (all symbologies) | +| +0xA| Param2 Decode options A | `0x01` | +| +0xB| Param3 Decode options B | `0x15` | +| +0xC| Param4 General params | `0x06` | +| +0xD| Param5 ITF length 1 | `0x04` | +| +0xE| Param6 ITF length 2 | `0x1E` | +| +0xF| Param7 Preamble | `0x80` | +| +0x10| Param8 Postamble 1 | `0x0D` (CR) | +| +0x11| Param9 Postamble 2 | `0x0A` (LF) | +| +0x12| Param10 General decode | `0x06` | + +So **decoded output is terminated by CR LF** (`0x0D 0x0A`), and Code type `0x3F` +enables all symbologies (UPC included). A reader should assemble bytes until +CR/LF and strip the preamble/postamble. + +### Still to confirm on-device + +The `int 0xCF` calls pass their argument by value in `DX`; replicating this from +C requires that `p_iow(chan, func, arg)` land `arg` in `DX` (or inline asm). The +exact ordering of the config-byte writes and the two enable ops, and two helper +subroutines (`0xD6DC4`, `0xD8DCB`), still need tracing and — crucially — +**validation on the device**, since none of this can be tested off-hardware. The +clean alternative remains the **Workabout MX C SDK** `SCANNER.DYL` header, which +`SCANAPP` was built against. ## Error codes seen (from `epocdefs.h`)