11 httpsrv

作者：拓毅恒　|　最后修改：2026-04-09

一、httpsrv 概述

httpsrv 是 Air8101 工业引擎提供的轻量级 HTTP 服务器实现，用于创建 Web 服务并处理 HTTP 请求。

其 HTTP 服务器功能主要包括：

基础 HTTP 服务器：创建 HTTP 服务、监听端口、处理请求和响应。
路由处理：支持不同 URI 路径的请求处理和路由分发。
静态文件服务：提供 HTML、CSS、JavaScript 等静态资源访问。
多网络模式支持：支持 WiFi AP、WiFi STA 和以太网 SPI 三种网络连接模式。
设备控制接口：提供 API 接口实现对设备功能的远程控制。

HTTP 服务器功能是 Air8101 工业引擎的重要扩展功能，通过它可以实现基于 Web 的设备配置、监控和控制，大大简化了设备的使用门槛和远程管理流程。

二、准备硬件环境

参考：Air8101 硬件环境清单，准备好硬件环境。

2.1 Air8101 核心板

本功能测试需要使用 Air8101 核心板 + AirETH_1000 配件板

2.2 Air8101 核心板 +AirETH_1000 配件板的硬件接线

如上图所示，Air8101 核心板和 AirETH_1000 配件板的硬件接线方式为:

Air8101核心板	AirETH_1000配件板
59/3V3	3.3v
gnd	gnd
28/DCLK	SCK
54/DISP	CSS
55/HSYN	SDO
57/DE	SDI
14/GPIO8	INT

三、准备软件环境

3.1 文章内容应用

在开始实践本示例之前，先筹备一下软件环境：

1. 烧录工具：Luatools 工具；

2. 本demo开发测试时使用的固件为Air8101 V1006 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；

3. 脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air8101/demo/httpsrv

4. LuatOS 运行所需要的 lib 文件：使用 Luatools 烧录时，勾选添加默认 lib 选项，使用默认 lib 脚本文件。

准备好软件环境之后，接下来查看 Air8101 产品手册中“Air8101 核心板使用手册 -> 使用说明”，将本篇文章中演示使用的项目文件烧录到 Air8101 核心板中。

3.2 API 介绍

这里仅介绍本篇文档所使用的 API，详情请查看：httpsrv 核心库；wlan 核心库

httpsrv.start(port, callback, adapter)

启动 HTTP 服务器

wlan.init()

初始化 WiFi 模块

wlan.createAP(ssid, password)

创建 WiFi 热点

wlan.scan()

扫描周围 WiFi 网络

wlan.scanResult()

获取 WiFi 扫描结果

四、httpsrv 功能实现概述

本小节详细介绍 Air8101 核心板上 HTTP 服务器各种功能的实现方法和核心代码逻辑。

4.1 HTTP 服务器初始化和启动

HTTP 服务器初始化和启动功能用于创建和配置 HTTP 服务，设置请求处理函数。

4.1.1 功能定义

初始化 HTTP 服务器，配置监听端口和请求处理回调函数，选择网络适配器（AP、STA 或 ETH），然后启动服务开始监听 HTTP 请求。

4.1.2 代码示例

-- 检测当前使用的网卡适配器
local function get_current_adapter()
    -- 检查各个网卡是否就绪
    if netdrv and netdrv.ready(socket.LWIP_AP) then
        return socket.LWIP_AP, "AP"
    elseif netdrv and netdrv.ready(socket.LWIP_STA) then
        return socket.LWIP_STA, "STA"
    elseif netdrv and netdrv.ready(socket.LWIP_ETH) then
        return socket.LWIP_ETH, "ETH"
    end
end

local function start_http_server()
    -- 等待网络就绪事件
    sys.waitUntil("CREATE_OK")

    -- 获取当前使用的网卡适配器
    local adapter, adapter_name = get_current_adapter()
    local local_ip = socket.localIP(adapter)

    -- 启动HTTP服务器
    httpsrv.start(80, handle_http_request, adapter)
    log.info("HTTP", "文件服务器已启动，使用" .. adapter_name .. "模式")

    if adapter == socket.LWIP_AP then
        log.info("HTTP", "请连接WiFi: luatos8888 密码: 12345678")
    end

    log.info("HTTP", "访问地址: http://" .. (local_ip or "192.168.4.1"))
end

-- 启动HTTP服务器任务
sys.taskInit(start_http_server)

4.2 HTTP 请求处理

HTTP 请求处理功能用于接收和解析 HTTP 请求，并根据 URI 路径返回相应的响应。

4.2.1 功能定义

定义请求处理回调函数，根据不同的 URI 路径执行相应的处理逻辑，并返回状态码、响应头和响应体。

4.2.2 代码示例

local function handle_http_request(fd, method, uri, headers, body)
    log.info("httpsrv", method, uri, body or "")

    if uri == "/led/1" then
        LEDA(1)
        log.info("LED Control", "Turned ON")
        return 200, {}, "ok"
    elseif uri == "/led/0" then
        LEDA(0)
        log.info("LED Control", "Turned OFF")
        return 200, {}, "ok"
    elseif uri == "/send/text" then
        log.info("Text Request", "Method:", method, "Body Length:", body and #body or 0)
        if method == "POST" and body and #body > 0 then
            -- 直接打印接收到的文本内容
            log.info("Received Text:", body)
            return 200, {}, "ok"
        end
        return 400, {}, "Invalid request"
    elseif uri == "/scan/go" then
        wlan.scan()
        return 200, {}, "ok"
    elseif uri == "/scan/list" then
        return 200, {["Content-Type"]="application/json"}, (json.encode({data=scan_result, ok=true}))
    elseif uri == "/connect" then
        if method == "POST" and body and #body > 2 then
            local jdata = json.decode(body)
            if jdata and jdata.ssid then
                sys.timerStart(wlan.connect, 500, jdata.ssid, jdata.passwd)
                return 200, {}, "ok"
            end
        end
        return 400, {}, "ok"
    elseif uri == "/connok" then
        log.info("connok", json.encode({ip=socket.localIP(2)}))
        return 200, {["Content-Type"]="application/json"}, json.encode({ip=socket.localIP(2)})
    end
    return 404, {}, "Not Found" .. uri
end

4.3 文本发送功能

文本发送功能允许通过 Web 界面向设备发送文本数据，并在设备日志中显示。

4.3.1 功能定义

提供 POST 接口接收文本数据，将接收到的文本内容打印到设备日志中。

4.3.2 代码示例

-- 在请求处理函数中的文本发送逻辑
if uri == "/send/text" then
    log.info("Text Request", "Method:", method, "Body Length:", body and #body or 0)
    if method == "POST" and body and #body > 0 then
        -- 直接打印接收到的文本内容
        log.info("Received Text:", body)
        return 200, {}, "ok"
    end
    return 400, {}, "Invalid request"
end

4.4 WiFi 扫描功能

WiFi 扫描功能用于搜索周围可用的 WiFi 网络，并以 JSON 格式返回扫描结果。

4.4.1 功能定义

提供扫描接口启动 WiFi 扫描，提供结果获取接口返回扫描到的 WiFi 网络列表，并监听扫描完成事件。

4.4.2 代码示例

-- 在请求处理函数中的WiFi扫描控制逻辑
if uri == "/scan/go" then
    wlan.scan()
    return 200, {}, "ok"
elif uri == "/scan/list" then
    return 200, {["Content-Type"]="application/json"}, (json.encode({data=_G.scan_result, ok=true}))
end

-- WiFi扫描完成事件处理
local function scan_done_handle()
    local result = wlan.scanResult()
    _G.scan_result = {}
    for k, v in pairs(result) do
        log.info("scan", (v["ssid"] and #v["ssid"] > 0) and v["ssid"] or "[隐藏SSID]", v["rssi"], (v["bssid"]:toHex()))
        if v["ssid"] and #v["ssid"] > 0 then
            table.insert(_G.scan_result, {
                ssid = v["ssid"],
                rssi = v["rssi"]
            })
        end
    end
    log.info("scan", "aplist count:", #_G.scan_result)
end

-- 订阅WiFi扫描完成事件
sys.subscribe("WLAN_SCAN_DONE", scan_done_handle)