Update ESP32 Agent firmware: Official vs TestFlight, over Wi-Fi or USB
Once the board is set up, update it from the iPhone app over Wi-Fi. Use the web installer over USB only for the first install, for a board too old for Wi-Fi updates, or to start fresh.
Two channels
Section titled “Two channels”Board firmware is released on two channels. Each one matches an app build.
| Channel | App | Installer |
|---|---|---|
| Official | The App Store app reads handsy.tech/firmware/firmware.json. |
handsy.tech/install |
| TestFlight | The TestFlight app reads handsy.tech/firmware/testflight/firmware.json. |
handsy.tech/install?build=testflight |
Each app offers updates only from its own channel. Install the board firmware from the channel that matches your app. The current versions are in the changelog.
Every release is signed. The app checks the signature and the image before it sends anything to the board.
Update from the app
Section titled “Update from the app”Open Settings → Board. The Firmware section shows the version on the board, with Check for Updates and Update Now. When an update is available, the Agent tab also shows a banner.
An update can start when:
- The board is connected to the app.
- The iPhone is on the board’s Wi-Fi. The image goes over that Wi-Fi; the internet keeps working over cellular data.
- No task or recording is running. Wait until it ends.
- The board’s firmware is new enough for Wi-Fi updates. A very old board needs one install over USB from the web installer first.
Keep the app open and the board plugged in. It takes about a minute. The board restarts at the end; start Screen Mirroring again afterwards. Your intents and settings stay as they are.
If the app needs later board firmware, it shows Board Update Required as soon as the board connects.
If an update fails
Section titled “If an update fails”- A dropped connection is retried, up to three times.
- The board keeps its current firmware until the whole new image is written and checked. A failed send leaves it unchanged.
- If the new firmware doesn’t start properly, the board goes back to the previous one by itself.
Reinstall from the web installer
Section titled “Reinstall from the web installer”A fresh install over USB from handsy.tech/install erases the board: its Bluetooth pairing, hotspot password, and settings such as station mode. Use it to start clean, or when the board can’t take a Wi-Fi update.
- Install the firmware from the channel that matches your app. If the board doesn’t show up, hold BOOT while plugging it in. See Failed to connect.
- On the iPhone, open Settings → Bluetooth, tap (i) next to the old ESP32 Agent, and choose Forget This Device.
- Plug the board into the iPhone and pair again in the app. Join the board’s hotspot with its new password.
If something goes wrong in the installer, click Download log and send it to [email protected].