Interface Catalog

This page lists all interfaces by function group. Every topic is prefixed with lixel/application/, omitted in the tables. Direction markers: REQ=request, RSP=response, RPT=report (see Message Model & Codec).

Status monitoring

Among the interfaces exposed by the OpenAPI, only the heartbeat uses JSON text, for discovering a device and reading the protocol version:

{"DeviceSN":"A256A60000","Timestamp":1697703246.5,"ProtocolVersion":"3.0.0"}

• DeviceSN: device serial number.
• Timestamp: current device time.
• ProtocolVersion: protocol version, for compatibility design.

The device status is reported once per second, carrying the mapping state, system resources, and RTK status:

message DeviceStatusReport {
    message DeviceStatus {
        sint32 app_sessions = 1; // number of APP sessions
    }
    Header header = 1;
    uint32 modeling_state = 2; // unified status code
    string device_sn = 3;      // device serial number
    string project_id = 4;     // project name
    string time_zone = 5;      // current time zone
    bool init_ready = 6;       // 0: not initialized, 1: initialized
    SystemStatus system_status = 7;
    RtkStatus rtk_status = 8;
    DeviceStatus device_status = 9;
}

For decoding the real-time point cloud and pose, see Real-time Data.

Device management

Device control supported ActionCmd: AC_USB_MASS, AC_USB_ETHER, AC_DISK_FORMAT, AC_POWER_OFF, AC_SYSTEM_REBOOT, plus the file-sharing switches AC_START_FS / AC_STOP_FS (see Project File Access; a fixed default credential is used once enabled). AC_DISK_FORMAT, AC_POWER_OFF, and AC_SYSTEM_REBOOT erase data or power off / reboot the device — confirm before calling.

message DeviceControlRequest {
    Header header = 1;
    Application.ActionCmd action = 2;
}

message DeviceControlResponse {
    Header header = 1;
    Application.ActionCmd action = 2;
    Error error = 15;
}

Device config supports setting the time and the main storage type:

message DeviceConfigRequest {
    message TimeConfig {
        sint64 time_secs = 1; // timestamp (second precision)
        string time_zone = 2; // time zone (e.g. "Asia/Shanghai")
    }
    message MainStorageConfig {
        sint32 storage_type = 1; // 0: internal storage, 1: TF card, 2: USB Disk
    }
    Header header = 1;
    optional TimeConfig time_config = 4;
    optional MainStorageConfig main_storage_config = 8;
}

Scan mapping

Scan action supports AC_START / AC_STOP. The response to AC_START only means the device received the request; the device then goes standby → starting → scanning (measured to reach scanning after 14 to 15 seconds), and an AC_STOP sent before it is scanning is deferred. Subscribe to report/device_status and read modeling_state instead of waiting a fixed time — see Quick Start (Python / C++).

modeling_status returns the current project's project_id and project_name, plus the URLs of the pose, control point, and measure point files; it does not return the scan state — use modeling_state from report/device_status for that. When the device has no current project data it returns without publishing a response; in standby there was no response (2 timeouts measured), and request() raises TimeoutError.

Key fields:

message ModelingRequest {
    Header header = 1;
    Application.ActionCmd action = 2;    // supports AC_START / AC_STOP
    string project_name = 3;             // custom project name
    Modeling.RecordMode record_mode = 4; // RM_CALC / RM_RECORD / RM_RECORD_CALC
    Modeling.ScanMode scan_mode = 5;     // SM_PCL / SM_LCC / SM_PORTRAIT
    Modeling.MountType mount_type = 6;   // MT_HAND / MT_CAR / MT_UAV / MT_BACKPACK
    string pre_project_id = 7;           // preceding project ID (continued-scan feature in later versions)
    Modeling.AssistMode assist_mode = 8; // scan assist mode AM_GUIDED / AM_VISUAL
}

The scan status report (report/modeling) carries the travel distance, speed, scan time, and the post-scan data-processing progress:

message ModelingReport {
    message ScanStatus {
        float move_distance = 1; // travel distance
        float move_speed = 2;    // movement speed
        sint64 scan_time = 3;    // scan time (seconds)
    }
    Header header = 1;
    sint32 pgo_progress = 2; // post-scan data-processing progress (0~100)
    ScanStatus scan_status = 3;
}

Point management

Control point action supports AC_ADD / AC_REMOVE. AC_UPDATE is defined in the proto but the device does not handle it and returns EC_ProtoError (desc is invalid action). Measure point action supports AC_ADD / AC_REMOVE only. The comment in the proto block below keeps the device-side original text saying AC_UPDATE is supported; follow the description here instead.

In standby the device does not reply to control point requests; in other states it does (only scanning was measured here), and returns EC_RequestError (desc is no project data) when there is no current project data. AC_ADD was measured to ignore the id in the request; the id in the response is chosen by the device and used to remove the point. On a successful AC_ADD, error.desc is the pose of the point (x y z qw qx qy qz, 7 floating-point numbers separated by spaces), not a text description.

Note: the measure point feature is supported on some devices only; verify that your target device provides it before use.

message ControlPointRequest {
    Header header = 1;
    Application.ActionCmd action = 2; // supports AC_ADD / AC_REMOVE / AC_UPDATE
    sint32 id = 3;                    // control point ID
    sint32 type = 4;                  // type (0: device, 1: centering pole, 100: legacy)
    string label = 5;                 // control point label
    sint32 height = 6;                // base point height (unit: mm)
}

Project management

action supports:

• AC_LIST_ALL_PROJECTS: list all projects.
• AC_MODIFY_PROJECT_LABELS: modify labels (needs id + tag_name).
• AC_DELETE_PROJECTS: delete projects (needs id_list).

Modifying labels and deleting projects are rejected while the device is starting, scanning, or stopping a scan; do them in standby. The poses_url, xbin_url, etc. returned by AC_LIST_ALL_PROJECTS are HTTP URLs; for the host value, see Project File Access.

message ProjectListRequest {
    Header header = 1;
    // supports AC_LIST_ALL_PROJECTS / AC_MODIFY_PROJECT_LABELS / AC_DELETE_PROJECTS only
    Application.ActionCmd action = 2;
    optional string id = 3;
    optional string tag_name = 4;
    repeated string id_list = 5; // delete multiple projects at once
}

RTK / Ntrip

• Set Ntrip action supports AC_LOGIN / AC_LOGOUT.
• CORS type: CUSTOM / QIANXUN / ZHONGYI.
• Coordinate frame: UNKNOWN / ITRF2008 / WGS84 / CGCS2000.
• RTK satellite systems: GPS / BDS / GLO / GAL / QZSS / IRNSS.

Note: when the RTK hardware is not connected (RtkStatus.state is HwDisconnected) or there is no RTK device, the set-Ntrip request is rejected and the device returns EC_RequestError (desc is operation forbidden). There is also a record that when the device Wi-Fi is in AP mode (Ntrip data is forwarded over WebSocket), the response returns an unknown error code that can be ignored and the device's Ntrip connection is unaffected; no corresponding handling was found in the device-side source, so this is unverified.

Data processing

data_source currently supports XBIN_DATA; if data_topics is omitted, everything is unpacked; report/data_unpack reports the unpack progress (0~100). When the device is not in standby, this request returns EC_RequestError.

message DataUnpackRequest {
    enum DataSource {
        XBIN_DATA = 0; // xbin data
    }
    Header header = 1;
    string project_name = 2;           // project name
    DataSource data_source = 3;        // data source
    repeated string data_topics = 4;   // data topics (unpack all by default if omitted)
    optional string data_ouputdir = 5; // output directory name (relative to the project directory)
}

Note: the data unpack feature is supported only on specific models and firmware versions. Before use, query the firmware version via the heartbeat ProtocolVersion or the device info, and confirm with XGRIDS whether the target model / firmware supports it. On an unsupported device the request has no effect.

Error code convention

Request-response messages carry the result in the Error error = 15 field. Common ones: EC_RequestSuccess, EC_RequestError, EC_ProtoError; Ntrip-related: EC_NtripLoginSuccess, EC_NtripLogoutSuccess, EC_NtripLogoutFailed, EC_NtripDisConnected, EC_NtripNetworkError, EC_NtripAuthError. For the full list, see Error Codes.