单片机与物联网 / 系统课时

搭建 Web 服务

搭建 Web 服务

ESP32 不只能访问服务器,也可以自己监听 HTTP 请求。本节在设备上启动一个局域网 Web 服务:浏览器访问首页,页面通过控制接口切换 GPIO,并能用 curl 独立验证接口。

学习目标

  • 使用 WebServer 注册网页路由和控制接口
  • 在请求处理函数中读取参数、返回状态码与 JSON
  • 从串口、浏览器和命令行三处验证局域网访问是否正常

服务结构

ESP32 连接路由器后获得局域网 IP,并在 80 端口监听请求。浏览器先获取 / 页面;点击按钮后,页面再请求 /api/led,处理函数更新 GPIO 状态并返回 JSON。

ESP32 局域网 Web 服务结构

WebServer 是 ESP32 Arduino Core 自带的轻量 HTTP 服务类,适合设备配置页、局域网控制和小型调试接口。它不是面向高并发互联网流量设计的通用 Web 服务器。

注册页面和控制接口

下面程序默认使用 GPIO 2 作为输出脚。不同开发板的板载 LED 引脚或有效电平可能不同;若硬件定义不同,请修改 LED_PIN 和 digitalWrite() 的电平逻辑。

cpp
#include <WiFi.h>
#include <WebServer.h>

const char* WIFI_SSID = "<SSID>";
const char* WIFI_PASSWORD = "<PASSWORD>";
constexpr int LED_PIN = 2;

WebServer server(80);
bool ledOn = false;

const char INDEX_HTML[] PROGMEM = R"HTML(
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>ESP32 LED 控制</title>
</head>
<body>
  <h1>ESP32 LED 控制</h1>
  <button onclick="setLed('on')">打开</button>
  <button onclick="setLed('off')">关闭</button>
  <p id="status">等待操作</p>
  <script>
    async function setLed(state) {
      const response = await fetch('/api/led?state=' + state);
      document.getElementById('status').textContent =
        await response.text();
    }
  </script>
</body>
</html>
)HTML";

void handleLed() {
  if (!server.hasArg("state")) {
    server.send(400, "application/json",
                R"({"error":"missing state"})");
    return;
  }

  String state = server.arg("state");
  if (state != "on" && state != "off") {
    server.send(400, "application/json",
                R"({"error":"state must be on or off"})");
    return;
  }

  ledOn = (state == "on");
  digitalWrite(LED_PIN, ledOn ? HIGH : LOW);

  String body = ledOn ? R"({"led":"on"})"
                      : R"({"led":"off"})";
  server.send(200, "application/json", body);
}

void setup() {
  Serial.begin(115200);
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);

  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  unsigned long startedAt = millis();

  while (WiFi.status() != WL_CONNECTED &&
         millis() - startedAt < 20000) {
    delay(500);
    Serial.print(".");
  }

  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("\nWi-Fi connect failed");
    return;
  }

  server.on("/", HTTP_GET, []() {
    server.send_P(200, "text/html; charset=utf-8", INDEX_HTML);
  });
  server.on("/api/led", HTTP_GET, handleLed);
  server.onNotFound([]() {
    server.send(404, "application/json",
                R"({"error":"not found"})");
  });

  server.begin();

  Serial.print("\nOpen: http://");
  Serial.println(WiFi.localIP());
}

void loop() {
  server.handleClient();
}

预期输出

text
Open: http://<IP>

上传并复位后,串口中的 <IP> 是路由器分配给 ESP32 的局域网地址。电脑或手机必须能访问同一局域网;在浏览器打开该地址,应看到“ESP32 LED 控制”页面。

验证控制接口

先把 <IP> 替换为串口显示的实际地址,再从同一局域网中的电脑执行:

bash
curl "http://<IP>/api/led?state=on"

预期输出

json
{"led":"on"}

此时 GPIO 2 被设置为高电平。若请求改为 state=off,响应会变为 {"led":"off"},GPIO 恢复低电平;若省略 state 或传入其他值,接口会返回 400 和对应错误 JSON。

运行时注意点

server.handleClient() 必须在 loop() 中持续被调用,否则已建立的 Wi-Fi 连接仍在,但 HTTP 请求不会被及时处理。处理函数也应尽量短,不要在里面执行长时间阻塞操作,否则其他页面和接口会一起变慢。

这个示例适合可信局域网内的设备控制。若要跨公网访问,应增加身份认证、HTTPS、访问控制和更严格的输入校验,并优先通过受控网关或消息服务暴露设备能力,而不是直接把 ESP32 的 80 端口映射到互联网。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭建 Web 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通