---
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/latest/
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/latest.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:**
>
> This request is functional only when the Notecard has been set to `dfu` mode with a `hub.set, mode:dfu` request.

Arguments

### `binary`

*boolean (optional)*

If `true`, the Notecard will return firmware data in the binary I/O buffer instead of the response `payload` field. This allows for larger data transfers and more efficient processing. When `true`, the response will include `cobs`, `length`, and `status` (MD5 hash) fields instead of `payload`.

Learn more in this guide on [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md).

### `length`

*integer (optional)*

The number of bytes of firmware data to read and return to the host. Set to `0` to verify that the Notecard is in DFU mode without attempting to retrieve data.

### `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 in DFU mode without retrieving data.

**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 using the binary I/O buffer for efficient large data transfers.

**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 I/O buffer.

### `length`

*integer*

When `binary` is `true` in the request, this field contains the actual length of the firmware data in bytes in the binary I/O buffer.

### `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*

When `binary` is `true` in the request, this field contains a 32-character hex-encoded MD5 hash of the firmware data. 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 DFU mode with length 0.

```json
{
  "payload": "dGVzdGZpcm13YXJlZGF0YQ=="
}
```

Example response with a small firmware data block.

```json
{
  "cobs": 10240,
  "length": 8192,
  "status": "5d41402abc4b2a76b9719d911017c592"
}
```

Example response when using binary mode with firmware data in the I/O buffer.

## 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.

### `on`

*boolean (optional)*

`true` to allow firmware downloads from Notehub.

### `status`

*string (optional)*

When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes.

### `stop`

*boolean (optional)*

`true` to clear DFU state and delete the local firmware image from the Notecard.

### `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`.

**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.

[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")