One of Notehub’s most powerful features is its ability to manage both Notecard firmware and host firmware updates.
Late last year we made this feature even more powerful by adding a handful of new APIs that allow you to programmatically manage your firmware, and to do so in ways that were not possible in the Notehub user interface alone.
Let’s look at how the new APIs work, and you may want to incorporate them into your workflows.
Get Available Firmware
The first step in the process is knowing what firmware binaries are available to use, which you can do with the Get Available Firmware request.
GET https://api.notefile.net/v1/projects/{projectUID}/firmware
The request returns all available Notecard and host firmware available for your project, for example:
[
{
"filename": "notecard-u5-8.1.3.17044$20241220135610.bin",
"version": "8.1.3.17044",
"MD5": "d3c28142791cba17082e86e4356e3a0d",
"organization": "Blues Wireless",
"built": "Dec 20 2024 08:45:13",
"product": "Notecard",
"tags": "publish",
"type": "notecard",
"created": "1734703050",
"target": "u5",
"published": true
},
{
"filename": "2024-12-20-143355$20241220143417.binpack",
"version": "1.0.3.0",
"MD5": "77d3a5282cb47eefc52a5227a253fceb",
"organization": "My Organization",
"built": "Dec 20 2024 09:32:45",
"product": "My Product",
"type": "host",
"created": "1734705257",
"published": true
},
...
]The list of available firmware can be long, so the request provides two filters you can use to limit your options:
-
The
firmwareTypeargument can be set to either"notecard"or"host"to return only Notecard or host firmware, respectively. -
The
targetargument can be used to only return Notecard firmware that matches a given target architecture. For example, if you wanted to get a list of firmware that could run on a Notecard Cell+WiFi, you could passtarget=u5. (See Notecard Firmware Updates for a full list of Notecard architectures.)
noteCurrently you can only upload host firmware binaries using the Notehub user interface. We are working on making that possible through the Notehub API as well.
Performing Firmware Updates
Now that you have a list of available firmware, you can use the Create DFU Action API to push firmware updates to your devices.
POST https://api.notefile.net/v1/projects/{projectUID}/dfu/{firmwareType}/{action}
Here, firmwareType can be either notecard for performing Notecard firmware updates, or host for performing host firmware updates. The action can either be update for updating firmware, or cancel for cancelling a firmware update.
Additionally, the request offers a number of filters you can provide in the query string to limit which devices should receive the update. For example, the following URL would select all devices in fleet fleet:abc-123:
https://api.notefile.net/v1/projects/app:123/dfu/notecard/update?fleetUID=fleet:abc-123
And the following URL would select all devices that are currently running a Notecard firmware version of 7.5.2.17004:
https://api.notefile.net/v1/projects/app:123/dfu/notecard/update?notecardFirmware=7.5.2.17004
Once you’ve selected the appropriate devices, you next need to provide the filename of the firmware file you’d like to apply in the POST request’s body. You can find a list of valid filenames from Get Available Firmware call shown above.
For example, the following POST body tells the Notehub API to apply the u5 version of the Notecard 8.1.3.17044 firmware to your device(s):
{"filename":"notecard-u5-8.1.3.17044$20241220135610.bin"}You’ll know every thing worked if you get a 200 response.
Checking Firmware Update Status
Finally, once your firmware updates are in progress, you can check on their status with a Get Devices DFU Status request.
GET https://api.notefile.net/v1/projects/{projectUID}/dfu/{firmwareType}/status
Here, firmwareType can again be set to either notecard or host to check on the status of Notecard firmware or host firmware updates, respectively. By default the request returns the status of all devices in your project, but you can again pass filters in the query string to limit the devices to query.
Here’s an example response from a project where the first device has no pending update, and the second has a Notecard DFU update in progress.
{
"devices": [
{
"device_uid": "dev:860322067705456",
"current": {
"version": "7.5.2.17004",
"organization": "Blues Wireless",
"product": "Notecard",
"built": "Nov 26 2024 14:01:26"
},
"status": {}
},
{
"device_uid": "dev:351077454522874",
"dfu_in_progress": true,
"current": {
"version": "7.5.2.17004",
"organization": "Blues Wireless",
"product": "Notecard",
"built": "Nov 26 2024 14:01:26"
},
"status": {
"requested_version": "8.1.3.17044",
"current_version": "7.5.2.17004",
"initiated": "2025-01-15T20:36:58Z",
"updates": [
{
"status": "awaiting connection to begin update",
"phase": "pending",
"datetime": "2025-01-15T20:36:58Z",
"description": "pending sync"
}
]
}
}
]
}As the DFU process continues, the updates array in the response will be updated with status messages.
"updates": [
{
"status": "downloaded 53% (524288/977345)",
"phase": "downloading",
"datetime": "2025-01-15T20:44:17Z",
"description": "downloading"
},
{
"status": "download started",
"phase": "download_started",
"datetime": "2025-01-15T20:41:50Z",
"description": "download started"
},
{
"status": "awaiting connection to begin update",
"phase": "pending",
"datetime": "2025-01-15T20:36:58Z",
"description": "pending sync"
}
]You’ll know the update succeeded when the "current" object updates to the new version.
{
"device_uid": "dev:351077454522874",
"current": {
"version": "8.1.3.17044",
"organization": "Blues Wireless",
"product": "Notecard",
"built": "Dec 20 2024 08:45:13"
},
"status": {
"requested_version": "8.1.3.17044",
"current_version": "7.5.2.17004",
"initiated": "2025-01-15T20:36:58Z",
"updates": [
{
"status": "successful firmware update",
"phase": "completed",
"datetime": "2025-01-15T20:45:38Z",
"description": "completed"
},
{
"status": "successfully downloaded",
"phase": "ready",
"datetime": "2025-01-15T20:44:52Z",
"description": "ready"
},
{
"status": "downloaded 80% (786432/977345)",
"phase": "downloading",
"datetime": "2025-01-15T20:44:47Z",
"description": "downloading"
},
{
"status": "download started",
"phase": "download_started",
"datetime": "2025-01-15T20:41:50Z",
"description": "download started"
},
{
"status": "awaiting connection to begin update",
"phase": "pending",
"datetime": "2025-01-15T20:36:58Z",
"description": "pending sync"
}
]
}
}The Get Devices DFU Status API only returns information about the firmware currently running on your device ("current") and information on any in-progress DFU ("status"). If you need a history of all previous firmware versions running on your device, you can use the Get Devices DFU History request.
Putting It All Together
In general, these requests allow you to automate your firmware processes in ways that are not possible through the Notehub user interface alone. You can build apps, dashboards, or scripts for viewing your device’s firmware, performing firmware updates, and checking on status of DFU processes.
So if you haven’t already—try them out! If you’re new to the Notehub API, start with our Using the Notehub API tutorial. And if you’re a veteran of the API, feel free to jump straight into the API documentation, check out our JavaScript and Python SDKs, or experiment with the API with our Postman Collection.
And if there are anything missing in our APIs, let us know in our developer forum.
