ESP-Jumpstart latest 简介 入门指南 驱动程序 Wi-Fi 连接 网络配置 远程控制（云端） 固件升级 量产 安全性 ESP-Jumpstart Docs » ESP-Jumpstart Edit on GitHub ESP-Jumpstart [English] 快速构建 ESP32 产品：从概念到生产的飞跃 Jumpstart Now Next © Copyright 2016 - 2019 乐鑫信息科技（上海）股份有限公司 Revision 51e35125. Built with Sphinx using a theme provided by Read the Docs. ESP-Jumpstart latest 简介 ESP-Jumpstart：快速构建 ESP32 产品 ESP8266 用户 其他 入门指南 驱动程序 Wi-Fi 连接 网络配置 远程控制（云端） 固件升级 量产 安全性 ESP-Jumpstart Docs » 简介 Edit on GitHub 简介 [English] ESP-Jumpstart：快速构建 ESP32 产品 众所周知，固件开发并非易事，特别是用于量产的固件。开发人员不但需要面临各种决策上的问题并权衡多种选择，而且还需开发手机 app，并接入各家云服务商。现在，我们盛情推出 ESP-Jumpstart 示例项目，内含产品开发的完整步骤、最佳做法，并结合其他产品开发经验，助您快速启动基于 ESP32 的产品开发！ ESP-Jumpstart 项目专注于在 ESP32 上构建产品，展示了基于 ESP32 的完整产品开发流程。该项目分步介绍了一款真实产品的完整开发流程，即一款功能齐全、随时可推广的“智能电源插座”。其中，每个步骤均为用户/开发人员的工作流提供指南/参考，并且都是基于 ESP32 的软件开发框架 ESP-IDF 进行开发。 智能电源插座 本项目中的智能电源插座拥有一个实体按钮和一个 GPIO 输出端，可实现以下常见功能： 允许用户在家庭 Wi-Fi 网络环境中，通过手机 app（苹果/安卓）进行配置； 允许通过手机 app，打开/关闭 GPIO 输出端； 允许通过实体按钮，打开/关闭 GPIO 输出端； 允许通过云端，远程打开/关闭 GPIO 输出端； 支持 OTA 固件升级； 长按实体按钮，恢复出厂设置。 在实际开发中，您仅需将本项目中的智能电源插座替换为您的设备驱动程序（灯泡、洗衣机）即可。 ESP-Jumpstart 适用性 准备工作： ESP32 开发板：ESP32-DevKitC，您也可以使用其他 ESP32 开发板； 用于开发的 PC（Windows、Linux 或 Mac OS）。 ESP8266 用户 准备工作： ESP8266 开发板：ESP8266-DevKitC，您也可以使用其他 ESP8266 开发板。 ESP8266_RTOS_SDK 是乐鑫 ESP8266 的软件开发框架，ESP8266 开发过程中出现的 IDF 路径均指向 ESP8266_RTOS_SDK。 除了上面专门针对 ESP8266 用户的说明，其他部分 ESP32 和 ESP8266 通用。 其他 如果您已经熟悉乐鑫硬件和/或嵌入式系统，想寻找一些产品参考，而不需要量产环节，那您可以： 直接使用 ESP-Jumpstart 中的最终应用程序； 如果您没有云帐户，请按照 亚马逊 AWS IoT 章节配置 AWS IOT 云； 按照 生成工厂数据 章节为设备特有的云证书创建量产配置文件，并将文件烧录至适当位置； 正常构建、烧录并启动固件； 使用 app（苹果/安卓）参考库构建自己的手机 app，或者直接参考 统一配置 章节尝试这种解决方案； 使用 亚马逊 AWS IoT 章节中的指令进行远程控制； 具备这些功能后，您就可以将这些功能适配到您的驱动程序上运行。 Next Previous © Copyright 2016 - 2019 乐鑫信息科技（上海）股份有限公司 Revision 51e35125. Built with Sphinx using a theme provided by Read the Docs. ESP-Jumpstart latest 简介 入门指南 驱动程序 Wi-Fi 连接 网络配置 远程控制（云端） 安全性第一 CA 证书 在固件中嵌入文件 亚马逊 AWS IoT 快速设置 演示 远程控制 代码 未完待续 固件升级 量产 安全性 ESP-Jumpstart Docs » 远程控制（云端） Edit on GitHub 远程控制（云端） [English] 智能硬件的真正优势在于通过联网对设备进行远程控制或监测，或者将联网功能集成于其他云服务。当集成联网功能与其他云服务时，需要用到云平台。在本章中，我们将智能插座连接到云平台，来实现对设备的远程控制和监测。 通常，我们可以通过图中所示的任一场景来实现对设备的远程控制和监测。 云连接价值所在 在大多数情况下，一旦设备连接到云，云平台就会通过 Web API 公开设备的控制和监控权限。通过身份验证的客户端（如智能手机应用）可以使用这些 API 远程访问设备。 此外，通过集成其他云服务也能够实现许多有价值的用途。例如，设备可以与天气信息系统连接，根据天气情况进行自动调节，或者连接到语音助理云界面（如 Alexa 或 谷歌语音助手），通过语音来进行控制。 安全性第一 在详细介绍云连接之前，让我们先了解一下安全性的重要知识。 连接远程云基础架构时，我们必须使用传输层安全性协议 (Transport Layer Security, TLS)。TLS 是一种安全标准，负责确保通信安全。同时，TLS 作为一种传输层协议，任何更高级别的协议（如 HTTP 或 MQTT）都可以将该协议用于底层传输。大多数云供应商都通过 TLS 提供设备服务。 CA 证书 TLS 协议内容之一是使用 CA 证书进行服务器验证，因此 TLS 层将使用 CA 证书来验证您是否在跟正确的服务器进行通信。要进行此验证，设备必须预先嵌入一个或多个有效且受信任的 CA 证书。TLS 层将这些证书视为可信证书，之后根据可信证书验证服务器。请参考 在固件中嵌入文件 章节，查看如何将 CA 证书嵌入固件。 在固件中嵌入文件 固件有时需要直接使用某些文件。比如，我们经常需要将 CA 证书嵌入固件中以进行服务器验证。 但问题是如何将这些文件的内容全部嵌入固件中并进行访问？ ESP-IDF 提供了一个很好的实现方法，即使用 CMakeLists.txt 文件告诉构建系统哪些文件的内容需要嵌入到固件映像中。只要将下面的代码添加到 CMakeLists.txt 文件中即可。 target_add_binary_data(${COMPONENT_TARGET} "cloud_cfg/server.cert" TEXT) 如果你使用的是 Legacy GNU 构建系统，而非 CMake 构建系统，向您应用中的 component.mk 文件加入如下行同样可以使能该功能。 COMPONENT_EMBED_TXTFILES := cloud_cfg/server.cert 在上面的示例中，构建系统将 cloud_cfg/server.cert 文件嵌入到固件中，文件内容存放在固件地址空间内，可通过如下方式直接访问： extern const uint8_t certificate_pem_crt_start[] asm("_binary_server_cert_start"); extern const uint8_t certificate_pem_crt_end[] asm("_binary_server_cert_end"); 然后我们可以使用开始和结束指针访问该文件。 亚马逊 AWS IoT 在本节中，我们将以亚马逊 AWS IoT 为例，将设备连接到该云端。 快速设置 如果您已经拥有云平台的注册帐户，您可以跳过此部分。 为了方便您试用该功能，我们创建了一个网页，该网页允许您快速将设备连接到 AWS IoT 云平台，这个网页为您的设备创建一组证书，设备可以使用这些证书进行身份验证。证书有效期为 14 天，您将有足够的时间来尝试本章和后续章节中演示的远程控制和 OTA 升级功能。试用期限过后，请自行在 AWS IoT 注册云帐户即可。 您可以通过以下方式为设备创建证书： 点击 证书创建页面 输入接收证书的电子邮件地址 您会收到一封电子邮件，里面包含您将用到的设备证书。 演示 现在，您应该已经准备好了以下文件，可以将设备连接到 AWS IoT 平台了： 设备私钥（文件） 设备证书（文件） 设备 ID（文件） AWS IoT 域名的 CA 证书（文件） 端点 URL（文件） 在详细了解代码之前，让我们先尝试一下设备远程控制。您可以参考 esp-jumpstart 项下 5_cloud/ 目录。 请按照以下步骤，设置 AWS IoT 应用示例： 进入 5_cloud/ 程序 复制如下文件，覆盖以前的所有文件。请注意，有些电子邮件客户端会将这些文件自动重命名，并为其添加 .txt 扩展名。请确保下载文件的名称与下列一致： 复制 AWS CA 到 5_cloud/main/cloud_cfg/server.cert 复制设备私钥到 5_cloud/main/cloud_cfg/device.key 复制设备证书到 5_cloud/main/cloud_cfg/device.cert 复制设备 ID 到 5_cloud/main/cloud_cfg/deviceid.txt 复制端点文件到 5_cloud/main/cloud_cfg/endpoint.txt 构建、烧录、上载固件至设备 现在，设备已经连接到 AWS IoT 云平台，并会在状态更改时通知云端。固件也将从云端获取所有状态更新，并应用到本地。 远程控制 AWS IoT 为连接到它的所有设备提供了 Web API，用以实现远程控制。手机应用程序可以与此 Web API 交互以控制和监测设备。在这里我们使用命令行工具 cURL 来模拟手机应用程序。 使用 cURL，然后在 Linux/Windows/Mac 控制台执行以下命令，就可以读取设备的当前状态： curl --tlsv1.2 --cert cloud_cfg/device.cert \ --key cloud_cfg/device.key \ https://a3orti3lw2padm-ats.iot.us-east-1.amazonaws.com:8443/things//shadow \ | python -mjson.tool 在上面的命令中，请复制粘贴 deviceid.txt 的文件内容替换 things 和 shadow 之间的 。 注意：AWS 仅允许获得授权的实体访问设备状态。因此，在上面的命令中，我们用到了 device.cert 和 device.key，与我们在固件中配置的文件相同，可以确保我们有权访问设备状态。但在生产中，必须要在云端为客户端（如该 cURL 和手机应用程序）创建单独的身份验证密钥，以访问/修改设备状态。 设备状态可以修改为： curl -d '{"state":{"desired":{"output":false}}}' \ --tlsv1.2 --cert cloud_cfg/device.cert \ --key cloud_cfg/device.key \ https://a3orti3lw2padm-ats.iot.us-east-1.amazonaws.com:8443/things//shadow \ | python -mjson.tool 此 cURL 命令将生成 HTTP POST 请求，并在 POST 主体中发送 JSON 数据（如上所示）。此 JSON 数据指导 AWS IoT 将设备状态更新为 false。 每当您将设备状态从 cURL 端更改为 true 或 false 时，您都可以观察设备上相应的状态更改。 这就是远程控制的实现方式。现在让我们来快速探讨一下代码。 代码 所有云通信的代码都已整合到 cloud_aws.c 文件中。此文件的结构与 AWS IoT SDK 所要求的结构标准相似。 该文件使用我们的驱动程序 API：app_driver_get_state() 和 app_driver_toggle_state()，分别用于获取设备状态和反转设备状态。 AWS IoT 需要在您的固件中嵌入以下 3 个文件： AWS CA 证书文件：5_cloud/main/cloud_cfg/server.cert 设备私钥文件：5_cloud/main/cloud_cfg/device.key 设备证书文件：5_cloud/main/cloud_cfg/device.cert 应用程序使用 在固件中嵌入文件 章节中所描述的机制将以上文件嵌入到固件中。 未完待续 通过这个应用程序，我们终于将插座自身的功能（插座电源的切换）与网络连接功能结合到了一起。设备连接到云端后，我们现在可以通过网络对其进行控制和监控。我们还提到了在连接到任何远程/云服务之前必须考虑的安全性问题。 下一章，我们会探讨连网设备的一个常见需求：空中（OTA）固件升级。 Next Previous © Copyright 2016 - 2019 乐鑫信息科技（上海）股份有限公司 Revision 51e35125. Built with Sphinx using a theme provided by Read the Docs. ESP-Jumpstart latest 简介 入门指南 开发过程概述 ESP-IDF 介绍 设置 ESP-IDF ESP-IDF 详解 获取 ESP-Jumpstart 库 ESP8266 用户 代码 未完待续 驱动程序 Wi-Fi 连接 网络配置 远程控制（云端） 固件升级 量产 安全性 ESP-Jumpstart Docs » 入门指南 Edit on GitHub 入门指南 [English] 在本章中，我们将介绍 ESP32 的开发环境，并帮助您了解 ESP32 可用的开发工具和代码仓库。 开发过程概述 使用 ESP32 开发产品时，常用的开发环境如下图所示： ESP32 产品开发过程 上图电脑，即开发主机可以是 Linux、Windows 或 MacOS 操作系统。ESP32 开发板通过 USB 连接到开发主机，开发主机上有 ESP-IDF (乐鑫 SDK)、编译器工具链和项目代码。主机先编译代码生成可执行文件，然后电脑上的工具把生成的文件烧到板子上，然后板子开始执行文件。最后你可以从主机查看日志。 ESP-IDF 介绍 ESP-IDF 是乐鑫为 ESP32 提供的物联网开发框架。 ESP-IDF 包含一系列库及头文件，提供了基于 ESP32 构建软件项目所需的核心组件。 ESP-IDF 还提供了开发和量产过程中最常用的工具及功能，例如：构建、烧录、调试和测量等。 设置 ESP-IDF 请参照 ESP-IDF 入门指南，按照步骤设置 ESP-IDF。注：请完成链接页面的所有步骤。 在进行下面步骤之前，请确认您已经正确设置了开发主机，并按照上面链接中的步骤构建了第一个应用程序。如果上面步骤已经完成，那让我们继续探索 ESP-IDF。 ESP-IDF 详解 ESP-IDF 采用了一种基于组件的架构： 组件设计 ESP-IDF 中的所有软件均以“组件”的形式提供，比如操作系统、网络协议栈、Wi-Fi 驱动程序、以及 HTTP 服务器等中间件等等。 在这种基于“组件”的架构下，你可以轻松使用更多自己研发或第三方提供的组件。 开发人员通常借助 ESP-IDF 构建 应用程序，包含业务逻辑、外设驱动程序和 SDK 配置。 应用程序架构 应用程序必须包含一个 main 组件，这是保存应用程序逻辑的主要组件。除此之外，应用程序根据自身需求还可以包含其他组件。应用程序的 CMakeLists.txt/Makefile 文件定义了应用程序的构建指令，此外，应用程序还包含一个可选的 sdkconfig.defaults 文件，用于存放应用程序默认的 SDK 配置。 获取 ESP-Jumpstart 库 ESP-Jumpstart 库包含了一系列由 ESP-IDF 构建的 应用程序，我们将在本次练习中使用这些应用程序。首先克隆 ESP-Jumpstart 库： $ git clone --recursive https://github.com/espressif/esp-jumpstart 我们将构建一个可用于量产的固件，因此选择使用 ESP-IDF 稳定版本进行开发。目前 ESP-Jumpstart 使用的是 ESP-IDF v4.4 稳定版本，请切换到这一版本。 $ cd esp-idf $ git checkout -b release/v4.4 remotes/origin/release/v4.4 $ git submodule update --recursive 现在，我们构建 ESP-Jumpstart 中的第一个应用程序 Hello World，并将其烧录到开发板上，具体步骤如下，相信您已经熟悉这些步骤： $ cd esp-jumpstart/1_hello_world $ export ESPPORT=/dev/cu.SLAB_USBTOUART # Or the correct device name for your setup $ export ESPBAUD=921600 $ idf.py menuconfig $ idf.py flash monitor 上面的步骤将构建整个 SDK 和应用程序。构建成功后，将会把生成的固件烧录到开发板。 烧录成功后，设备将重启。同时，你还可以在控制台看到该固件的输出。 ESP8266 用户 请确保已将 IDF_PATH 设置为 ESP8266_RTOS_SDK 的路径，并使用 esp-jumpstart 的 platform/esp8266 分支。请使用以下命令切换到该分支： $ cd esp-jumpstart $ git checkout -b platform/esp8266 origin/platform/esp8266 代码 现在，让我们研究一下 Hello World 应用程序的代码，只有如下几行： #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" void app_main() { int i = 0; while (1) { printf("[%d] Hello world!\n", i); i++; vTaskDelay(5000 / portTICK_PERIOD_MS); } } 这组代码非常简单，下面是一些要点： app_main() 函数是应用程序入口点，所有应用程序都从这里开始执行。FreeRTOS 内核在 ESP32 双核上运行之后将调用此函数，FreeRTOS 一旦完成初始化，即将在 ESP32 的其中一个核上新建一个应用程序线程，称为主线程，并在这一线程中调用 app_main() 函数。应用程序线程的堆栈可以通过 SDK 的配置信息进行配置。 printf()、strlen()、time() 等 C 库函数可以直接调用。IDF 使用 newlib C 标准库，newlib 是一个占用空间较低的 C 标准库，支持 stdio、stdlib、字符串操作、数学、时间/时区、文件/目录操作等 C 库中的大多数函数，不支持 signal、locale、wchr 等。在上面示例中，我们使用 printf() 函数将数据输出打印到控制台。 FreeRTOS 是驱动 ESP32 双核的操作系统。FreeRTOS 是一个很小的内核，提供了任务创建、任务间通信（信号量、信息队列、互斥量）、中断和定时器等机制。在上面示例中，我们使用 vTaskDelay 函数让线程休眠 5 秒。有关 FreeRTOS API 的详细信息，请查看 FreeRTOS 文档。 未完待续 到现在为止，我们已经具备了基本的开发能力，可以进行编译代码、烧录固件、查看固件日志和消息等基本开发操作。 下一步，让我们用 ESP32 构建一个简单的电源插座。 Next Previous © Copyright 2016 - 2019 乐鑫信息科技（上海）股份有限公司 Revision 51e35125. Built with Sphinx using a theme provided by Read the Docs. ESP-Jumpstart latest 简介 入门指南 驱动程序 实体按钮 代码 输出端 代码 未完待续 Wi-Fi 连接 网络配置 远程控制（云端） 固件升级 量产 安全性 ESP-Jumpstart Docs » 驱动程序 Edit on GitHub 驱动程序 [English] 在本章中，我们将使用 ESP32 驱动程序 API 创建一个简单的电源插座应用。该电源插座： 包含一个实体按钮 按下按钮即可打开/关闭 GPIO 输出端 本章节只关注实现插座自身的功能，后续章节会具体介绍插座的连网功能。请参考 esp-jumpstart 项下的 2_drivers/ 目录，查看相关代码。 此驱动程序的代码已被单独放入 app_driver.c 文件，因此如果后续需要修改此应用程序用于产品，您只需更改此文件内容，即可与外设通信。 实体按钮 首先，我们需要创建一个实体按钮。在 DevkitC 开发板上设有一个名为 Boot 的按钮，并连接至 GPIO 0。我们将配置此按钮，用于打开/关闭插座。 代码 实现此功能的代码如下： #include button_handle_t btn_handle=iot_button_create(JUMPSTART_BOARD_BUTTON_GPIO, JUMPSTART_BOARD_BUTTON_ACTIVE_LEVEL); iot_button_set_evt_cb(btn_handle, BUTTON_CB_RELEASE, push_btn_cb, "RELEASE"); 我们使用 iot_button 模块来实现按钮功能。首先，创建 iot_button 对象，指定 GPIO 输出端及其有效电平用于检测按钮动作。DevKitC 开发板的 BUTTON_GPIO 设置为 GPIO 0。 然后我们为按钮注册事件回调函数，松开按钮时，就会在 esp-timer 线程中调用 push_btn_cb 函数。请确保为 esp-timer 线程配置的默认堆栈足以满足回调函数需求。 push_btn_cb 代码如下： static void push_btn_cb(void* arg) { static uint64_t previous; uint64_t current = xTaskGetTickCount(