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.

Open gap (not yet solved)

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.

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.

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