ESP32 OTA & Firmware Repository

Base URL: http://192.168.0.87:8080

When to Use OTA (vs Serial Flashing)

Use OTA when:

• Device already runs firmware with an OTA HTTP endpoint
• Device is on the WiFi network (connected to workbench's AP or same LAN)
• You want to update firmware without blocking the serial port
• You're doing iterative development (build → upload → trigger → monitor cycle)

Do NOT use OTA when:

• Device is blank/bricked — use serial flashing (see esp32-workbench-serial-flashing)
• Device firmware has no OTA support — use serial flashing
• Device has no WiFi connectivity — use serial flashing
• You need to flash a bootloader or partition table — only esptool can do this

Endpoints

End-to-End OTA Workflow

Step 1: Upload firmware to workbench

bash
1curl -X POST http://192.168.0.87:8080/api/firmware/upload \
2  -F "project=my-project" \
3  -F "file=@build/firmware.bin"

Response: {"ok": true, "project": "my-project", "filename": "firmware.bin", "size": 456789}

Step 2: Verify upload

bash
1curl -s http://192.168.0.87:8080/api/firmware/list | jq .

Step 3: Ensure device is on the network

The device must be able to reach http://192.168.0.87:8080. Use enter-portal to provision if needed (see esp32-workbench-wifi).

Step 4: Clear UDP log buffer (for clean monitoring)

bash
1curl -X DELETE http://192.168.0.87:8080/api/udplog

Step 5: Trigger OTA on the ESP32 via HTTP relay

bash
1OTA_BODY=$(echo -n '{"url":"http://192.168.0.87:8080/firmware/my-project/firmware.bin"}' | base64)
2
3curl -X POST http://192.168.0.87:8080/api/wifi/http \
4  -H 'Content-Type: application/json' \
5  -d "{\"method\": \"POST\", \"url\": \"http://192.168.4.2/ota\", \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": \"$OTA_BODY\", \"timeout\": 30}"

Step 6: Monitor OTA progress

bash
1# Via UDP logs (preferred — non-blocking)
2curl "http://192.168.0.87:8080/api/udplog?limit=50"
3
4# Or via serial monitor (see esp32-workbench-logging)
5curl -X POST http://192.168.0.87:8080/api/serial/monitor \
6  -H 'Content-Type: application/json' \
7  -d '{"slot": "slot-1", "pattern": "OTA.*complete", "timeout": 60}'

Managing Firmware Files

bash
1# List all uploaded firmware
2curl http://192.168.0.87:8080/api/firmware/list
3
4# Delete a firmware file
5curl -X DELETE http://192.168.0.87:8080/api/firmware/delete \
6  -H 'Content-Type: application/json' \
7  -d '{"project": "my-project", "filename": "firmware.bin"}'
8
9# The download URL for ESP32 to fetch:
10# http://192.168.0.87:8080/firmware/<project>/<filename>

Troubleshooting