产品概述
X-Brain 是什么
X-Brain 是 XGRIDS 推出的空间智能感知设备。 它自带定位与建图算力，开机即输出设备自身的实时位姿、点云、IMU 与相机图像，无需外部高性能计算平台。
X-Brain 是通用感知模组：客户购买后，将其部署到机器狗、AGV、无人机等各种形态的机器人平台上，作为该平台的空间感知与定位单元。设备只负责输出"以设备自身为基准"的感知数据；它被装在什么载体上、载体中心在哪，由集成方自行标定并叠加变换（详见 核心概念 · 坐标系）。
本手册面向在自有机器人平台上集成 X-Brain 的开发者，讲解如何用 X-Brain SDK 获取设备数据、控制录制、管理重定位地图。
X-Brain SDK 是什么
X-Brain SDK 是 X-Brain 设备的配套 C/C++ SDK。主机（上位机，即机器人平台上的计算单元）通过以太网直连设备后，即可：
- 订阅设备输出的位姿、点云、原始点云、IMU、相机图像、错误码；
- 控制录制的启停并查询录制状态；
- 管理重定位地图（上传 / 激活 / 列出 / 删除）；
- 查询设备的标定参数（相机 / IMU / 雷达）与运行状态（电量、存储、内存等）。
设计目标是让集成方几行代码拿到位姿和点云，不必自建定位系统、不必调参、不必做传感器融合的底层工作，也不需要高性能的外部计算平台——定位与建图的算力在设备内部。
获取 SDK
代码仓库：http://gitlab.xgrids-dev.com/Guozr/x-brain-sdk
克隆后按 快速开始 编译示例、接入你的工程。
关键特性
| 特性 | 说明 |
|---|---|
| 开箱即用 | 头文件 + 单个动态库 liblixel_sdk.so，除系统库外无需额外部署 |
| 全量数据订阅 | 位姿(~100Hz)、reloc 点云(~10Hz)、原始点云(~10Hz)、IMU(~200Hz)、三路相机 JPEG、错误码 |
| 统一订阅模型 | 所有数据同构：subscribeXxx(回调) / unsubscribeXxx()，回调交付 POD 结构体 |
| 稳定的对外契约 | C ABI + header-only C++ 封装，规避 C++ ABI 不兼容；库内只导出 xg_ 前缀符号 |
| ROS2 桥接 | 自带桥接节点，一条命令把设备数据转成标准 ROS2 Topic |
| 双架构交付 | 仓库内含 x86_64 与 aarch64 两套预编译库（lib/<arch>），头文件与接口完全一致 |
| 结构化错误可观测 | 设备各模块（定位/建图/SLAM）错误码以独立数据流批量推送 |
| 重定位地图管理 | 上传/激活/列出/删除设备上的重定位地图（uploadMap / setActiveMap / listMaps / deleteMap） |
数据能力一览
| 数据 | 接口 | 频率（量级） | 坐标系 | 结构体 |
|---|---|---|---|---|
| 位姿 | subscribePose | ~100 Hz | 设备(IMU)系 | Pose |
| reloc 点云 | subscribeCloud | ~10 Hz | 设备(IMU)系 | CloudFrame |
| 原始点云 | subscribeRawCloud | ~10 Hz | 雷达系（去畸变单帧） | CloudFrame |
| 原始 IMU | subscribeImu | ~200 Hz | IMU 系 | Imu |
| 相机图像 | subscribeImage(CameraId, cb) | 取决于设备端 JPEG 编码配置（默认约 2fps） | 相机光学系 | ImageFrame |
| 错误码 | subscribeErrCode | ~10 Hz 批量 | — | ErrCodeFrame |
注：
subscribeCloud是重定位配准点云（约 10Hz，设备系，NDT 产物）；subscribeRawCloud是去畸变的单帧雷达扫描（约 10Hz，未经建图配准）。需要每帧扫描请用后者。详见核心概念。
交付内容
include/xg/robot_sdk.h C++ 接口（推荐使用，header-only）
include/xg/robot_sdk_c.h C 接口（ABI 真源）
lib/x86_64/ lib/aarch64/ 动态库（按架构分目录，已内含全部第三方依赖）
bin/x86_64/ bin/aarch64/ 预编译示例程序（按架构分目录）
examples/ 示例源码（connection/record/subscribe/relocation_map/comprehensive）
ros2/ ROS2 Bridge 源码（colcon build 即用）
头文件、示例源码、ROS2 桥接两架构通用；仅 lib/ 与 bin/ 按架构分目录。liblixel_sdk.so 已包含全部第三方依赖，除系统库（glibc、libstdc++）外无需额外部署。
平台与运行要求
仓库直接包含双架构预编译动态库，clone 后按目标机架构选用对应目录即可，无需另行下载：
| 架构 | 动态库目录 | 示例程序目录 | 运行要求 |
|---|---|---|---|
| x86_64 | lib/x86_64/ | bin/x86_64/ | glibc ≥ 2.34 |
| aarch64 | lib/aarch64/ | bin/aarch64/ | glibc ≥ 2.30 |
头文件与接口两架构完全一致，只是动态库的二进制架构不同。部署前请确认目标机的 glibc 版本满足要求：
ldd --version | head -1
uname -m
glibc 版本不足时表现为程序启动即失败（提示找不到 GLIBC_2.xx），不是运行期出错。
语言绑定
| 语言 | 形态 |
|---|---|
| C | xg/robot_sdk_c.h，纯 C ABI，可自行封装到其他语言 |
| C++（≥11，推荐 17） | xg/robot_sdk.h，header-only，全部 inline，是 C 接口的薄封装 |
| ROS2 | 自带 lixel_sdk_ros2 桥接包（Humble / Foxy） |
C++ 接口是 header-only 的，由调用方自行编译，不产生需要链接的符号——这样规避了编译器版本、libstdc++ 版本、_GLIBCXX_USE_CXX11_ABI 取值不一致导致的链接失败或运行期崩溃。库本身只导出 C 接口，故无此风险。