Skip to content

Host setup (Windows)

This guide covers Windows 11 and Windows 10 (build 1903 and later). 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 is required — Windows' inbox drivers bind automatically:

  • Device Manager → Network adapters: a new adapter appears (bound by the inbox UsbNcm class driver).
  • Device Manager → Ports (COM & LPT): a new USB Serial Device (COMx) appears (bound by the inbox usbser.sys).

Both should appear within a few seconds of plugging in, with no "Installing device driver software" prompt and no unknown/exclamation-mark entries in Device Manager.

Only a network adapter, no COM port (or vice versa)?

That usually means the cable is charge-only (see Hardware) or the device hasn't finished booting yet — give it the full boot time described in First boot before troubleting further. See Troubleshooting for the full symptom table.

2. Reaching the device

The new network adapter gets an IPv4 address by DHCP from the device itself (the device runs its own DHCP server on the link, handing out addresses in 10.99.0.100–10.99.0.199). The device's own address is always 10.99.0.1.

Confirm connectivity by opening this URL in a browser:

http://10.99.0.1/api/v1/device

You should get a small JSON document back describing the device (serial number, model, firmware version, capabilities). If this times out, see Troubleshooting.

3. Connection sharing (Internet Connection Sharing)

If the content you want to display lives on the internet (a remote URL rather than a bundle you upload), the device itself has no general-purpose network route — by design, it only talks to your host over the USB link. The recommended way to give it internet access is the proxy path below, not Windows' Internet Connection Sharing (ICS).

Why ICS is not recommended here: turning on ICS on the device's adapter forces that adapter to 192.168.137.1 and starts Windows' own DHCP server on it — which conflicts with the device's own DHCP server on the same link. Both attempt to provide DHCP, address assignment becomes unpredictable, and the device's fixed 10.99.0.1 address (which the API and every guide in this documentation depend on) is no longer guaranteed. Use the proxy path instead.

Run any HTTP/HTTPS proxy on your host machine, then point the device's browser at it through the API. This lets the device reach remote URLs through your host's existing internet connection without any routing changes on either side.

  1. Run a local proxy on the host, listening on all interfaces (so the device, on the 10.99.0.x subnet, can reach it) — any standard HTTP proxy works for this; pick one you're comfortable running (a lightweight one you can start with a single command is easiest for testing).

  2. Point the device at it:

    PATCH http://10.99.0.1/api/v1/config
Content-Type: application/json

{"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, which is the device itself) — typically 10.99.0.100 unless another device already took that lease.

  3. If the proxy performs HTTPS interception (a corporate/dev proxy presenting its own certificate), either:

    • set "insecure": true in the same config block for quick local testing (not for production — it disables certificate validation entirely), or
    • upload the proxy's CA certificate so the device trusts it properly: POST /api/v1/files/certificates/ca with the certificate file.

5. Serial

Each device also exposes a serial port (the COM port from step 1) carrying the same API as NDJSON — useful for hosts that would rather not touch a network stack, and as a recovery channel.

  1. Open the COM port with any serial terminal (e.g. PuTTY, "Serial" connection type, baud rate is irrelevant over USB CDC-ACM).
  2. On open, the device sends a hello line — a single line of JSON confirming the link is up and identifying the device (serial number, model).
  3. Every other line is a JSON API request/response (see the Serial (NDJSON) reference) — lines must end with \n.
  4. For field debugging, sending the exact line {"type":"shell"} switches the port to an interactive root shell on the device. Type exit to return to NDJSON mode (the device sends a fresh hello).

Garbled output in the terminal?

Most terminal programs add local echo or translate line endings by default, which corrupts NDJSON framing. See Troubleshooting for the fix.

6. Multiple devices

Each device you plug in gets its own network adapter and its own COM port — they don't share anything. Identify which adapter/port belongs to which physical device by its serial number: it's shown in Device Manager (adapter/port properties → Details tab → hardware IDs) and in the hello frame / GET /api/v1/device response. If you're using the Go client library, this matching is done for you automatically — see the Client library guide.