homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightdfu Requests - API Reference

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.

Notecard Firmware Version:

dfu.get CellCell+WiFiWiFi

Retrieves downloaded firmware data from the Notecard for use with IAP host MCU firmware updates.

This request is functional only when the Notecard has been set to dfu mode with a hub.set, mode:dfu request.

Arguments

`length`

integer

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.

Example

JSON

{
  "req": "dfu.get",
  "length": 32,
  "offset": 32
}

C/C++

J *req = NoteNewRequest("dfu.get");
JAddNumberToObject(req, "length", 32);
JAddNumberToObject(req, "offset", 32);
NoteRequest(req);

Python

req = {"req": "dfu.get"}
req["length"] = 32
req["offset"] = 32
rsp = card.Transaction(req)

Response Members

`payload`

string

A base64 string containing firmware data of the provided length.

Example Response

{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

dfu.status CellCell+WiFiWiFi

Gets and sets the background download status of MCU host or Notecard firmware updates.

Arguments

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

`stop`

boolean (optional)

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

`status`

string (optional)

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

`version`

string (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.

`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. For example, with usb:1;0;, DFU downloads would occur when USB-powered, but not in any other state.

`on`

boolean (optional)

true to allow firmware downloads from Notehub.

`off`

boolean (optional)

true to disable firmware downloads from Notehub.

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

Enable

JSON

{
  "req": "dfu.status",
  "on": true
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "on", true);

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["on"] = True
rsp = card.Transaction(req)

Disable

JSON

{
  "req": "dfu.status",
  "off": true
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "off", true);

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["off"] = True
rsp = card.Transaction(req)

Voltage-Variable Enable

JSON

{
  "req": "dfu.status",
  "vvalue": "usb:1;high:1;normal:0;low:0;dead:0"
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddStringToObject(req, "vvalue", "usb:1;high:1;normal:0;low:0;dead:0");

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["vvalue"] = "usb:1;high:1;normal:0;low:0;dead:0"
rsp = card.Transaction(req)

Response Members

`mode`

string

The current DFU mode. Will be one of:

"idle" when there is no firmware download in progress, and no data previously downloaded.

"error" when the download or verification has failed. In this mode, the status field will contain the reason.

"downloading" when the download is in progress. In this mode, the status field will contain info about progress.

"ready" when the firmware data is fully downloaded.

"completed" when the firmware has been installed.

`status`

string

The current status of the firmware download.

`on`

boolean

true when firmware downloads are enabled.

`off`

boolean

true when firmware downloads are disabled.

`pending`

boolean

true when Notecard DFU is currently in-progress.

`body`

JSON object

Object that includes essential details about the firmware binary, including the length of the length, its md5 hash, notes from the Notehub admin, created and updated dates, and more.

Example Response

{
  "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"
  }
}

More information:

card Requests env Requests