# One sensor image, five hardware options

> Flash the unified WLAN Commander image, claim each device, update it over SSH, and connect it to the app.

## What “one image” means

One **factory `.img.xz` file** boots NanoPi Zero2, Raspberry Pi 4, Raspberry Pi 5, WLAN Pi Go and WLAN Pi Pro. You do not pick a board variant when you write it. On first boot the image identifies the board, or the CM4 carrier, and enables the matching boot and hardware settings. Radio features still depend on the adapter installed.

The image has A/B system partitions and a separate **Data** partition. Data grows to fill the rest of the card or eMMC on first boot, so the download is the same size for every board.

Flash a fresh copy for **each** device and claim each one separately. Do not clone a card that has already been set up: its password, SSH host keys and hostname would be duplicated.

| Hardware | Where to write the factory image | First connection and notes |
| --- | --- | --- |
| NanoPi Zero2 | Its microSD card | Ethernet and stable power. Direct USB-C setup at `198.18.42.1` was tested with Intel and Qualcomm radio builds. |
| Raspberry Pi 4, including the WLAN Pi R4 display HAT | Its microSD card | Ethernet. The original R4 HAT stays blank until you [enable it](#enable-the-original-wlan-pi-r4-display-hat). Other display HATs need separate support. |
| Raspberry Pi 5 | Its microSD card | Ethernet and a suitable power supply. The Wi-Fi card and its adapter decide radio capability. |
| WLAN Pi Pro (CM4) | The removable SD path used by the tested Pro | Ethernet/PoE or the board's supported power source. The carrier selects the Pro's display and buttons. Check your Pro's storage configuration before writing. |
| WLAN Pi Go (CM4) | Its eMMC, exposed to the computer in Go flash mode | USB-C gives both power and management; the Go has no Ethernet port. Use a stable, well-powered USB connection. |

## How to flash the factory image and claim the sensor

Flashing erases everything on the target: the current installation, captures and settings. Back up what you need, and write only to storage that belongs to the intended sensor.

1. On [Downloads](/downloads/), download the **factory** `.img.xz` and its `.sha256`. Do not use the **OTA** file: it only updates a sensor already on the unified A/B layout.
2. Check the SHA-256. On a Mac, run `shasum -a 256` on the file; on Linux, `sha256sum`. The full digest must match the published value.
3. Write the image with a tool that accepts `.img.xz`, such as Raspberry Pi Imager (custom image) or balenaEtcher. With `dd`, decompress first, for example `xz -dc FILE.img.xz | sudo dd of=/dev/DISK bs=4M conv=fsync`. Check the target by size and name before you write. A 32 GB or larger card is a practical starting point.
4. Put the card in the sensor (the Go keeps its flashed eMMC). Connect the radio, Ethernet where the board has it, and reliable power.
5. Power on and wait several minutes. The first boot expands Data and applies board settings, and may reboot once. Do not interrupt it.
6. Find the sensor. It is named `WC-<board>-<id>`, for example `WC-pi5-…`, and appears in WLAN Commander's Devices view, through mDNS as `<name>.local`, or in your router's DHCP list. Finding it does not mean it is claimed.
7. Get the **one-time setup code** in one of these ways:
    - **Direct USB** (NanoPi Zero2, WLAN Pi Go): connect the sensor's USB data port straight to a Mac or phone and open `https://198.18.42.1/`. The setup page fills the code automatically. On iPhone, WLAN Commander's **Add Discovered Device** screen offers **Set up device over USB**.
    - **Front panel:** on a supported screen, scan **Scan to set up** with a phone on the same LAN or USB link. The QR opens the sensor's page with the code filled in. If the QR will not scan, use the panel's readable code: it appears on three rows; type it without spaces or line breaks.
    - **The card:** see [Setup recovery](#setup-recovery). The code is in `WC-SETUP.TXT` on the `CONFIGFS` partition.
8. Open the sensor's HTTPS page. It uses its own certificate, so your browser may warn you. Before you accept it, compare the certificate's SHA-256 fingerprint with the **Certificate SHA-256** line in `WC-SETUP.TXT` or your installer's record.
9. On **Set up your sensor**, check the **One-time setup code**, then enter a **New password · 8 characters minimum** and **Confirm password**. Use 12 or more characters: this password also becomes the SSH password for the `wlanpi` account.
10. Select **Set password and open Commander**. The Dashboard opens, and the code and `WC-SETUP.TXT` are invalidated. There is no default password on these images.

Use `wlanpi` and the new password when you add the sensor in WLAN Commander. Treat the QR, the code and `WC-SETUP.TXT` as secrets until the sensor is claimed.


**Limits in this beta:** direct USB setup was tested on NanoPi Zero2 and WLAN Pi Go. Pro OTG cable and power behaviour is still under investigation, so use its screen or Ethernet. A fresh R4 needs its HAT profile before its screen can show the setup QR. Automatic R4 profile selection is unfinished. Every sensor uses `198.18.42.1` over USB, so connect only one sensor to a computer or phone by USB at a time.

<h3 id="setup-recovery">Setup recovery</h3>

Use this when a headless device has no supported USB setup, no working screen and no code recorded by your installer.

1. Shut the sensor down cleanly and remove the card.
2. On a computer, open the `CONFIGFS` volume and read `WC-SETUP.TXT`. It holds the **Code** and the **Certificate SHA-256**.
3. Put the card back, boot, and finish steps 8–10 above.

## How to update a sensor over SSH

Use this for a sensor already on the unified A/B layout. The WLAN Commander app offers the same signed update. An update keeps the Data partition. A sensor on an older two-partition image reports `reflash_required` and needs the factory image instead.

The sensor checks for updates every 6 hours and downloads a newer image by itself. It **never installs on its own**: you start the install.

1. Stop captures, scans and Kismet. Disconnect the WLAN Commander app's live session; your SSH session does not count. Keep the sensor on stable power.
2. Connect: `ssh wlanpi@DEVICE_ADDRESS`.
3. Check what is offered:
   ```sh
   sudo wc-update --json check
   ```
   `state` is `up_to_date`, `update_available`, or `downloaded` if the background download already finished.
4. If it is not downloaded yet: `sudo wc-update --json download`.
5. Verify and stage the image into the inactive slot:
   ```sh
   sudo wc-update --json stage
   ```
   This checks the SHA-256 and signature, refuses an older version, writes the inactive slot and reads its version back. It ends in `ready`.
6. Preview the safety checks, then install:
   ```sh
   sudo wc-update --json --dry-run install
   sudo wc-update --json install
   ```
   The checks look for running captures or scans, an open app session, power, and the staged image's hash and signature. All failures are listed at once; fix them and run it again. A successful install reboots into the new slot as a **trial**.
7. Reconnect after a few minutes and run `sudo wc-update --json status`. `committed` means the update is done.

You do not run `confirm` yourself. On the trial boot, the sensor checks that its core service answers, its radios match and the board is still identified. If they pass, it commits the new slot. If they fail, it records `failed` and the next boot returns to the previous slot. An early boot failure can need a power cycle, so keep physical access during beta updates. `sudo boot-info --json` shows which slot is active.

What you added yourself is carried into the new slot: packages you installed, edits under `/etc`, services you enabled and accounts you created. The check lists them first, and the app shows the same list before it uploads. If one of your `/etc` edits clashes with a new default, your file is kept and the new default is saved beside it as `.wc-new`. If something cannot be carried, the update holds and asks first. Data keeps device identity, owner settings, display calibration and Bluetooth bonds.

## Enable the original WLAN Pi R4 display HAT

The image leaves the Pi 4 display pins off until you select the original R4 HAT, so a blank display during first setup is expected. This setting is only for a Raspberry Pi 4 with that HAT.

After claiming the device, connect by SSH as `wlanpi` with your new password:

```sh
ssh wlanpi@DEVICE_ADDRESS
sudo install -d /data/settings
printf '%s\n' 'waveshare-1.44-st7735' | sudo tee /data/settings/panel
sudo reboot
```

When it returns, check that the Commander menu appears and that the joystick, centre press and all three side buttons work. The setting lives on Data, so it survives signed updates. A fresh factory flash needs it again.

## Check the device before capturing

In the device details, confirm the board, image version, radio interfaces, storage and health. Pick a known local channel for a first scan. A card's advertised band or Wi-Fi generation does not prove every band, width or capture mode works on that board; check the release's verified-hardware notes.

For long captures, watch **Temperatures** and, where supported, **Power health**. If the temperature keeps climbing or the app reports undervoltage, stop and check cooling, cable and power. A cleared voltage alarm does not erase a dip recorded earlier in the same boot. An idle Qualcomm radio may show its temperature as unavailable; that is not zero.

The image controls a Pi 5 fan on the dedicated **FAN** socket. It spins up briefly at start, can stop when the CPU is cool, and speeds up at 50, 60, 67.5 and 75°C, with hysteresis. The PWM value is the speed requested; no fan RPM is measured. Generic GPIO fans need their own configuration.

## Experimental Qualcomm features

- **Spectrum (Pi 5 with WCN7850):** 64 FFT bins of **relative, uncalibrated magnitude, not dBm**. One card captures one tuned channel at a time.
- **Two-link station advertisement (STR work):** included and off by default. Two associated links carrying traffic do not prove simultaneous transmit/receive or a throughput gain.
- **802.11mc FTM diagnostic (Pi 5 with WCN7850):** opt-in, single peer, tested only against a 5 GHz, 80 MHz responder. Timing and antenna delay are uncalibrated. It is not 802.11az support.

Normal scanning and capture need none of these.

## If it doesn't work

| What you see | What to do |
| --- | --- |
| The sensor never appears | Check the Ethernet link, power and that the USB cable carries data. A lit LED alone does not mean SSH and the website started. Keep the card for boot-log inspection. See [troubleshooting](/guides/troubleshooting/). |
| The USB setup code did not fill | Use a direct, data-capable cable to one sensor only, or read `WC-SETUP.TXT` ([Setup recovery](#setup-recovery)). |
| `wc-update` says `reflash_required` | The sensor is not on the A/B layout. Flash the factory image. |
| `install` is refused | Read the listed checks. Stop the named capture or scan, close the app session, connect power, then run it again. |
| `status` shows `failed` after a trial | The previous slot boots next. Reconnect and run `sudo wc-update --json status` for the reason. |

## WLAN Pi software and community credit

This independent image includes software from the [WLAN Pi community](https://github.com/WLAN-Pi), including [wlanpi-core](https://github.com/WLAN-Pi/wlanpi-core), the [front-panel menu system](https://github.com/WLAN-Pi/wlanpi-fpms) and selected WLAN Pi tools. Their authors stay credited in the image's notices and on the front panel. WLAN Commander integrates and adapts these components; it did not create them.

WLAN Commander supports installation, first-use setup, updates and the integrations a release lists as tested. Support for the inherited WLAN Pi menus and scripts is limited. If one behaves differently from the upstream WLAN Pi image, [report the board, image version, menu action and result](/support/). The [credits and source references](/notices/) list the projects behind the image.

## Related

[Sensor console](/guides/sensor-console/) · [Touchscreen and Bluetooth input](/guides/touch-console/) · [APIs, MQTT, PKI and MCP](/developers/) · [ESP32-C5 updater](/guides/esp32-sensor-updater/) · [Troubleshooting](/guides/troubleshooting/)