alxndrchernov/auto-lamp

# auto-lamp 通过 USB 从任何计算机控制 **小米米家显示器挂灯 (MJGJD01YL)**，使用一块廉价的 **RF-NANO** 开发板（Arduino Nano + nRF24L01）作为 2.4 GHz 无线电桥接。 ``` PC ──USB/serial── RF-NANO (ATmega328P + nRF24L01) ──2.4 GHz RF── Light Bar host CLI / library generic serial bridge firmware Telink TLSR8368 ``` 与大多数现有项目不同，本项目是**由主机驱动**的：无线电逻辑存在于一个小型固件中，该固件通过串口使用纯文本协议进行通信，并由一个跨平台的主机程序（此处的 Go CLI）进行驱动。你**不**需要 Raspberry Pi，也**不**需要原始遥控器——请参阅[配对](#pairing-no-remote-needed)。 ## 我们使用的硬件 | 部件 | 具体型号 | 备注 | |------|-------------|-------| | 台灯 | **小米米家显示器挂灯 `MJGJD01YL`** | 由无线旋转遥控器控制的非 BLE 版本 | | 无线电桥接 | **RF-NANO**（带有板载 nRF24L01 的 Arduino Nano 克隆版） | 在我们的设备上为 `CE=D10`, `CSN=D9`（某些修订版可能会互换） | | 数据线 | USB → Mini/Micro-USB | 取决于你的 RF-NANO 使用的接口 | 普通的 Arduino Nano + 独立的 nRF24L01+ 模块也可以工作；只需连接 `CE`/`CSN`/SPI 并在固件中调整引脚 `#define` 即可。 台灯遥控器使用的是 Telink TLSR8368，在 PHY 层*几乎*与 nRF24 兼容，这正是实现此 hack 的基础。 ## 工作原理 * 只有遥控器（以及我们的桥接器）会进行发射；台灯是一个纯粹的接收器，就像无线鼠标的接收器一样。没有确认机制或配对加密。 * 台灯接受来自它绑定的任何 3 字节“遥控器 ID”的命令。 * 你可以通过在台灯通电后的短时间内发送 `reset` 命令，将台灯绑定到**你选择的任何 ID**。不需要原始遥控器。 完整的字节级详情：[`docs/PROTOCOL.md`](docs/PROTOCOL.md)。 ## 快速开始 ### 1. 烧录固件 使用 [PlatformIO](https://platformio.org/)： ``` cd firmware pio run -t upload ``` 在 nRF24 初始化完成后，开发板会在启动时通过串口打印 `READY`。 ### 2. 构建主机 CLI 需要 Go 1.22+。 ``` go build -o lamp ./cmd/lamp ``` ### 3. 配对（无需遥控器！） ``` ./lamp pair --port /dev/cu.usbserial-10 # macOS example; pick your port # Linux: /dev/ttyUSB0 # Windows: COM3 ``` 按照提示操作：拔下台灯，重新插上，然后在几秒钟内按下 Enter 键。当台灯绑定到所选 ID（默认为 `11:11:11`）时，它会**闪烁一次**。端口和 ID 会保存到配置文件中，因此之后你可以省略 `--port`。 ### 4. 控制它 ``` ./lamp on # on/off (it is a single toggle) ./lamp bright +5 # brightness up (step 1..15) ./lamp bright -3 # brightness down ./lamp warm +5 # cooler (see note in CLI reference) ./lamp warm -2 # warmer ``` ## CLI 参考 ``` lamp [--port DEV] [arg] pair [AA:BB:CC] Bind the lamp to an ID of your choice (no original remote needed). Defaults to the saved ID, then to 11:11:11. scan Listen for the original remote's ID and save it (Ctrl-C to stop). set-id [AA:BB:CC] Write a Remote ID to firmware EEPROM + config manually. on / off Toggle the lamp (same code; the lamp has no discrete on/off). bright +N | -N Brightness step, N = 1..15. warm +N | -N Colour-temperature step, N = 1..15. reset Factory-reset the lamp. config Show the saved port and ID. --port DEV Serial device. Defaults to config, then /dev/ttyUSB0. ``` **备注 / 注意事项** * `on` 和 `off` 发送**相同**的切换代码（`0x01 0x00`）；该协议没有绝对的开/关。每次调用都会翻转当前状态。 * `warm +N` 当前发送*冷色*代码（`0x02`），而 `warm -N` 发送*暖色*代码（`0x03`）。可随意重命名——请参阅 [`TODO.md`](TODO.md)。 * 不要同时运行两个 `lamp` 进程 → `Serial port busy`。 * 亮度/暖度值为带符号的（`-3`），需手动解析，以免 shell/flags 在处理前导 `-` 时出错。 ## 项目结构 ``` lib/ ├── firmware/ │ ├── platformio.ini # PlatformIO: atmelavr / nanoatmega328new / RF24 │ ├── src/main.cpp # serial-bridge firmware (protocol + UART parser) │ └── sws_reader/ # optional: read the remote's ID off its Telink chip via SWS ├── cmd/lamp/main.go # host CLI ├── internal/ │ ├── config/ # config file (~/.config/lamp/config.json) │ └── serial/ # serial port wrapper (115200, READY handshake) ├── docs/PROTOCOL.md # byte-level protocol + attribution ├── TODO.md # roadmap to turn this into a real library ├── go.mod # module: github.com/alxndrchernov/auto-lamp └── LICENSE ``` ## 致谢 * **协议逆向工程：** [lamperez/xiaomi-lightbar-nrf24](https://github.com/lamperez/xiaomi-lightbar-nrf24) — 数据包格式、CRC 参数、命令代码以及电源循环配对技巧均出自此项工作。 * 相关实现与先例技术： * [ebinf/lightbar2mqtt](https://github.com/ebinf/lightbar2mqtt) — ESP32 + MQTT / Home Assistant * [BAJ810/xiaomi-lightbar-nrf24-esp32](https://github.com/BAJ810/xiaomi-lightbar-nrf24-esp32) * [eugene-reim/lightbar2mqtt-esp8268](https://github.com/eugene-reim/lightbar2mqtt-esp8268) * [benallen-dev/xiaomi-lightbar](https://github.com/benallen-dev/xiaomi-lightbar) — Arduino Nano sketch 本项目在上述基础之上增加了：**主机驱动、跨平台**的控制路径（PC ↔ USB-serial ↔ 通用桥接固件），以及一种**配对优先**的工作流程，既不需要 Raspberry Pi，也不需要原始遥控器。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。

标签：Arduino, Go语言, 射频通信, 小米智能设备, 嵌入式开发, 日志审计, 物联网控制, 硬件桥接, 程序破解