Firmware Upload Session

Uploading an .ota file is implemented as a sequential upload session in the OTA slot.

---

GET /api/service/firmware/upload/status/

Retrieve the current upload-session status and OTA image validity.

Auth: Bearer (powerUser).

Response 200

{
  "uploadInProgress": false,
  "imageValid": true,
  "receivedBytes": 524288,
  "totalBytes": 524288,
  "percent": 100,
  "lastError": 0,
  "lastInstallState": "ready",
  "meta": {
    "fwVersion": "1.0",
    "buildTimestamp": 1785412800,
    "deviceStr": "TR-100E (48)",
    "description": "Production firmware"
  }
}

Field	Type	Description
uploadInProgress	boolean	Erase/receive/verify is in progress
imageValid	boolean	The OTA image has been fully uploaded and verified
receivedBytes	number	Number of confirmed bytes
totalBytes	number	Expected image size
percent	number	Progress as a percentage
lastError	number	Error code (0 = none)
lastInstallState	string	Most recent installation state: "idle", "ready", "running", "failed", "unknown"
meta	object	Metadata of the verified image; present only when imageValid: true
meta.fwVersion	string	Firmware version from the OTA image, up to 15 ASCII characters (for example, 1.0 or 1.2.3-rc4)
meta.buildTimestamp	number	Build Unix timestamp
meta.deviceStr	string	Target hardware tag; TR-100E (48) for this device
meta.description	string	Image description

---

POST /api/service/firmware/upload/begin/

Open an upload session, set the image size, and prepare the OTA slot.

Auth: Bearer (powerUser).

Request

{
  "size": 524288
}

Field	Type	Required	Description
size	number	yes	Integer: OTA image size in bytes (> 0 and ≤ the OTA slot size)

• Calling this endpoint again resets an incomplete session.
• If erase/verify is in progress → 503 ERROR_NOT_READY.

Response 200

{
  "acceptedOffset": 0
}

---

POST /api/service/firmware/upload/chunk/?offset=0

Write a chunk of the OTA image.

Auth: Bearer (powerUser).

Request

• Content-Type: application/octet-stream
• Query parameter offset: chunk offset within the complete image.
• Body: raw chunk bytes (maximum 1024 bytes).

Parameter	Type	Required	Description
offset	number	yes	Integer: non-negative offset within the complete OTA image

• offset must match the expected offset or refer to an already confirmed chunk (idempotent retry).
• Gap → 400 ERROR_INVALID_VALUE.
• Chunk > 1024 bytes → 400 ERROR_INVALID_VALUE.

Response 200

{
  "acceptedOffset": 1024
}

---

POST /api/service/firmware/upload/finish/

Complete the upload session and start validation.

Auth: Bearer (powerUser).

Request

{
  "confirm": true
}

• Incomplete image or validation failure → 400 ERROR_INVALID_VALUE.

Response 200

{
  "uploadInProgress": false,
  "imageValid": true,
  "receivedBytes": 524288,
  "totalBytes": 524288,
  "percent": 100,
  "lastError": 0,
  "lastInstallState": "ready",
  "meta": {
    "fwVersion": "1.0",
    "buildTimestamp": 1785412800,
    "deviceStr": "TR-100E (48)",
    "description": "Production firmware"
  }
}

---

POST /api/service/firmware/upload/discard/

Delete the staged OTA image and reset the upload session.

Auth: Bearer (powerUser).

Request

{
  "confirm": true
}

An empty or syntactically invalid JSON body → 400 ERROR_API_PARSING. A missing confirm, a non-boolean value, or false → 400 ERROR_INVALID_ARGUMENT.

Response 200

Returns the complete status in the same format as GET /api/service/firmware/upload/status/.