API 接口参考
Base URL 为 http://<设备IP>；AP 模式使用 http://192.168.4.1。除特别标注外，接口都需要登录后返回的 sessionId Cookie。会话保存在内存中，设备重启后需要重新登录。
通用约定
开发候选补充（2026-10-04，UNTESTED）：GET /api/peripherals/types在IO扩展器driver descriptor和PCA9685类型57中输出configSchemaVersion:1及configFields，包含key/type/unit/default/required以及min/max/exclusiveMin/maxBytes中的适用项；PCA另外输出保留地址及commandSchemaVersion:1/commandDescriptors。真实配置和规则表单消费这些结构，缺描述则保留输入并阻止相关保存。PCA配置仍须显式提供全部11字段，default仅用于新建表单；六命令中没有prepare/start，不改变原开发者权限、RESET/OE或上电确认流程。接口返回参数域不是现场电气额定、可自动重试许可或实物证明。
- 请求和响应通常为
application/json；部分配置/控制接口也接受application/x-www-form-urlencoded。 - 登录接口只读取表单或 query 参数，不要发送 JSON body。
- 成功响应通常包含
success: true；失败响应包含 HTTP 状态码和error/message。 - 内存压力下，重型接口可能返回
503与Retry-After，客户端应退避重试。 GET /api/health免认证，适合设备探活和重启恢复判断。- “设备屏幕”与共享来源接口见设备屏幕和天气与远程资源。配置写入要求开发者模式；系统重启需要全局许可及卡片二次确认（Rev4 示例已显式配置，固件通用默认关闭）。Web 预览不执行真实控制，物理屏也不接收 Wi-Fi 凭据或提供 Web 网络配置快捷入口。
认证
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/login | 表单 username、password，返回 sessionId |
| POST | /api/auth/logout | 使当前会话失效 |
| GET | /api/auth/session | 查询当前会话 |
| POST | /api/auth/change-password | 修改当前用户密码 |
curl.exe -s -c cookie.txt -X POST http://192.168.4.1/api/auth/login `
-d "username=admin&password=admin123"
curl.exe -s -b cookie.txt http://192.168.4.1/api/system/status首次登录后请立即修改默认密码。连续登录失败会触发账户锁定。
系统、健康与设备
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| GET | /api/health | 否 | 轻量探活 |
| GET | /api/system/info | 是 | 芯片、固件和构建信息 |
| GET | /api/system/status | 是 | 运行时状态、内存、网络和功能 |
| GET | /api/system/health | 否 | 与/api/health相同的轻量健康响应，不提供全任务栈 |
| GET | /api/system/metrics | 是 | 直接返回运行指标JSON，无success/data包装 |
| GET | /api/system/capabilities | 否 | 编译能力和可用模块 |
| GET | /api/system/diag-bundle | 是 | 重启原因和诊断信息 |
| POST | /api/system/task-stack-snapshot | 是+开发者模式 | 单次SDK任务栈快照，48条上限、30秒冷却；后继候选尚未验证 |
| POST | /api/system/restart | 是 | 重启设备 |
| POST | /api/system/factory-reset | 是 | 恢复默认配置并重启 |
| GET/POST | /api/device/config | 是 | 设备配置读写 |
| GET | /api/device/info | 是 | 设备信息 |
| GET | /api/device/time | 是 | 读取设备时间 |
| POST | /api/device/time/sync | 是 | NTP 同步 |
2026-10-04开发候选的完整/api/system/info?full=1和/api/system/diag-bundle还提供data.memory.capabilityPools：internal8、internalDma、psram8分别含observed/free/minFree/largestBlock（字节）。未观察的值为null，池有重叠且非原子快照，不能相加或作为功能独占用量。裸/api/system/info默认精简，显式full仍可能因内存保护降级；精简/probe响应不含该增量，旧固件也可能缺失，调用方应检查字段是否存在。语义和当前验证边界见内存口径。
任务栈POST不接受或保存配置，不驱动外设，也没有自动轮询。它可能暂时挂起调度，须由开发者明确发起。缺健康监控、SEVERE及以上、内部8-bit空闲不足32768字节、最大块不足8192字节、采集忙、冷却或超容量时不扫描。无后端/SDK返回0/数量越界/分配或时钟失败均不能视为完整空列表。
有效响应为success=true、data.status=observed及completeAtCapture=true；后端未观察结果为HTTP200、success=false、status=unknown、原因码，observedCount/tasks=null。身份/开发模式失败保留401/403，响应JSON溢出为503。冷却理由为CAPTURE_COOLDOWN，retryAfterMs表示剩余毫秒，不要求自动重试。
每个任务只返回taskNumber/priority/highWaterBytes/stateCode/name（name固定null）；栈单位bytes，0是真实低水位而非未知。countBefore/countAfter/countChangedAroundCapture说明列表周围的数量变化；sampledAtUptimeMs为64位运行时标，captureDurationUs为SDK实测耗时，schedulerPausePossible=true、hardDeadlineEnforced=false、atomicSnapshot=false。这些字段不证明任务仍存活、最差路径或WDT通过。r20集中诊断r2的26项Host回归通过；完整固件与实机仍待验收，见健康监控。
健康探针示例：
curl.exe -s http://192.168.4.1/api/health网络与配网
| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| GET | /api/wifi/status | 条件 | WiFi/AP 状态、IP 和信号 |
| GET | /api/wifi/scan | 条件 | 扫描附近 WiFi |
| POST | /api/wifi/config | 条件 | 保存首次配网参数 |
| POST | /api/wifi/connect | 条件 | 连接指定 SSID 并保存 |
| GET | /api/network/status | 是 | 当前网络模式和适配器 |
| GET/POST | /api/network/config | 是 | 读取/保存网络配置 |
配网接口仅在AP模式，或APSTA且STA未连接时允许匿名；其它状态需登录。不能将这些路由永久视为免认证。
mode：0 为 STA，1 为 AP；networkType：0 WiFi，1 W5500 以太网，2 EC801E-CN 4G。以太网和 4G 还需要对应功能已编译、外部硬件已接好并在“功能配置”中开启。
外设与自动化
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/peripherals | 外设列表（支持 id、分页和筛选参数） |
| POST/PUT | /api/peripherals、/api/peripherals/update、/api/peripherals/<id> | 新增或更新 |
| DELETE | /api/peripherals/<id> | 删除 |
| GET | /api/peripherals/types | 外设类型清单 |
| POST | /api/peripherals/enable、/disable | 启用/停用 |
| GET | /api/peripherals/read | 读取外设值；UART会消费RX，每次最多128字节，与规则共用接收流，见UART接收边界 |
| POST | /api/peripherals/write | 写入外设值 |
| GET | /api/peripherals/status | 运行状态 |
| GET | /api/peripherals/resources | 登录后只读配置规划与十三类受管运行资源快照；非硬件空闲检测 |
| GET | /api/peripherals/validate-pins | 引脚校验 |
| GET/POST | /api/periph-exec | 规则列表/新增 |
| POST | /api/periph-exec/update | 更新规则 |
| POST | /api/periph-exec/enable、/disable | 启用/停用规则 |
| POST | /api/periph-exec/run | 手动执行 |
| GET | /api/periph-exec/results | 执行结果 |
规则脚本 API（/api/rule-script*）只有在功能编译且 ruleScript 已启用时才会工作。规则最多 3 个触发器、4 个动作，触发器为 OR 关系。
/api/peripherals/resources 使用success/data包装。data.resources是配置规划，不能当作硬件实际占用；data.runtime是各管理器分别复制的I2C、SPI、UART、控制输出、编码器、DHT/RMT、外设/脚本LEDC、背光、ADC、GPIO、DAC、NeoPixel和步进登记。固定边界为schemaVersion=1/status=partial/complete=false/atomicAcrossSources=false/hardwareProbed=false/freeCapacityKnown=false。比较其它profileId只影响配置规划，运行记录仍属于runtime.activeProfileId。
每源status=busy或临时快照分配失败时，leaseCount/leases=null，不能解析为零占用。未支持的DAC/NeoPixel为unsupported；NeoPixel管理器同步尚未建立为PM_SYNCHRONIZATION_UNAVAILABLE。最终JSON内存不足返回503，不返回截断成功。页面仅手动刷新，不轮询、不清理资源或访问SDK硬件。
编码器active/interruptAttached/interruptCleanupPending/fault/cleanupPending区分事件接收、SDK确认与待清理。NeoPixelobjectAllocated及configuredLedCount不等于传输成功/RMT通道数；writeAttempted/releaseAttempted=false时结果为null，已尝试才给ABI结果码0～8（依次为成功、忙、内存不足、无效参数、隔离、初始化失败、发送失败、释放失败、owner变化）。步进pins固定为IN1～4，五个GPIO/保留掩码的bit0～3与之对应；最多16条，超出时truncated=true，running不证明实测位置。控制输出、编码器和步进与GPIO登记有父子关系，不能累加为不同引脚。
ADC要同时查看leases/units/channels/calibrationCount/calibrationCleanupPending，零消费者不代表单元释放；采样失败质量为read_failed=6，不能当有效零值。参见ADC生命周期及外设管理。这些后继接口仍待完整候选和实机验收，详见当前状态。
协议
| 方法 | 路径 | 说明 |
|---|---|---|
| GET/POST | /api/protocol/config | 协议总配置 |
| POST | /api/protocol/mqtt/config | MQTT/MQTTS 配置 |
| POST | /api/protocol/modbus-rtu/config | Modbus RTU 配置 |
| GET | /api/mqtt/status | MQTT 状态 |
| POST | /api/mqtt/reconnect、/disconnect | 连接控制 |
| POST | /api/mqtt/test | 保全原配置后暂存仅连接测试，延迟恢复；有连接和存储副作用 |
| POST | /api/mqtt/ntp-sync | 通过 MQTT/NTP 同步 |
| GET | /api/modbus/status | Modbus 状态 |
| POST | /api/modbus/write | 通用写入 |
| GET/POST | /api/modbus/register/read、/write | 寄存器读写 |
| POST | /api/modbus/coil/control | 线圈控制 |
当前开发候选的/api/mqtt/test先创建并回读校验恢复记录，再暂存带connectionTestOnly的MQTT节点并重建主客户端；测试隔离业务上报、订阅和连接动作，结果检测后尝试恢复原配置。这仍有Flash写入、断连与重建副作用，不能当作只读探测。testRestorePending或“配置恢复待处理”表示尚未恢复完成；期间用户修改、存储故障或旧/损坏恢复记录会阻止自动覆盖，原证据保留。自动化验收须核对最终配置、恢复状态与正式连接，不能只看测试握手成功。旧固件行为以其版本为准，候选/部署边界见MQTT配置。Modbus当前定位为主站，FASTBEE_MODBUS_SLAVE_ENABLE默认关闭。
功能开关
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/features/status | 查看编译/用户意图、准入、实例观察和预算估算 |
| POST | /api/features/config | 提交功能开关 |
| POST | /api/features/estimate | 估算 Flash/RAM 影响 |
| POST | /api/features/apply | 保存并重启使配置生效 |
active表示准入，activeMeaning=admission_only，不是驱动已初始化或线路可用证明。准入要求编译支持、用户启用、预算与依赖满足且没有运行期禁用；MQTTS依赖MQTT，命令脚本与规则脚本强制组合。低内存时准入可关闭，但实际对象可能仍在退役或被保留。
实际观察另看instanceObserved/instanceState/instanceScope/instanceReason。owner_lifetime只说明管理对象生命周期，transport_allocation只说明传输对象分配，均不证明服务器监听、TLS握手或物理动作。锁忙/未观察不能当作已释放。resourceAccounting=static_estimate、instanceMemoryMeasured=false表示预算仍为静态估算；字段及候选边界见功能配置。4MB环境的OTA因分区限制不编译；otaFs当前未实现文件系统升级，不能通过开启兼容配置键获得该能力。
OTA
只有 8MB/16MB A/B 分区环境注册以下接口：
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/ota/begin | 检查 ota_1 和内存并开始会话 |
| POST | /api/ota/upload | multipart 上传固件 |
| GET | /api/ota/status | 查询进度 |
| POST | /api/ota/cancel | 取消会话 |
| POST | /api/ota/url | 从 URL 下载升级 |
| POST | /api/ota/update | 保留入口，仅返回提示，未实现本地更新 |
4MB正式环境未注册OTA路由，通常返回 404。501仅适用于已编入OTA但缺升级槽的路径。上传应用 firmware.bin，不能上传合并镜像或LittleFS；200须按阶段判断，并核验终态、重启和版本。完整流程见 OTA 升级。
配置传输、日志与文件
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/config/transfer/list | 可导入导出的配置文件 |
| GET | /api/config/transfer/export | 导出指定配置 |
| POST | /api/config/transfer/import、/import-begin、/import-chunk | 旧逐文件入口；常规迁移使用整组流程 |
| GET | /api/logs、/api/logs/list、/api/logs/info | 日志查询 |
| POST | /api/logs/clear | 清理日志 |
| GET | /api/files、/api/files/content | 文件列表/读取（仅定制固件启用 FASTBEE_ENABLE_FILE_MANAGER=1） |
| POST | /api/files/save | 保存文件（仅定制固件启用 FASTBEE_ENABLE_FILE_MANAGER=1） |
| GET | /api/filesystem | LittleFS 空间（仅定制固件启用 FASTBEE_ENABLE_FILE_MANAGER=1） |
当前整组迁移包括暂存、预检、确认准备、单独重启及启动恢复状态核验，完整入口见设备配置。八文件白名单不包括network、protocol、users和auth。不能以旧逐文件写入替代整组校验。
日志查看器受功能状态控制；文件 API 只在定制构建显式启用对应宏时注册，当前发布版没有文件管理页面。能力不确定时先查询免认证的 /api/system/capabilities，再读取需要登录的状态接口。
SSE 实时事件
GET /api/events 建立 Server-Sent Events 长连接。浏览器 EventSource 会自动携带 Cookie（同源时），可接收 sensor-data、modbus-data、mqtt-status 和 heartbeat 等事件。内存不足或并发超限时服务会返回 503，客户端应关闭连接并退避重连。
const events = new EventSource('/api/events');
events.addEventListener('sensor-data', (event) => {
const data = JSON.parse(event.data);
console.log(data);
});版本与能力判断
不要根据页面菜单猜测功能是否可用。集成程序应在启动时读取：
/api/system/info：芯片、Flash、PSRAM 和固件版本（需要登录）。/api/system/capabilities：编译能力（免认证）。/api/features/status：用户开关、预算准入和有明确范围的实例观察；未观察不等于未占用。
接口变更以源码路由注册和本页为准；新增硬件或功能后请同步运行设备 API 冒烟测试。