v1/firmware
Use the v1/firmware API to list, search, and download Digi device firmware and modem firmware.
You can also use the v1/firmware API to create, list, update or remove custom firmware. This can be useful in products where Digi does not provide firmware or if you want to provide your own firmware and use it the same way as other Digi firmware, even in Automations or Configurations.
Each user can store up to 10 GB of custom firmware. After reaching this limit, you will not be allowed to upload more custom firmware until you delete any image. If you need more space, please contact a Digi representative.
Some notes about these APIs:
- Some of these APIs are available to an un-authenticated caller, other APIs require authentication or have features which require authentication. For example, setting the
include_non_production
parameter to true, requires that you have the permission to view non-production firmware, so an authenticated call is required. - These APIs are also available using the
firmware.devicecloud.com
hostname. It is recommended you use thefirmware.devicecloud.com
hostname to access these APIS. Using this hostname will isolate you from future changes in firmware hosting infrastructure. - The APIs for fetching firmware often redirect to another location. You should follow the redirect to get the firmware image.
- The APIs for listing firmware often return a secure, signed and expiring link. You can safely share this link to download the firmware image, but the link will usually expire in 24 hours.
URI
https://<hostname>/ws/v1/firmware
Formats
HTTP method | Format | Description | Authentication Required | Required Parameter | Parameters |
---|---|---|---|---|---|
GET | /ws/v1/firmware | Get summary of the device APIs. | Yes | ||
GET | /ws/v1/firmware/download/{model_name}/{firmware_version}/{filename} | Download the firmware image. | No | ||
GET | /ws/v1/firmware/inventory | List Digi device firmware, custom firmware or modem firmware. | Yes | size query cursor orderby firmware_type device_filtered | |
GET | /ws/v1/firmware/inventory/{vendor_id} | List firmware of the given internal device type | No | device_type_internal | size query cursor orderby firmware_type device_filtered device_type_internal firmware_version artifact_id get_all_artifacts include_non_production include_deprecated production deprecated filename information_link security_related sha_512 sha3_512 shared |
GET, POST, PUT, DELETE | /ws/v1/firmware/inventory/{vendor_id}/{device_type} | List firmware and create, update or delete custom firmware. | No | Various depending on method | firmware_version artifact_id get_all_artifacts include_non_production include_deprecated device_type_internal production deprecated filename information_link security_related sha_512 sha3_512 shared |
POST | /ws/v1/firmware/inventory_with_list | List firmware of the given vendor IDs and device types. | No | size cursor include_non_production include_deprecated | |
GET | /ws/v1/firmware/list | List only the firmware version numbers available for the model | No | model_name | production deprecated |
GET | /ws/v1/firmware/{version} | Get firmware information for a specific version and model name. | No | model_name | |
GET | /ws/v1/firmware/{version}/firmware_url | Return a limited set of info about firmware, including the URL | No | model_name |
Payloads
The inventory_with_list
API accepts a payload to filter the returned list. Specify one or more vendor IDs and device types to filter the list. The payload is a JSON array of objects with the following fields:
[{
"vendor_id": "FE00000A",
"device_type": "Digi EX15"
},
{
"vendor_id": "FE00000A",
"device_type": "Digi TX64"
}]
Path Parameters
These parameters are required in the URL path of some API calls.
Name | Type | Description |
---|---|---|
device_type | string | The device type of the firmware. Requires encoding special characters (link blanks) correctly. |
filename | string | Usually optional, but might be required for the client calling the API so that the file can be saved locally. |
model_name | string | Usually the same as the device type, but requires representing blanks as a slash (/) character, creating a new URL path component. For example: GET https://firmware.devicecloud.com/ws/v1/firmware/download/Digi/EX15/22.11.48.10/test.bin where Digi EX15 is the model name |
vendor_id | string | The vendor ID of the firmware in hex. For example, Devices running DAL OS usually have a vendor ID of FE00000A , so the list request is GET https://firmware.devicecloud.com/ws/v1/firmware/inventory/FE00000A/Digi%20TX64 |
Parameters
Name | Type | Description |
---|---|---|
size | integer | Number of items to return. The maximum and default is 1000. |
query | string | The Remote Manager query language query condition used to filter results. See v1 API Query Language. |
cursor | string | Cursor to get the next page of devices. Omit on initial call. |
orderby | string | Specify any field described in the query parameter syntax. Optionally add asc or desc to control the sort order. For example, to order with most recently created jobs first, specify orderby=id desc. Note The default sort order is desc (descending). |
firmware_type | string | Specify the type of the firmware to get: device (Digi device firmware), custom (customer uploaded firmware) or modem (modem firmware). If no type is provided, it defaults to device . |
device_type_internal | string | The hex value representing the XBee hardware version. Usually this is just the upper byte of the hardware version |
device_filtered | boolean | true to only get firmware that match the vendor ID and device type of the devices added to your account, false to get all firmware. It defaults to false . |
firmware_version | string | The version of the firmware following the format X.X.X.X (X between 0 and 255). |
artifact_id | string | The artifact ID of the firmware. Do not specify the artifact ID for the main firmware image, that is, the image that will be sent to the device. |
get_all_artifacts | boolean | true to get all artifacts for each firmware version, false to only get the main image. It defaults to false . |
include_non_production | boolean | true to include non-production firmware in the list, false to only get production firmware. It defaults to false . Your account must be enabled to view non-production (pre-release) firmware. Contact customer support for more info. |
include_deprecated | boolean | true to include deprecated firmware in the list, false to only get non-deprecated firmware. It defaults to false . Your account must be enabled to view deprecated (removed from public) firmware. Contact customer support for more info. |
device_type_internal | integer | The device type internal (hardware version) of the firmware, from 0x00 to 0xFF . Only applicable for XBee firmware. |
production | boolean | true to mark the firmware as production, false to mark it as non-production. It defaults to true . |
deprecated | boolean | true to mark the firmware as deprecated, false to mark it as non-deprecated. It defaults to false . |
filename | string | The filename of the firmware. If no filename is provided, <device_type>-<firmware_version>.bin is used. |
information_link | string | URL of the firmware release notes. |
security_related | string | The CVSS score of the firmware: not-identified , none , low , medium , high or critical . |
sha_512 | string | The SHA-512 of the firmware. If no SHA-512 is provided, it is calculated automatically. |
sha3_512 | string | The SHA3-512 of the firmware. If no SHA3-512 is provided, it is calculated automatically. |
shared | string | A comma-separated list of subaccount customer IDs to share the custom firmware with. It can also be all to share the firmware with all subaccounts. If no shared is provided, the firmware is not shared with any subaccount. |