连接与鉴权

Lixel 设备内置 MQTT Broker 与 RTSP 服务。实时控制与实时点云数据通过 MQTT 传输，实时视频通过 RTSP 传输。设备支持与其他设备的有线和无线组网：有线用 USB 线缆连接，无线用 Wi-Fi 组网。

连接参数

不同产品型号只支持其中一种连接协议（不是同时支持两种）：

协议	端口	用户名	密码	适用型号
MQTT	1883	—	—	K1 / L2PRO
MQTTS	8883	由厂商提供	由厂商提供	已知 K2 / H1 / F1 / Porcam 使用 MQTTS（来源：示例工程注释），其他型号以设备实际开放的端口为准

MQTT 版本：V3.1.1
有线组网使用固定 IP 192.168.55.1；无线组网时通过蓝牙获取 IP。
快连（闪连）模式下设备 IP 固定为 192.168.56.1。

注：MQTTS 使用 TLS。设备端采用自签名证书，客户端示例默认关闭证书校验以适配。选择 MQTTS 时需要带上厂商提供的用户名与密码。关闭证书校验后，客户端无法确认连接的是不是真的设备，同一网络里的中间人可以冒充设备并读取请求（包括 openapi_key）。用于正式环境前，请改为导入设备证书并开启校验。

USB 连接

运行 Linux、Windows 或 Android 的设备，通过 RNDIS 与 Lixel 设备进行网络共享；iOS 设备通过 USB Tethering（USB 网络共享）与设备组网。

  Lixel 设备 (192.168.55.1)                       其他设备
      +---------+                                    +---------+
      |   USB   | <----- RNDIS / USB Tethering ----> |   USB   |
      +---------+                                    +---------+

Wi-Fi 连接

设备支持三种无线连接模式：

普通模式：其他设备作为热点。
快连模式：Lixel 设备作为热点。
桥接模式：使用路由器组网。

所有模式都需要先通过蓝牙完成网络配置。设备接受蓝牙连接以配置 Wi-Fi，使其连接到指定网络。

设备的蓝牙名称由 10 个字符组成：多数型号是固定前缀 XGR- 加 SN 码后 6 位，例如 XGR-A12345；部分 ODM 型号的前缀不同（例如 PCAM），以实际扫描到的蓝牙名称为准。

      Lixel 设备                                    其他设备
      +---------+                                      +---------+
      |   BT    | <----- 蓝牙 (网络配置) ------------> |   BT    |
      |  WiFi   | <----- WiFi (数据) ---------------> |  WiFi   |
      +---------+                                      +---------+

配网流程

设备与客户端之间的 BLE 配网流程：客户端作为主机搜索并连接设备（从机）；连接成功后设备先发送当前 Wi-Fi 状态；若未连接 Wi-Fi，客户端下发 Wi-Fi 信息（SSID 与密码），设备据此连接目标网络。

        Lixel 设备                                      客户端
  +----------------------+                     +----------------------+
  |   BLE 从机模式         |                     |   BLE 主机模式         |
  +----------+-----------+                     +----------+-----------+
             |                                            |
             v            <---- 建立连接 ---->             v
  +----------------------+                     +----------------------+
  |   发送 WiFi 状态       | ------------------> |   获取 WiFi 状态       |
  +----------+-----------+                     +----+------------+-----+
             |                                      |            |
             |                        WiFi 未连接    |            | WiFi 已连接
             |   <------ 下发 WiFi 信息 ------------ |            |
             v                                      v            v
  +----------------------+                     +----------------------+
  |   连接目标 WiFi        |                     |         结束          |
  +----------------------+                     +----------------------+

OpenAPI 的请求只有在设备认证通过后才会被执行。请求消息的消息头中需要填写 openapi_key，设备据此校验请求是否合法。openapi_key 缺失或不正确时，设备仍会返回响应：error.code 为 EC_ProtoError（0x32040001），error.desc 为 openapi auth error，响应中不含业务数据，request() 正常返回，不会超时。

申请 OpenAPI Key

OpenAPI Key 由 XGRIDS 统一分发，不能自行生成。获取方式：

通过 XGRIDS 的商务或技术支持渠道提出申请，说明设备型号与用途。
XGRIDS 核对后下发一串 Key 字符串。
拿到后直接填入连接配置即可，无需额外激活步骤。

注：Key 与具体设备 / 授权绑定，请妥善保管，不要硬编码进公开仓库或分发给第三方。

在代码中使用

为 ClientOptions.openapi_key 赋值，request() / publish() 会自动把它填入消息头：

from example.core import ClientOptions, OpenApiClient

opts = ClientOptions(host="192.168.55.1", openapi_key="<由 XGRIDS 提供>")
with OpenApiClient(opts) as client:
    ...  # header.openapi_key 会被自动填充

消息头字段

所有请求、响应、上报消息的第一个字段通常是 Header：

字段	类型	说明
`seq`	uint32	帧序号
`stamp`	sint64	帧时间戳。设备上报的帧以微秒计，时基为 Unix 纪元
`scaler`	sint64	缩放系数（点云等使用）
`device_id`	string	设备 ID（设备生成）
`session_id`	string	会话 ID（请求 / 上报端生成）
`openapi_key`	string	API 密钥（proto 中为 optional，但设备只执行带有效密钥的请求）

对应的 proto 定义：

message Header {
    uint32 seq = 1;                  // 帧序号
    sint64 stamp = 2;                // 帧时间戳
    sint64 scaler = 3;               // 缩放系数（正：放大，负：缩小，0：禁用缩放）
    string device_id = 4;            // 设备 ID（设备生成）
    string session_id = 5;           // 会话 ID（请求 / 上报端生成）
    optional string openapi_key = 6; // API 密钥（向 XGRIDS 申请）
}

附：底层配网接口

注：本节仅在你需要自行实现蓝牙配网（不使用现成 App）时参考。大多数情况下用随附工具或 App 完成配网即可，无需关心这些底层定义。

配网通过 BLE GATT 服务读写特征值。Android 与 iOS 使用不同的 UUID：

/* Android GATT Characteristic Types */
#define UUID_GATT 0x1801
#define GATT_CHARAC_WIFI_INFO_SET 0x2AB0
#define GATT_CHARAC_WIFI_STATUS_GET 0x2AB1

/* iOS GATT Characteristic Types */
#define IOS_UUID_GATT 0x7F00
#define IOS_GATT_CHARAC_WIFI_INFO_SET 0x7F01
#define IOS_GATT_CHARAC_WIFI_STATUS_GET 0x7F02

写入 Wi-Fi 配置、读取 Wi-Fi 状态的数据结构：

#pragma pack(1)
/***********************************************************
 * WiFi status information (device -> Android)
 * ssid_len : 0 means WiFi is disconnected
 * ssid     : WiFi access point name
 * ip_len   : 0 means WiFi has no assigned IP
 * ip       : WiFi IP address
 * auth_mode: Not used yet
 * wifi_mode: 0 - STA mode  1 - AP mode (Quick Connect mode) 255 - ignore WiFi mode
 **********************************************************/
typedef struct wifi_info_s {
    uint8 ssid_len;
    uint8 ssid[32];
    uint8 passwd_len;
    uint8 passwd[64];
    uint8 auth_mode;
    uint8 wifi_mode;        // 0: Normal mode 1: Quick Connect mode 255: Only configure country code
    uint8 country_code[2];  // Country code (ISO2)
} wifi_info_t;

typedef struct wifi_status_s {
    uint8 ssid_len;
    uint8 ssid[32];
    uint8 ip_len;
    uint8 ip[16];
    uint8 connect_state;    // 0 - Not connected 1 - Connected successfully 2 - Connecting 3 - Device scanning
    uint8 wifi_mode;        // 0: Normal mode 1: Quick Connect mode
    uint8 country_code[2];  // Country code (ISO2)
} wifi_status_t;
#pragma pack()