1. FujitsuAC 开源库深度解析面向嵌入式工程师的 Fujitsu 空调本地化控制方案1.1 项目定位与工程价值FujitsuAC 是一个专为 ESP32 平台设计的开源固件库其核心目标是完全替代 Fujitsu 原厂 UTY-TFSXW1 / UTY-TFSXF3 WiFi 通信模块实现对 Fujitsu 全系列变频空调含 FGLair® App 兼容机型的纯本地、零云依赖、高可靠性控制。该方案不依赖任何云端服务或官方 App所有协议解析、状态管理、指令下发均在 ESP32 本地完成从根本上规避了厂商停服、网络中断、隐私泄露等智能家居系统常见风险。从嵌入式系统工程角度看该项目的价值远超“遥控器替代”层面协议逆向工程实践范本完整复现 Fujitsu 空调 UART 串行通信协议栈涵盖物理层电平适配、链路层帧结构、应用层命令集及状态反馈机制工业级硬件接口设计针对空调主控板非隔离 UART 接口CN3903 插座的电气安全约束提出符合 IEC 61000-4-5 浪涌防护要求的 DC/DC 隔离 逻辑电平转换双保险方案嵌入式 OTA 升级架构基于 ESP32 的 Secure Boot Flash Encryption OTA 分区机制实现带签名验证的远程固件更新满足消费电子类产品量产安全规范Home Assistant 深度集成通过 MQTT Auto-Discovery 协议自动注册设备实体支持温度设定、模式切换、风速调节、定时开关等全部 HVAC 功能且可无缝接入 Zigbee2MQTT、ESPHome 等主流生态。关键工程警示空调 CN3903 接口为非隔离设计其 GND 电位浮动于市电火线/零线之间典型共模电压达 ±50V。若直接将 ESP32 GND 与 PC USB GND 连通将形成地环路电流瞬间击穿 ESP32 的 USB-to-Serial 芯片如 CP2102及空调主板 MCU 的 UART 收发器。本项目强制要求使用 DC/DC 隔离模块12V→5V 双向逻辑电平转换器TX/RX 独立隔离此为不可妥协的安全底线。1.2 硬件架构与电气设计原理1.2.1 物理连接拓扑FujitsuAC 模块采用两级隔离架构严格遵循工业控制设备接地规范[空调主板 CN3903] │ ├── Pin1 (12V) → DC/DC 隔离模块 Vin → Vout → ESP32 5V 输入 ├── Pin2 (GND) → DC/DC 隔离模块 Vin- → Vout- → ESP32 GND隔离域 ├── Pin3 (DATA_OUT) → 逻辑电平转换器 HV侧 → LV侧 → ESP32 GPIO16 (RX) └── Pin4 (DATA_IN) → ESP32 GPIO17 (TX) → 逻辑电平转换器 LV侧 → HV侧DC/DC 隔离模块必须选用输入/输出间耐压 ≥1500VDC 的隔离型 DC/DC如 RECOM R-78E5.0-0.5其作用不仅是降压更是切断空调主板与 ESP32 之间的地电位耦合路径逻辑电平转换器采用 TXB0104 或 SN74LVC4245 等双向自动方向检测芯片HV 侧接空调 UART标称 3.3V实测摆幅 0~12VLV 侧接 ESP323.3V TTL避免因空调 UART 输出高电平超标导致 ESP32 IO 永久性击穿。1.2.2 关键器件选型依据器件类型推荐型号/参数工程选型理由DC/DC 隔离模块RECOM R-78E5.0-0.5 (12V→5V, 500mA)输入耐压 1500VDC效率 85%内置 EMI 滤波满足 EN55032 Class B 辐射标准逻辑电平转换器TI TXB0104 (4通道双向)自动方向检测无外部使能信号支持 1.2V~3.6V ↔ 1.65V~5.5V 电平转换传播延迟 10nsESP32 主控ESP32-WROOM-32 (30pin)内置 4MB Flash支持 OTA 分区Wi-Fi 802.11 b/g/nBT 4.2GPIO16/17 为 UART2 引脚连接器JST PHR-4 (P1.25mm)与空调 CN3903 插座完全兼容插拔寿命 20 次防误插卡扣设计成本优化提示批量采购时DC/DC 模块¥2.65/5pcs、ESP32¥4.40、JST 连接器¥3.00/5pcs、PCB 板¥2.00/5pcs、逻辑电平转换器¥2.50/5pcs合计单套 BOM 成本约 ¥14.55。若自焊 5 套单套成本可降至 ¥6.50显著低于原厂 UTY-TFSXW1 模块市价 ¥120。1.3 Fujitsu 空调通信协议逆向分析1.3.1 物理层与链路层规范Fujitsu 空调 UART 接口工作在9600bps, 8N1标准格式但存在两个关键非标特性电平摆幅异常实测 DATA_IN/OUT 引脚在空闲态为 0V逻辑高电平可达 12V非标准 3.3V 或 5V直接连接 ESP32 将导致 IO 损毁帧间间隔敏感发送指令后必须等待 ≥150ms 才能接收响应否则空调主控会丢弃后续数据帧。协议帧结构采用HDLC-like 封装每帧由以下字段组成字段长度说明SOF (Start)1B固定值0x02帧起始标志LEN (Length)1B后续数据长度不含 SOF/LEN/CRC最大 0x1F31 字节CMD (Command)1B命令码如0x10读取状态、0x11设置模式、0x12设置温度等DATAN B命令参数长度由 LEN 字段指定如设置温度时为0x1E30℃CRC (Checksum)1B从 SOF 到 DATA 最后一字节的累加和低 8 位用于校验帧完整性EOF (End)1B固定值0x03帧结束标志1.3.2 核心应用层命令集FujitsuAC 库已完整实现 Fujitsu 空调全功能控制主要命令如下表所示基于 ASYG/ASTG 系列实测命令码功能DATA 示例说明0x10读取当前状态0x00返回包含运行模式、设定温度、室内温度、风速、定时状态等 28 字节数据包0x11设置运行模式0x010x00关机,0x01制冷,0x02制热,0x03送风,0x04除湿,0x05自动0x12设置设定温度0x1E(30℃)范围0x14(20℃) ~0x23(35℃)步进 0.5℃需配合0x11命令生效0x13设置风速0x030x00自动,0x01低,0x02中,0x03高,0x04超强0x14设置上下扫风0x010x00关,0x01开部分机型支持0x15设置左右扫风0x010x00关,0x01开部分机型支持0x16设置睡眠模式0x010x00关,0x01开0x17设置定时开关0x01 0x1E0x01开机定时,0x00关机定时0x1E30 分钟0x00~0x3C单位分钟协议健壮性设计库中FujitsuAC::sendCommand()函数内置三次重传机制每次重传间隔 200ms并在发送前执行uart_flush()清空发送缓冲区。接收端采用超时中断UART_INTR_RX_TOUT DMA 接收确保在空调响应延迟波动时仍能可靠捕获完整帧。1.4 软件架构与核心 API 解析1.4.1 整体软件栈分层FujitsuAC 固件采用分层架构设计各层职责清晰便于维护与扩展┌─────────────────────────────────────────────────────────────────────┐ │ Application Layer: HomeAssistant MQTT Integration (PubSubClient) │ ├─────────────────────────────────────────────────────────────────────┤ │ Protocol Layer: FujitsuAC Class (Command Encoding/Decoding) │ ├─────────────────────────────────────────────────────────────────────┤ │ HAL Layer: ESP-IDF UART Driver (uart_driver_install, uart_param_config) │ ├─────────────────────────────────────────────────────────────────────┤ │ Hardware Abstraction: GPIO Control (for Reset Button, LED Status) │ └─────────────────────────────────────────────────────────────────────┘1.4.2 FujitsuAC 类核心 API// 初始化空调通信指定 UART 号、TX/RX 引脚、波特率 FujitsuAC(uint8_t uart_num, int tx_pin, int rx_pin, uint32_t baud_rate 9600); // 发送控制命令阻塞式返回 true 表示成功 bool sendCommand(uint8_t cmd, const uint8_t* data, uint8_t len); // 读取空调当前状态返回状态结构体指针 const FujitsuState* readState(); // 设置空调模式封装了 0x11 命令 void setMode(FujitsuMode mode); // enum FujitsuMode { OFF, COOL, HEAT, FAN, DRY, AUTO } // 设置设定温度封装了 0x12 命令自动处理 0.5℃ 步进 void setTargetTemp(float temp_c); // 获取室内环境温度从最新状态帧解析 float getIndoorTemp(); // 强制同步空调状态主动轮询用于 HA 状态恢复 void forceSync();1.4.3 状态数据结构定义struct FujitsuState { bool isOn; // 是否开机 FujitsuMode mode; // 当前运行模式 float targetTemp; // 设定温度℃ float indoorTemp; // 室内温度℃ FujitsuFanSpeed fanSpeed; // 风速等级 bool swingVertical; // 上下扫风使能 bool swingHorizontal; // 左右扫风使能 bool sleepMode; // 睡眠模式使能 uint8_t timerMinutes; // 定时剩余分钟数0 表示未启用 uint32_t lastUpdateMs; // 最后更新时间戳毫秒 };1.5 Home Assistant 集成与 MQTT Auto-Discovery 实现1.5.1 MQTT 主题设计规范FujitsuAC 严格遵循 Home Assistant 的 MQTT Discovery 协议v1.0设备注册主题为homeassistant/climate/device_id/config其中device_id为 ESP32 MAC 地址后 6 位如a1b2c3确保全局唯一性。1.5.2 Discovery Payload 关键字段{ name: Fujitsu AC, unique_id: fujitsu_ac_a1b2c3, state_topic: fujitsu/ac/a1b2c3/state, command_topic: fujitsu/ac/a1b2c3/set, temperature_state_topic: fujitsu/ac/a1b2c3/temperature, temperature_command_topic: fujitsu/ac/a1b2c3/temperature/set, mode_state_topic: fujitsu/ac/a1b2c3/mode, mode_command_topic: fujitsu/ac/a1b2c3/mode/set, fan_mode_state_topic: fujitsu/ac/a1b2c3/fan_mode, fan_mode_command_topic: fujitsu/ac/a1b2c3/fan_mode/set, swing_mode_state_topic: fujitsu/ac/a1b2c3/swing_mode, swing_mode_command_topic: fujitsu/ac/a1b2c3/swing_mode/set, min_temp: 20, max_temp: 35, temp_step: 0.5, modes: [off, cool, heat, fan_only, dry, auto], fan_modes: [auto, low, medium, high, very_high], swing_modes: [off, on], device: { identifiers: [fujitsu_ac_a1b2c3], name: Fujitsu AC, model: ASYG09KMTB, manufacturer: Fujitsu General } }1.5.3 MQTT 消息处理流程当 HA 发送fujitsu/ac/a1b2c3/set消息时固件解析 JSON 并映射到 FujitsuAC API// 示例处理模式切换 if (strcmp(topic, fujitsu/ac/a1b2c3/mode/set) 0) { if (strcmp(payload, cool) 0) { ac.setMode(COOL); } else if (strcmp(payload, heat) 0) { ac.setMode(HEAT); } else if (strcmp(payload, off) 0) { ac.setMode(OFF); } }1.6 OTA 固件升级机制详解1.6.1 双分区 OTA 架构FujitsuAC 采用 ESP32 标准 OTA 分区表partitions.csv包含otadata存储当前运行分区信息app_0 或 app_1app_0主应用程序分区当前运行app_1备用应用程序分区OTA 更新目标nvs非易失性存储区保存 WiFi/MQTT 凭据1.6.2 网络 OTA 流程触发更新HA 点击 “Update Firmware” 按钮向fujitsu/ac/a1b2c3/ota主题发布{url:https://example.com/firmware.bin}下载校验ESP32 使用esp_http_client下载固件同时计算 SHA256 校验和并与预置签名比对写入备用分区校验通过后固件流式写入app_1分区标记启动调用esp_ota_set_boot_partition()将app_1设为下次启动分区安全重启执行esp_restart()BootROM 加载新固件。安全增强自 v1.1.6 起固件镜像需经 RSA-2048 签名ESP32 启动时通过esp_secure_boot_verify_signature()验证签名有效性防止恶意固件注入。1.7 实际部署与调试指南1.7.1 首次配置流程上电后 ESP32 创建 SoftAPSSID 为Fujitsu-MAC_SUFFIX如Fujitsu-a1b2c3手机/PC 连接该热点浏览器访问http://192.168.1.1在 Web 表单中填写WiFi SSID/Password2.4GHz 网络MQTT Broker 地址如mqtt://192.168.1.100:1883MQTT 用户名/密码如启用认证设备名称HA 中显示名OTA 密码用于固件更新鉴权提交后设备自动重启并连接配置网络。1.7.2 常见问题诊断现象可能原因解决方案无法创建 SoftAPESP32 WiFi 模块故障检查CONFIG_ESP_WIFI_ENABLEDy编译选项连接 WiFi 后无法访问 MQTTMQTT Broker 地址错误或防火墙拦截使用mosquitto_sub -h broker_ip -t #测试连通性空调无响应或状态不更新UART 电平不匹配或接线错误用示波器测量 CN3903 Pin3/Pin4 电平确认是否需逻辑电平转换器HA 中设备显示 “unavailable”MQTT Discovery 主题未正确发布检查串口日志确认homeassistant/climate/xxx/config是否发布成功1.7.3 生产级加固建议Flash 加密编译时启用CONFIG_SECURE_FLASH_ENC_ENABLEDy防止固件被读取Secure Boot烧录前生成 RSA-3072 签名密钥启用CONFIG_SECURE_BOOT_V2_ENABLEDy看门狗监控在主循环中调用esp_task_wdt_reset()避免 UART 协议死锁导致系统挂起电源管理空调待机时通过esp_sleep_enable_timer_wakeup(30000000)设置 30 秒唤醒周期降低功耗至 15mA。2. 结语从协议逆向到产品化落地的工程实践FujitsuAC 项目本质是一次完整的嵌入式系统工程闭环从空调 UART 信号的示波器捕获与协议逆向到隔离电源与电平转换的硬件安全设计从 ESP32 FreeRTOS 任务调度与 UART DMA 接收的底层驱动开发到 MQTT Auto-Discovery 与 HA 深度集成的应用层抽象最终落脚于 OTA 签名验证与 Flash 加密的量产安全规范。它证明了开源社区完全有能力构建出比原厂方案更可靠、更透明、更具扩展性的工业级控制模块。对于正在规划类似家电协议破解项目的工程师本项目的硬件隔离方案、协议状态机设计、以及 MQTT 与 HA 的标准化对接模式均具备直接复用价值。