Installing and pairing Bridge step by step

Bridge is a local service (Node/TypeScript) running on the computer next to the register or printer. It connects to the cloud only via an outbound connection, so no ports need to be opened. It reaches devices over TCP, a serial port (COM) or USB-serial.

Requirements

• Node.js version 22.13 or newer (Bridge uses the built-in node:sqlite).
• A computer that is always on, with internet access and a connection to the device.
• For serial ports, the serialport package (native binaries): after building, run `npm install --omit=dev` in the dist directory. It is not needed for TCP cash registers.
• Bridge is a single cli.mjs file: you start the service manually and install new versions yourself.

Installation and pairing

1. In the app, open "Cash registers and printers", the "Devices" tab, click "Add device" and then "Pair" (the wizard shows the same steps). The pairing code is single-use and valid for 30 minutes.
2. Build the package with `pnpm --filter @zaksio/bridge build`. The output goes to apps/bridge/dist (cli.mjs, package.json, deploy/).
3. Copy deploy/bridge.config.example.json as bridge.config.json and adjust the devices. The `key` field is the device's local name in Bridge.
4. Pair: `node dist/cli.mjs pair --device kasa1 --code ABCD-EFGH --config bridge.config.json`. The command saves the device token and signing key in the local database (dataDir/bridge.sqlite).
5. Run: `node dist/cli.mjs run --config bridge.config.json`, and permanently as a service (next section).
6. The indicator in the wizard will change to "Paired" by itself once Bridge reports in with the code.

Running as a service

• Linux: the file deploy/zaksio-bridge.service (systemd).
• Windows, e.g. NSSM: `nssm install ZaksioBridge "C:\Program Files\nodejs\node.exe" "C:\ZaksioBridge\cli.mjs run --config C:\ZaksioBridge\bridge.config.json"`, then `nssm set ZaksioBridge AppDirectory C:\ZaksioBridge` and `nssm set ZaksioBridge Start SERVICE_AUTO_START`.
• The configuration file (JSON) has the fields apiUrl, dataDir, heartbeatSeconds, pollWaitSeconds and a devices list (key, driver, transport, options). Typos in driver options are an error.
• By default, Bridge prints without Polish characters (ascii encoding). Set a different code page only after checking the register's settings, because a wrong one prints garbage. A VAT rate the register does not know ends in an error with no printout.

Heartbeat, status and offline alert

Bridge regularly sends a heartbeat with the device status, including paper. In the "Devices" tab you see the status: "Online", "Offline", "Problem", "Unpaired" or "Disabled" and the time of the last contact. The "Alert after no signal (minutes)" field in the device form (default 5, range 1 to 1440) sets after how many minutes of silence the device gets the "Offline" status and the "Device is not responding" alert appears. The `status` command shows the status locally.

Token, rotation and security

• The device token (zbt_...) is stored in the cloud database only as a hash. The "Rotate token" button replaces it without any action on the computer: Bridge sees the expiry in the heartbeat, fetches a new token and saves it. The old one keeps working for another 15 minutes.
• Pairing again invalidates the old token, and a new code invalidates the previous one. A disabled device loses access immediately.
• Jobs are signed (HMAC-SHA256, key from pairing) and verified before execution. A job cancelled or redirected in the app will not be printed.
• The token and key are stored in the local database: protect the data directory with system permissions (Linux: StateDirectoryMode=0700, Windows: ACL for the service account only).

Offline mode

The local queue is SQLite in WAL mode. Jobs fetched before connectivity was lost print locally, and the results wait and are sent once the internet is back. After a restart during printing, Bridge checks the register's document counter instead of retrying blindly. New jobs require an internet connection.

Where to find it in the app

• "Sales" menu, "Cash registers and printers", "Devices" tab: the buttons "Add device", "Pair" (after pairing, "Pair again"), "Edit", "Rotate token", "Disable" and "Enable".
• Adding, editing and pairing require the fiscal:write permission; viewing requires fiscal:read. The module requires the `fiscal` business profile feature.