iPhone joins home Wi-Fi instead of the ESP32 Agent hotspot

By default the board opens its own Wi-Fi hotspot, and the iPhone joins it. If the hotspot is missing and the iPhone stays on your home Wi-Fi, the board is probably in station mode. Switch it back with one of the steps below.

Two Wi-Fi modes

Mode	What the board does	What the iPhone joins
Hotspot (default)	Opens its own network, named ESP32Agent-…, with its own password. It has no internet.	The board’s hotspot. The internet keeps working over cellular data.
Station	Joins an existing Wi-Fi network instead, such as your home or office Wi-Fi.	That same network. There is no ESP32Agent-… hotspot.

Station mode is for development, for example with the developer harness. Normal use needs hotspot mode.

The board remembers its mode. Station mode stays on after the board restarts and after in-app firmware updates, until you switch it back.

How to tell which mode it is in

• Hotspot: ESP32Agent-… shows up in Settings → Wi-Fi on the iPhone, and 0 netinfo over USB serial answers with "mode":"ap".
• Station: no ESP32Agent-… network appears. Over USB serial, 0 netinfo answers with "mode":"sta" (see the FAQ).

Switch back to the hotspot

Use any one of these.

From a clone of the repository, over Bluetooth. Quit the app on the iPhone so the computer can reach the board, then run:

uv run harness/board.py net ap

A computer that hasn’t paired with the board before can pair only in the 3 minutes after the board powers on, so replug it first.

Over USB serial. Unplug the board from the iPhone and plug it into a computer. Open its serial port at 115200 baud and send one line:

0 net {"mode":"ap"}

The board answers 0 ok and opens its hotspot again. If no serial port shows up, use the next option.

Fresh install from the web installer. Install the firmware again from handsy.tech/install. If the board doesn’t appear, hold BOOT while plugging it in. This erases all board settings: Wi-Fi mode, hotspot password, and Bluetooth pairing. Afterwards, forget the old ESP32 Agent device in the iPhone’s Settings → Bluetooth and pair again in the app. See Update ESP32 Agent firmware.

Then plug the board back into the iPhone, join ESP32Agent-…, and start Screen Mirroring again.

The iPhone keeps going back to home Wi-Fi

In hotspot mode, iOS may still switch back to a network it knows. Before joining the board’s hotspot:

• Turn off Personal Hotspot on the iPhone.
• Join ESP32Agent-… in Settings → Wi-Fi, or use Settings → Board → Join the Board’s Wi-Fi in the app.
• If the phone keeps hopping back, turn off Auto-Join for your home network while you run tasks.
• Keep the board close to the phone. Its hotspot uses low transmit power.

Video is slow: Local Network permission

The app gets the picture from the board over Wi-Fi. For that, iOS needs to allow Local Network access for ESP32 Agent. iOS asks once, the first time it’s needed.

If you tapped Don’t Allow, video falls back to Bluetooth. Tasks still run, but slower: the picture lags and animations are choppy. To turn it back on:

1. Open the iPhone’s Settings → Privacy & Security → Local Network.
2. Turn on ESP32 Agent.
3. Quit and reopen the app, then start Screen Mirroring again.

Still stuck? See the FAQ or write to [email protected].