Skip to content

First boot

With the image flashed, connect everything and power it on.

Connect

  1. Insert the flashed microSD card into the Pi.
  2. Connect the screen (HDMI, or the DSI Touch Display on Pi 4/5).
  3. Connect the OTG port (see Hardware for which port that is on your board) to your host machine with a data-capable cable. This single cable both powers the device (Pi Zero 2 W) or contributes to powering it (Pi 4/5 — see the power notes) and carries the control link.

You do not need a keyboard, mouse, or any other peripheral. There is no setup wizard, no network to join, no account to create.

What happens on power-up

sequenceDiagram
    participant Board as Device (Raspberry Pi)
    participant Screen
    participant Host

    Board->>Board: Firmware + kernel boot
    Board->>Screen: Boot splash (if enabled)
    Board->>Board: Read-only rootfs mounted, data partition mounted/grown
    Board->>Board: displayd starts
    Board->>Board: USB gadget enumerates (NCM network + serial)
    Board->>Screen: Waiting page (splash + status)
    Host->>Board: Detects new network adapter + serial port
    Host->>Board: GET /api/v1/device (or NDJSON hello)
    Host->>Board: Navigate to URL / activate content bundle
    Board->>Screen: Displays host-driven content

Roughly, in order:

  1. Boot splash. A branded image appears on screen almost immediately after power-up (well under 5 seconds on any supported board) — this comes straight from the OS image before the browser or any application logic is running.
  2. System comes up. The read-only system partition and the writable data partition mount; on a brand-new card, the data partition grows to fill the rest of the card the first time (a one-time step).
  3. displayd starts and brings up the USB composite gadget — this is the point your host machine will see a new network adapter and a new serial (COM) port appear.
  4. Waiting page. The kiosk browser starts fullscreen and shows the waiting page: the same splash image plus a small, discreet status corner (hostname/IP information) — this is the device's steady state until a host takes it over. On the Pi Zero 2 W this whole sequence should complete in under 30 seconds; Pi 4/5 are faster.
  5. Host connects. Once your host machine recognizes the new adapter/serial port (see Host setup (Windows) or Host setup (Linux)), it can query the device, push configuration or content, and navigate the display away from the waiting page.

If you unplug the device at any point, it simply disappears from the host — there is nothing to "disconnect" gracefully. Plugging it back in resumes exactly where it left off (same configuration, same last-displayed content), since all of that state lives on the device's own data partition, not on the host.

What you should see

  • A screen showing the boot splash, then the waiting page (splash image with a small status readout) within the timing above.
  • On your host: a new network adapter and a new serial/COM port, with no driver installation prompt on Windows, Linux or macOS.

If either of those doesn't happen, see Troubleshooting.

Next steps