Firmware Control API
Version: 1.0.0
Status: 
FirmwareControl interface for Thunder framework.
(Defined by FirmwareControl.json)
Table of Contents
Introduction
Scope
This document describes purpose and functionality of the FirmwareControl interface (version 1.0.0). It includes detailed specification about its methods and properties as well as sent notifications.
Case Sensitivity
All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.
Acronyms, Abbreviations and Terms
The table below provides and overview of acronyms used in this document and their definitions.
| Acronym | Description |
|---|---|
| API | Application Programming Interface |
| HTTP | Hypertext Transfer Protocol |
| JSON | JavaScript Object Notation; a data interchange format |
| JSON-RPC | A remote procedure call protocol encoded in JSON |
The table below provides and overview of terms and abbreviations used in this document and their definitions.
| Term | Description |
|---|---|
| callsign | The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique. |
References
| Ref ID | Description |
|---|---|
| HTTP | HTTP specification |
| JSON-RPC | JSON-RPC 2.0 specification |
| JSON | JSON specification |
| Thunder | Thunder API Reference |
Description
Firmware Control JSON-RPC interface.
Methods
The following methods are provided by the FirmwareControl interface:
FirmwareControl interface methods:
| Method | Description |
|---|---|
| upgrade | Upgrade the device to the given firmware |
| resume | Resume download from the last paused position |
upgrade method
Upgrade the device to the given firmware. (Note: Ensure size of firmware image should be < 500MB).
Also see: upgradeprogress
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.name | string | mandatory | Name of the firmware |
| params?.location | string | optional | Location or URL of the firmware to be upgraded |
| params?.type | string | optional | Type of the firmware (must be one of the following: CDL, RCDL) |
| params?.progressinterval | integer | optional | Number of seconds between progress update events (5 seconds, 10 seconds etc). 0 means invoking callback only once to report final upgrade result |
| params?.hmac | string | optional | HMAC value of firmare |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null (default: None) |
Errors
| Message | Description |
|---|---|
ERROR_INPROGRESS |
Operation in progress |
ERROR_INCORRECT_URL |
Invalid location given |
ERROR_UNAVAILABLE |
Error in download |
ERROR_BAD_REQUEST |
Bad file name given |
ERROR_ILLEGAL_STATE |
Invalid state of device |
ERROR_INCORRECT_HASH |
Incorrect hash given |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.upgrade",
"params": {
"name": "firmware_v.0",
"location": "http://my.site.com/images",
"type": "RCDL",
"progressinterval": 10,
"hmac": "2834e6d07fa4c7778ef7a4e394f38a5c321afbed51d54ad512bd3fffbc7aa5debc"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
resume method
Resume download from the last paused position.
Also see: upgradeprogress
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.name | string | mandatory | Name of the firmware |
| params?.location | string | optional | Location or URL of the firmware to be upgraded |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null (default: None) |
Errors
| Message | Description |
|---|---|
ERROR_INPROGRESS |
Operation in progress |
ERROR_INCORRECT_URL |
Invalid location given |
ERROR_UNAVAILABLE |
Error in download |
ERROR_BAD_REQUEST |
Bad file name given |
ERROR_ILLEGAL_STATE |
Invalid state of device |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.resume",
"params": {
"name": "firmware_v.0",
"location": "http://my.site.com/images"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
Properties
The following properties are provided by the FirmwareControl interface:
FirmwareControl interface properties:
| Property | R/W | Description |
|---|---|---|
| status | read-only | Current status of a upgrade |
| downloadsize | read-only | Max free space available to download image |
status property
Provides access to the current status of a upgrade.
This property is read-only.
Also see: upgradeprogress
Value
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | string | mandatory | Upgrade status (must be one of the following: downloadaborted, downloadcompleted, downloadstarted, installaborted, installinitiated, installnotstarted, installstarted, none, upgradecancelled, upgradecompleted, upgradestarted) |
Example
Get Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.status"
}
Get Response
{
"jsonrpc": "2.0",
"id": 42,
"result": "completed"
}
downloadsize property
Provides access to the max free space available to download image.
This property is read-only.
Value
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | integer | mandatory | Available free space in bytes |
Example
Get Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.downloadsize"
}
Get Response
{
"jsonrpc": "2.0",
"id": 42,
"result": 315576
}
Notifications
Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.
The following events are provided by the FirmwareControl interface:
FirmwareControl interface events:
| Notification | Description |
|---|---|
| upgradeprogress | Notifies progress of upgrade |
upgradeprogress notification
Notifies progress of upgrade.
Notification Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.status | string | mandatory | Upgrade status (must be one of the following: downloadaborted, downloadcompleted, downloadstarted, installaborted, installinitiated, installnotstarted, installstarted, none, upgradecancelled, upgradecompleted, upgradestarted) |
| params.error | string | mandatory | Reason of error (must be one of the following: downloaddirectorynotexist, generic, incorrecthash, invalidparameters, invalidrange, invalidstate, noenoughspace, none, operationotsupported, resumenotsupported, timedout, unauthenticated, unavailable, unkown) |
| params.progress | integer | mandatory | Progress of upgrade (number of bytes transferred during download or percentage of completion during install |
Example
Registration
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.register",
"params": {
"event": "upgradeprogress",
"id": "myid"
}
}
Notification
{
"jsonrpc": "2.0",
"method": "myid.upgradeprogress",
"params": {
"status": "completed",
"error": "operationotsupported",
"progress": 89
}
}
The client ID parameter is passed within the notification designator, i.e.
<client-id>.upgradeprogress.