The Lixel series is a line of handheld 3D scanners. Lixel OpenAPI is the set of open communication interfaces exposed by the device software. Through them you can remotely control a Lixel device, receive its data in real time, and build applications integrated with the device.
This page gives you the big picture. To get started right away, choose your development language: Python Quick Start or C++ Quick Start.
What the OpenAPI can do
- Control the device: start/stop scanning, configure parameters, reboot or power off, format storage, enable file sharing.
- Receive data in real time: subscribe to the real-time point cloud, real-time pose, device status, and system errors; get camera frames over the video stream.
- Manage data: manage the project list, control points and measure points, and unpack recorded data.
- Configure positioning: set RTK / Ntrip parameters and read the satellite positioning status.
Protocol architecture
The device and client communicate through an MQTT broker running on the device. All business messages are serialized with Protobuf and carried as the MQTT payload (the heartbeat is the exception, carried as JSON text). The real-time camera video stream is carried over the device's built-in RTSP service.
┌────────────┐ publish request ┌──────────────┐
│ │ ───────────────────► │ │
│ Client │ │ Lixel device │
│ (your app) │ ◄─────────────────── │ (MQTT Broker)│
│ │ response / report │ (RTSP Server)│
└────────────┘ └──────────────┘Topics use a three-segment naming scheme:
lixel/<domain>/<type>/<name>domain: business domain, mainlyapplication.type: message direction.request: client → device (request)response: device → client (reply to a request)report: device → client (active push)
name: specific feature, e.g.device_info,modeling.
There are two typical interaction patterns:
- Request-response: the client publishes to
.../request/xxxand subscribes to.../response/xxxto await the reply. - Subscribe-report: the client subscribes to
.../report/xxxand passively receives data pushed by the device.
Key conventions
| Convention | Description |
|---|---|
| Transport | MQTT / MQTTS, depending on the device model |
| Payload | Protobuf binary (JSON text for the heartbeat) |
| Proto package | openapi.aiot_msgs |
| Authentication | The request header carries the OpenAPI Key, provided by XGRIDS |
| Video stream | RTSP, pushed after scanning starts |
| Development | Python or C++; both share the same MQTT topics and proto definition |
| Version | The documentation version v1.1.0 corresponds to the example project Lixel_OpenAPI release tag 1.1.0 (that release moved Python into python/ and added the C++ client). The device protocol version is separate: the ProtocolVersion in the device heartbeat was measured as 3.0.0 on a Lixel L2Pro, firmware V3.2.1 |
Note: the interface catalog and message fields follow the public proto (
proto/openapi/aiot_msgs.protoin the example project). The device's internal proto defines more than the public one; the extra parts are out of scope here.
Documentation map
The protocol itself is language-independent; the following shared chapters apply to both Python and C++:
| Shared chapter | Content |
|---|---|
| Connection & Authentication | USB / Wi-Fi / Bluetooth provisioning, MQTT/MQTTS parameters, OpenAPI Key |
| Message Model & Codec | Topic rules, proto compilation, JSON ↔ Protobuf |
| Interface Catalog | Status monitoring, device management, scan mapping, points, projects, RTK/Ntrip, data processing |
| Real-time Data | Real-time point cloud decompression, real-time pose, RTSP video stream |
| Project File Access | Access project files over file sharing |
| Error Codes | Error code categories and meanings |
Choose an entry by development language:
This chapter is from the official XGRIDS user manual. Official source (opens in a new tab) · Updated:
