OTA Updates

ESP-Claw supports over-the-air (OTA) firmware updates over Wi-Fi. This means you can update your device remotely without physically connecting a USB cable — essential for devices mounted in hard-to-reach locations or deployed at scale.

How OTA Works

The ESP32’s flash is divided into two application partitions: ota_0 and ota_1. The currently running firmware occupies one partition, and the new firmware is written to the other. After a successful update, the bootloader switches to the new partition on the next reboot.

Flash Layout:
┌──────────────┐ 0x000000
│  Bootloader  │
├──────────────┤ 0x008000
│  Partition   │
│  Table       │
├──────────────┤ 0x010000
│  ota_0       │ ← Currently running firmware
│  (App)       │
├──────────────┤ 0x190000
│  ota_1       │ ← New firmware written here during OTA
│  (App)       │
├──────────────┤ 0x310000
│  SPIFFS      │ ← SOUL.md, config, memory files
│  (Data)      │
└──────────────┘

This dual-partition scheme provides rollback protection: if the new firmware fails to boot, the bootloader automatically reverts to the previous working version.

Checking for Updates

ESP-Claw can check for updates in two ways:

Automatic Check

By default, the device checks for new releases every 24 hours by querying the GitHub Releases API. This check sends only the current firmware version and chip type — no personal data.

You can adjust the interval or disable automatic checks in the configuration:

{
  "ota": {
    "auto_check": true,
    "check_interval_hours": 24,
    "channel": "stable"
  }
}

Set channel to "beta" to receive pre-release updates.

Manual Check

Trigger an update check via your communication channel:

• Telegram: Send “check for updates” to your bot
• MQTT: Publish to espclaw/command with payload {"action": "ota_check"}
• Serial: Send ota_check command

The AI agent will respond with the current version, available version, and changelog.

Performing an Update

When a new version is available, you can update through several methods:

Via Chat Command

Simply tell your AI agent: “Update the firmware” or “Install the latest version.” The agent will confirm the update, download the firmware, and install it.

During the update process (typically 30-60 seconds), the device will:

1. Download the firmware binary over HTTPS
2. Verify the SHA256 checksum
3. Write to the inactive OTA partition
4. Verify the written data
5. Set the new partition as bootable
6. Reboot

The AI agent will send you a message after the reboot confirming the update was successful.

Via Web Interface

Access the device’s configuration web interface and navigate to the “Firmware” section. Click “Check for Updates” and follow the prompts.

Via Custom Server

For deployments where you don’t want devices reaching out to GitHub, you can host your own OTA server. Set the update URL in the configuration:

{
  "ota": {
    "server_url": "https://your-server.com/firmware",
    "auto_check": true
  }
}

Your server should respond with a JSON manifest listing available firmware versions and download URLs.

Rollback

If something goes wrong after an update, the device can roll back to the previous firmware version.

Automatic rollback happens if the new firmware fails to boot three consecutive times. The bootloader will revert to the last known working partition.

Manual rollback can be triggered via serial console:

# Connect via serial
idf.py -p /dev/ttyUSB0 monitor

# In the monitor, press the reset button and quickly send:
ota_rollback

Or if the device is still reachable over Wi-Fi, send “rollback firmware” to your chat bot.

Security Considerations

OTA updates are a potential attack vector. ESP-Claw includes several security measures:

HTTPS only: Firmware is downloaded over encrypted connections. Plain HTTP is not supported for OTA.

Checksum verification: Every firmware binary has a SHA256 hash that is verified before writing to flash. If the hash doesn’t match, the update is aborted.

Signed firmware (optional): For production deployments, you can enable firmware signing. The device will only accept updates signed with your private key. Enable this in menuconfig under “Security Features.”

Rollback protection: The dual-partition scheme ensures a bad update can always be reverted.

Troubleshooting

“OTA update failed: not enough space”: Your firmware binary exceeds the OTA partition size. Check the partition table — the default allows ~1.5MB per app partition. For larger builds, adjust partitions.csv.

“OTA update failed: connection timeout”: The device can’t reach the update server. Check Wi-Fi connectivity. Verify the update URL is accessible from the device’s network.

“OTA update failed: hash mismatch”: The downloaded binary is corrupted, likely due to a network error. Try again. If the issue persists, download the binary manually and flash via USB.

Device stuck in boot loop after update: Wait for the automatic rollback (3 failed boot attempts). If it doesn’t trigger, flash the previous version manually via USB using the flashing guide.