Load 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