Overview

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, mainly application.
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/xxx and subscribes to .../response/xxx to await the reply.
Subscribe-report: the client subscribes to .../report/xxx and 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.proto in 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:

Entry	Content
Python	OpenAPI-XPanel GUI, 18 example scripts, reusable client (Linux / Windows)
C++	Client library and 18 command line examples (Linux only)