Raspberry Pi Bridge Setup

Turn a Raspberry Pi 5 into a dedicated, always-on headless print server — no PC required.

What you need

  • Raspberry Pi 5 — 4GB RAM or higher is recommended.
  • MicroSD card — 16GB or larger. A high-endurance card (e.g. Samsung PRO Endurance) gives best long-term reliability.
  • Network access — Ethernet (recommended) or Wi-Fi. The Pi needs internet access to reach ReceiptKit Cloud and local network access to reach your printer.
  • Star Micronics printer — connected via Ethernet or USB. See Supported Printers for compatible models.
  • SD card reader — needed to flash the image from your computer.
1

Download the image and config file

Go to Dashboard → Devices → Add Raspberry Pi and follow the guided setup wizard. It will walk you through:

  1. Downloading the ReceiptKit SD card image — a custom headless image (no desktop environment) with Receipt Bridge pre-installed.
  2. Selecting an API key — choose a secret key to embed so the Pi authenticates automatically on first boot.
  3. Downloading your config file — generates a receiptkit.toml file containing your API key and optionally your Wi-Fi credentials. You'll copy this onto the SD card in step 3.
Open Pi Setup Wizard
2

Flash the image to your SD card

Download and install Raspberry Pi Imager, insert your microSD card, then configure it as follows:

Device:Select Raspberry Pi 5
OS:Click Use custom and select the .img.xz file you downloaded in Step 1
Storage:Select your microSD card
Settings:Click Next to begin writing — no extra OS customisation is needed. Your receiptkit.toml handles Wi-Fi, SSH, and API key setup automatically.

Wait for Imager to finish writing and verifying the image.

3

Copy the config file to the SD card

After flashing, the SD card will have a boot partition visible on your computer. Copy the receiptkit.toml file you downloaded in Step 1 to the root of that partition.

Tip: you may need to unplug and re-insert your SD card reader after flashing for the boot partition to appear.

4

Connect your printer

Ethernet (recommended)

Connect the printer and the Pi to the same network switch or router. This is the most reliable option.

USB

Plug the printer's USB cable directly into a USB port on the Pi. The printer must be directly connected — USB does not work across the network.

5

Insert the SD card and power on

Insert the SD card into your Raspberry Pi 5 and connect power. The Pi will boot, read your config file, and automatically connect to ReceiptKit Cloud. The config file is deleted from the card after the first successful boot.

Allow about 60–90 seconds for the Pi to fully start up and connect.

6

Verify your Pi is online

Log in to your ReceiptKit dashboard and go to Devices. Your Pi will appear automatically once it connects — there is no manual registration step.

7

Add your printer

Open the Receipt Bridge UI to add and configure your printer. You can access it two ways:

From the dashboard (recommended)

Go to your device in the dashboard and use Remote View to open the Bridge UI directly from your browser.

On the local network

From any device on the same network, open http://receiptkit.local:3000 in a browser.

Once the Bridge UI is open, add your printer and send a test print to confirm everything is working.

Troubleshooting

Pi doesn't appear in the dashboard

Wait 90 seconds after powering on. If it still hasn't appeared, check that the receiptkit.toml was copied to the boot partition before inserting the card. If using Wi-Fi, verify your SSID and password in the config. Connecting via Ethernet removes the Wi-Fi dependency entirely.

Printer not detected in the Bridge UI

For Ethernet-connected printers, ensure the printer and Pi are on the same network segment. For USB, check the cable is firmly connected to the Pi and try a different USB port. Only USB-connected printers appear when scanning from the Pi — network printers are discoverable via IP address.

Bridge goes offline after a few minutes

This is usually a power issue. Use the official Raspberry Pi 5 power supply (27W USB-C) — underpowered supplies cause instability, especially under USB load.

Need help? Contact us and we'll get you sorted.