ESP-Jumpstart Programming Guide Choose target... Choose version... Introduction ESP-Jumpstart: Build ESP32 Products Fast Hardware Requirements For the Restless Getting Started The Driver Wi-Fi Connection Network Configuration Remote Control (Cloud) Firmware Upgrades Manufacturing Security Considerations ESP-Jumpstart Programming Guide » Introduction Edit on GitHub Introduction [中文] ESP-Jumpstart: Build ESP32 Products Fast Building production-ready firmware can be hard. It involves multiple questions and decisions about the best ways of doing things. It involves building phone applications, and integrating cloud agents to get all the features done. What if there was a ready reference, a known set of best steps, gathered from previous experience of others, that you could jumpstart with? ESP-Jumpstart is focused on building products on ESP32 series chips. It is a quick-way to get started into your product development process. ESP-Jumpstart builds a fully functional, ready to deploy “Smart Power Outlet” in a sequence of incremental tutorial steps. Each step addresses either a user-workflow or a developer workflow. Each step is an application built with ESP-IDF, ESP32’s software development framework. Smart Power Outlet The ESP-Jumpstart’s Smart Power Outlet firmware assumes the device has one input push-button, and one GPIO output. It implements the following commonly required functionality. Allows an end-user to configure their home Wi-Fi network through phone applications (iOS/Android) Switch on or off the GPIO output Use a push-button to physically toggle this output Allow remote control of this output through a cloud Implement over-the-air (OTA) firmware upgrade Perform Reset to Factory settings on long-press of the push-button Once you are familiar with ESP-Jumpstart, building your production firmware, is a matter of replacing the power-outlet’s device driver, with your device driver (bulb, washing machine). Jumpstart Applicability Hardware Requirements You will require the following to get started: ESP32 Series Development Kit: ESP-Jumpstart supports multiple ESP32 variants. Choose a development kit based on your target chip: ESP32: ESP32-DevKitC - Wi-Fi + Bluetooth Classic + BLE ESP32-S2: ESP32-S2-DevKitC-1 - Wi-Fi only ESP32-S3: ESP32-S3-DevKitC-1 - Wi-Fi + BLE ESP32-C2: ESP8684-DevKitC-02 - Wi-Fi + BLE ESP32-C3: ESP32-C3-DevKitC-02 - Wi-Fi + BLE ESP32-C6: ESP32-C6-DevKitC-1 - Wi-Fi + BLE All development kits are available through Espressif’s distributors. You can also use any other ESP32 series development board if you already have one. A Development host setup (Windows, Linux or Mac) that will be used for development. For the Restless If you are familiar with Espressif’s hardware and/or embedded systems, and are looking for a production-reference without the incremental steps, you can do the following: Directly use the final application in ESP-Jumpstart If you don’t have a cloud account, configure your AWS IoT Cloud configuration as mentioned in Section AWS IoT Create the manufacturing configuration file for your device’s unique cloud credentials, based on the instructions provided in Section Generating the Factory Data and flash it at the appropriate location Build, flash and boot up the firmware image as you usually do Use the reference phone-app (iOS/Android) libraries for building your phone applications. Or use the reference application to try things out as discussed in Section Network Provisioning Use the commands discussed in Section AWS IoT for remote control Now that you have this functional, modify to work with your driver Previous Next © Copyright 2018-2025, Espressif Systems (Shanghai) CO., LTD. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. ESP-Jumpstart Programming Guide Choose target... Choose version... Introduction Getting Started The Driver Wi-Fi Connection Network Configuration Remote Control (Cloud) Security First CA Certificates Embedding Files in the Firmware AWS IoT Quick Setup Demo Remote Control The Code Progress so far Firmware Upgrades Manufacturing Security Considerations ESP-Jumpstart Programming Guide » Remote Control (Cloud) Edit on GitHub Remote Control (Cloud) [中文] The true potential for smart connected devices can be realised when the connectivity is used to control or monitor the device remotely, or through integration with other services. This is where the cloud communication comes into picture. In this Chapter, we will get the smart outlet connected to a cloud platform, and enable remote control and monitoring of the device. Typically, this is achieved through either of the scenarios as shown in the figure. Value of Cloud Connectivity In most cases, once a device is connected to the cloud, the Device Cloud platforms expose the device control and monitoring through a RESTful web API. Authenticated clients, like smartphone apps can use these APIs to access the device remotely. Additionally, integration with other clouds also helps in realising valuable use cases. For example, the device can be linked with a weather information system to automatically tune itself, or it can be linked to voice-assistant cloud interfaces (like Alexa or Google Voice Assistant) to expose control through voice. Security First Before we get into the details about cloud connectivity, a few important words about security. Connecting with any remote cloud infrastructure must always happen using TLS (Transport Layer Security). It is a standard and it takes care of ensuring that the communication stays secure. This is a transport layer protocol. Any higher-level protocols like HTTP, or MQTT can use TLS as the underlying transport. All reputable cloud vendors provide device services over TLS. CA Certificates One aspect of TLS is server validation using CA certificates. The TLS layer uses the CA certificate to validate that you are really talking to the server that you are supposed to talk to. For this validation to happen, your device must be pre-programmed with one or more valid and trusted CA certificates. The TLS layer will use these as trusted certificates and then validate the server based on these trusted certificates. Please refer to Section Embedding Files in the Firmware for more details about how the CA certificate can be made part of your firmware. Embedding Files in the Firmware At times, the firmware has to use certain files directly. Most commonly, in the case of CA certificates, that need to be embedded within the firmware for server validation. The question is how do you make the entire contents of these files be part of your firmware image, and how do you access them within your firmware? ESP-IDF provides a great mechanism for enabling this. The CMakeLists.txt file can be used to inform the build system that the contents of certain files should be embedded within firmware image. This can be enabled by adding the following line into your application’s CMakeLists.txt file. target_add_binary_data(${COMPONENT_TARGET} "cloud_cfg/device.cert" TEXT) In the above example, the build system will make the file cloud_cfg/device.cert be part of the firmware. The contents of this file are in the firmware’s address space and can be directly accessed as follows: extern const uint8_t certificate_pem_crt_start[] asm("_binary_device_cert_start"); extern const uint8_t certificate_pem_crt_end[] asm("_binary_device_cert_end"); The file can then be accessed using these start and end pointers. AWS IoT In this section we will take AWS IoT as an example and connect the device to this cloud. Quick Setup Feel free to skip this sub-section, if you already have a registered account with a cloud platform. As a way for you to try this functionality out, we have created a web-page that allows you to quickly connect a device to the AWS IoT cloud platform. This page will create a set of credentials for your device, that your device can use to authenticate with the cloud. The credentials will stay valid for a duration of 14 days, which gives you enough time to experiment with the remote control and OTA upgrades feature that are demonstrated in this and subsequent chapters. Beyond this duration, you can register with AWS IoT for a cloud account yourself and then use that cloud in your production. You can create credentials for your device by: Visit the following URL: https://espressif.github.io/esp-jumpstart/ Enter your email address to which the device credentials should be mailed You will receive an email that contains the device credentials that should be programmed on your device Demo By now, you should have the following items ready to get your device to start talking with AWS IoT: A Device Private Key (a file) A Device Certificate (a file) A Device ID (a file) An endpoint URL (a file) Before getting into the details of the code, let us actually try to use the remote control for our device. You may refer to the 5_cloud/ directory of esp-jumpstart for trying this out. To setup your AWS IoT example, Go to the 5_cloud/ application Copy the files (overwriting any previous files) as mentioned below: (Note that some email clients will rename the files and add a .txt extension to them. Please make sure that the downloaded files have names as expected below.) The Device Private Key to 5_cloud/main/cloud_cfg/device.key The Device Certificate to 5_cloud/main/cloud_cfg/device.cert The Device ID to 5_cloud/main/cloud_cfg/deviceid.txt The Endpoint to 5_cloud/main/cloud_cfg/endpoint.txt Build, flash and load the firmware on your device The device will now connect to the AWS IoT cloud platform and will notify the cloud of any state changes. The firmware will also fetch any updates to the state from the cloud and apply them locally. Remote Control For remote control, AWS IoT exposes a RESTful web API for all devices that connect to it. Phone applications can interact with this Web API to control and monitor the device. We will use cURL, a command-line utility, that can be used to simulate this phon