sibo-playground/code/inventory/README.md

# inventory

A demo inventory application for the Psion Workabout MX: scan UPC barcodes, and
(Phase 2) keep stock counts in a database file, adding stock or consuming it by
scanning.

Written in PLIB C, built with the TopSpeed compiler (`tsc /m scan`).

## Phases

- **Phase 1 (current): scan and validate.** Read UPC barcodes from the integral
  laser and display them.
  Modules: `upc` (validation), `bcode` (scanner input), `scan` (the demo).
- **Phase 2 (next): inventory database.** A DBF file keyed on UPC holding a
  quantity and a name. Scan to add stock, scan to consume by a quantity unit.
  Built on the SIBO `Dbf*` API (`p_dbf.h`).

## Build

```
tsc /m scan
```

Produces `scan.img`. `scan.pr` compiles `upc.c`, `bcode.c`, `scan.c` and links
`scan.img`.

## How the scanner is read (important)

The Workabout MX integral laser is an **undecoded (HHLC)** scanner: it emits a
raw bar/space signal, not decoded ASCII. The hardware serial decoder in the
RS232/Barcode module handles only wands and wand-emulation scanners — the HC
guide explicitly lists "Undecoded Laser Scanner (HHLC)" as **unsupported** there.
That is why reading `TTY:D` directly returned nothing even though the laser's
own good-read LED lit.

The decode is done in **software** by a barcode decoder LDD. The SDK ships
several in `\SIBOSDK\LIB`; each registers the device `BAR:`:

| LDD | Symbology |
| --- | --- |
| `BAREAN.LDD` | EAN / **UPC** |
| `BARC39.LDD` | Code 39 |
| `BAR128.LDD` | Code 128 |
| `BARITF.LDD` | Interleaved 2 of 5 |
| `BARMPLES.LDD` | MSI Plessey |
| `BARRAW.LDD` | raw / undecoded |

So the flow is: `p_loadldd("BAREAN")` → `p_open("BAR:")` → read decoded
barcodes. **`BAREAN.LDD` must be present on the device** for `p_loadldd` to find
it (copy it from `\SIBOSDK\LIB`, or load it via the system config).

The current build is a **diagnostic**: it dumps every byte of each read
(`n=<count>: <decimal bytes> "<printable>"`) so the exact decoded format — length,
any type/prefix byte, terminator — can be confirmed before the reader and the
Phase 2 database key are finalised.

## The `BAR:` read protocol

The precise read semantics of `BAR:` (data format, any symbology configuration
via escape sequences) live in the I/O Devices Reference manual, which is not
among the committed docs. The diagnostic build exists to establish that format
empirically. Once a scan prints, the reader (terminator handling, UPC
validation via `upc.c`) and Phase 2 follow.