Xgimi-4-Home-Assistant项目：XGIMI投影仪控制协议解析与故障排查指南

Xgimi-4-Home-Assistant项目：XGIMI投影仪控制协议解析与故障排查指南

Xgimi-4-Home-Assistant XGIMI integration for home assistant 项目地址: https://gitcode.com/gh_mirrors/xg/Xgimi-4-Home-Assistant

项目背景与功能概述

Xgimi-4-Home-Assistant是一个专为XGIMI投影仪设计的Home Assistant集成项目，它通过两种不同的通信协议实现对投影仪的全面控制：

1. 蓝牙低功耗(BLE)广播：专门用于开机功能
2. UDP局域网通信：用于关机、音量调节、输入源选择等大部分控制功能

这两种通信方式相互独立，互不影响。这意味着BLE开机功能正常并不意味着UDP控制也能正常工作，反之亦然。

协议实现细节

BLE广播开机机制

该功能需要配置token参数，其工作原理是：

• 通过蓝牙广播特定数据包唤醒处于待机状态的投影仪
• 仅适用于支持BLE唤醒功能的XGIMI机型
• 需要投影仪处于待机状态而非完全断电

UDP控制协议

UDP控制需要配置投影仪的IP地址，通过以下端口实现不同功能：

• 16735/UDP：主要控制端口
• 16750/UDP：辅助控制端口
• 554/UDP：用于电源状态检测（仅部分机型支持）

常见问题排查指南

UDP控制失效的排查步骤

1. 网络连通性验证

   • 确认投影仪IP地址正确无误
   • 确保Home Assistant主机能够访问投影仪IP
   • 检查网络访问限制设置，确保UDP端口未被阻止

2. 端口状态检测 使用nmap工具检查关键UDP端口状态：

   nmap -sU -p 16735,16750,554 [投影仪IP]
   

3. 机型兼容性分析

   • 中国版XGIMI设备通常支持UDP控制协议
   • 国际版设备可能使用不同的控制协议
   • 部分新型号可能改用纯Android TV协议

替代方案建议

对于不支持UDP控制协议的设备，推荐使用以下方案：

1. 官方Android TV远程控制集成
2. 红外遥控方案（如Broadlink等）
3. HDMI-CEC控制（如投影仪支持）

设备兼容性现状

根据用户反馈，目前已确认：

• 支持UDP控制的机型：XGIMI Z6X等中国版设备
• 不支持UDP控制的机型：XGIMI HORIZON (XK03H)、Halo+等国际版设备

对于国际版设备，这些设备通常：

• 运行原生Android TV系统
• 仅开放TCP控制端口（8008、8009、8443等）
• 完全兼容标准Android TV远程控制协议

技术建议与最佳实践

1. 混合控制方案：

   • 使用本项目的BLE功能实现开机
   • 结合Android TV集成实现其他控制功能

2. 网络优化建议：

   • 为投影仪分配静态IP
   • 确保投影仪与HA主机处于同一子网
   • 考虑使用有线连接提高可靠性

3. 开发建议：

   • 国际版用户可贡献设备信息帮助扩展协议支持
   • 开发者可考虑增加TCP协议支持

总结

Xgimi-4-Home-Assistant项目为XGIMI投影仪提供了深度集成方案，但用户需根据设备型号和区域版本选择合适的控制方式。中国版设备通常支持完整的BLE+UDP控制，而国际版设备可能需要结合Android TV集成使用。通过本文提供的排查方法和替代方案，用户可以构建稳定可靠的投影仪自动化控制系统。

Xgimi-4-Home-Assistant XGIMI integration for home assistant 项目地址: https://gitcode.com/gh_mirrors/xg/Xgimi-4-Home-Assistant