会议室智能灯光系统使用手册

1. 系统简介

本系统用于通过网页快速控制会议室状态灯。使用者只需用自然语言描述准备召开的会议或当前情境，无需指定灯的颜色、亮度或闪烁方式。AI 后端会理解会议语义，自动生成 JSON 灯光指令，再通过 WebSocket 推送给 ESP32-S3，由设备控制红、黄、蓝、白、绿五路 LED。

系统适用于会议开始提醒、会议进行中、紧急通知、欢迎接待、专注办公等场景。

2. 使用前准备

使用前请确认以下条件：

• ESP32-S3 设备已通电，已烧录会议室智能灯光系统固件；
• ESP32-S3 已成功连接会议室 Wi-Fi；
• 后端服务已启动，且网页可访问后端 API；
• 后端已与 ESP32-S3 建立 WebSocket 连接；
• 使用电脑、平板或手机打开前端页面；
• 建议使用最新版 Chrome 或 Microsoft Edge。语音输入功能依赖浏览器语音识别支持和麦克风授权。

3. 系统工作流程

用户输入文字或语音
        |
        v
网页前端 POST /api/ai/analyze
        |
        v
AI 后端理解自然语言并生成灯光指令
        |
        v
后端通过 WebSocket 推送给 ESP32-S3
        |
        v
ESP32-S3 控制会议室 LED

注意：网页右上角的“后端连接”状态只表示网页能否访问 AI 后端，并不直接表示 ESP32-S3 已经连接。设备连接情况应由后端设备状态页或 ESP32-S3 串口日志确认。

4. 页面功能说明

4.1 顶部连接状态

页面右上角显示当前后端连接状态：

状态	指示灯	含义
已连接	绿色	网页可以访问 AI 后端接口
未连接	红色	后端地址不可访问、服务未启动或网络异常
异常	红色	后端返回了非预期状态

打开页面后，系统会自动执行一次后端连通性测试。

4.2 AI 智能控制区

在输入框中描述会议情境，再点击“发送”按钮，或直接按 Enter 键提交。

用户不需要了解灯光协议，也不需要明确给出颜色、模式、亮度或持续时间。例如，可以直接输入：

我现在需要开一个紧急攻关会

我们要开一个轻松的讨论会

下午要召开正式的项目汇报会

客户马上到，请准备一个友好的接待环境

AI 会结合“紧急、攻关、轻松、讨论、正式、接待”等语义，自动决定灯光颜色、模式、亮度、紧急程度和持续时间。用户也可以补充人数、会议性质或氛围，但不必描述具体灯效。

发送后，按钮会短暂显示“处理中”。在请求完成前请不要重复提交同一指令。

4.3 语音输入

点击输入框右侧的麦克风按钮可启动语音识别：

1. 首次使用时，浏览器会请求麦克风权限，选择“允许”；
2. 点击麦克风后开始说出指令；
3. 识别结束后，文字会自动填入输入框；
4. 检查识别文本后点击“发送”。

再次点击麦克风可主动停止识别。

如果页面提示当前浏览器不支持语音识别，请使用 Chrome 或 Edge，并确认浏览器已允许访问麦克风。

4.4 预设指令

页面提供常用场景快捷按钮。点击后会立即向后端发送对应自然语言指令，无需再点击“发送”。常见场景包括：

• 紧急通知；
• 会议模式；
• 会议信息模式；
• 专注模式；
• 欢迎模式。

预设场景和自由输入都由 AI 解释。具体颜色、模式、亮度、紧急程度和时长由后端 AI 生成；若单位需要统一的视觉规范，可以在 AI 提示词或后端规则中为关键会议类型设置固定约束。

4.5 连接日志

右侧“连接日志”区域会显示最近的操作和接口结果，包括：

• 页面初始化；
• 用户提交的自然语言指令；
• AI 后端的返回结果；
• 请求耗时；
• 网络错误、超时和语音识别错误。

日志最多保留 50 条，新日志会自动滚动到可见位置。点击“折叠”可以隐藏日志区以扩大控制区域，点击“展开”可恢复显示。

4.6 后端地址设置

页面底部显示当前后端地址，默认形式如下：

http://服务器IP:端口

点击“修改地址”可更换后端服务地址。输入格式必须以 http:// 或 https:// 开头，末尾不需要添加 /。

示例：

http://192.168.43.161:5000

修改后地址会保存在当前浏览器中，下次打开页面会自动使用该地址。点击“测试连接”可立即验证后端是否可访问。

5. 灯光指令说明

用户无需填写 JSON。自然语言经过 AI 分析后，后端会在内部生成标准 JSON，再向 ESP32-S3 推送。设备指令包含以下内容：

参数	可选值/范围	说明
颜色	红、绿、蓝、黄、白、关闭	当前点亮的 LED 颜色
模式	常亮、呼吸、闪烁、关闭	LED 显示效果
亮度	0-100	LED 亮度百分比
紧急程度	0-100	供后端判断和日志记录使用
持续时间	0-60 秒	0 表示保持当前状态，直到下一条指令
原因	文本	指令对应的业务说明

以下表格展示 AI 对不同自然语言场景的一种可能解释。它用于说明系统行为，不要求用户按表格指定灯效；实际结果由 AI 规则决定：

场景	建议灯效	示例指令
紧急攻关会	红灯闪烁、高亮度、高紧急度	我现在需要开一个紧急攻关会
轻松讨论会	绿灯或白灯呼吸、中等亮度	我们要开一个轻松的讨论会
正式汇报会	蓝灯常亮、较高亮度	下午要召开正式的项目汇报会
客户接待	白灯呼吸、柔和亮度	客户马上到，请准备一个友好的接待环境
专注工作	绿灯常亮、中等亮度	我们需要安静地集中讨论技术方案
会议结束	全部关闭	会议结束了

例如，输入“我现在需要开一个紧急攻关会”后，AI 可能在后端生成：

{
  "color": "red",
  "mode": "flash",
  "brightness": 100,
  "urgency": 95,
  "duration": 60,
  "reason": "紧急攻关会议，需要醒目的高优先级提示"
}

输入“我们要开一个轻松的讨论会”后，AI 可能生成：

{
  "color": "green",
  "mode": "breath",
  "brightness": 55,
  "urgency": 20,
  "duration": 0,
  "reason": "轻松讨论场景，营造柔和舒适的会议氛围"
}

6. 操作示例

示例一：召开紧急攻关会

1. 在输入框中输入“我现在需要开一个紧急攻关会”；
2. 点击“发送”；
3. AI 自动分析会议的紧迫性并生成 JSON 指令；
4. 在连接日志中确认后端返回成功；
5. 观察会议室状态灯是否按 AI 生成的高优先级灯效运行。

示例二：召开轻松讨论会

1. 输入“我们要开一个轻松的讨论会”；
2. 系统将自然语言发送给 AI 后端；
3. AI 自动选择适合轻松交流氛围的颜色、亮度和模式；
4. 后端将生成的 JSON 推送给 ESP32-S3；
5. 会议结束后输入“会议结束了”，系统会生成关闭灯光的指令。

示例三：使用语音控制

1. 点击麦克风按钮；
2. 说出“我们需要安静地集中讨论技术方案”；
3. 识别文字出现后核对内容；
4. 点击“发送”；
5. 观察日志和灯光状态。

7. 常见问题

7.1 页面显示未连接

检查后端地址、电脑网络和后端服务状态。点击“测试连接”查看日志中的详细错误。若页面部署在 HTTPS 网站，而后端仍使用 HTTP，浏览器可能因混合内容策略阻止请求，建议后端也启用 HTTPS。

7.2 提示请求超时

前端接口请求超时时间为 5 秒。请检查：

• 后端 AI 服务是否正在运行；
• 后端 IP 地址和端口是否正确；
• 防火墙是否允许访问对应端口；
• 后端 AI 处理是否超过 5 秒；
• 当前网络是否稳定。

7.3 网页显示成功，但灯没有变化

网页成功只说明 AI 接口返回成功。还需要检查：

• 后端是否已将指令推送到正确的 WebSocket 路径；
• ESP32-S3 是否已连接 Wi-Fi；
• ESP32-S3 串口是否出现 WebSocket connected；
• 后端推送的 JSON 是否包含全部必填字段；
• LED 接线、限流电阻和 GPIO 配置是否正确。

7.4 ESP32-S3 日志提示无效 JSON

若串口出现：

Received invalid LED command JSON

表示后端发送的消息不符合设备协议。后端需要发送包含 color、mode、brightness、urgency、duration、reason 的完整 JSON 对象；心跳、普通文本或缺少字段的数据不能作为灯光指令发送。

7.5 语音识别无法使用

请使用 Chrome 或 Edge，确认浏览器已授权麦克风。部分浏览器要求页面通过 HTTPS 或 localhost 打开才能使用语音识别功能。

8. 使用注意事项

• 不要在公开页面、截图或日志中暴露 Wi-Fi 密码、后端令牌和内部服务器地址；
• 紧急灯效应建立明确的管理权限和使用流程，避免误触发；
• 不建议让 ESP32 GPIO 直接驱动大功率灯具，应使用 MOSFET 或专用驱动器；
• 长时间运行时保持 ESP32-S3 电源稳定，避免使用质量较差的 USB 供电；
• 如后端或设备异常重连，日志可能出现短暂失败提示，等待自动恢复后再确认状态；
• 系统用于会议室提示和辅助管理，不应作为消防、医疗或人身安全告警的唯一装置。

9. 技术支持信息

出现故障时，建议按以下顺序收集信息：

1. 截取前端连接日志；
2. 记录当前后端地址；
3. 提供 ESP32-S3 串口启动和 WebSocket 日志；
4. 提供后端接收到的自然语言指令与实际推送的 JSON；
5. 说明 LED 实际表现和预期表现。

这些信息可以快速定位问题位于网页、AI 后端、WebSocket 通信、ESP32-S3 固件还是硬件接线。