Printer Bridge
The Printer Bridge is a small utility that runs on a Windows PC or Linux machine and bridges USB-connected printers to the network. Brother POS sends print jobs over the network, and the Printer Bridge translates them into USB commands for your printer. This is only needed if your printers connect via USB rather than Ethernet or Wi-Fi.
When You Need the Printer Bridge
You need the Printer Bridge if:
- Your receipt printer connects to your computer via USB (not Ethernet or Wi-Fi).
- Your label printer connects via USB.
- You want to use a USB printer with a cloud-hosted Brother POS instance.
You do not need the Printer Bridge if:
- Your printers connect via Ethernet or Wi-Fi directly to the network.
- Your printers support Star CloudPRNT (which uses HTTP polling).
How It Works
Brother POS ──(network)──> Windows PC ──(USB)──> Printer
(cloud) (Printer Bridge) (USB receipt/label)
When Brother POS sends a print job to the Windows PC's IP address, the Printer Bridge receives it and forwards it to the appropriate USB printer. The Printer Bridge uses the Windows default printer unless a specific printer name is configured in the script.
Cloud Deployments: Browser-Side Bridge Relay
On cloud-hosted (multi-tenant) deployments, the Brother POS server runs in the cloud and cannot reach a Printer Bridge running on the customer's localhost. To make USB printing work from the cloud, certain print paths relay through the browser instead of the server:
Cloud server ──> Browser (admin/POS) ──(localhost network)──> Printer Bridge ──(USB)──> Printer
- Product labels from the React POS already print this way -- the browser generates the label commands and POSTs them directly to the bridge.
- Loyalty card printing from the Rails admin now uses the same approach. When you click Print Card, the browser detects the bridge on the page load, fetches the card commands (base64) plus the bridge IP/port and printer type from the server, then POSTs the decoded bytes straight to the bridge on port 9101 (
application/octet-stream). If no bridge is detected (on-premise installs where the server can reach the printer), it falls back to the original server-side submit. - Non-Zebra Bluetooth printers (for example Munbyn) also use this client-side bridge path. Previously only the Zebra Bluetooth path was supported, and other printers fell through to a server API that could not reach the shop's local bridge -- causing a 422 error. The POS now renders the customer card template in the browser and POSTs commands to the bridge for any bridge-enabled printer.
Unlike product labels (printed from the React POS in the browser), loyalty cards are rendered by the Rails admin, which had no browser-side print path before. On a cloud deployment the server cannot reach the customer's localhost:9101, so the browser-side relay was added to use the same transport that already works for product labels.
System Requirements
- Operating System: Windows 10, Windows 11, or Linux (Ubuntu/Debian)
- Python: Required only if running from source. A pre-compiled
.exe(built with PyInstaller from the GUI version) is also available and does not require Python. - USB Ports: One per printer (one for receipt, one for label)
- Network: The computer must be on the same network as the POS device
- Ports: The bridge listens on TCP port 9100 for receipt print jobs and TCP port 9101 for label print jobs (configurable via
--receipt-portand--label-portarguments) - Always On: The computer must remain powered on and the Printer Bridge must be running for printing to work
The Printer Bridge should run on a PC that is always on during business hours. A mini-PC or an inexpensive Windows laptop dedicated to this task is ideal. Do not rely on an employee's workstation that may be shut down or restarted.
Installation
Step 1: Install Python
The Printer Bridge is a Python script. Download and install Python from python.org if it is not already installed on the Windows computer.
Step 2: Get the Printer Bridge Script
Download the Printer Bridge for your operating system:
- Windows: Download from your Brother POS admin panel or request from support.
- Linux: Download the Linux Printer Bridge package from your admin panel (available at
/downloads/printer_bridge_linux.zip).
Step 3: Connect Your Printers
- Connect your USB receipt printer to the Windows PC.
- Connect your USB label printer (if you have one) to a second USB port.
- Ensure the printers are powered on and detected by Windows (check Device Manager).
Configuration
Identifying Your Printers
The Printer Bridge uses the Windows default printer unless a specific printer name is configured in the script. To verify your printers are recognized:
- Open Device Manager on the Windows PC.
- Expand Printers or USB Devices.
- Confirm that your receipt and label printers are listed.
Running the Printer Bridge
From the compiled .exe (recommended):
- Double-click the Printer Bridge executable. A system-tray icon appears.
- The bridge starts listening for print jobs automatically on ports 9100 (receipt) and 9101 (label).
From source (Python):
- Open a command prompt or terminal on the Windows PC.
- Navigate to the directory containing the Printer Bridge scripts.
- Run the multi-printer script:
python printer_bridge_multi.py. - Optionally specify printers:
python printer_bridge_multi.py --receipt-printer "Epson TM-m30II" --label-printer "Zebra ZD421". - You should see log output confirming the Printer Bridge is running and the printers are detected.
To have the Printer Bridge start automatically when the PC boots:
- Press
Win + R, typeshell:startup, and press Enter. - Create a shortcut to the Printer Bridge script in the startup folder, or create a batch file that runs the Python script.
- Alternatively, use Windows Task Scheduler to run the script at login.
Configuring Brother POS
Once the Printer Bridge is running:
- Log in to the Admin Panel.
- Navigate to the Printers page.
- Add or edit a printer.
- Set the IP Address to the Windows PC's IP address (e.g.,
192.168.1.150). - The port settings will be configured automatically. If prompted, use the default values provided by the Printer Bridge.
- Click Save.
- Click Test Print to verify the connection.
Always configure your label printer as a Printer record on the /printers page rather than relying on the older Store-level label printer fields. The label print path now prefers a configured Printer record (including its bridge IP/port) over the legacy Store-level flag. This fixes a case where the Store-level "label printer enabled" flag was on but its IP fields were blank, which used to make the loyalty card print path report "Label printer not enabled" even though product label printing worked.
Verifying the Connection
Test Receipt Print
- In the admin panel, go to the Printers page.
- Click Test Print next to your receipt printer.
- The print job travels: Brother POS -> Network -> Printer Bridge -> USB -> Receipt Printer.
- A test receipt should print within a few seconds.
Test Label Print
- In the admin panel, go to the Printers page.
- Click Test Print next to your label printer.
- A test label should print.
If either test fails, check the Printer Bridge window for error messages.
Monitoring the Printer Bridge
The Printer Bridge logs all activity to its application window and to a log file.
Log entries include:
- Connection events -- When a print job arrives.
- Print status -- Whether the job was sent to the USB printer successfully.
- Errors -- USB disconnections, communication failures, or other issues.
Review the log if you experience intermittent printing issues.
Troubleshooting
Printer Bridge Does Not Start
| Problem | Solution |
|---|---|
| Script fails to run | Verify Python is installed and accessible from the command line. |
| "USB device not found" | Reconnect the USB cable. Check Device Manager. |
Print Jobs Not Arriving
- Check the network -- Verify the Windows PC is reachable from the POS device. Ping the PC's IP address.
- Check the firewall -- Windows Firewall may be blocking incoming connections on the ports used by the Printer Bridge. Add a firewall exception (see below).
- Check the Printer Bridge -- Is the Printer Bridge script still running? It may have crashed or been closed.
Adding Firewall Exceptions
- Open Windows Defender Firewall.
- Click Advanced Settings.
- Click Inbound Rules > New Rule.
- Select Port, click Next.
- Enter the ports used by the Printer Bridge (shown in the Printer Bridge window when it starts).
- Select Allow the connection.
- Apply to all profiles (Domain, Private, Public).
- Name the rule "Brother POS Printer Bridge" and save.
USB Printer Disconnects
If the USB printer disconnects intermittently:
- Try a different USB cable.
- Try a different USB port on the PC.
- Avoid using a USB hub -- connect directly to the PC.
- Check that the printer's power supply is stable.
If the Printer Bridge script is closed, printing will stop. The Printer Bridge must be running at all times during business hours. Consider using the auto-start method described above to ensure it launches when the PC boots.
Common Questions
Can the Printer Bridge run on macOS or Linux? The Printer Bridge is available for Windows and Linux. A Linux version is provided for Mini-PC deployments running Ubuntu or Debian. macOS is not currently supported -- contact support if you need macOS USB printing.
Can one PC bridge multiple receipt printers? The Printer Bridge supports one receipt printer and one label printer per installation. For multiple receipt printers, contact support for guidance on your setup.
Does the Printer Bridge work over VPN? Technically yes, as long as the POS device can reach the Windows PC's IP address over the VPN. However, network latency may cause slow printing.
What's Next?
- Receipt Printers -- Configure receipt printer settings in Brother POS.
- Label Printers -- Configure label printer settings.
- Cash Drawers -- Connect a cash drawer to your receipt printer.