--- title: dfu Requests - API Reference description: Notecard offers a set of host firmware update APIs that can be utilized by developers, in concert with Notehub, to update firmware of a Host MCU. source_url: https://dev.blues.io/api-reference/notecard-api/dfu-requests/2-x-lts/ canonical_url: https://dev.blues.io/api-reference/notecard-api/dfu-requests/latest/ markdown_url: https://dev.blues.io/api-reference/notecard-api/dfu-requests/2-x-lts.md --- # dfu Requests The Notecard offers a set of host firmware update APIs that can be utilized by developers, in concert with Notehub, to update the firmware of a [Host MCU](https://dev.blues.io/api-reference/glossary.md#host-mcu). ## dfu.get Supported on (Cell, Cell+WiFi, Skylo, WiFi) Retrieves downloaded firmware data from the Notecard for use with [IAP host MCU firmware updates](https://dev.blues.io/notehub/host-firmware-updates/iap-firmware-update.md). > **Note:** > > Modern Notecards store the downloaded firmware image in onboard flash and can serve this request at any time. Green Notecard Cellular (legacy) devices stage the image in the cellular modem's file system instead, and must first be placed in DFU mode. If this request returns a `not currently in the DFU operating mode` error, issue a `hub.set, mode:dfu` request and retry. Arguments ### `length` *integer (optional)* The number of bytes of firmware data to read and return to the host, up to a maximum of 8192 per request. Set to `0` to verify that the Notecard is ready to serve firmware data without retrieving any. ### `offset` *integer (optional)* The offset to use before performing a read of firmware data. **Retrieve Firmware Data** **JSON** ```json { "req": "dfu.get", "length": 32, "offset": 32 } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.get"); JAddNumberToObject(req, "length", 32); JAddNumberToObject(req, "offset", 32); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.get"} req["length"] = 32 req["offset"] = 32 rsp = card.Transaction(req) ``` Retrieve 32 bytes of firmware data from the Notecard with an offset of 32 bytes. **Verify DFU Mode** **JSON** ```json { "req": "dfu.get", "length": 0 } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.get"); JAddNumberToObject(req, "length", 0); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.get"} req["length"] = 0 rsp = card.Transaction(req) ``` Verify that the Notecard is ready to serve firmware data without retrieving any. **Read First Block** **JSON** ```json { "req": "dfu.get", "length": 1024, "offset": 0 } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.get"); JAddNumberToObject(req, "length", 1024); JAddNumberToObject(req, "offset", 0); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.get"} req["length"] = 1024 req["offset"] = 0 rsp = card.Transaction(req) ``` Read the first 1024 bytes of firmware data from the beginning. **Retrieve Large Firmware Data with Binary Buffer** **JSON** ```json { "req": "dfu.get", "length": 8192, "offset": 0, "binary": true } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.get"); JAddNumberToObject(req, "length", 8192); JAddNumberToObject(req, "offset", 0); JAddBoolToObject(req, "binary", true); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.get"} req["length"] = 8192 req["offset"] = 0 req["binary"] = True rsp = card.Transaction(req) ``` Retrieve 8192 bytes of firmware data through the binary storage area, then read it out with `card.binary.get`. **Response Members** ### `cobs` *integer* When `binary` is `true` in the request, this field contains the COBS-encoded length of the firmware data in the binary storage area. ### `length` *integer* When `binary` is `true` in the request, this field contains the decoded length of the firmware data in bytes in the binary storage area. ### `payload` *string* A base64 string containing firmware data of the provided `length`. This field is only present when `binary` is not used or is `false` in the request. ### `status` *string* A 32-character hex-encoded MD5 hash of the firmware data returned by this request, covering only the requested `offset` and `length`. Useful for the host to verify data integrity. Example Response ```json { "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg=" } ``` Example response with base64-encoded firmware data. ```json { "payload": "" } ``` Example response when verifying readiness with length 0. ```json { "payload": "dGVzdGZpcm13YXJlZGF0YQ==" } ``` Example response with a small firmware data block. ```json { "cobs": 8225, "length": 8192, "status": "5d41402abc4b2a76b9719d911017c592" } ``` Example response when using binary mode with firmware data in the binary storage area. Related Articles - [IAP Only: Retrieving Host Firmware from the Notecard](https://dev.blues.io/notehub/host-firmware-updates/notecard-api-requests-for-dfu.md#iap-only-retrieving-host-firmware-from-the-notecard) - [IAP Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/iap-firmware-update.md) - [card.binary.get](https://dev.blues.io/api-reference/notecard-api/card-requests.md#card-binary-get) - [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md) ## dfu.status Supported on (Cell, Cell+WiFi, Skylo, WiFi) Gets and sets the background download status of MCU host or Notecard firmware updates. Arguments ### `err` *string (optional)* If `err` text is provided along with `"stop":true`, this sets the host DFU to an error state with the specified string. ### `name` *string (optional)* Determines which type of firmware update status to view. The value can be `"user"` (default), which gets the status of MCU host firmware updates, or `"card"`, which gets the status of Notecard firmware updates. `"user"`: Gets the status of MCU host firmware updates (default). `"card"`: Gets the status of Notecard firmware updates. ### `off` *boolean (optional)* `true` to disable firmware downloads from Notehub. This setting persists across Notecard restarts. If both `on` and `off` are provided in the same request, `off` takes precedence. ### `on` *boolean (optional)* `true` to allow firmware downloads from Notehub. Downloads are enabled by default, and this setting persists across Notecard restarts. Enabling downloads here does not guarantee that a download will proceed. It can still be deferred by the `_fw_download_disabled` and `_fw_download_window_mins` environment variables, or by the `vvalue` voltage gate below. ### `status` *string (optional)* When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes. If `stop` is `true` and no `status` is provided, the Notecard reports `successful firmware update`. ### `stop` *boolean (optional)* `true` to end the current DFU. The Notecard exits DFU operating mode and marks the update `completed`, or `error` if an `err` string is also provided. ### `version` *string or object (optional)* Version information on the host firmware to pass to Notehub. You may pass a simple version number string (e.g. `"1.0.0.0"`), or an object with detailed information about the firmware image (recommended). If you provide an object it must take the following form. `{"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","ver_major":1,"ver_minor":2,"ver_patch":4,"ver_build": 5,"builder":"The Builder"}` Code to help you generate a version with the correct formatting is available in [Enabling Notecard Outboard Firmware Update](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md#enabling-notecard-outboard-firmware-update). ### `vvalue` *string (optional)* A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled. Use a boolean `1` (on) or `0` (off) for each source/voltage level: `usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0`. The default is `usb:1;high:1;normal:1;low:0;dead:0`. **Enable DFU Downloads** **JSON** ```json { "req": "dfu.status", "on": true } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddBoolToObject(req, "on", true); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["on"] = True rsp = card.Transaction(req) ``` Enable firmware downloads from Notehub. **Disable DFU Downloads** **JSON** ```json { "req": "dfu.status", "off": true } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddBoolToObject(req, "off", true); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["off"] = True rsp = card.Transaction(req) ``` Disable firmware downloads from Notehub. **Voltage-Variable Enable** **JSON** ```json { "req": "dfu.status", "vvalue": "usb:1;high:1;normal:0;low:0;dead:0" } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddStringToObject(req, "vvalue", "usb:1;high:1;normal:0;low:0;dead:0"); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["vvalue"] = "usb:1;high:1;normal:0;low:0;dead:0" rsp = card.Transaction(req) ``` Enable DFU downloads only when USB-powered or high voltage. **Check Notecard DFU Status** **JSON** ```json { "req": "dfu.status", "name": "card" } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddStringToObject(req, "name", "card"); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["name"] = "card" rsp = card.Transaction(req) ``` Get the status of Notecard firmware updates. **Stop DFU with Status** **JSON** ```json { "req": "dfu.status", "stop": true, "status": "Update cancelled by user" } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddBoolToObject(req, "stop", true); JAddStringToObject(req, "status", "Update cancelled by user"); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["stop"] = True req["status"] = "Update cancelled by user" rsp = card.Transaction(req) ``` Clear DFU state and provide status information. **Set Version Information** **JSON** ```json { "req": "dfu.status", "version": "1.2.4" } ``` **C/C++** ```cpp J *req = NoteNewRequest("dfu.status"); JAddStringToObject(req, "version", "1.2.4"); NoteRequest(req); ``` **Python** ```python req = {"req": "dfu.status"} req["version"] = "1.2.4" rsp = card.Transaction(req) ``` Provide version information for host firmware. **Response Members** ### `body` *object* Object that includes essential details about the firmware binary, including its length, md5 hash, notes from the Notehub admin, created and updated dates, and more. ### `mode` *string* The current DFU mode. Will be one of: `"idle"`: There is no firmware download in progress, and no data previously downloaded. `"error"`: The download or verification has failed. In this mode, the `status` field will contain the reason. `"downloading"`: The download is in progress. In this mode, the `status` field will contain info about progress. `"ready"`: The firmware data is fully downloaded. `"outboard-ready"`: The firmware data is fully downloaded and ready for an outboard DFU operation, where the Notecard will flash the firmware to the host MCU via the AUX or ALT\_DFU pins. `"completed"`: The firmware has been installed. ### `off` *boolean* `true` when firmware downloads are disabled. ### `on` *boolean* `true` when firmware downloads are enabled. ### `pending` *boolean* `true` when Notecard DFU is currently in-progress. ### `status` *string* The current status of the firmware download. Example Response ```json { "mode": "ready", "status": "successfully downloaded", "on": true, "body": { "crc32": 2525287425, "created": 1599163431, "info": {}, "length": 42892, "md5": "5a3f73a7f1b4bc8917b12b36c2532969", "modified": 1599163431, "name": "stm32-new-firmware$20200903200351.bin", "notes": "Latest prod firmware", "source": "stm32-new-firmware.bin", "type": "firmware" } } ``` Example response showing firmware is ready for installation. ```json { "mode": "idle", "status": "no download in progress", "on": true } ``` Example response showing no firmware download in progress. ```json { "mode": "downloading", "status": "downloading: 45% complete", "on": true, "pending": true } ``` Example response showing firmware download in progress. ```json { "mode": "error", "status": "download failed: checksum mismatch", "on": true } ``` Example response showing download error. ```json { "mode": "outboard-ready", "status": "successfully downloaded", "on": true } ``` Example response showing firmware is ready for an outboard DFU operation. Related Articles - [Notecard API Requests for DFU](https://dev.blues.io/notehub/host-firmware-updates/notecard-api-requests-for-dfu.md) - [Notecard Outboard Firmware Update Guide](https://dev.blues.io/notehub/host-firmware-updates/notecard-outboard-firmware-update.md) [card Requests](https://dev.blues.io/api-reference/notecard-api/card-requests.md "card Requests") [env Requests](https://dev.blues.io/api-reference/notecard-api/env-requests.md "env Requests")