# 使用说明 —— RS485 → Pharos LPC 灯光控制系统

日期：2026-10-09（2026-10-10 更新：LPC 自治架构——照度采集与闭环全部移到 LPC Lua，Ubuntu 只做监控/记录）

## 1. 控制协议

通过 RS485 总线发送 ASCII 文本帧（**4800 8N1**（2026-10-10 起由 9600 改为 4800，与照度传感器共总线），`\n` 结尾）即可控制灯光：

| 命令 | 格式 | 功能 | 示例 |
|------|------|------|------|
| 手动亮度 | `BRT=NNN` | 总亮度 0~100%（3 位补零） | `BRT=080` |
| 灯光效果 | `FX=NN` | 01 常亮 / 02 呼吸 / 03 闪烁 / 04 缓变 | `FX=02` |
| 场景 | `SC=NN` | 01 全亮 / 02 半亮 / 03 微亮 / 04 全灭 | `SC=01` |
| 照度闭环 | `LUX=NNNNNN` | 上报实测照度（Lux），自动调光到目标 | `LUX=000350` |
| 目标照度 | `LXT=NNNNNN` | 设定闭环目标（默认 500 Lux） | `LXT=000500` |
| 照度指示 | `LX2=NNNNNN` | 灯亮度直接映射照度（对数映射） | `LX2=001000` |

**FX 与 SC 互斥**：发 FX 会清除 SC 的亮度覆盖并启动对应 Timeline；
发 SC 会停掉所有 Timeline 并设定静态亮度。后到的命令生效。
FX 效果会一直循环播放，直到收到下一条 FX/SC 命令（由 FXLoop 触发器在播完时自动重启）。

**亮度叠加关系**：`最终亮度 = Timeline/场景基础亮度 × BRT/LUX/LX2 设定的总调光系数`。
例如 FX=01（常亮 255）+ BRT=050 → 实际输出约 50%。

## 2. 发送方式

### ESP32 / 单片机

串口 9600 8N1，直接 `printf("FX=02\n")` 即可。

### Ubuntu 主机（192.168.58.7）

```bash
python3 ~/rs485-lpc_test_rs485.py -s 'FX=02'
```

### Windows 本机

```powershell
powershell -File Run-Remote.ps1 -Cmd "python3 ~/rs485-lpc_test_rs485.py -s 'SC=01'"
```

## 2.5 网页控制台（2026-10-10 新增）

浏览器访问 **http://192.168.58.7:8090/**（手机/电脑均可，与 LPC 同网段）：

- 实时显示：4 条 Timeline 状态/进度、DMX 通道 1~32 输出柱状图、总亮度（1.5s 刷新）
- 控制：FX 效果（常亮/呼吸/闪烁/缓变）、SC 场景（全亮/半亮/微亮/全灭）、总亮度滑杆（均经 LPC HTTP 触发器下发，不走串口）
- **照度联动开关**：切换 LPC 全局变量 `lux_link_on`（HTTP 触发器 #16 开 / #17 关），并实时显示 LPC 采集的照度 Lux 值
- **48 小时历史曲线**（60s 刷新）：输出%（实线）+ BRT%（虚线，左轴）与照度 lux（右轴，对数刻度）；
  数据由服务每 30s 从 LPC HTTP API 采样一次，持久化在 `~/rs485-lpc/history.jsonl`，重启不丢

服务为 Ubuntu 侧 `~/rs485-lpc/lpc_web.py`（端口 8090；8080 被 esp32-voice 的 light-web 占用，勿动）。
重启须分两条命令执行（pkill 与启动不能同一条，否则 pkill 会误杀自身会话导致服务起不来）：
```powershell
Run-Remote.ps1 -Cmd "pkill -f 'lpc_web.py'"
Run-Remote.ps1 -Cmd "setsid bash -c 'nohup python3 ~/rs485-lpc/lpc_web.py > ~/rs485-lpc/lpc_web.log 2>&1 < /dev/null &'"
```

## 3. 状态查询（免认证 HTTP API）

```bash
curl.exe http://192.168.58.109/api/timeline               # 各 Timeline 运行状态
curl.exe "http://192.168.58.109/api/output?universe=dmx:1" # 32 通道实时输出
curl.exe http://192.168.58.109/api/group                   # 总调光系数
curl.exe "http://192.168.58.109/api/lua?variables=lux_value,lux_target,lux_link_on,lux_cur_level"  # 闭环全局变量
```

远程触发（网页控制台即用此方式）：

```bash
curl.exe -X POST "http://192.168.58.109/api/trigger?num=11&var=2"   # 触发器 #11 FXSelect，var=2 → 呼吸
curl.exe -X POST "http://192.168.58.109/api/trigger?num=16"         # 开照度联动（#17 关）
curl.exe -X POST "http://192.168.58.109/api/timeline" -H "Content-Type: application/json" -d @tl.json  # tl.json: {"action":"start","num":1}
```

输出值前缀含义：`"255"`=正常输出，`"!255"`=Override，`"=0"`=外部直通源。

## 4. 照度自动调光（LPC 自治，2026-10-10 起）

照度采集与闭环全部在 LPC 内运行，**不依赖 Ubuntu/网络**：

- 触发器 **#14 LuxPoll**（Real Time，每秒）→ Output Serial 发 Modbus 轮询帧 `02 03 00 02 00 02 65 F8`（hex，RS485 口 4800）
- 触发器 **#15 LuxIn**（Serial Input，hex 匹配 `020304<4c><2c>`）→ Lua 自适应闭环（在线辨识灵敏度 k=Δlux/Δlevel，步长=err/k 一步到位、上限 20%、误差变号减半、限幅 5%~100%；`lux_value=lux` 全局暴露）
- 联动开关：全局变量 `lux_link_on`（默认 true），由触发器 #16（串口 `LLON` 或 HTTP）/ #17（`LLOFF`）切换
- **网页可调参数**（控制台"照度联动"卡，立即生效）：目标照度 `lux_target`（#9 / `LXT=`）、轮询周期 `lux_poll_s` 1~60s（#19 / `PER=N`，=闭环调节间隔，照度采集仍每秒）、渐变时间 `lux_fade` 0.1~10s（#18 / `FAD=N`，单位 0.1s）、死区 `lux_deadband` 1~1000 Lux（#20 / `DBD=N`，**默认 1**）；步长上限 20% / 限幅 5%~100% 为脚本常量，灵敏度 k 在线自动辨识无需手调
- Ubuntu 侧 `lux_sync.py` / `poll_lux.py` **已停用**（避免双主机抢总线）；网页控制台照度改读 `/api/lua?variables=lux_value`

## 5. 常见问题

| 现象 | 排查 |
|------|------|
| 发命令无反应 | 检查波特率 **4800**、帧尾 `\n`、命令前缀大小写；用 `/api/log` 看触发记录 |
| 上传项目后灯不亮 | Upload 会清空 Override，重新发一次 `SC=` 或 `FX=` |
| 通道显示 `=0` | eDMX Pass-Through 被打开，外部源黑场压过本地；改回 None |
| 亮度偏暗 | BRT/LUX 总调光系数不是 100%，发 `BRT=100` 或查 `/api/group` |
| 修改了 Designer 项目 | 务必 Save Project → Upload All → 归档 pd2 到项目目录 |