REST API Devices Routes Special Load firmware
April 13, 2023 at 2:39 AMLoad a new firmware into a device
Role
Use this command to upload a new firmware into the device, and then restart it.
The firmware could either be provided as a local file name, relative to the local machine, or as an URL. In the later case, the SpringCard Companion Service downloads the file from the URL before loading it into the device.
Prototype
URL : /device/{$id}/load-firmware
Method : POST
URL Params : {$id} : the DeviceId of the device. Use GET /devices to enumerate the connected devices.
Request data :
| Field name | Type | Status | Description |
|---|---|---|---|
File |
string | option | The firmware file name or URL. Local files: start the string with “file://” Remote files: start the string with either “http://” or “https://” Other schemes (FTP etc) are not supported. |
Blob |
string | option | The firmware itself, in base64. |
File and Blob are both optional, but one of the two shall be provided (not both).
Remark
The request returns immediately, yet loading the firmware into the device takes some time (5 to 10 seconds through USB or Ethernet, a few minutes through BLE or a slow serial link). The application may use the WebSocket to monitor the progress.
Success Response
Code : 200 OK
Content : a SUCCESS object.
Error Response
See Error Responses.
When error code is 422 Unprocessable Entity, the Message field takes one of the following values:
| Message | Explanation |
|---|---|
Invalid arguments |
Both File and Blob specified, or neither |
Scheme not supported |
The File field does not use a supported scheme (should be file://, http:// or https://) |
File not found |
Local file: the specified file name does not exist Remote file: a 404 error has been received |
Access denied |
Local file: the file name is not readable Remote file: a 401 or 403 error has been received |
Download failed |
Remote file: failed to download the file from the specified URL, error is neither 401, 403, 404 |
Read failed |
Failed to read the file |
Invalid base64 string |
The BLOB is not a valid base64 string |
Unsupported content |
The file or the BLOB is not a valid firmware image |
Not available |
The target device does not support loading a new firmware (at least in its current operating mode) |
Failed |
The device has denied the firmware upgrade request |