常见问题

连接超时怎么办

检查以下几点：

设备地址与端口是否正确（1883 为 MQTT，8883 为 MQTTS）。
协议是否匹配设备型号（K1 / L2PRO 用 MQTT；已知 K2、H1、F1、Porcam 用 MQTTS，其他型号以设备实际开放的端口为准）。
MQTTS 是否带上了用户名和密码。

连接失败时客户端封装的 connect() 会抛出异常：地址不可达或端口未开放时抛出 OSError（含 ConnectionRefusedError；Python 3.10 及以上的网络超时是 TimeoutError）；已连上 TCP 但 10 秒内没有收到成功的 CONNACK（包括 broker 拒绝连接）时抛出 TimeoutError，超时时间由 ClientOptions.connect_timeout 设置。

请求无响应 / 超时

先看设备有没有回复：

回复了 EC_ProtoError，desc 为 openapi auth error：openapi_key 缺失或不正确。设备会立即回复，不会超时。
完全没有回复，request() 抛出 TimeoutError：确认请求 Topic 与消息类型是否匹配，以及设备是否处于可响应状态。部分请求在设备待机时不会被回复，例如 modeling_status 和 control_point；扫描中实测有响应。刚开机时，业务可能还没就绪，先重试 device_info。

request() 默认 10 秒超时，可通过脚本参数 --timeout 或 ClientOptions.request_timeout 调整。

Protobuf 版本报错

运行 python python/src/generate_proto.py 重新生成模块，保持生成代码与运行时的 protobuf 版本一致。项目默认使用纯 Python 实现，规避 C 扩展不兼容。

点云解码失败

按顺序检查：

安装解压依赖：pip install lz4 zstandard。
确认设备处于扫描中；待机时订阅位姿实测没有数据，点云是在扫描中取到的。
CompressionLz4 数据是 LZ4 block 格式，用 lz4.block.decompress(data, uncompressed_size=compressed_size) 解压；用 lz4.frame 会报 ERROR_frameType_unknown。
解码后的 x、y、z 与 scaler 是字符串，先转成整数，再用线上整数除以 header.scaler 还原坐标，见实时数据。
订阅回调里的异常只会被记录到日志，不会中断程序；调试时留意终端里的日志输出。

点云的完整解码步骤见实时数据。

枚举字段怎么填

枚举字段可以用枚举名字符串（推荐，如 "AC_START"），也可以用整数值。

注意：编码时拼写错误的枚举名和字段名不会报错，会被直接忽略，请求里就缺少这个字段。例如把 "AC_START" 写成 "AC_STRAT"，codec.encode 单独对 {"action": "AC_STRAT"} 编码得到空字节；经 request() 发送时只剩消息头，设备收到的 action 是 AC_UNKNOW。枚举的零值（如 SM_PCL、RM_CALC）在线上也不会被编码，设备收到的请求里等于没有指定该字段。参数没生效时，先用 codec.default_json("<消息名>") 核对字段名与枚举名。

测量点 / 数据解包不生效

这两类功能仅部分型号、部分固件支持。使用前通过设备信息查询固件版本，并向 XGRIDS 确认目标设备是否具备该能力。不具备该能力或条件不满足时，设备会返回错误码，例如在 Lixel L2Pro（固件 V3.2.1）上发送测量点请求，实测返回 EC_RequestError（add point error）。不支持测量点的设备，按设备端源码会返回 rtk unavailable 或 unsupported operation，没有当前工程时返回 project data empty，这三种未实测。