Quicktill Kiosk Plugin

Quicktill register plugin for the Polybius Space Bar. Handles two jobs:

1. Barcode recall — when the payment-point barcode scanner reads a kiosk slip, verifies the HMAC check digit and recalls the matching open transaction into the quicktill register.
2. Soft-only auto-pay — if the recalled order contains only soft drinks, triggers Square payment automatically without staff intervention.

Order creation lives in emftillweb. This plugin does not create orders; it manages them post-creation.

QR is not supported: the dot-matrix printer's ink bleed makes QR codes unreliable to scan, and the till's barcode scanners can't read QR at all. Anything presenting a QR code (e.g. spacebar-badge's on-screen order QR) will not scan here — see that repo for its own barcode/QR handling.

Barcode format

hook_unknown_barcode decodes every scanned barcode as a single fixed-length, all-numeric 10-digit format (_decode_barcode_1d / _checkdigits_1d). If it doesn't decode, the hook returns False (unrecognised — not a kiosk barcode) and quicktill's normal barcode handling continues.

Permutation cipher, 10 digits. The barcode itself — permutation and HMAC check digits both — is generated by emftillweb's emf/kiosk.py _order_barcode() and returned verbatim as barcode by the order API; this plugin only decodes it. The first 5 digits are the quicktill Transaction ID run through a fixed LCG permutation (a=73141, b=49873, m=100000) so small transaction IDs don't produce leading zeros; the plugin recovers trans_id with the modular inverse of a. The last 5 digits are a check digit: the last 5 decimal digits of HMAC-SHA1(barcode_secret, trans_id) mod 100000, zero-padded to 5 digits.

Rejects on wrong length, non-decimal characters, or a check-digit mismatch. With no barcode_secret configured, the HMAC falls back to a plain (unauthenticated) SHA1 hash — dev only; both the plugin and emftillweb must be configured with the same barcode_secret in production.

Till configuration

Install this package in the till environment, then instantiate from the till config file:

from quicktill_kiosk_plugin import KioskPlugin

KioskPlugin(
    barcode_secret="<shared-secret-from-emftillweb-toml>",
    oms_url="http://groundcontrol",
    square_paytype="SQUARE",
)

All parameters are keyword-only. All are optional, but barcode_secret should always be set in production.

Parameter	Default	Description
barcode_secret	""	HMAC secret; must match kiosk.barcode_secret in emftillweb.toml. Without this, barcodes are accepted without verification (dev only).
oms_url	None	If set, POSTs order-loaded (on recall) and order-paid (on close) notifications to the OMS. order-loaded is required for the payment instruction screen to update on scan; order-paid is a latency shortcut only — the OMS still confirms payment via its own poll of tillweb.
square_paytype	None	If set, automatically triggers this payment type after recalling a soft-only order. The soft_only flag is set by emftillweb when all items have maxabv ≤ 0.5%.
meta_key	"emf:kiosk-order"	TransactionMeta key used by emftillweb. Change only if you changed it there too.

Recall behaviour

On a valid barcode scan the plugin:

1. Tries to decode the scanned code as a 1D barcode (includes its own HMAC-SHA1 check-digit verification against barcode_secret, see "Barcode format" above). If it doesn't decode, the hook returns False and the scan is left for quicktill's normal handling.
2. Checks the till is not mid-transaction (won't interrupt an active sale — shows a brief toast if busy).
3. Looks up the transaction by ID. Rejects if: not found, missing kiosk metadata, already paid (trans.closed), or the order's kiosk metadata has rejected set — meaning bar staff refused the order via the kiosk's ID-check flow. The first three are low-stakes, transient conditions shown as a toast (auto-dismisses, no keypress needed); the rejected case is safety-critical and shown as a blocking popup addressed to the till operator: "Order refused" / "Order {id} was rejected during ID check. Do not take payment. Recall this transaction and press Cancel to void it."
4. Calls reg.recalltrans() to load the transaction into the register.
5. If oms_url is set, fires a background POST to {oms_url}/pay/order-loaded with { order_ref, soft_only }.
6. If square_paytype is set and the order is soft-only, calls reg.paymentkey(square_paytype) to trigger Square payment immediately.

Separately, whenever a kiosk transaction closes (balanced/paid), hook_close_transaction fires a background POST to {oms_url}/pay/order-paid with { order_ref } immediately — this plugin does not add any delay before sending it. This isn't authoritative — the OMS doesn't mark anything paid off the back of it; it just uses the ping to trigger an early re-poll of tillweb instead of waiting out its normal poll interval, so the staff board updates faster. Any delay between receiving this ping and the OMS actually re-polling (e.g. to avoid racing the till's own commit of the closed transaction) is implemented in the OMS's own handler, in the separate spacebar-oms repo — not in this plugin.

emftillweb.toml — shared secret

[kiosk]
barcode_secret = "<random-secret>"

Generate with:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

The same value goes in both emftillweb.toml and the KioskPlugin(barcode_secret=...) call in the till config.