2. ESP32开发环境搭建与第一个传感器读取程序

在农业远程监控系统中，ESP32 承担着采集土壤湿度、空气温湿度、光照等环境参数并通过 Wi-Fi 上传的任务。要让这块开发板真正“跑起来”，第一步是搭建一个稳定、可复现的开发环境，第二步是完成一次从传感器到串口的完整数据链路验证。本节围绕这两件事展开：先完成 Arduino IDE 或 ESP-IDF 的安装与 ESP32 开发板支持配置，再编写一个读取土壤湿度传感器模拟量的程序，烧录后通过串口监视器确认数据输出正常。

一、开发环境的两条路线与选择依据

ESP32 的官方开发框架是 ESP-IDF，基于 FreeRTOS，功能完整、底层控制能力强，适合需要精细管理任务、低功耗、蓝牙配网等复杂场景。Arduino IDE 则通过 arduino-esp32 核心包支持 ESP32，封装了大量常用外设库，上手快、代码短，非常适合课程前期快速验证传感器与通信功能。本课程建议以 Arduino IDE 为主线完成前期的传感器读取与联网实验，在需要深入任务调度或优化功耗时再引入 ESP-IDF。两条路线并不冲突，同一块开发板可以分别烧录两种框架编译出的固件。

选择 Arduino IDE 时，建议使用 2.x 版本，其内置的库管理器和开发板管理器比 1.8.x 更直观。安装完成后，需要在“文件 → 首选项 → 附加开发板管理器网址”中填入 arduino-esp32 的板管理器索引地址，然后在“工具 → 开发板 → 开发板管理器”中搜索 esp32 并安装。安装过程会下载数百 MB 的编译工具链，网络不稳定时容易中断，可多次重试或配置代理。安装完成后，在开发板列表中应能看到“ESP32 Dev Module”等条目。

二、开发板参数配置与硬件连接

开发板选型确定后，还需要配置几个关键参数，否则容易出现烧录失败或串口无输出。以常见的 ESP32 DevKit V1（基于 ESP32-WROOM-32 模组）为例，推荐配置如下：开发板选择“ESP32 Dev Module”，上传速度 921600 或 115200，Flash 大小 4MB，分区方案默认，CPU 频率 240MHz，端口选择开发板实际枚举出的 COM 口。若烧录时提示“Failed to connect”，可把上传速度降到 115200，并在按住 BOOT 键的同时点击上传，待出现“Connecting...”后松开。

土壤湿度传感器选用常见的电阻式模块（如 FC-28 一类），其输出分为模拟量 AO 和数字量 DO。本实验读取 AO 引脚。接线时注意：传感器 VCC 接开发板 3.3V，GND 接 GND，AO 接 ESP32 的某个 ADC 引脚，例如 GPIO34。GPIO34 属于仅输入引脚，适合做 ADC 采集，且位于 ADC1 通道，在 Wi-Fi 工作时仍可正常使用；这一点在后续联网章节中很重要，因为 ADC2 的部分引脚在 Wi-Fi 启用后会受限。传感器插入土壤后，其电阻随含水量变化，模块输出的模拟电压随之改变，ESP32 的 ADC 将其转换为 0～4095 的数字量。

三、第一个读取程序：从模拟量到可判读的数值

新建一个 Arduino 工程，写入下面的最小可用程序。它完成三件事：初始化串口、周期性读取 GPIO34 的 ADC 值、把原始值和换算后的电压一并打印出来。电压换算依据 ESP32 的 12 位 ADC 与默认 3.3V 参考电压：电压 = 原始值 / 4095 × 3.3。

const int SOIL_PIN = 34;      // 土壤湿度模块 AO 接 GPIO34
const int ADC_MAX  = 4095;    // 12 位 ADC 满量程
const float VREF   = 3.3;     // 参考电压

void setup() {
  Serial.begin(115200);
  delay(500);
  analogReadResolution(12);   // 明确设置为 12 位
  Serial.println("Soil sensor ready.");
}

void loop() {
  int raw = analogRead(SOIL_PIN);
  float voltage = raw * VREF / ADC_MAX;
  Serial.print("raw: ");
  Serial.print(raw);
  Serial.print("  voltage: ");
  Serial.print(voltage, 3);
  Serial.println(" V");
  delay(1000);
}

这段代码刻意保留了原始值输出，因为电阻式土壤湿度传感器的输出与含水量并非严格线性，直接换算成百分比会带来误导。更稳妥的做法是先记录“空气中”和“浸入水中”两个边界值，建立本批次传感器的经验区间，再在后续章节做标定与映射。示例中若空气中读数约为 4095、浸水后约为 1200，则说明模块工作正常；若读数长期固定在 0 或 4095 不动，应优先检查 AO 是否接错引脚、供电是否正常、探头是否接触不良。

四、烧录与串口验证的判读方法

点击上传后，观察 IDE 底部的编译与烧录日志。正常流程会依次出现编译完成、连接开发板、写入 Flash、校验通过、复位运行等阶段。烧录成功后打开串口监视器，波特率必须与代码中的 115200 一致，否则会看到乱码。此时应能看到每秒一行的“raw”和“voltage”输出。把探头从空气中插入湿润土壤，raw 值应明显下降，电压随之降低；取出后数值回升。这个“变化方向正确、数值连续、无跳变到极值”的现象，就是本节要验证的核心结果。

完成本节后，你应当拥有一套可重复使用的开发环境、一个能稳定输出传感器数值的固件，以及一套判断“采集链路是否打通”的观察方法。这套方法将在后续接入 Wi-Fi、构建数据上报与远程监控功能时反复用到。