跳到主要内容

ESP-IDF 开发

本章节包含以下内容：

ESP-IDF 入门教程​

初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置开发环境​

备注

以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。

安装 ESP-IDF 开发环境​

  1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

    在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你要安装的版本。

    下载 EIM 和整合包

    确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

    下载 EIM 和整合包2

    请耐心等待两个文件下载完成。

  2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

    启动后，可在右上角将界面语言切换为中文。

    切换 EIM 语言

    安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

    自动检测整合包

    接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。

    选择安装路径

  3. 当看到如下界面时，表示 ESP-IDF 已安装成功。

    安装成功

  4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

    用 ESP-IDF 安装管理器安装驱动

安装 Visual Studio Code 与 ESP-IDF 扩展​

  1. 下载并安装 Visual Studio Code。

  2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

  3. 在 VS Code 中,点击侧边活动栏中的 扩展图标 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

  4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

    在 VS Code 中搜索并安装 ESP-IDF 扩展

  5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

示例程序​

示例程序位于示例包的 ESP-IDF 目录： ESP32-S3-LR1121-XF-Demo.zip

以下示例名称与说明对齐 ESP32-S3-LR1121-XF 示例包的目录结构，可用于快速定位对应功能点：

示例程序基础例程说明
lr1121_cad执行通道活动检测（CAD）- 仅限 LoRa
lr1121_firmware_updateLR1121 更新固件工具
lr1121_lr_fhss传输 LR-FHSS 格式数据包
lr1121_per执行数据包错误率（PER）测试 — Tx 和 Rx 角色
lr1121_ping_pong在两台设备之间启动数据交换
lr1121_read进入接收模式
lr1121_sigfox发送符合 Sigfox 标准的上行链路
lr1121_spectral_scan获取 RX 模式下的 inst-RSSI 值以形成热图
lr1121_spetrum_display获取 RX 模式下的 inst-RSSI 值，形成动态频谱曲线
lr1121_tx_cwTx 连续波模式
lr1121_tx_infinite_preamble传输无限前导码
lr1121_write周期性发送数据
lr1121_LoRaWAN简单的 LoRaWAN A 类应用程序

示例代码框架​

下载示例，进入到 ESP32-S3-LR1121/esp32s3/ESP-IDF 中，使用 VS Code 打开示例 ESP-IDF 的示例使用需要配置 ESP32-S3-LR1121/esp32s3/ESP-IDF/main/CMakeLists.txt 的脚本文件，默认为 lr1121_ping_pong 示例，如果需要其他示例，像下图去解除注释即可：

环境搭建好后，选好开发板端口，不知道如何烧录的，参考下图：

①：选择 UART ②：选择端口 ③：选择芯片 ④：编译烧录

lr1121_cad​

  • 该应用程序将执行通道活动检测（CAD）- 仅限 LoRa。
  • 一台设备刷入 CAD_EXIT_MODE 为 TX，一台 CAD_EXIT_MODE 为 RX，就可开始测试
  • 效果如下：

lr1121_firmware_update​

  • 默认烧录 收发器 0101 版本的固件，如果需要测试其他固件版本，需要注释掉 lr1121_firmware_update.h 中的#include "lr1121_transceiver_0101.h"，解除注释其他头文件即可编译烧录，每次只能选择一个固件进行烧录。 效果如下：

lr1121_lr_fhss​

  • 该应用程序将配置设备以在 LR-FHSS 中传输数据包。
  • 效果如下：

lr1121_per​

  • PER（包错误率）测试，在 lr1121_per.h 中将一个设备设置成发送即 #define RECEIVER 1 ，另一台设备设置成接收即#define RECEIVER 0
  • 效果如下：

lr1121_ping_pong​

  • 该应用程序将设备设置为乒乓模式（点对点双向通信测试）。
  • 效果如下：

lr1121_read​

  • 该应用程序将设备设置为读模式，自动识别字符串跟十六进制数，搭配 lr1121_write 可以实现点对点通信。
  • 效果如下：

lr1121_write​

  • 该应用程序将设备设置为写模式，自动发送数据，搭配 lr1121_read 可以实现点对点通信。
  • 效果如下：

lr1121_sigfox​

  • 该应用程序将配置设备以发送符合 Sigfox 标准的上行链路。
  • 效果如下：

lr1121_spectral_scan​

  • 该应用程序通过将设备设置为 Rx continuous 模式并定期逐个频率通道读取瞬时 RSSI 来实现频谱扫描操作。
  • 可以搭配 lr1121_tx_cw 来进行测试。
  • 使用 lr1121_tx_cw 发出一个频率 868MHz, 功率 22dBm 的信息进行测试，效果如下：

lr1121_spetrum_display​

  • 该应用程序通过将设备设置为 Rx continuous 模式并定期逐个读取各个频道的瞬时 RSSI 来实现频谱显示操作。
  • 可以搭配 lr1121_tx_cw 来进行测试。
  • 绘图功能需要 VT100 控制代码的支持，例如：MobaXterm
  • 使用 lr1121_tx_cw 发出一个频率 868MHz, 功率 22dBm 的信息进行测试，效果如下：

lr1121_tx_cw​

  • 该应用程序将配置设备持续发射一个无线前导信号（Preamble）。
  • 效果如下：

lr1121_tx_infinite_preamble​

  • 该应用程序将配置设备持续发射一个无线前导信号（Preamble）。
  • 会一直发射一个波形，这个波形属于有调制（LoRa 格式），主要测试 LoRa 发射性能、频谱、认证（LoRa 模式）
  • 不发完整包，但是合法 LoRa 前导码调制

LoRa 和 LoRaWAN​

什么是 LoRa?​

Semtech 的 LoRa 是一种长距离、低功耗的物联网 (IoT) 无线平台，一般情况下泛指使用 LoRa 技术的射频芯片。主要特点如下

  • LoRa（long range 的缩写）采用的扩频调制技术源于啁啾扩频 (CSS) 技术，是远距离无线传输技术和 LPWAN 通信技术中的一种。扩频技术用带宽换取灵敏度的技术，Wi-Fi,ZigBee 等都使用了扩频技术，但 LoRa 调制的特点是接近香农定理的极限，最大效率地提高灵敏度。相比于传统 FSK 技术，在相同的通信速率下，LoRa 比 FSK 灵敏度好 8~12dBm. 目前，LoRa 主要在 Sub-GHz 的 ISM 频段运行，
  • LoRa 技术融合了数字扩频、数字信号处理和前向纠错编码等技术使得在长距离通信性能层面大幅度提高，LoRa 的链路预算优于其他任何标准化的通信技术，链路预算是指给定的环境中决定距离的主要因素。
  • LoRa 射频芯片主要有 SX127X 系列，SX126X 系列，SX130X 系列，其中 SX127X，SX126X 系列用于 LoRa 节点，SX130X 用于 LoRa 网关，详情可参考 Semtech 的产品列表

什么是 LoRaWAN?​

  • LoRaWAN 是一种建立在 LoRa 无线电调制技术之上的低功耗广域网开放协议。旨在将电池供电的“事物”无线连接到区域、国家或全球网络中的互联网，并针对关键的物联网 (IoT) 要求，例如双向定向通信、端到端安全、移动性和本地化服务。其中节点无线连接到互联网有入网认证，相当于建立节点和服务器间的加密通信信道，LoRaWAN 协议层次下图所示。

  • MAC 层中的 Class A/B/C 三类节点设备基本覆盖了物联网所有的应用场景，三者之间不同点在于节点收发的时隙不同

  • Modulation 层中 EU868，AS430 等表明不同国家使用频段参数不同，地区参数请点击参考链接

    LoRaWAN 协议栈

  • 实现 LoRaWAN 网络覆盖城市或其它区域需要由节点（LoRa 节点射频芯片）、网关（或称基站，LoRa 网关射频芯片）、Server 和云四部分组成，如下图所示

  • DEVICE（节点设备）需先发起入网请求数据包到 GATEWAY（网关）再到服务器，认证通过后才可以正常和服务器收发应用数据

  • GATEWAY（网关）可通过有线网络，3/4/5G 无线网络与服务器进行通信

  • 服务器端主要运营商有 TTN 等，自行搭建云端服务请参考 lorawan-stack，chirpstack

    LoRaWAN 网络结构

应用

  • 本应用基于 LoRaWAN 官方示例 ModemE_application_examples, 仅演示了基础的 LoRaWAN Class A 应用。其他高级示例可参考官方仓库自行移植，包括：认证申请、LoRaWAN B 类应用、LoRaWAN 多播 B/C 类示例和 FUOTA 示例。

器件准备​

  • 树莓派 4B（含配套电源）

  • SD 卡（建议使用容量大于 8GB 的 SD 卡）

  • 读卡器

  • 网关设备

  • 节点设备

  • 开发板（可选型号）：ESP32、树莓派、STM32 和 Raspberry Pi Pico

    LoRaWAN 网络覆盖

服务器搭建​

  • 本示例使用 ChirpStack 作为 LoRaWAN 网络服务器，请按照官方提供的 Raspberry Pi 安装步骤进行配置。

  • 先下载 ChirpStack Gateway OS 镜像，将其解压后，使用 Win32DiskImager 将镜像写入 SD 卡。

    下载镜像

    下载镜像

    写入镜像

    写入镜像

  • 写入完成后，请参考官方文档进行详细配置。本文仅提供简要安装流程，详细信息请参见：ChirpStack Gateway OS 入门指南

  • 将 SD 卡插入树莓派并通电启动。启动后，电脑 Wi-Fi 将扫描到名为 ChirpStackAP-XXXXXX 的无线热点，密码为 ChirpStackAP。连接成功后，在浏览器中访问：192.168.0.1，即可打开 ChirpStack 管理界面，首次登录无需密码。

    连接 Wi-Fi

    连接 Wi-Fi

    访问 Web 界面

    访问 Web 界面

  • 启动后可通过以太网或 Wi-Fi 接入外部网络。此处以连接以太网为例，若需配置 Wi-Fi，请参考：Wi-Fi 配置，联网后可在 Web 管理界面查看当前 IP 地址。

    获取网关 ID

添加网关​

  • 服务器配置完成并获取 IP 地址后，关闭树莓派并断电，将 SX1303-868M-LoRaWAN-Gateway-HAT（网关设备）连接至树莓派，并接上天线。启动树莓派后，使用前面获取的 IP 地址通过 SSH 工具（如 MobaXterm）远程访问设备。默认用户名为 root，连接成功后，在终端中输入以下命令获取网关 ID：gateway-id，系统将输出当前设备的网关 ID，请记下该 ID，稍后添加网关时将用到。

    使能网关

  • 在浏览器中访问前面获取的 IP 地址，进入 ChirpStack 管理界面，依次点击 ChirpStack -> Concentratord，启用网关功能。以 SX1303（868 MHz）为例，配置如下，配置完成后点击“保存并应用”：

    使能网关

    使能网关

    配置网关参数

    配置网关参数

  • 进入应用程序：Applications -> ChirpStack，首次进入时需要登录，默认账号和密码均为 admin。登录后，点击 Gateways -> Add gateway，在添加页面中填写前面获取的 gateway-id，并保存。返回 Gateways 页面，即可看到网关是否已经成功上线。

    添加网关到服务器

    添加网关到服务器

    查看网关是否上线

    查看网关是否上线

添加节点​

  • 首先，在 Web 界面中添加一个设备配置文件：Device Profiles -> Add device profile, 配置如下图所示：

    添加节点

  • 然后添加一个应用程序：Applications -> Add application，填写相关信息并保存：

    添加节点

    设置 EUI

    设置 EUI

    设置密钥

    设置密钥

  • 注意：ESP32-S3-LR1121 模块默认工作在收发器（Transceiver）模式。若要运行 LoRaWAN 协议，需先通过开发板烧录对应的固件。 示例可参考 Demo 中的 lr1121_firmware_update 示例，并运行 lr1121_firmware_update + lr1121_modem_05020001。

    ESP-IDF 示例

    ESP-IDF 示例

    Arduino ESP32 示例

    Arduino ESP32 示例

  • 烧录成功效果如下图所示

    节点状态

  • 如果后续需要恢复收发器模式（非 LoRaWAN），请重新烧录 lr1121_transceiver_0101 固件。

  • 固件烧录完成后，下载 LoRaWAN 示例程序，打开后进入目录：ESP32-S3-LR1121\esp32s3\ESP-IDF\main\examples\lr1121_LoRaWAN 中，编辑其中的 lorawan_commissioning.h 文件，将前面生成的 EUI 和 密钥 等信息填入对应位置。完成后编译并烧录。

    填入 EUI

    填入 EUI

    填入密钥

    填入密钥

  • 烧录完成后，节点将自动请求加入 LoRaWAN 网络。加入成功后，节点将定时发送上行数据。可通过 Web 界面查看设备事件与通信状态：

    ①、点击 Events，查看节点运行状态

    ②、观察是否加入失败

    ③、若加入成功，可看到入网事件

    ④、查看节点上报的数据

    ⑤、通过串口查看调试信息

    烧录成功效果

  • 服务器也支持向节点下发数据：

    ①、点击 Queue

    ②、输入需要下发的十六进制数据

    ③、点击发送

    ④、节点接收数据并在串口打印

    服务器下发数据