Kerf Bridge
Set-up guide

Set up Kerf Bridge.

Install the bridge on a Raspberry Pi beside the laser, or on a PC that's already there. Plug the laser in by USB, check the bridge's web page, then connect whatever you design with.

Start with a Pi Downloads

Install the bridge

Pick one computer to run it: the laser plugs into that computer by USB, and everything else reaches the laser over the network.

Raspberry Pi

Any Raspberry Pi 3, 4, 5 or Zero 2 W with Raspberry Pi OS. Choose the 64-bit version if you can: the camera needs it.

  1. Set the Pi up with Raspberry Pi OS and connect it to your network.
  2. Plug the laser into the Pi by USB.
  3. On the Pi (in a terminal, or over SSH), run:
curl -fsSL https://trykerf.com/install.sh | sh

Rather read it before it runs? You should be wary of piping any script from the internet into a shell, ours included. This downloads the installer, shows it to you, and runs it only when you choose to:

curl -fsSLo install.sh https://trykerf.com/install.sh less install.sh sh install.sh

What it does, and nothing else: downloads the bridge for your Pi from trykerf.com and checks it against its published SHA-256 checksum (it stops if they don't match); copies it to /usr/local/bin/kerf-bridge; adds a kerf system user that can't log in, in the dialout and video groups so it can reach the laser and the camera; writes /etc/kerf-bridge/config.json if it isn't there; and adds a kerf-bridge systemd service. It uses sudo for those steps. To remove it: sudo systemctl disable --now kerf-bridge.

The installer and the bridge's source code are on GitHub: github.com/itconor/kerf-bridge. You can build the bridge from it yourself and check it matches our download.

That installs the bridge as a service that starts whenever the Pi does. Run the same line again to update; your settings are kept in /etc/kerf-bridge/config.json.

If port 23 is already in use (by ser2net, say), the installer leaves it alone and puts LightBurn pass-through on port 2323 instead.

Windows PC

Windows 10 or 11, 64-bit. Plug the laser into this PC by USB.

  1. Download the bridge from the download section and run it.
  2. It isn't code-signed yet, so Windows may warn you: choose More info → Run anyway.
  3. When Windows asks, allow it through the firewall so the rest of the network can reach it.
  4. Open http://localhost:8023 in a browser on that PC.

Mac

macOS 13 or later, Apple silicon or Intel. Plug the laser into this Mac by USB.

  1. Download Kerf Bridge for Mac from the download section and open it.
  2. Drag Kerf Bridge to Applications, then open it from there. It's signed and notarised by Apple, so it opens like any other app.
  3. A bolt appears in the menu bar. The first time, the bridge's page opens in your browser with the set-up wizard.
  4. If macOS asks whether Kerf Bridge may find devices on your local network or accept incoming connections, choose Allow: that's how Kerf and LightBurn reach it.

The menu bar icon has Open Kerf Bridge…, Start at Login and Quit. Its log is in ~/Library/Logs/Kerf Bridge.log.

Check it's working

Open http://<bridge address>:8023 in any browser on the network, using the Pi's or the PC's address.

The first time, a set-up wizard opens. It walks you through four steps: choose the laser (Test checks a laser answers on that port), choose the camera with its live picture, give the bridge a name, then how to connect Kerf and LightBurn. You can run it again any time from Settings → Set-up wizard.

What you'll see

  • The laser's state and the head's position.
  • A big STOP button.
  • Jogging, to move the head about.
  • Job upload and progress.
  • Settings.

Finding the laser

  • The bridge finds the laser by itself on the usual USB serial chips: CH340, CP210x, FTDI, Arduino, ESP32 and STM32.
  • It reads the laser's bed size from GRBL's $$ settings.
  • If it doesn't find the laser, open Settings → Set-up wizard and test each port until the laser answers. Testing a port restarts whatever is plugged into it, so if a 3D printer shares the computer, only test the laser's port.

Connect Kerf for iPad

The iPad needs to be on the same Wi-Fi as the bridge.

  1. In Kerf, open the Laser tab.
  2. The bridge appears under Kerf Bridges on this network. Tap it.
  3. If it doesn't appear, use Connect by address and type the bridge's address, port 8023.

In job mode the bridge runs the whole job itself, so the iPad can go to sleep without stopping the burn.

LightBurn

LightBurn talks to the bridge as a network laser.

  1. In LightBurn, open Devices → Create Manually and choose GRBL.
  2. Pick Ethernet/TCP.
  3. Enter the bridge's address and port 23 (or 2323, if the installer told you port 23 was taken).
  4. Set the bed size to match the laser. The bridge's web page shows it if you're not sure.

Camera

Almost any USB webcam works: the bridge needs one that sends MJPEG, which nearly all do.

Fitting it

  • Plug it into a Pi running the 64-bit OS, or a Linux PC. The camera doesn't work on Windows, Mac or a 32-bit Pi yet.
  • Mount it looking down at the whole bed.
  • It shows live on the bridge's web page and in Kerf.

Lining work up with it

  • In Kerf: Laser tab → Camera → Line Up the Camera…
  • Cover the bed with card. Kerf burns a grid of 35 dots (about a minute; it asks first), then takes pictures with the head at the two back corners and works out where the camera sees the bed.
  • Light the card well and evenly. A lamp helps; shadows hide the dots.
  • If the dots are already burned, choose Use the dots already burned.

Then, in Kerf

Home Assistant

You need Home Assistant's MQTT broker (the Mosquitto broker add-on) and a Home Assistant user for the bridge to log in as. Nothing to install in Home Assistant itself.

Connecting

  1. On the bridge's web page, open Settings → Home Assistant (MQTT).
  2. Enter the broker's address (for example 192.168.1.10). The port is 1883 unless you've been given another.
  3. Enter that user's name and password, and press Save.
  4. The line underneath says Connected.

What appears

A Kerf Bridge device, with:

  • Laser (its state), Job, Job state, Job progress and Time left
  • Head X and Head Y
  • Laser connected and Burning
  • Stop, Pause and Resume buttons
  • Bed camera: a picture every 5 seconds while a job runs

Stop always works, whoever is running the job. So an automation can stop the laser for you: when a smoke alarm goes off, for example.

If something's not right

The bridge can't find the laser

Check the USB cable: some are for charging only and carry no data, so try another. Then pick the laser's serial port in Settings on the bridge's web page.

It says "Held", or the laser won't move

A lid or safety switch is open, or the laser is paused. Close the lid or reset the switch, or press Resume.

LightBurn can't connect

Only one program controls the laser at a time: if a job is running from Kerf or the web page, wait for it to finish. Check the port: 23, or 2323 if the installer moved it. If ser2net is still running on the Pi, stop it and run the installer again:

sudo systemctl disable --now ser2net
The camera isn't showing

The camera needs a Pi with the 64-bit OS (or a Linux PC) and a USB webcam. To check the camera on its own, this takes one picture without touching the laser. Close the camera view in Kerf and on the bridge page first: a camera can only be read by one program at a time.

kerf-bridge -config /etc/kerf-bridge/config.json -snapshot test.jpg

If it says the camera is busy or not found, unplug it and plug it in again, then try once more.

I restarted the bridge and the laser has lost its place

Restarting the bridge resets the laser's controller, so home the laser again before the next job.

Stay with the laser

Never leave a laser unattended. The bridge makes jobs reliable, not safe: stay with the laser, keep a fire extinguisher nearby, and use the STOP button or the laser's own emergency stop if anything looks wrong.