Start with Diagnose on the device. It separates the three possible faults immediately.
| Result | What it means | Where to look |
|---|---|---|
| Hub is offline | The agent is not connected | The box and its network |
| Device not answering | Agent is up, hardware did not reply | Cable, power, path, driver |
| Device answering | The link is fine | The job or the app sending it |
The hub will not come online
Never connected — the agent has never reached the server. In order:
1. Confirm the hub name in the config matches the record exactly.
2. Confirm the API key matches. If unsure, regenerate and reconfigure — you cannot read the original back.
3. Confirm the organization is right.
4. Confirm outbound WebSocket on 443 is allowed. Guest and captive-portal networks commonly block it.
Offline after working — the box slept, lost power, or lost its network. Check the service is running: journalctl -u appmint-hub -f on Linux. The agent reconnects on its own with backoff, so if it is running and the network is back, wait a few seconds before intervening.
Nothing prints
Work down this list:
1. Is the hub online? If not, that is the problem.
2. Is the driver set? Missing driver fails with "No driver set!" — set epson or star.
3. For a CUPS printer, is the queue enabled? CUPS disables a queue after any error, and jobs then pile up silently. This is the single most common cause of "it just stopped." Re-enable the queue.
4. Is the path still right? USB paths can change across reboots and re-plugs. Re-scan the hub and compare.
5. Is it reported? A device configured but not in the hub's endpoint list is unplugged or powered off.
Output is garbled or wrapped wrongly
Width. Default is 48 characters for 80 mm paper; a 58 mm roll needs a smaller value. Set width explicitly.
The drawer will not open
The drawer opens through its printer. If the printer is unreachable the drawer cannot fire. Fix the printer first — they fail together.
Scanning does not work
Nothing arrives at all. Check the read mode matches the platform:
- macOS or Windows — HID-raw is not available. The scanner must be switched into USB-COM / CDC mode with the vendor's configuration barcode, and configured with a
/dev/cu.*path. - Linux —
/dev/hidraw*works, but needs read permission. Run as root, add the service user to theinputgroup, or add a udev rule.
It types into other applications instead. The scanner is still in HID-keyboard mode. Switch it to USB-COM.
Scans arrive doubled or truncated. Terminator mismatch. Most Bluetooth scanners are CR-terminated or unterminated; confirm the scanner's suffix setting.
Card taps do nothing
Reading uses the same path as a scanner, so the same checks apply — mode and permissions.
Write or erase returns an error. Those need PC/SC and the optional native module, and only work on ACR122U-class readers. Reading is unaffected. If you only need staff sign-in and card registration, you do not need write at all.
A device disappeared from the list
The peripheral list is captured when the agent connects. Anything plugged in afterwards will not appear until you press rescan in Diagnose, or the agent reconnects.
Reading the peripheral statuses
| Status | Meaning | Usual cause |
|---|---|---|
Configured as x · not answering | Connected, not responding | Powered off, or a bad cable |
| device not detected | Configured, agent cannot see it | Unplugged, or its path changed on reboot |
| (no status) | Discovered, not yet connected | Press Connect to use it |
The hub is locked out after a key change
Regenerating the API key invalidates the old one immediately. Reconfigure the box:
sudo hub-agent setupand paste the new key.
Changes are not sticking
"Hub did not acknowledge the change" means the record was saved but the agent did not confirm — it went offline mid-edit. Bring the hub back online and save again.
Everything works except from one device
If one tablet cannot print but others can, the fault is not the hub. Check that the app is targeting the right endpoint name, and that the tablet has network access to the platform.
Getting help
Have these ready:
- The hub name and its state
- What Diagnose returned
- The device kind, path and config
- Agent logs —
journalctl -u appmint-hub -fon Linux