FAQ

Connection timeout

Check the following:

Whether the device host and port are correct (1883 for MQTT, 8883 for MQTTS).
Whether the protocol matches the device model (L2PRO use MQTT; K2, H1, F1, and Porcam are known to use MQTTS, other models follow the port the device actually exposes).
Whether MQTTS has the username and password.

On a failed connection the wrapper's connect() raises an exception: an unreachable address or closed port raises OSError (including ConnectionRefusedError; a network timeout on Python 3.10+ is TimeoutError); if the TCP connection is up but no successful CONNACK arrives within 10 seconds (including the broker rejecting the connection) it raises TimeoutError, with the timeout set by ClientOptions.connect_timeout.

No response / request timeout

First check whether the device replied:

Replied with EC_ProtoError, desc is openapi auth error: the openapi_key is missing or wrong. The device replies immediately, so it is not a timeout.
No reply at all, request() raises TimeoutError: confirm the request topic matches the message type and the device is in a state that can respond. Some requests are not answered while the device is in standby, e.g. modeling_status and control_point; a response was measured while scanning. Right after boot the device may not be ready — retry device_info first.

request() defaults to a 10-second timeout, adjustable via the script argument --timeout or ClientOptions.request_timeout.

Protobuf version error

Run python python/src/generate_proto.py to regenerate the module, keeping the gencode consistent with the runtime protobuf version. The project uses the pure-Python implementation by default to avoid C-extension incompatibilities.

Point cloud decode fails

Check in order:

Install the decompression deps: pip install lz4 zstandard.
Confirm the device is scanning; subscribing to the pose in standby produced no data (measured), and the point cloud is only available while scanning.
CompressionLz4 data is the LZ4 block format; decompress it with lz4.block.decompress(data, uncompressed_size=compressed_size). Using lz4.frame fails with ERROR_frameType_unknown.
The decoded x, y, z, and scaler are strings; convert them to integers first, then divide the wire integer by header.scaler to reconstruct the coordinate — see Real-time Data.
An exception in a subscription callback is only logged and does not interrupt the program; watch the terminal log output while debugging.

For the full point cloud decoding steps, see Real-time Data.

How to fill enum fields

Enum fields accept the enum name string (recommended, e.g. "AC_START") or the integer value.

Note: a misspelled enum name or field name is not reported during encoding — it is silently ignored and the field is simply absent from the request. For example, writing "AC_START" as "AC_STRAT": codec.encode on {"action": "AC_STRAT"} alone produces empty bytes, and when sent via request() only the header remains, so the device sees action as AC_UNKNOW. An enum's zero value (e.g. SM_PCL, RM_CALC) is also not encoded on the wire, so the device sees the request as if the field were not specified. When a parameter has no effect, verify the field and enum names with codec.default_json("<message name>").

Measure point / data unpack has no effect

These two features are supported only on specific models and firmware. Before use, query the firmware version via the device info and confirm with XGRIDS whether the target device provides the capability. When the capability is missing or the conditions are not met, the device returns an error code — for example, sending a measure point request on a Lixel L2Pro (firmware V3.2.1) returned EC_RequestError (add point error) in testing. On devices that do not support measure points, the device-side source returns rtk unavailable or unsupported operation, and project data empty when there is no current project; these three were not measured.