--- title: Automating Firmware Management with the Notehub API description: Learn how to use the Notehub API to manage firmware updates for your devices or fleets of devices. source_url: https://dev.blues.io/blog/automating-firmware-notehub-api/ canonical_url: https://dev.blues.io/blog/automating-firmware-notehub-api/ markdown_url: https://dev.blues.io/blog/automating-firmware-notehub-api.md --- # Automating Firmware Management with the Notehub API ![Automating Firmware Management with the Notehub API banner](https://dev.blues.io/images/blog/posts/automating-firmware-notehub-api/banner.png?v=5ab7fe16) January 16, 2025 ## Learn how to use the Notehub API to manage firmware updates for your devices or fleets of devices. - [Notehub](https://dev.blues.io/blog/tag/notehub) [![TJ VanToll](https://dev.blues.io/images/blog/authors/tj-vantoll.jpg?v=c3d7f336)](https://dev.blues.io/blog/author/tj-vantoll/) [TJ VanTollPrincipal Developer Advocate](https://dev.blues.io/blog/author/tj-vantoll/) 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](https://dev.blues.io/api-reference/notehub-api/project-api.md#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: ```json [ { "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 `firmwareType` argument can be set to either `"notecard"` or `"host"` to return only Notecard or host firmware, respectively. - The `target` argument 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 pass `target=u5`. (See [Notecard Firmware Updates](https://dev.blues.io/notecard/notecard-firmware-releases.md) for a full list of Notecard architectures.) > **Note:** > > Currently you can only [upload host firmware binaries](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#uploading-firmware-to-notehub) 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 [Perform DFU Action](https://dev.blues.io/api-reference/notehub-api/project-api.md#perform-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](#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): ```json {"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](https://dev.blues.io/api-reference/notehub-api/project-api.md#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 action in progress. ```json { "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. ```json "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. ```json { "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" } ] } } ``` > **Note:** > > 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](https://dev.blues.io/api-reference/notehub-api/project-api.md#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](https://dev.blues.io/guides-and-tutorials/using-the-notehub-api.md) tutorial. And if you’re a veteran of the API, feel free to jump straight into the [API documentation](https://dev.blues.io/api-reference/notehub-api.md), check out our [JavaScript and Python SDKs](https://dev.blues.io/tools-and-sdks/notehub-sdks.md), or experiment with the API with our [Postman Collection](https://dev.blues.io/tools-and-sdks/notehub-sdks/notehub-api-postman-collection.md). And if there are anything missing in our APIs, let us know in our [developer forum](https://discuss.blues.com/t/automating-firmware-management-with-the-notehub-api).