171 lines
7.0 KiB
Markdown
171 lines
7.0 KiB
Markdown
# 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
|
|
|
|
```c
|
|
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 |
|