Troubleshoot setup & agent runs

Work through the system in order: firmware → app → Bluetooth → hotspot → mirroring → pointer → model. A successful check at one layer does not prove the next layer is working.

The board does not appear over USB

Use a known USB data cable and check arduino-cli board list. Confirm the connection reaches the S3’s native USB port. If necessary, use the vendor’s bootloader procedure and retry the firmware script.

If the script complains about its path, move your project checkout to a path without spaces. Its compiler include flag requires this.

Xcode cannot sign the app

Verify DEVELOPMENT_TEAM and IA_BUNDLE_ID in ios/Config/Local.xcconfig, then read Xcode’s actual provisioning message.

For a free team, optional capabilities can prevent provisioning. The example config supports blank IA_ENTITLEMENTS and IA_WIDGET_ENTITLEMENTS values to build without the optional entitlement files. You then join the hotspot manually. Follow the app installation guide rather than copying another developer’s signing settings.

If a previously installed free-account build stops launching after seven days, re-sign and reinstall it from Xcode.

Bluetooth scanning or pairing times out

• Confirm the app has Bluetooth permission and the board has power.
• Keep the board near the phone and avoid shielding it with metal objects.
• Use the app’s scan/retry controls. Allow the connection check to finish.
• Check for another app or debugging tool holding a board connection; disconnect it while isolating the issue.

USB enumeration is not a Bluetooth health check. Repeated failures need logs, not an assumption that a powered board must be paired.

The phone cannot join the hotspot

Use the current SSID and password shown in your app. If automatic joining is unavailable, open Wi-Fi settings and join manually. Confirm that the phone stays on the board’s network.

The hotspot having no internet is expected. Check cellular data separately for model access. Do not substitute an unrelated Wi-Fi network and expect the board’s AirPlay receiver to remain discoverable there.

ESP32 Agent is missing from Screen Mirroring

Confirm the hotspot connection first, then reopen Control Center → Screen Mirroring. Verify board connectivity in the app. Keep the phone unlocked; locking stops mirroring.

If the receiver appears but the app receives no useful screen, report the firmware version and logs. Avoid treating a BLE pairing success as proof that the video transport is healthy.

Taps miss their targets

Enable AssistiveTouch and repeat the app’s pointer calibration without touching the screen. Use portrait orientation and start with a large target such as a Settings row.

If the pointer moves correctly but the chosen target is wrong, inspect the screenshot and model action in the run replay. That may be a perception or planning error rather than a calibration error.

The model test fails

Check the base URL, API key, exact model ID, and image support. Model-list access does not prove that a model can process images. While on the board’s hotspot, the endpoint must be reachable through cellular data.

Use model setup to separate authentication errors, missing models, rejected images, and network timeouts.

Chinese or Japanese typing does not work

Direct non-ASCII keyboard input is not supported yet. Translating the website or writing a task in Chinese or Japanese does not change the firmware’s input capability. Use an ASCII-only first task.

Report a reproducible problem

Include your board variant, iPhone and iOS version, source revision, signing setup, and the exact failed step. For model problems, include the provider and model ID, never your API key.

Export a relevant run trace or log and inspect it for personal content before attaching it. Use the upstream security policy for security reports.