The following instructions should work for any ESP32 development board or module. The steps below illustrate how to test-drive Deploy the Fleet using our SDK playground project. We also cover how to add the SDK to an existing project.

Video Walkthrough

Before You Start

Before continuing, create a product in Deploy the Fleet if you haven’t already.

What are you trying to do?

SDK Playground

Follow these instructions if you would like to quickly get up and running to test-drive Deploy the Fleet with a sample project we provide. It has everything out of the box configured to connect to the service. If you have an existing project to which you want to add Deploy the Fleet, skip to the Add to Existing Project section below.

Before continuing, make sure you have the ESP-IDF installed in your environment.

  1. Clone the DTF SDK Playground project.
  2. Open the project in your code editor of choice.
  3. Run idf.py menuconfig
  4. Navigate to Component config -> Deploy the Fleet SDK Playground
  5. Set the DTF Product ID. The product ID can be found on the main dashboard for your product. Do not use the full update URL here. Just the ID portion.
  6. Navigate to Component config -> Deploy the Fleet SDK Playground -> WiFi
  7. Configure your WiFi SSID and password
  8. Save and exit menuconfig

The sample project is a very simple firmware that repeatedly outputs the current version over serial. Proceed to the Updates From Deploy the Fleet section below.

Add to Existing Project

This section explains how to integrate an existing project with Deploy the Fleet using the SDK.

Install the DTF SDK

To make the integration as easy as possible we created the DTF SDK. It is installed into your components directory.

  1. Open a terminal in the root of your repository.

  2. Run

    git submodule add https://github.com/deploythefleet/dtf_sdk.git ./components/dtf_sdk

  3. Add the following lines to your sdkconfig.defaults file.

    #
# Custom Certificate for DTF Failover
#
CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE=y
CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH="components/dtf_sdk/certs/dtf_root_x1.pem"
  4. Regenerate your sdkconfig file so it picks up these new changes.

If you don’t use the sdkconfig.defaults file you can set the certificate bundle options using idf.py menuconfig. The settings are located under Component config -> mbed TLS -> Certificate Bundle. Be sure to add the additional custom certificate located at components/dtf_sdk/certs/dtf_root_x1.pem.

Add Code to Request Updates

With the SDK installed you now need to decide where, in your project, you will add logic to request OTA updates from Deploy the Fleet. This is completely up to you and will depend on your project requirements. The only prerequisite is that your device needs an active connection to the internet when the SDK is called. Once you have decided where to call the SDK, make the following code changes.

Make sure the SDK header is included at the top of your source file.

#include "dtf_ota.h"

Add the following code wherever you would like the update process to occur.

const dtf_ota_cfg_t cfg = {
      .product_id = [YOUR_DTF_PRODUCT_ID],
      .reboot_option = DTF_NO_REBOOT};

DTF_OtaResponse ret = dtf_get_firmware_update(&cfg);

IMPORTANT: Make sure you replace the YOUR_DTF_PRODUCT_ID placeholder in the above code with your own value. Do NOT use the entire update URL, only the ID portion. The product ID can be found on the main dashboard for your product.

Updates from Deploy the Fleet

With your project now configured to get updates from Deploy the Fleet, you’re ready to upload firmware releases to the service.

Build Your Firmware

Before you can upload your firmware to Deploy the Fleet you need to build it.

  1. Build your project by running idf.py build
  2. The binary will be created in the build folder and will have whatever name you have specified in the CMakeLists.txt file in the root of your project. If you are using the sample project from above the file will be named dtf_sdk_playground.bin.

OTA PARTITION SIZE: Make sure your configured OTA partition size is sufficient for the size of your exported firmware binary.

WARNING: Deploy the Fleet can not validate that your firmware binary will fit in your device’s OTA partition. You should validate this prior to uploading the firmware.

Flash Firmware to your Device

Now that you’ve made your firmware Deploy the Fleet aware, flash it to your device.

  1. Upload the firmware by running idf.py flash

Upload Firmware to Deploy the Fleet

  1. Open Deploy the Fleet.
  2. Navigate to the Firmware page for your Product.
  3. Click Upload A New Firmware.
  4. Select the firmware binary you built above.
  5. Set the version to the same value used in the firmware code. In our example we set it as 1.0.0 but you may have set it differently for your project.
  6. Optionally add any release notes.

  7. Click Upload.

    ESP32 Quickstart firmware upload dialog

Since this is the first firmware for your product it will automatically be marked as the default.

Your First Update

Now that everything in your firmware is configured let’s create an update.

  1. If you are using the SDK Playground, modify the contents of the version.txt file in the root of the project to be 2.0.0 . If you are integrating into your own project, update the firmware version using your preferred method. Alternatively, you can specify a custom_version attribute on the dtf_ota_cfg_t struct.
  2. Compile the project by running idf.py build.
  3. Open Deploy the Fleet.
  4. Navigate to the Firmware page.
  5. Click Upload A New Firmware
  6. Select the newly created firmware binary
  7. Set the version to 2.0.0 (or whatever custom version you chose).
  8. Select Mark as product default
  9. Optionally add any release notes
  10. Click Upload
  11. Reset your device

Your device should update and start outputting the new message indicating it is running version 2.0.0.

Updated: