FAQ

Build cannot find lz4 or OpenSSL

Install the development files libssl-dev and liblz4-dev, and pkg-config (lz4 is found through it). On Ubuntu:

sudo apt-get install -y libssl-dev liblz4-dev pkg-config

The first build is slow

The first configure builds the pinned protobuf release (3.21.12) from source. On the verified machine it took about 47 s with 20 parallel jobs. Later incremental builds do not repeat this step.

The generated code and the runtime must be the same protobuf release. The default option LIXEL_OPENAPI_PROTOBUF_PROVIDER=AUTO uses the system protobuf when it is 3.21.0 or newer, otherwise builds the pinned release. Set it to SYSTEM to force the system one, or FETCH to always build the pinned release.

MQTTS connection fails / certificate error

The C++ client verifies the server certificate by default, while the device uses a self-signed certificate. Two ways to handle it:

Pass the device certificate: --ca-file <path> in the examples.
Turn verification off: --insecure in the examples (matches the Python client's behavior, but does not verify identity; use for debugging only).

Note: this differs from Python — the Python client never verifies the certificate.

Request timeout / no response

Request returning RequestTimeout means no response with the same seq arrived within the timeout. Confirm the openapi_key is correct, the request and response topics match, and the device is in a state that can respond. Note the device may already have carried out the request; confirm with the device before assuming otherwise. The default timeout is 10 seconds, adjustable via ClientOptions::request_timeout.

Calling Request in a subscription callback does nothing

This is intentional: subscription callbacks run on the MQTT layer's thread, and calling Request there returns Errc::CalledFromCallback instead of blocking; Connect / Disconnect are also not allowed in a callback. Move request logic to a thread outside the callback.

Point cloud decode fails

The real-time point cloud is the LZ4 block format (not frame). Use the library's DecodePointCloud, which handles it correctly. A Zstd-compressed point cloud and a negative header.scaler return Errc::Unsupported.

Can I use it on Windows / macOS

Only Linux is supported and verified for now. Other platforms, MQTTS against a real device, and ThreadSanitizer are not verified.