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.

dfu.get CellCell+WiFiWiFi

Retrieves downloaded firmware data from the Notecard. Note: 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.

{
  "req": "dfu.get",
  "length": 32,
  "offset": 32
}
J *req = NoteNewRequest("dfu.get");
JAddNumberToObject(req, "length", 32);
JAddNumberToObject(req, "offset", 32);
NoteRequest(req);
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)

The host firmware version passed to Notehub.

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.

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

NoteRequest(req);
req = {"req": "dfu.status"}
req["on"] = True
rsp = card.Transaction(req)
{
  "req": "dfu.status",
  "off": true
}
J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "off", true);

NoteRequest(req);
req = {"req": "dfu.status"}
req["off"] = True
rsp = card.Transaction(req)
{
  "req": "dfu.status",
  "vvalue": "usb:1;high:1;normal:0;low:0;dead:0"
}
J *req = NoteNewRequest("dfu.status");
JAddStringToObject(req, "vvalue", "usb:1;high:1;normal:0;low:0;dead:0");

NoteRequest(req);
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.

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: