homechevron_rightDocschevron_rightNotehubchevron_rightHost Firmware Updateschevron_rightUsing IAP Firmware Update

Using IAP Firmware Update

warning

If you're using a compatible STM32, ESP32, or nRF microcontroller, we highly recommend using Notecard Outboard Firmware Update to perform DFU operations as it's more reliable, secure, and you can roll back any unintended changes.

IAP (In Application Programming) is a more traditional form of DFU that performs firmware updates while the program is running.

Read more about IAP vs ISP (In System Programming) in this kanda.com article.

Upload Host MCU Firmware

  1. Select Settings > Firmware from the left navigation bar and click Upload Firmware.

    Upload firmware option

  2. Upload your new firmware binary with the form provided.

    Upload page

Deploy Firmware

  1. Select Devices from the left navigation bar, select a device from the list of devices in the Host Firmware tab, and then click Update.

    Device selected from list

  2. Select the firmware you wish to apply from the list of available firmware, and click Apply.

    Update host firmware button

  3. Consult Notecard API Requests for DFU to configure how Notecards process DFU requests.

Implementing IAP on the Host

Once a firmware binary has been uploaded to Notehub and a DFU action has been applied to a device, the host MCU is responsible for polling the Notecard, transferring the binary in chunks, validating it, and rebooting into the new image. Each individual API request used during this flow is documented on Notecard API Requests for DFU; the steps below show how those requests fit together end-to-end.

A typical host DFU loop, called periodically, performs the following actions:

  1. Issues a dfu.status request to the Notecard and checks the mode field in the response to determine whether a firmware image is being downloaded by the Notecard (downloading), has finished downloading and is ready for installation (ready), failed to download (error), or no new firmware is available (idle). Only the ready mode should advance the loop.

  2. Prepares the host's secondary (inactive) partition or update region to receive the incoming binary. Do this before entering DFU mode, so that slow work like erasing a large flash region doesn't run against the DFU-mode timeout described below.

  3. Once a new firmware binary has been downloaded and any pending network activity completes, issues a hub.set request with mode set to dfu, signaling to the Notecard that the host is ready to retrieve firmware.

  4. Confirms the Notecard has finished entering DFU mode by issuing a dfu.get request with length set to 0, which checks readiness without transferring data. The Notecard has to finish any in-progress network activity and close its connection first, so this request returns a {dfu-not-ready} error until that completes — retry it until it succeeds rather than assuming a fixed delay. See Ensuring Host DFU Mode is Active.

  5. Performs a series of dfu.get requests to obtain the host firmware binary in chunks, incrementing offset by the requested length on each request. Each chunk is CRC-validated and written to the host's update region using whatever flash-write or OTA utility the host platform provides.

  6. After the entire binary is retrieved, issues another hub.set with mode set to dfu-completed to indicate that the Notecard can resume its normal operations.

  7. Performs a final CRC check, comparing the CRC of the downloaded firmware to the body.crc32 value provided by Notehub in the initial dfu.status response. (The same body object also carries length and md5 values you can verify against.) If the values match, marks the new image as the boot target.

  8. Issues a dfu.status request with the stop field set to true. Upon receipt, the Notecard removes the firmware binary from its internal storage.

  9. Restarts the host and begins running the new firmware.

warning

The Notecard does not stay in DFU mode indefinitely. If 15 minutes elapse without a dfu.get request, the Notecard leaves DFU mode on its own and resumes normal operation, and any in-progress transfer will start failing.

If your host aborts partway through the update—because a dfu.get fails, or the CRC check does not match—make sure your error path still takes the Notecard back out of DFU mode with a hub.set request, and clears the DFU state so Notehub reflects the outcome. See Clearing DFU State for the requests to use.

tip

For a complete reference implementation in C++ for the ESP32, see the note-samples ESP32 DFU example on GitHub. The dfu.cpp file in that repository implements the full loop above and can be adapted to other host platforms.