Chapter 3 — Bridge App (hardware connection bridge)

The point of sale runs in a browser, and a browser cannot talk directly to a card reader, printer, scale and customer display. The Bridge app is that bridge: it runs next to the till and connects these devices to the till.

It comes in three forms, all of which do the same job (the iOS version is experimental):

• An Android app on a tablet
• A desktop app on a computer (Windows/Mac/Linux)
• An iOS app (experimental)

⚠️ Language: the Android app's interface is effectively English. Only a few old strings have been translated into German; the whole dashboard the operator sees (statuses, Power Guard, Keep Bridge Awake, logs, etc.) is in English.

💡 You usually set up Bridge once and then it runs in the background. You enter the Bridge address in the till at Settings ← Bridge (the till guide, Chapter 9). The Android app runs as a persistent foreground service: it stays alive even if you close the app from the list, restarts automatically after an update, and a watchdog brings the server back up every 30 seconds if needed.

3-1. Android app — status screen

A full-screen (kiosk) page with a summary line at the top and several status cards. While it is starting up you see the message "preparing the bridge, connecting the card reader and customer display".

• The overall summary at the top of the screen, for example: "bridge ready for payment", "card reader ready, waiting for the browser", "browser connected / card reader offline", "recovering the card-reader connection", or "a transaction is in progress".
• Status cards (each with a coloured dot and a status word):
• WebSocket — the local port the till connects to.
• Browser (Browser) — whether the till is connected.
• Card reader (POS Terminal) — statuses: disconnected / connecting / reconnecting / connected / busy (Busy) during a transaction.
• Customer display — the status of the second display.
• Power Guard — battery/CPU/Wi-Fi protection to prevent drops while idle.

The Bridge address card

• It shows the address (local 127.0.0.1:PORT or a network address with the device's IP) that must be entered in the till.
• The connection-mode button is three-state and cycles with each press: local ← network ← automatic (Auto). Automatic mode uses the network if a local network address is available, and otherwise falls back to local.
• Holding the connection-mode button: create or clear a pairing token — a 6-character code that is appended to the address (?token=XXXXXX) so that only the authorised till can connect. This token only applies in network mode (it is ignored in local mode) and is shown in the address as "Paired/Open".

Other cards and opening the logs

• Power Guard → "Keep Bridge Awake" (Keep Bridge Awake): opens the Android battery settings so that Bridge is not cut off while idle.
• Logs: turned on/off with the Enable/Disable Logs button, and View Logs opens the log screen; turning it off clears the stored logs. A second way to open the logs is a long-press on the bar at the top of the screen.
• Log screen: it is read-only — monospaced text that refreshes every second and scrolls to the bottom; it has no share/export button (to send it to support you must copy it manually).
• Customer display screen: on the second display, it shows the order items and total to the customer using a web template. On Android it attaches automatically to any connected second display (no manual selection; it is removed when the cable is disconnected).

3-2. Desktop app — "LonioBridge — Host"

A small control window for running Bridge on a computer:

• Setup form:
• WebSocket port (default 8088)
• Bind address (Bind): just this computer or the whole network (default 0.0.0.0).
• Customer display: manually choose the monitor that will be the customer display (or none).
• Start/stop to run the bridge; the settings are kept between runs in the file ~/.loniobridge/host.properties.
• Autostart (Autostart): with the --autostart parameter (the installer sets it up on Windows with enable/disable scripts so that it starts when the system is switched on).
• Windowless mode (Console): with --console it can run without a graphical interface.
• Status panel: the server state (stopped / starting / listening on the port / invalid port / error), the number of connected tills, the card-reader status, and a busy/idle indicator (during a transaction).
• Activity report: a time-stamped log of events; a Verbose option to record the raw card-reader frames (for troubleshooting only).

⚠️ In the desktop window there is no printer or scale selection; only the port, the bind address and the customer display. The printer and scale are configured from the till side, and Bridge sets them up according to the till's message.

3-3. Which devices connect

• Card reader: there are two drivers, chosen in the terminal profile:
• ZVT (default) — over network/TCP, with automatic reconnection (backoff) and connecting/recovering/connected statuses.
• GP Tom (SoftPOS) — the Global Payments driver that talks to the GP card-reader app on the same Android tablet (sale/void/refund; daily settlement over this App2App route is not yet supported).
• Customer display: a web template (order items and total) that the till sends to it; Android attaches automatically, the desktop by manual monitor selection.
• Printer:
• ⚠️ On Android, printing is currently only accepted but actual print execution has not been implemented; real printing works on the desktop.
• The desktop has three routes: serial, system printer (Windows), and network/TCP (default, port 9100); this includes paper cutting and opening the cash drawer.
• Scale: only on the desktop — serial or USB-HID, with unit detection (kg/g/lb/oz) and a stable/unstable state. Android has no scale.

3-4. The configuration the installer needs to know

• Port (default 8088) and bind address (local versus network).
• The difference between 127.0.0.1 (local) and a network IP: if the till is on this same device, local is enough; if it is on a different device, network mode + IP is required and both must be on the same network.
• The pairing token (?token=…) only in network mode.
• The Android battery settings (Keep Bridge Awake) to prevent drops.

3-5. Quick troubleshooting