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.

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 Settings tab for your product.
  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. Run idf.py menuconfig
  4. Navigate to Component Config->mbedTLS->Certificate Bundle and ensure that Enabled trusted root certificate bundle is enabled. It is by default. If you need more flash space you can change the option from Use the full default certificate bundle to Use only the most common certificates and the SDK will still properly connect to Deploy the Fleet.
  5. Exit menuconfig and save any changes made.
  6. Modify the CMakeLists.txt file in the component to which you are adding the SDK. Either create a PRIV_REQUIRES dtf_sdk or add dtf_sdk to an existing PRIV_REQUIRES.

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. The product ID can be found on the Settings tab 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 the Deploy the Fleet Management Console.
  2. Navigate to the Deployments page for your product.
  3. Click Create a new deployment.
  4. Provide a name and description.
  5. Attach the firmware binary you built above. The version should automatically populate.

  6. Click Deploy now.

    ESP32 Quickstart firmware upload dialog

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 the Deploy the Fleet Management Console.
  4. Navigate to the Deployments page for your product.
  5. Click Create a new deployment.
  6. Provide a name and description.
  7. Attach the firmware binary you built above. The version should automatically populate and now indicate 2.0.0.
  8. Click Deploy now.
  9. Reset your device

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

Updated: