Host setup (Linux)¶

This guide assumes a modern Linux distribution with NetworkManager (the common case on current desktop and many server distributions). It assumes you've already flashed the image and completed first boot with the device connected to this machine.

1. Recognition¶

Plug the device into a USB port with a data-capable cable. No driver installation or extra kernel modules are required — the inbox cdc_ncm and cdc_acm drivers handle it.

Check dmesg (or journalctl -k -f while plugging in) for lines showing a CDC-NCM network device and a CDC-ACM serial device being bound, and confirm with:

lsusb

which should list the device (manufacturer MyCustomerDisplay).

ip link

should show a new interface — typically named usb0 or a predictable enx<mac> name, depending on your distribution's naming policy. Its MAC address is derived deterministically from the device's own serial number, so it stays the same across replugs.

The serial function appears as:

/dev/ttyACM0        # or ttyACM1, etc. — the first free node
/dev/serial/by-id/... # stable path, survives renumbering

Prefer the /dev/serial/by-id/... path in scripts/configuration — it doesn't shift if you plug in devices in a different order.

2. Reaching the device¶

NetworkManager (or dhclient if you're managing interfaces manually) picks up an address automatically from the device's own DHCP server on the link (10.99.0.100–10.99.0.199). The device itself is always at 10.99.0.1.

Confirm connectivity:

curl http://10.99.0.1/api/v1/device

You should get back a small JSON document describing the device. If this hangs or fails, see Troubleshooting.

If you need the device to reach a remote URL (rather than only displaying locally uploaded content), the device has no general-purpose network route of its own — by design, it only talks to the host over USB. The recommended way to give it internet access is the proxy path below.

NetworkManager can share a connection with nmcli:

nmcli connection modify <device-connection> ipv4.method shared

but this has the same problem as Windows' ICS: "shared" mode starts NetworkManager's own DHCP server on the interface, which conflicts with the device's own DHCP server on the same link. Address assignment becomes unreliable and the device's fixed 10.99.0.1 address is no longer guaranteed. Use the proxy path instead.

For headless hosts without NetworkManager, the manual equivalent (routing, not recommended for the same reason — shown here only for completeness/troubleshooting) would be an nftables/iptables masquerade rule on the interface facing the internet; but note the device itself has no default route configured in v1 by design — it will not use a routed path even if one is available on the host side. Traffic from the displayed browser only ever goes out through the proxy you configure in step 4.

4. Proxy path¶

Run any HTTP/HTTPS proxy on the host, listening on an address reachable from the 10.99.0.x subnet, then point the device's browser at it through the API:

# example: a minimal proxy listening on all interfaces, port 3128
tinyproxy -c /etc/tinyproxy/tinyproxy.conf   # or any HTTP proxy you prefer

curl -X PATCH http://10.99.0.1/api/v1/config \
  -H 'Content-Type: application/json' \
  -d '{"proxy": {"url": "http://10.99.0.x:3128"}}'

Use your host's own address on the 10.99.0.x link, not 10.99.0.1 (the device itself). If the proxy intercepts HTTPS with its own CA, either set "insecure": true for local testing only, or upload its CA certificate with POST /api/v1/files/certificates/ca.

5. Serial¶

The serial port carries the same API as NDJSON. It can be used directly with any serial tool, or (optional, recommended for non-root applications) given a stable path and permissions via a udev rule, e.g. matching on the device's vendor/product IDs and tagging the node with a dedicated group so your POS software doesn't need root to open it. On open, the device sends a hello line (JSON), then every line is an NDJSON API request/response — see the Serial (NDJSON) reference. Sending the line {"type":"shell"} switches to a recovery root shell; exit returns to NDJSON mode.

6. Multiple devices¶

Each device gets its own network interface and its own /dev/ttyACM* node — nothing is shared between them. To talk to a specific one over HTTP, bind to its interface:

curl --interface usb0 http://10.99.0.1/api/v1/device

and identify serial ports by their stable /dev/serial/by-id/... path (which encodes the device's serial number) rather than the renumbering /dev/ttyACM* name. If you're using the Go client library, discovery and this matching are handled for you — see the Client library guide.