OTA Management

The OTA Manager component provides 3 tools for creating OTA update packages, deploying them to devices over HTTP, and rolling back to previous firmware versions. These tools work with any ESP device that has an OTA-capable partition layout (see Partition Management).

esp_ota_package_create

Create a self-contained OTA update package as a ZIP archive. The package contains the firmware binary and a JSON manifest with version, checksum, and timestamp metadata.

Parameters

Name	Type	Default	Description
`firmware_path`	`str`	(required)	Path to the firmware binary (`.bin`) to package.
`version`	`str`	(required)	Version string for the update (e.g., `"1.2.0"`, `"2026.02.23"`).
`output_path`	`str`	(required)	Path for the output ZIP package.

Package Contents

File	Description
`firmware.bin`	The raw application binary.
`manifest.json`	Metadata: version, filename, size, SHA-256 hash, creation timestamp.

Example

result = await client.call_tool("esp_ota_package_create", {
    "firmware_path": "/build/app.bin",
    "version": "2026.02.23",
    "output_path": "/releases/ota-2026.02.23.zip"
})

Return Value

{
  "success": true,
  "output_path": "/releases/ota-2026.02.23.zip",
  "package_size_bytes": 312456,
  "manifest": {
    "version": "2026.02.23",
    "firmware_name": "app.bin",
    "firmware_size": 524288,
    "firmware_sha256": "a1b2c3d4e5f6...64 hex chars...",
    "created_at": "2026-02-23T12:00:00Z"
  }
}

esp_ota_deploy

Deploy an OTA update package to a device over HTTP. Extracts firmware.bin from the ZIP package and POSTs it to the device’s OTA endpoint.

The target device must be running an HTTP OTA server — for example, the esp_https_ota component from ESP-IDF or a custom HTTP handler.

Parameters

Name	Type	Default	Description
`package_path`	`str`	(required)	Path to the OTA ZIP package created by `esp_ota_package_create`.
`target_url`	`str`	(required)	Device OTA endpoint URL (e.g., `http://192.168.1.100/ota/update`).

Example

result = await client.call_tool("esp_ota_deploy", {
    "package_path": "/releases/ota-2026.02.23.zip",
    "target_url": "http://192.168.1.100/ota/update"
})

Return Value

On success (HTTP 2xx):

{
  "success": true,
  "target_url": "http://192.168.1.100/ota/update",
  "http_status": "200",
  "firmware_size_bytes": 524288,
  "version": "2026.02.23"
}

On HTTP error:

{
  "success": false,
  "target_url": "http://192.168.1.100/ota/update",
  "http_status": "500",
  "firmware_size_bytes": 524288,
  "error": "Device returned HTTP 500"
}

esp_ota_rollback

Roll back to the previous firmware version by erasing the otadata partition. When otadata is erased (all 0xFF), the bootloader falls back to the factory app or ota_0 slot on the next boot.

The tool reads the device’s partition table to locate the otadata partition automatically, then erases that region.

Parameters

Name	Type	Default	Description
`port`	`str \| None`	`None`	Serial port or `socket://` URI. Required.

Example

result = await client.call_tool("esp_ota_rollback", {
    "port": "/dev/ttyUSB0"
})

Return Value

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "otadata_offset": "0xf000",
  "otadata_size": "0x2000",
  "message": "OTA data partition erased. On next boot, the device will fall back to the factory app or ota_0 slot."
}

If the device does not have an OTA partition layout:

{
  "success": false,
  "error": "No otadata partition found -- device may not use OTA layout",
  "port": "/dev/ttyUSB0"
}