ESP32 WiFi & Provisioning

# Check current mode
curl http://workbench.local:8080/api/wifi/mode

# Switch to wifi-testing mode
curl -X POST http://workbench.local:8080/api/wifi/mode \
  -H 'Content-Type: application/json' \
  -d '{"mode": "wifi-testing"}'

# Switch to serial-interface mode (joins a WiFi network)
curl -X POST http://workbench.local:8080/api/wifi/mode \
  -H 'Content-Type: application/json' \
  -d '{"mode": "serial-interface", "ssid": "MyNetwork", "pass": "password"}'

Endpoints

WiFi AP (Access Point)

# Start AP
curl -X POST http://workbench.local:8080/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123", "channel": 6}'

# Check AP status and connected clients
curl http://workbench.local:8080/api/wifi/ap_status

# Stop AP
curl -X POST http://workbench.local:8080/api/wifi/ap_stop

AP and STA are mutually exclusive — starting one stops the other.

WiFi STA (Station)

# Join a network
curl -X POST http://workbench.local:8080/api/wifi/sta_join \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "MyNetwork", "pass": "password", "timeout": 15}'

# Disconnect
curl -X POST http://workbench.local:8080/api/wifi/sta_leave

WiFi Scan

curl http://workbench.local:8080/api/wifi/scan

WiFi On/Off Testing

To test a device's behavior when WiFi connectivity is lost and restored:

# 1. Ensure device is connected to workbench AP
curl -X POST http://workbench.local:8080/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123"}'

# 2. Stop AP — device loses WiFi
curl -X POST http://workbench.local:8080/api/wifi/ap_stop

# 3. Monitor device behavior (serial or UDP logs)
# ... wait for desired duration ...

# 4. Restart AP — device should reconnect
curl -X POST http://workbench.local:8080/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123"}'

# 5. Wait for device to reconnect
curl "http://workbench.local:8080/api/wifi/events?timeout=30"

HTTP Relay

IMPORTANT: Devices on the workbench AP (192.168.4.x) are NOT directly reachable from the development machine. Always use this relay to make HTTP requests to device endpoints (e.g. /status, /ota). The response body is base64-encoded — decode it to get the actual JSON.

# GET request to device
curl -X POST http://workbench.local:8080/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d '{"method": "GET", "url": "http://192.168.4.2/status", "timeout": 10}'

# POST with base64-encoded body
BODY=$(echo -n '{"key":"value"}' | base64)
curl -X POST http://workbench.local:8080/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d "{\"method\": \"POST\", \"url\": \"http://192.168.4.2/config\", \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": \"$BODY\", \"timeout\": 10}"

# Decode the base64 response body
curl -s -X POST http://workbench.local:8080/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d '{"method": "GET", "url": "http://192.168.4.x:8080/endpoint", "timeout": 10}' \
  | python3 -c "import json,sys,base64; r=json.load(sys.stdin); print(base64.b64decode(r['body']).decode())"

WiFi Events

Long-poll for STA_CONNECT / STA_DISCONNECT events:

curl "http://workbench.local:8080/api/wifi/events?timeout=30"

Enter-Portal (Captive Portal Provisioning)

Ensures a device is connected to the workbench AP. If the device has no WiFi credentials, the workbench provisions it via the device's captive portal.

curl -X POST http://workbench.local:8080/api/enter-portal \
  -H 'Content-Type: application/json' \
  -d '{"portal_ssid": "iOS-Keyboard-Setup", "ssid": "TestAP", "password": "testpass123"}'

Procedure:

1. Starts workbench AP (using ssid/password) if not already running
2. Waits for the device to connect (it may already have credentials)
3. If device doesn't connect, workbench joins the device's captive portal SoftAP (portal_ssid)
4. Follows the auto-redirect to the portal page
5. Parses the HTML form and fills in the workbench AP credentials
6. Submits the form
7. Disconnects from the device's SoftAP
8. Waits for the device to reboot and connect to the workbench AP

All three values must come from the project FSD — never guess them.

Monitor progress via GET /api/log.

Common Workflows

1. Ensure device is connected to workbench AP:

   • POST /api/enter-portal with all three values
   • GET /api/wifi/ap_status — verify device appears as connected client

2. Test device WiFi connectivity:

   • POST /api/enter-portal — ensure device is on workbench AP
   • POST /api/wifi/http — relay HTTP to device's IP to verify it responds

3. Test WiFi disconnect/reconnect behavior:

   • POST /api/wifi/ap_stop — device loses WiFi
   • Monitor device via serial (see workbench-logging)
   • POST /api/wifi/ap_start — device should reconnect
   • GET /api/wifi/events — confirm reconnection

Troubleshooting