sibo-playground/code/inventory/SCANNER-API.md

Workabout MX barcode scanner — API notes (reverse-engineered)

There is no official SDK documentation for the Workabout MX integral laser scanner. The Psion SIBO C SDK and I/O Devices Reference predate the MX and describe only the older external barcode modules (wands / wand-emulation), not the integral laser. These notes are reverse-engineered from device behaviour and from the Workabout MX ROM w2mx_v7.20f_eng.bin (strings), so treat unconfirmed items as such.

Hardware

• Integral laser scanner, Symbol engine. The demo (DEMMAN.APP) reports Type: Laser 1223 (some units 1222).
• It is a decoded scanner: it decodes in hardware and lights a green good-read LED. It does not emit an undecoded (HHLC) signal.
• Trigger: the keyboard scan key, which the Window Server reports as key code 368. The key alone does not fire the laser from an arbitrary app; the scanner software arms/reads the engine.

Device driver and ports

LLDEV on the device lists a logical driver wl2 (units=1). The scanner is reached through this driver. The demo's "Select Scanner" screen lets you pick both a decoder type and a port (device driver + unit letter):

• Port device drivers offered: TTY, WLS, WL2. The MX integral laser uses WL2.
• Units seen in the ROM: WL2:A and WL2:D.

Decoder types (from the demo, "chosen from those used in standard Workabout products"):

Decoder	Meaning
Generic	External non-configurable reader
Symbol1	Workabout standard scanner
Datalogic	Workabout CCD
HP	Workabout Wand
Symbol2	Workabout MX scanner (the integral laser)

Opening the device

VOID *h;
INT  err = p_open(&h, "WL2:D", (UINT)-1);

Observed results:

Call	Result	Meaning
p_open("WL2:D", -1)	0	opens — this is the integral-laser unit
p_open("WL2:A", -1)	-9 (E_GEN_INUSE)	in use — held by the resident scanner software
p_open("WL2:B" / ":C")	(untested)	—

WL2 has a single unit, so only one process may hold it. WL2:A is permanently -9 even with the demo closed, indicating a resident holder; WL2:D is the unit an application opens.

The 11-byte parameter block

The scanner is configured by an eleven-byte parameter block. The application interprets these bytes and converts them into commands for the selected decoder (so the same block means different wire commands for Symbol2 vs HP, etc.):

Byte	Parameter
Param0	Decode security
Param1	Code type (symbology select)
Param2	Decode options A
Param3	Decode options B
Param4	General parameters
Param5	ITF length 1
Param6	ITF length 2
Param7	Preamble
Param8	Postamble byte 1
Param9	Postamble byte 2
Param10	General decode options

The preamble/postamble bytes mean decoded output may carry configurable leading / trailing characters — parsing code must account for them.

Access model

Applications do not drive WL2 byte-by-byte themselves; they use the ROM library SCANNER.DYL (used by SCANAPP.APP and DEMMAN.APP). That library opens the port, converts the 11-byte block to decoder commands, configures and enables the engine, and returns decoded scans.

Paths that do NOT work for the integral laser

Recorded so they are not retried:

• bar*.ldd decoders (BAREAN, BARC39, …) + BAR: device. These are software decoders for the external wand modules. Loading BAREAN.LDD and opening BAR:A/BAR:B returns -41 (E_FILE_DEVICE, "no interface found in slot") — the integral laser is not a BAR: expansion interface. BAR:D/BAR:E return -38 (E_FILE_NAME, invalid unit).
• TTY:D serial reads. Opening TTY:D powers the laser (it fires briefly), but no decoded bytes ever arrive on the serial channel — not with default config, not after P_FSET to 9600/8/1, not with P_OBEY_DSR cleared, not with the intelligent-reader escape commands (<Esc>-y1J / <Esc>-y1K), not reading one byte at a time. The integral laser's decoded data is not on TTY:D.

Initialisation sequence (reverse-engineered from the ROM)

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.

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)

Value	Name	Meaning
-9	E_GEN_INUSE	device already open / in use
-32	E_FILE_EXIST	(LDD) already loaded
-38	E_FILE_NAME	invalid device name / unit
-41	E_FILE_DEVICE	device / interface not present