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.

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

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

Retrieve 32 bytes of firmware data from the Notecard with an offset of 32 bytes.

{
  "req": "dfu.get",
  "length": 0
}
J *req = NoteNewRequest("dfu.get");
JAddNumberToObject(req, "length", 0);

NoteRequest(req);
req = {"req": "dfu.get"}
req["length"] = 0
rsp = card.Transaction(req)

Verify that the Notecard is in DFU mode without retrieving data.

{
  "req": "dfu.get",
  "length": 1024,
  "offset": 0
}
J *req = NoteNewRequest("dfu.get");
JAddNumberToObject(req, "length", 1024);
JAddNumberToObject(req, "offset", 0);

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

Response Members

payload

string

A base64 string containing firmware data of the provided length.

Example Response
{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

Example response with base64-encoded firmware data.

{
  "payload": ""
}

Example response when verifying DFU mode with length 0.

{
  "payload": "dGVzdGZpcm13YXJlZGF0YQ=="
}

Example response with a small firmware data block.

dfu.status CellCell+WiFiWiFi

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.

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.

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

Enable firmware downloads from Notehub.

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

Disable firmware downloads from Notehub.

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

Enable DFU downloads only when USB-powered or high voltage.

{
  "req": "dfu.status",
  "name": "card"
}
J *req = NoteNewRequest("dfu.status");
JAddStringToObject(req, "name", "card");

NoteRequest(req);
req = {"req": "dfu.status"}
req["name"] = "card"
rsp = card.Transaction(req)

Get the status of Notecard firmware updates.

{
  "req": "dfu.status",
  "stop": true,
  "status": "Update cancelled by user"
}
J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "stop", true);
JAddStringToObject(req, "status", "Update cancelled by user");

NoteRequest(req);
req = {"req": "dfu.status"}
req["stop"] = True
req["status"] = "Update cancelled by user"
rsp = card.Transaction(req)

Clear DFU state and provide status information.

{
  "req": "dfu.status",
  "version": "1.2.4"
}
J *req = NoteNewRequest("dfu.status");
JAddStringToObject(req, "version", "1.2.4");

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

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

{
  "mode": "idle",
  "status": "no download in progress",
  "on": true
}

Example response showing no firmware download in progress.

{
  "mode": "downloading",
  "status": "downloading: 45% complete",
  "on": true,
  "pending": true
}

Example response showing firmware download in progress.

{
  "mode": "error",
  "status": "download failed: checksum mismatch",
  "on": true
}

Example response showing download error.