Upgrade File Upload

Uploading upgrade files to the server.

ti_upgrade

Upload an upgrade file.

The file is uploaded by the SDK internally in a chunked stream. Returning success only means the server has fully received the file and started parsing it; the final parsing result is obtained through the upgradeStatus event.

  • client: Client handle.
  • key: Upgrade target key; currently supports TI_UPGRADE_TARGET_SYSTEM.
  • file_path: Upgrade file path (UTF-8 encoded).
  • Returns: TI_OK — upload complete; the server has received the file and started parsing (does not mean parsing passed)
  • Returns: TI_ERR_NOT_CONNECTED — not connected
  • Returns: TI_ERR_INVALID_ARG — client / key / file_path is NULL or empty, the file does not exist or cannot be opened, or the file size exceeds the limit (256 MiB)
  • Returns: TI_ERR_TIMEOUT — upload timed out (300s deadline)
  • Returns: TI_ERR_SERVER — the server failed to receive the file

Note: Synchronous blocking call (up to 300s); do not call it directly on the UI thread or the interface will freeze.

See also: ti_start_event_subscription()

TI_UPGRADE_TARGET_SYSTEM

Upgrade target key: full-system upgrade file.

upgradeStatus event

After the upload completes, the parsing result is pushed through the event subscription; status has three states:

statusMeaning
"parsing"The file has been fully received and is being parsed (intermediate state; keep waiting)
"ready"Parsing passed; the upgrade file is ready. The operator can be prompted to follow the product manual for the subsequent upgrade steps
"failed"Parsing failed; message carries the failure reason. Retry after replacing the upgrade file

Event JSON shape (message is omitted when empty):

{"upgradeStatus":{"key":"SYSTEM","status":"parsing"}}
{"upgradeStatus":{"key":"SYSTEM","status":"ready"}}
{"upgradeStatus":{"key":"SYSTEM","status":"failed","message":"invalid file format"}}

Example

// Event callback: parse upgradeStatus
void on_event(const char *event_json, void *user_data) {
    // Parse {"upgradeStatus": {"key": "SYSTEM", "status": ...}} here
    // The flow ends when status is "ready" or "failed"
}

// 1. Register the callback and start the event subscription (must be before ti_upgrade)
ti_set_event_callback(cli, on_event, NULL);
ti_start_event_subscription(cli);

// 2. Upload the system upgrade file
int rc = ti_upgrade(cli, TI_UPGRADE_TARGET_SYSTEM, "/path/to/upgrade.bin");
if (rc != TI_OK) {
    fprintf(stderr, "Upload failed: %s\n", ti_last_error(cli));
    return;
}

// 3. Keep waiting for the upgrade_status event (final result in the callback)

File Requirements & Notes

  • Use the system upgrade file for the device model
  • File size must not exceed 256 MiB
  • The upgradeStatus event depends on the event subscription being established; without a valid subscription, the parsing result cannot be obtained
  • Re-upload during upgrade: uploading again while a previous parsing is still in progress will overwrite the received file, and the final event of the previous parsing may no longer be meaningful