Skip to main content

Web-Bridge Mode

Web-Bridge mode lets a Chrome or Edge desktop browser tab act as a thermal printer bridge — no software installation required.

Recommended path for most merchants: the Print-Bridge agent. Web-Bridge is complementary, not a replacement. It covers USB/Serial/Bluetooth printers on Chromium desktops. Safari, Firefox, and iOS are not supported.

Browser Support Matrix​

BrowserWebUSBWebSerialWebBluetooth
Chrome / Edge (desktop)✅✅✅
Chrome (Android)✅✗✅
Safari / iOS / iPad✗✗✗
Firefox✗✗✗

Windows note: WebUSB is blocked when the printer's OEM driver is installed. The PWA automatically falls back to WebSerial if the printer exposes a virtual COM port. If neither works, use the Print-Bridge agent.

Station vs. Location Bridge​

  • Station web printer — only jobs for the specific kitchen station you selected (e.g. COCINA). A TCP printerUrl for that station is suppressed while the bridge is active; other stations are unaffected.
  • Location web printer — all location-wide jobs not already claimed by a station bridge. This is the existing behaviour before the per-station feature.

You choose the mode when pairing:

  • To pair a station bridge, click Connect printer on the station card (Kitchen Stations → station name → Connect printer).
  • To pair a location bridge, click Connect Web Printer in the top-right toolbar on the Kitchen Stations page.

How It Works​

  1. A staff member navigates to Kitchen Stations in the PWA (Chrome/Edge).
  2. They click Connect printer on the desired station card (or the toolbar button for a location-wide bridge).
  3. They choose a connection type (USB, Serial, or Bluetooth) and click Connect Printer — the browser shows a device picker.
  4. The PWA registers as a web_bridge device scoped to that station (or the location), and stores the device token in localStorage:
    • Station bridge: flowpos:web-bridge:{locationId}:{stationId}
    • Location bridge: flowpos:web-bridge:{locationId}
  5. The PWA opens a Socket.IO connection, subscribes to the station room (or location room), and listens for print_job.new events.
  6. When a print job arrives for that station, the PWA claims it (others receive already_claimed), encodes to ESC/POS bytes, sends them to the printer, and patches the job status to printed.
  7. A heartbeat ping fires every 30 seconds. The server holds a Redis owner lock (kds:bridge:owner:{deviceId}) that self-clears if the tab disconnects.

Resume After Reload​

Closing and reopening a tab does not unpair the station. The station card shows a Paired — Disconnected chip (yellow). Click Resume to reconnect without going through the pairing dialog again — no new pairing code is needed.

If the tab is gone for more than ~60 seconds the Redis owner lock expires. The next tab to click Resume acquires the lock immediately.

One Tab Per Station — What Happens If Two Open​

Each station bridge holds a Redis single-owner lock (kds:bridge:owner:{deviceId}, 60 s TTL). When a second tab connects with the same device credentials:

  1. The server detects the duplicate socket.
  2. It sends a superseded event to the first tab.
  3. The first tab transitions to Owned by another tab (red chip).
  4. The second tab becomes the active owner and starts receiving jobs.

The losing tab shows a Take over button. Clicking it repeats the process in reverse — the new tab acquires the lock and the previous owner receives superseded.

This coordination works across tabs in the same browser. Across different browsers or Cloud Run pods the Redis lock ensures only one socket can own the device at a time.

Status Badge​

When a web-bridge device is active, a Web Printer: Connected badge appears in the PWA header. Closing the tab or the printer going offline changes it to Web Printer: Offline. Receipt routing continues via any paired Print-Bridge agent; the badge simply indicates this tab's contribution.

Station bridge status is shown on the station card, not the header badge — the header badge reflects location-wide bridges only.

Concurrent Devices​

Multiple devices can be paired at the same location (Node bridge + web bridge, or two browser tabs). The backend uses an atomic claim: the first device to PATCH a job status=sent wins. Losers receive an already_claimed response and silently drop the job — no error toast, no duplicate print.

Pairing a Printer​

  1. In the PWA, go to Kitchen Stations.
  2. Click Connect Web Printer (top-right toolbar).
  3. Select your connection type: USB, Serial, or Bluetooth.
  4. Click Connect Printer — the browser will show a device picker (requires a user gesture).
  5. Once connected, the dialog shows a success state and the status badge appears in the header.

The device token is stored in localStorage and reused on subsequent page loads.

Stop using the web printer in this browser:

  • Header badge (Web Printer: Connected / Offline) → menu → Disconnect this browser or Manage web printer…
  • Kitchen Stations → Manage Web Printer → Disconnect this browser (local only) or Unpair web printer (removes server registration)

Closing the tab stops printing but does not clear saved credentials or remove the server device — use Disconnect or Unpair above.

Revoking a Device​

Web-bridge devices are registered at the location level (station_id is null), not on a specific kitchen station. They still appear in the PWA alongside Print-Bridge and KDS devices for that location.

  1. Go to Kitchen Stations.
  2. On any station card (e.g. COCINA), expand KDS devices (collapsed by default; the button label toggles to Hide devices when open).
  3. Find the Web Bridge row in the list.
  4. Click the trash icon and confirm Unpair (English UI; Spanish: Desvincular).

Note: The control is labeled Unpair, not “Deregister”. It removes the device from the backend so it can no longer claim print jobs.

Connections panel: Expanding Connections on a station card only lists devices tied to that station (KDS displays). Web-bridge devices do not appear there because they are not station-scoped.

WebSocket monitor (all location devices)​

For a full list (useful when many test pairings accumulated):

  1. Go to Settings → Websockets.
  2. In the Devices section, find the Web Bridge entry.
  3. Click Unpair (trash icon) and confirm.

Local-only vs full revoke​

ActionEffect
Disconnect this browserStops socket/printer in this tab; clears flowpos:web-bridge:{locationId} from localStorage. Device row remains on the server.
Unpair web printerCalls the same API as KDS Unpair, then disconnects locally. Device is removed from the location.

Printer Compatibility​

Any ESC/POS USB, Serial, or Bluetooth printer that works with Chrome's Web APIs is supported. Verified SKUs:

PrinterUSBSerialBLE
Epson TM-T88VI✅✅✅
Epson TM-T20III✅✅✗
Star TSP100IV✅✅✅
Bixolon SRP-350V✅✅✗

For printers not listed, use the Print-Bridge agent instead.

Cash Drawer​

The ESC/POS drawer-pulse command (0x1B 0x70 0x00 0x19 0xFA) is included when the job payload has drawerPulse: true. This works on all three transport types. BLE drawer pulse works on Epson/Star BLE printers that expose the drawer port; consult the printer datasheet for your specific SKU.

Limitations​

  • Tab must remain open. Closing the PWA tab stops all web-bridge printing. Staff need a dedicated browser tab or kiosk setup.
  • Single receipt paper width. Print jobs are rendered server-side at 42 columns (standard 80mm paper). 58mm paper merchants must use the Print-Bridge agent.
  • No offline queue. If the printer goes offline mid-shift, jobs are not queued — they time out on the server side and must be reprinted.
  • No Windows USB with OEM driver. WebUSB is blocked by Windows when the OEM USB driver is installed. WebSerial (virtual COM port) is the fallback.
  • Safari/iOS not supported. Apple's WebKit does not implement WebUSB, WebSerial, or WebBluetooth. iPad/iPhone merchants should use Star CloudPRNT or route through a Print-Bridge agent.