Device Configuration
Device Configuration
Synchronized Device Documentation
This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.
What This Page Covers
- Web console page purpose and related device-side configuration model.
- Available fields, operational workflow, and safety checks.
- Validation steps, logs, and maintenance recommendations.
Source Reference
The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.
设备配置
概述: 设备配置管理设备基本信息和系统级设置,包括设备名称、固件信息、NTP 时间同步、调试选项等。配置文件存储在 LittleFS 的
/config/device.json中,支持通过 Web 界面或 API 修改,也可通过配置导入/导出功能批量备份和恢复。
功能说明
设备配置页面用于管理设备的基本信息和系统级设置，包括设备名称、固件信息、NTP时间同步、调试选项等。
页面中的基础配置用于维护设备身份和时间同步；涉及外设新增、删除、编辑的现场保护项集中在“高级配置”中。
操作指南
- 进入 Web 界面 → 设备配置
- 修改需要的配置项
- 点击 保存 应用更改
- 部分配置修改后需重启设备生效
参数说明
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 设备名称 | 设备显示名称，用于 MQTT 和 Web 标识 | FastBee-Device |
| 设备ID | 设备唯一标识符（不可修改） | 自动生成 |
| NTP 服务器 | 时间同步服务器地址 | ntp.aliyun.com |
| 时区 | 时区偏移（小时） | 8（UTC+8） |
| 日志级别 | 系统日志输出级别 | INFO |
| 自动重启 | 内存不足时自动重启 | 启用 |
| 重启阈值 | 触发自动重启的最低内存（字节） | 30000 |
| 开发环境功能 | 控制外设配置、外设执行、Modbus 子设备的新增/删除/编辑/映射入口 | 启用 |
高级配置：开发环境功能
设备配置的“高级配置”页提供“开发环境功能”开关，默认启用。禁用或重新启用时需要输入当前登录用户的登录密码，用于避免现场误操作。
禁用后：
- 外设配置中的新增、编辑、删除、启用/禁用按钮不可用。
- 外设执行中的新增、编辑、删除、启用/禁用按钮不可用；执行一次保留可用。
- Modbus RTU 子设备和采集任务的新增、删除、编辑、寄存器映射以及 Modbus RTU 配置保存不可用。
- 设备监控、传感器读取、Modbus 实时控制、网络配置和普通设备信息查看不受影响。
后端接口也会校验该状态。即使绕过 Web 页面直接调用外设、外设执行或 Modbus RTU 配置写接口，禁用开发环境时也会返回 403。
配置示例
修改设备名称
设备名称会作为 MQTT 客户端ID的一部分，同时显示在 Web 界面标题栏。
NTP 时间配置
设备联网后自动同步时间，用于 Cron 定时任务和日志时间戳。
常用 NTP 服务器：
ntp.aliyun.com— 阿里云（国内推荐）pool.ntp.org— 全球 NTP 池time.windows.com— Windows 时间服务
故障排除
| 问题 | 可能原因 | 解决方案 | |------|---------|---------|| | 时间不正确 | NTP 同步失败 | 检查网络连通性和 NTP 服务器地址 | | 配置不保存 | Flash 写入失败 | 检查 LittleFS 文件系统空间 | | 重启循环 | 配置错误 | 使用 AP 模式恢复默认配置 |
配置导入导出完整指南
功能位置: Web 界面 → 设备配置 → 高级配置 → 配置导入/导出
支持的配置类型
| 类型 | 文件 | 说明 |
|---|---|---|
| 全部配置包 | fastbee-config-*.json | 包含多个配置文件的备份包 |
| 设备信息 | device.json | 设备 ID、名称、缓存时间、NTP 等基础信息 |
| 网络配置 | network.json | STA/AP、静态 IP、mDNS、重连策略 |
| 外设配置 | peripherals.json | 本地 GPIO、UART、I2C、传感器、显示屏等外设 |
| 外设执行 | periph_exec.json | 本地自动化规则、触发条件、动作列表 |
| 通信协议 | protocol.json | MQTT、Modbus RTU、子设备、映射任务 |
| 用户配置 | users.json | 完整版多用户配置；精简版通常会跳过 |
| 角色配置 | roles.json | 完整版角色权限配置；精简版通常会跳过 |
提示: 精简版开启 FASTBEE_ENABLE_CONFIG_TRANSFER=1，但关闭多用户、角色、文件管理和 OTA。导入时如果遇到精简版不支持的 users.json、roles.json，后端会按当前编译开关跳过或拒绝，避免破坏单管理员模式。
推荐使用方式
日常备份建议优先按类型导出，尤其是：
- 外设执行规则
- 外设配置
- 通信协议
这样恢复时只覆盖目标模块，风险更低，也更容易在不同设备之间迁移。
完整迁移设备时再选择"全部配置包"。导入全部配置包后建议重启设备，使外设初始化、协议启动和规则调度都从新配置干净加载。
为什么不再使用大文件内联导入
ESP32 Web 服务解析表单时会临时占用 RAM。较大的配置文件如果通过 /api/config/transfer/import 一次性内联上传，容易触发内存不足。
当前版本采用分块上传+流式解析，避免单次内存占用过大。
导入导出步骤
导出配置
- 进入 设备配置 → 高级配置 → 配置导入/导出
- 选择导出类型：
- 全部配置包: 导出所有配置文件
- 按类型导出: 选择特定配置类型（推荐）
- 点击 导出，浏览器自动下载 JSON 文件
- 保存为本地备份
导入配置
- 进入 设备配置 → 高级配置 → 配置导入/导出
- 选择导入类型：
- 全部配置包: 导入完整备份
- 按类型导入: 选择特定配置类型
- 点击 选择文件，上传 JSON 文件
- 系统验证配置格式
- 点击 导入，配置写入 LittleFS
- 重启设备使配置生效
配置迁移最佳实践
- 迁移前备份: 导出当前设备配置
- 按模块迁移: 优先迁移外设配置、执行规则、协议配置
- 验证配置: 导入后检查外设是否正常初始化
- 重启设备: 确保所有模块从新配置加载
- 测试功能: 验证自动化规则、通信协议是否正常工作
故障排除
| 问题 | 可能原因 | 解决方案 | |------|---------|---------|| | 导入失败 | 配置格式错误 | 检查 JSON 格式是否正确 | | 导入后外设不工作 | 引脚冲突 | 检查引脚分配是否冲突 | | 规则不执行 | 触发器配置错误 | 检查触发器类型和参数 | | 精简版导入失败 | 包含不支持的配置 | 精简版跳过 users.json/roles.json |