Notecard API Requests for DFU

Notecard provides a set of APIs to help you monitor and manage both host MCU and Notecard firmware updates. Based on the Notecard's own firmware update protocols, these APIs offload a significant part of the burden of implementing over-the-air firmware updates.

warning

Certain API requests below are only available for IAP host MCU firmware updates, Notecard Outboard Firmware Update, and/or Notecard firmware updates and are identified on a per-API basis.

NOFU Only: Enabling Notecard Outboard Firmware Update

The card.dfu API is only relevant for Notecard Outboard Firmware Update.

The card.dfu API is used to configure a Notecard to enable or disable Notecard Outboard Firmware Update.

For example, to allow the Notecard to flash the host MCU with a downloaded binary on an STM32-based host, set "name" to "stm32" and "on" to true:

JSON

{
  "req": "card.dfu",
  "name": "stm32",
  "on": true
}

C/C++

J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);

NoteRequest(req);

Python

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

Obtaining Firmware Download Status

The dfu.status API works with all types of firmware updates.

The dfu.status API is used to determine the status of the background download of firmware, and locally control whether the Notecard will allow a background firmware download.

When called with no arguments, a dfu.status request returns an object with two fields that answer two different questions:

mode reports where the firmware download currently stands. On a Notecard that has never downloaded firmware this is idle, meaning no download is in progress and no data has been downloaded. The other possible values are covered in DFU modes below.
on reports whether the Notecard is allowed to download firmware at all. This is true by default.

Use the "name" argument to specify the type of firmware update you want to check:

"user" (the default) for IAP or Notecard Outboard Firmware Update host MCU updates.
"card" for Notecard firmware updates.

JSON

{
  "req":  "dfu.status",
  "name": "user"
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddStringToObject(req, "name", "user");

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["name"] = "user"

rsp = card.Transaction(req)

{
 "mode": "idle",
 "on": true
}

To disable firmware downloads to the Notecard, set the off argument to true:

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)

To turn it back on, set the on argument to true:

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)

You can also use a voltage-variable value to control whether or not firmware updates are allowed, based on the battery level of the device, by using the vvalue argument. This argument expects a semicolon-delimited string of <state>:<1|0> pairs, where 1 allows firmware downloads in that state and 0 disallows them. The pre-defined Notecard battery states are:

usb
high
normal
low
dead

When the Notecard's power source is in a given state, it will adjust whether a firmware download is allowed based on the values in that string. For instance, if you want to allow firmware updates when the battery is full or high, but NOT when the voltage is lower, send a request like this:

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)

DFU Modes

In addition to idle mode, dfu.status will return one of the following mode values after a device firmware update has been activated:

downloading
ready
outboard-ready
error
completed

The downloading mode indicates that the Notecard detected the presence of new firmware on a previous sync and is in the process of downloading it. When in this mode, a status string is included in the response with additional details about download progress.

{
 "mode": "downloading",
 "status": "downloaded 66% (28672/42892)",
 "on": true
}

Once the download is complete, the mode changes to ready to indicate that the firmware binary is fully downloaded and verified. When in this mode, a status string is included, as well as a body JSON object that includes essential details about the firmware binary, including the length of the binary, its md5 hash, and more.

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

If the Notecard encounters an error during the download, the mode reports as error and the status field will provide a reason for the error.

{
 "mode": "error",
 "status": "DFU did not complete",
 "on": true
}

IAP Only: Entering Host DFU Mode on the Notecard

The hub.set API's "mode":"dfu" argument is only relevant for IAP host MCU firmware updates.

Once the firmware binary is available, Notecard can be put into DFU mode by setting the hub.set API's mode argument to dfu. This request halts all Notecard communications activity and allows the host to access downloaded host MCU firmware from internal storage.

note

This step is not required on modern Notecards that store the downloaded image in onboard flash, which can serve dfu.get requests while connected and syncing normally. It is required on green Notecard Cellular (legacy) devices though. See When DFU Mode Is Required for more information.

JSON

{
  "req": "hub.set",
  "mode": "dfu"
}

C/C++

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "dfu");

NoteRequest(req);

Python

req = {"req": "hub.set"}
req["mode"] = "dfu"

rsp = card.Transaction(req)

IAP Only: Ensuring Host DFU Mode is Active

The dfu.get API is only relevant for IAP host MCU firmware updates and only applies if you entered DFU mode with a hub.set, mode:dfu request.

Setting the device to "dfu" mode does not make it ready to retrieve host MCU firmware immediately. The Notecard first has to wind down any in-progress communications and close its network connection, and how long that takes depends on what it was doing at the time. To check whether the Notecard is ready, use the dfu.get API to set the length argument to 0. This will verify that the device is in DFU mode without attempting to retrieve firmware.

JSON

{
  "req": "dfu.get",
  "length": 0
}

C/C++

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

NoteRequest(req);

Python

req = {"req": "dfu.get"}
req["length"] = 0

rsp = card.Transaction(req)

note

This request returns a {dfu-not-ready} error if the Notecard is not ready yet.

{
  "err": "disconnecting so that we can enter DFU mode {dfu-not-ready}"
}

IAP Only: Retrieving Host Firmware from the Notecard

The dfu.get API is only relevant for IAP host MCU firmware updates.

Once the Notecard is in dfu mode, use the dfu.get API to retrieve the downloaded host MCU firmware. This is typically done in successive chunks of length n until the entire binary has been delivered to the host. Use the length argument to provide a number of bytes to read for each request, and offset on each successive request to skip to the next available chunk.

For instance, if you wanted to read the binary 32 bytes at a time, the first request to dfu.get would look like this:

JSON

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

C/C++

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

NoteRequest(req);

Python

req = {"req": "dfu.get"}
req["length"] = 32

rsp = card.Transaction(req)

And each subsequent request would add an offset value that increments by the previously-requested length, each time:

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)

The first request to dfu.get returns the same body returned by dfu.status after a successful download. The first and subsequent requests also return a payload string containing the portion of the binary of the requested length and offset.

{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

note

A single dfu.get request can return at most 8192 bytes. A larger length returns a the maximum length of any single request must be <= 8192 error.

Faster Transfers with the Binary Storage Area

The payload field is base64-encoded, which inflates every chunk by roughly a third and makes the transfer of a large host binary slow (especially over I2C or a low-baud serial connection). Notecard firmware v9.1.1 added a binary argument to dfu.get that avoids the encoding entirely. Instead of returning payload, Notecard places the chunk in its binary storage area, where your host reads it out with card.binary.get.

note

The binary storage area holds one object at a time, and the whole application shares it. If yours also uses it for web.post uploads or note.add payloads, make sure those operations have finished before starting a firmware transfer.

Clear anything left in the binary storage area from a previous operation.
>
```
{"req":"card.binary", "delete":true}
```
```
{"max":130554}
```
Request a chunk of firmware with binary set to true. The response describes what currently sits in the binary storage area: length is the number of firmware bytes, cobs is the COBS-encoded length you will read off the wire, and status is the MD5 hash of that chunk.
>
```
{"req":"dfu.get", "binary":true, "offset":0, "length":8192}
```
```
{
 "cobs": 8225,
 "length": 8192,
 "status": "5d41402abc4b2a76b9719d911017c592"
}
```

Read the chunk out of the binary storage area. note-c's NoteBinaryStoreReceive() handles the COBS decoding and MD5 verification for you, and is available to any host that links note-c, including Arduino sketches using note-arduino.

uint32_t chunk_len = 0;
NoteBinaryStoreDecodedLength(&chunk_len);

// NoteBinaryStoreReceive() reads the COBS-encoded bytes off the wire and
// decodes them in place, so the buffer must be sized for the encoded form.
uint32_t buf_len = NoteBinaryCodecMaxEncodedLength(chunk_len) + 1;
uint8_t *chunk = (uint8_t *)malloc(buf_len);
NoteBinaryStoreReceive(chunk, buf_len, 0, chunk_len);

Or issue the card.binary.get request directly and COBS-decode the result yourself. See Reading Binary Data from Notecard for both paths in full.

> {"req":"card.binary.get"}
{"status":"5d41402abc4b2a76b9719d911017c592"}

Write the chunk to your host's update region, then repeat steps 2 and 3, incrementing offset by the previous length each time, until you have retrieved body.length bytes.
>
```
{"req":"dfu.get", "binary":true, "offset":8192, "length":8192}
```
```
{
 "cobs": 8225,
 "length": 8192,
 "status": "0cc175b9c0f1b6a831c399e269772661"
}
```
Each dfu.get overwrites the binary storage area, so there is no need to clear it between chunks. Reading the area does not empty it either, which means you can re-read a chunk with card.binary.get if a transfer to your host's flash fails, without asking the Notecard for it again.
Release the binary storage area once the entire image has been retrieved, so the rest of your application can use it.
>
```
{"req":"card.binary", "delete":true}
```
```
{"max":130554}
```

tip

Pair this with Faster Binary Transfers over AUX UART to move the read off I2C and onto a high-baud serial connection.

warning

While Notecard is using Starnote for non-terrestrial connectivity, the binary storage area is repurposed as the satellite queue, and dfu.get cannot return firmware data at all. To work around this you would have to switch Notecard back to a terrestrial transport before running an IAP update.

Clearing DFU State

The dfu.status API works with all types of firmware updates.

After a host MCU or Notecard firmware update is complete, you can clear the Notecard's DFU state with a dfu.status request and the stop argument. You can optionally supply a status message that will be sent to Notehub to indicate the final update status.

Use the "name" argument to specify the type of firmware update to clear:

"user" for host MCU updates.
"card" for Notecard updates.

JSON

{
  "req": "dfu.status",
  "stop": true,
  "status": "firmware update successful",
  "name": "user"
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "stop", true);
JAddStringToObject(req, "status", "firmware update successful");
JAddStringToObject(req, "name", "user");

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["stop"] = True
req["status"] = "firmware update successful"
req["name"] = "user"

rsp = card.Transaction(req)

This request will set the dfu.status mode to completed and set the status field to the string value provided.

Reporting a Failed Update

status is an informational string only, and it does not make a stop look like a failure. A dfu.status request with stop set to true always results in a completed mode unless you supply the err argument, which sets the mode to error instead and records your string as the reason.

JSON

{
  "req": "dfu.status",
  "stop": true,
  "err": "CRC check failed",
  "name": "user"
}

C/C++

J *req = NoteNewRequest("dfu.status");
JAddBoolToObject(req, "stop", true);
JAddStringToObject(req, "err", "CRC check failed");
JAddStringToObject(req, "name", "user");

NoteRequest(req);

Python

req = {"req": "dfu.status"}
req["stop"] = True
req["err"] = "CRC check failed"
req["name"] = "user"

rsp = card.Transaction(req)

If both err and status are supplied, err takes precedence and status is ignored. Both arguments are ignored entirely unless stop is also true.

warning

Don't forget to exit DFU mode if performing an IAP host MCU firmware update!

Once the IAP host DFU process is completed, take the Notecard out of dfu mode with another hub.set request. If you don't, the device remains in dfu mode, unable to sync with Notehub.

Prefer mode set to dfu-completed, which exits DFU mode and resumes whatever synchronization mode the Notecard was using beforehand.

JSON

{
  "req": "hub.set",
  "mode": "dfu-completed"
}

C/C++

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "mode", "dfu-completed");

NoteRequest(req);

Python

req = {"req": "hub.set"}
req["mode"] = "dfu-completed"

card.Transaction(req)

Notehub API Requests for DFU Environment Variables for DFU