You mostly do not add devices by hand. Plug hardware into the hub box and the agent reports it; you then connect the ones you want to use.
The flow
1. Plug the hardware into the hub box.
2. Open Operations → Hubs → Diagnose on that hub.
3. Look at Peripherals. Everything the agent can see is listed, each with a type badge, a name and a device path.
4. Press Connect on the ones you want. That creates the device record and makes it usable from tablets and the POS.
5. Press Disconnect to stop using one. The hardware stays plugged in; it just stops being a configured device.
If you plug something in while the panel is open, use rescan — the peripheral list is captured when the agent connects, so new hardware does not appear until it re-scans.
Reading the peripheral list
Each row shows a status, and the three you will see are:
| Status | Meaning |
|---|---|
| (nothing) | Discovered and available — press Connect to use it |
Configured as x · not answering | You connected it, but it is not responding now |
| device not detected | Configured previously, and the agent cannot see it at all |
Not answering usually means powered off or a bad cable. Not detected usually means unplugged, or its path changed across a reboot.
Direct versus remote
Some devices do not need a hub at all. When adding a device manually you choose:
| Connection | Meaning | Examples |
|---|---|---|
| Remote (via hub) | The on-site hub reaches it | USB thermal printer, USB scanner, cash drawer — anything on a tablet-based POS |
| Direct | The server reaches it without a hub | Network printer, SMS pager, Stripe Terminal, a PC POS running the cloud SDK |
Use Add direct device for the second kind. Anything the server can reach on its own does not need a box in the venue.
Adding a device by hand
When you do add one manually, the fields are:
| Field | Notes |
|---|---|
| Name (ID) | URL-safe identifier, lowercase, no spaces. This is what the API references |
| Display name | Human label — "Kitchen line 1" |
| Kind | printer, scanner, drawer and so on |
| Service point | Optional. Scopes the device to a specific table or station |
| Capabilities | Pick all that apply: page, print, drawer, charge, weigh, display, kds |
| Connection | Direct, or Remote via a named hub |
| Endpoint name on hub | The USB path or local label the agent uses to find it — /dev/usb/lp0 |
| Adapter config | JSON for extra settings — printer encoding, Twilio fromNumber and similar |
Adapter config must be valid JSON or the form rejects it.
A printer set to bar-1 is reached by that station rather than by the whole venue. Leave it blank for shared hardware like a front-counter printer.
What each device type needs
Receipt and kitchen printers
Three transports:
| Transport | Path format | Notes |
|---|---|---|
| Network | tcp://host:port | Most reliable for a fixed install. Give it a static IP or DHCP reservation |
| Raw USB | /dev/usb/lp0 | Linux. The agent writes ESC/POS to the device file |
| CUPS queue | a queue name | macOS and Linux. The agent pipes to lp -d QUEUE -o raw |
Set driver to epson or star — without one, printing fails with "No driver set!". Width is characters per line, default 48 for 80 mm paper; set it explicitly for 58 mm rolls or text wraps wrongly.
A print job is a list of parts, so the same job renders anywhere: text with optional bold and size, cut, feed, barcode, image. Ticket types are receipt, kitchen, bar and label.
On any error CUPS flips the queue off and jobs pile up silently — printing looks fine and nothing comes out. If a CUPS printer stops, re-enable the queue before looking anywhere else.
Barcode and QR scanners
The read mode comes from the device path, and it decides what you must configure on the scanner itself.
HID-raw — /dev/hidraw*. Linux only. The scanner stays in default HID-keyboard mode. Needs read permission: root, the input group, or a udev rule.
CDC-serial — /dev/cu.usbmodem*, /dev/cu.usbserial*, /dev/ttyUSB*. The supported path on macOS and Windows, which do not expose HID devices as readable files.
It behaves as a keyboard and types into whatever has focus. Switch it into USB-COM / CDC mode with the vendor's configuration barcode, then use its /dev/cu.* path.
Scans arrive as events pushed up to the server, not replies to a command, and are fanned out to whichever screens subscribed.
NFC and RFID card readers
Reading a tap works exactly like a scanner — readers in keyboard-wedge or USB-COM mode type the card's hardware UID and Enter. This is all you need for staff sign-in and card registration.
Writing or erasing needs PC/SC and an ACR122U-class reader plus an optional native module. The agent runs without it; write and erase then return a clear error rather than crashing.
The card carries only an employee id, not a credential. Whether a PIN is also required is an organization setting.
Cash drawers
A drawer has no connection of its own — it plugs into a printer with an RJ11 cable and is opened by a kick command through that printer. When adding one you pick which printer it plugs into. If the printer is unreachable the drawer will not open; they fail together.
Cash-drawer attachment is also available under Advanced in the Diagnose panel, alongside manual path entry and network printers.
Displays, KDS, scales and terminals
Capabilities exist for display, kds, weigh and charge. Configure them as devices the same way, or as direct devices where the server reaches them itself — a Stripe Terminal being the common case.
Naming
Name devices after the job, not the hardware — kitchen, front-counter, bar-1. Commands route by name first and fall back to capability, so a good name survives the printer being replaced.