XOS Glasses SDK — API Reference

Version: 0.0.1 | Updated: 2026-07-03

完整的 SDK API 参考，覆盖所有公开接口、参数说明和用法示例。

1. 核心生命周期

init()

初始化 SDK，请求蓝牙和位置权限，准备 BLE 协议栈。

static Future<XOSGlassesSDK> init({GlassesSDKConfig? config})

参数	类型	必需	说明
`config`	`GlassesSDKConfig?`		初始化配置

返回: Future<XOSGlassesSDK> — SDK 实例

示例:

final sdk = await XOSGlassesSDK.init(
  config: GlassesSDKConfig(
    autoReconnect: true,
    enableDebugLog: false,
  ),
);

dispose()

释放 SDK 所有资源，断开设备连接，关闭流。

Future<void> dispose()

示例:

@override
void dispose() {
  sdk.dispose();
  super.dispose();
}

sdkVersion

SDK 版本号。

String get sdkVersion

setDebugMode()

启用/禁用调试日志。

void setDebugMode(bool enabled)

2. 设备发现

startDiscovery()

扫描附近眼镜设备。结果通过 onDeviceDiscovered 流推送。

Future<void> startDiscovery()

stopDiscovery()

停止扫描。

Future<void> stopDiscovery()

isScanning

是否正在扫描。

bool get isScanning

onDeviceDiscovered

设备发现流。

Stream<DiscoveredDevice> get onDeviceDiscovered

示例:

sdk.onDeviceDiscovered.listen((device) {
  print('${device.name} | ${device.deviceId} | RSSI: ${device.rssi}');
});
await sdk.startDiscovery();

getSystemPairedDevices()

获取系统蓝牙已配对的设备列表。

Future<List<PairedDevice>> getSystemPairedDevices()

3. 配对管理

pair()

与指定设备配对（绑定）。

Future<bool> pair(String deviceId)

参数	类型	说明
`deviceId`	`String`	设备 ID

返回: true 表示配对成功

unpair()

取消配对。

Future<bool> unpair(String deviceId)

hasPairedDevice

是否有已配对设备。

bool get hasPairedDevice

pairedDevice

当前已配对设备信息。

PairedDevice? get pairedDevice

4. 连接管理

connect()

连接指定设备。

Future<bool> connect(String deviceId)

参数	类型	说明
`deviceId`	`String`	设备 ID（来自扫描结果或配对列表）

返回: true 表示连接成功并完成握手

connectToPairedDevice()

连接已配对设备（快捷方法）。

Future<bool> connectToPairedDevice()

disconnect()

断开当前连接。

Future<void> disconnect()

isConnected / isReconnecting / isConnectionFailed

连接状态。

bool get isConnected
bool get isReconnecting
bool get isConnectionFailed

onConnectionStateChanged

连接状态变化流。

Stream<ConnectionStateInfo> get onConnectionStateChanged

示例:

sdk.onConnectionStateChanged.listen((state) {
  switch (state.state) {
    case ConnectionState.connected:
      print('已连接: ${state.deviceName}');
    case ConnectionState.failed:
      print('失败: ${state.errorMessage}');
    case ConnectionState.reconnecting:
      print('重连中...');
  }
});

connectedDevice / deviceDisplayName

当前连接的设备。

DiscoveredDevice? get connectedDevice
String? get deviceDisplayName

enableAutoReconnect() / disableAutoReconnect()

启用/禁用自动重连。

void enableAutoReconnect(String deviceId)
void disableAutoReconnect()

5. 设备信息

deviceInfo / onDeviceInfoChanged

设备信息和变更推送。

DeviceInfo? get deviceInfo
Stream<DeviceInfo> get onDeviceInfoChanged

示例:

sdk.onDeviceInfoChanged.listen((info) {
  print('电量: ${info.batteryLevel}%, 文件: ${info.fileCount}个');
});

getBatteryLevel()

查询电池电量（0-100）。

Future<int> getBatteryLevel()

isCharging()

是否正在充电。

Future<bool> isCharging()

getWiFiStatus() / onWiFiStatusChanged

眼镜 WiFi 连接状态。

Future<WiFiStatus> getWiFiStatus()
Stream<WiFiStatus> get onWiFiStatusChanged

getDeviceIP() / onDeviceIPChanged

眼镜 IP 地址（用于 WiFi Direct 传输）。

Future<String?> getDeviceIP()
Stream<String?> get onDeviceIPChanged

getSoftAPInfo() / onSoftAPInfoChanged

SoftAP / WiFi Direct 连接信息。

Future<SoftAPInfo?> getSoftAPInfo()
Stream<SoftAPInfo?> get onSoftAPInfoChanged

6. 显示控制

setBrightness()

设置屏幕亮度。

Future<bool> setBrightness(int level)

参数	说明
`level`	0（最暗）~ 100（最亮）

setSleepTimeout()

设置休眠超时。

Future<bool> setSleepTimeout(int seconds)

参数	说明
`seconds`	无操作后多少秒进入休眠

setDisplayDistance()

设置显示距离（影响字体渲染大小）。

Future<bool> setDisplayDistance(int centimeters)

setRgbRatio()

设置 RGB 色彩比例。

Future<bool> setRgbRatio({
  required int red,
  required int green,
  required int blue,
})

参数	范围
`red` / `green` / `blue`	0 - 255

setDesktopViewport() / resetDesktopViewport()

桌面模式视口设置。

Future<bool> setDesktopViewport({
  required int x, required int y,
  required int w, required int h,
})
Future<bool> resetDesktopViewport()

getDisplaySettings()

获取当前显示设置。

Future<DisplaySettings> getDisplaySettings()

7. 音频控制

setVolume()

设置音量。

Future<bool> setVolume(int level)

参数	说明
`level`	0（静音）~ 100（最大）

8. WiFi 管理

scanWiFiNetworks()

由眼镜扫描附近 WiFi 网络。

Future<List<WiFiNetwork>> scanWiFiNetworks()

返回: WiFi 网络列表

connectWiFi()

眼镜连接指定 WiFi。

Future<bool> connectWiFi(String ssid, String password)

disconnectWiFi()

眼镜断开当前 WiFi。

Future<bool> disconnectWiFi()

getSavedWiFiNetworks()

获取眼镜已保存的 WiFi 列表。

Future<List<WiFiNetwork>> getSavedWiFiNetworks()

connectSavedWiFi()

连接已保存的 WiFi。

Future<bool> connectSavedWiFi(String ssid)

forgetWiFiNetwork()

遗忘已保存的 WiFi。

Future<bool> forgetWiFiNetwork(String ssid)

9. 蓝牙网络共享

enableBluetoothTethering() / disableBluetoothTethering()

启用/禁用蓝牙网络共享（PAN）。

Future<bool> enableBluetoothTethering()
Future<bool> disableBluetoothTethering()

isBluetoothTetheringEnabled()

蓝牙网络共享是否已启用。

Future<bool> isBluetoothTetheringEnabled()

10. 相机与录制

capturePhoto()

拍照。返回眼镜上的文件路径。

Future<String?> capturePhoto()

返回: 照片文件路径（眼镜端路径），或 null

示例:

final path = await sdk.capturePhoto();
if (path != null) print('照片: $path');

startRecording() / stopRecording()

开始/停止录像。

Future<bool> startRecording()
Future<bool> stopRecording()

getRecordingStatus() / onRecordingStatusChanged

录制状态。

Future<RecordingStatus> getRecordingStatus()
Stream<RecordingStatus> get onRecordingStatusChanged

示例:

sdk.onRecordingStatusChanged.listen((status) {
  if (status.isRecording) {
    print('录制中: ${status.durationSeconds}秒');
  }
});

launchCamera() / closeCamera()

打开/关闭相机预览。

Future<bool> launchCamera()
Future<bool> closeCamera()

11. 文件管理

fetchFileList()

请求眼镜文件列表。

Future<void> fetchFileList()

fetchFileCount()

获取眼镜文件数量。

Future<int> fetchFileCount()

startDownload()

开始下载文件。SDK 自动选择 BLE 或 WiFi Direct 通道。

Future<FileTransferTask> startDownload({
  required List<String> fileIds,
})

参数	说明
`fileIds`	文件 ID 列表（来自文件列表）

返回: 传输任务，可跟踪进度

startUpload()

上传文件到眼镜。

Future<FileTransferTask> startUpload(String localFilePath)

cancelTransfer()

取消传输。

Future<bool> cancelTransfer(String taskId)

onFileListReceived / onFileCountReceived / onTransferUpdated

文件相关事件流。

Stream<List<GlassesFile>> get onFileListReceived
Stream<int> get onFileCountReceived
Stream<FileTransferTask> get onTransferUpdated

完整示例:

// 监听
sdk.onFileListReceived.listen((files) {
  for (var f in files) {
    print('${f.type}: ${f.name} (${f.size} bytes)');
  }
});

sdk.onTransferUpdated.listen((task) {
  print('${task.id}: ${(task.progress * 100).toStringAsFixed(1)}% - ${task.phase.name}');
});

// 请求列表
await sdk.fetchFileList();

// 下载
final task = await sdk.startDownload(fileIds: ['file_123']);

12. 提词器

sendTeleprompterFile()

发送提词器脚本文件到眼镜。自动分片传输。

Future<bool> sendTeleprompterFile(String localFilePath)

参数	说明
`localFilePath`	手机本地脚本文件路径

onTeleprompterSync

提词器同步状态流（当前行、播放状态、字符位置）。

Stream<TeleprompterState> get onTeleprompterSync

TeleprompterState 字段:

字段	类型	说明
`currentLine`	`int`	当前行号
`totalLines`	`int`	总行数
`isPlaying`	`bool`	是否播放中
`charPosition`	`int?`	当前字符位置

onTeleprompterScroll

滚动位置变化流。

Stream<TeleprompterScrollInfo> get onTeleprompterScroll

示例:

// 发送脚本
await sdk.sendTeleprompterFile('/path/to/script.txt');

// 监听同步
sdk.onTeleprompterSync.listen((state) {
  print('行 ${state.currentLine}/${state.totalLines} ${state.isPlaying ? "▶️" : "⏸️"}');
});

13. 媒体投屏

startMediaCasting()

投屏媒体到眼镜。

Future<bool> startMediaCasting({
  required String mediaPath,
  CastProtocol? protocol,
  bool fullscreen = false,
  bool soundEnabled = true,
})

参数	说明
`mediaPath`	媒体文件路径或 URL
`protocol`	投屏协议: `CastProtocol.dlna` 或 `CastProtocol.rtsp`
`fullscreen`	是否全屏
`soundEnabled`	是否启用音频

startScreenMirroring()

开始屏幕镜像。

Future<bool> startScreenMirroring()

stopCasting()

停止投屏/镜像。

Future<bool> stopCasting()

14. 翻译

startTranslation()

开始实时翻译。

Future<bool> startTranslation({
  String sourceLang = 'auto',
  String targetLang = 'en',
})

参数	说明
`sourceLang`	源语言代码（默认 `auto` 自动检测）
`targetLang`	目标语言代码（默认 `en` 英语）

stopTranslation()

停止翻译。

Future<bool> stopTranslation()

updateTranslationStyle()

更新翻译显示样式。

Future<bool> updateTranslationStyle({
  String? sourceTextColor,
  String? targetTextColor,
  int? sourceFontSize,
  int? targetFontSize,
})

参数	说明
`sourceTextColor`	源文字颜色（如 `"#FFFFFF"`）
`targetTextColor`	译文字颜色
`sourceFontSize`	源文字体大小
`targetFontSize`	译文字体大小

getTranslationStatus()

获取翻译状态。

Future<TranslationStatus> getTranslationStatus()

onTranslationResult

翻译结果流（实时推送）。

Stream<TranslationResult> get onTranslationResult

完整示例:

// 开始中译日
await sdk.startTranslation(sourceLang: 'zh', targetLang: 'ja');

// 监听结果
sdk.onTranslationResult.listen((result) {
  print('${result.sourceText} → ${result.targetText}');
});

// 自定义样式
await sdk.updateTranslationStyle(
  sourceTextColor: '#AAAAAA',
  targetTextColor: '#00FF00',
  targetFontSize: 18,
);

// 停止
await sdk.stopTranslation();

15. AI 配置

getAIConfig() / setAIConfig()

获取/设置 AI 配置。

Future<AIConfig> getAIConfig()
Future<bool> setAIConfig(AIConfig config)

AIConfig 字段:

字段	类型	说明
`voiceAI`	`Map`	语音 AI 模型设置
`visualAI`	`Map`	视觉 AI 模型设置
`voiceWake`	`Map`	语音唤醒设置

getQuickCenterConfig() / setQuickCenterConfig()

获取/设置快捷中心配置（视觉 AI 触发词等）。

Future<QuickCenterConfig> getQuickCenterConfig()
Future<bool> setQuickCenterConfig(QuickCenterConfig config)

QuickCenterConfig 字段:

字段	类型	说明
`triggerWords`	`List<String>`	视觉 AI 触发词（最多 10 个）
`viewportX/Y/W/H`	`int?`	覆盖层位置

16. 数据转发

sendGPS()

发送 GPS 位置数据。

Future<bool> sendGPS({
  required double lat,
  required double lng,
  double? accuracy,
  double? speed,
  double? bearing,
})

参数	说明
`lat` / `lng`	经纬度
`accuracy`	精度（米）
`speed`	速度（m/s）
`bearing`	方位角（度）

sendNotification()

推送通知到眼镜。

Future<bool> sendNotification({
  required String title,
  required String content,
  String? appName,
  String? packageName,
})

startNavigation() / endNavigation()

开始/结束导航。

Future<bool> startNavigation()
Future<bool> endNavigation()

setNavigationDisplayMode()

设置导航显示模式。

Future<bool> setNavigationDisplayMode(NavigationMode mode)

枚举值	说明
`NavigationMode.walk`	步行
`NavigationMode.drive`	驾车
`NavigationMode.bike`	骑行

syncReminders()

同步提醒到眼镜。

Future<bool> syncReminders(List<Reminder> reminders)

Reminder 字段:

字段	类型	说明
`id`	`String`	唯一 ID
`title`	`String`	提醒标题
`time`	`String`	时间（ISO 8601）
`repeatType`	`String?`	重复类型: `none`/`daily`/`weekly`/`monthly`

17. 系统命令

restartGlassesApp()

重启眼镜应用（OTA 升级后使用）。

Future<bool> restartGlassesApp()

openBluetoothSettings()

打开系统蓝牙设置页。

Future<void> openBluetoothSettings()

isClassicBluetoothPaired()

经典蓝牙（A2DP）是否已配对。

Future<bool> isClassicBluetoothPaired()

18. 蓝牙外设

getGlassesBluetoothDevices()

获取眼镜端蓝牙设备列表。

Future<List<PairedDevice>> getGlassesBluetoothDevices()

connectBluetoothAudio()

通过眼镜连接蓝牙音频设备。

Future<bool> connectBluetoothAudio(String address)

HID 控制

模拟键盘/鼠标输入。

Future<bool> hidKeyBack()     // 返回键
Future<bool> hidKeyHome()     // 主页键
Future<bool> hidKeyEnter()    // 确认键
Future<bool> hidKeyRecent()   // 最近任务键
Future<bool> hidMouseMove({required int x, required int y})
Future<bool> hidMouseClick({String button = 'left'})  // 'left' | 'right'

19. 高级接口

onRawMessage

原始 BLE 消息流（长协议解码后）。供高级用途使用。

Stream<Map<String, dynamic>> get onRawMessage

sendRawCommand()

发送原始 BLE 命令。优先使用类型化方法，此接口用于自定义命令。

Future<Map<String, dynamic>?> sendRawCommand(
  Map<String, dynamic> command, {
  int maxRetries = 2,
})

参数	说明
`command`	原始命令 Map（长协议格式）
`maxRetries`	失败重试次数

示例:

final resp = await sdk.sendRawCommand({
  'type': 'custom_command',
  'param1': 'value',
});

20. 类型定义

GlassesSDKConfig

class GlassesSDKConfig {
  final bool autoReconnect;         // 断线自动重连（默认 true）
  final int scanTimeoutSeconds;     // 扫描超时（默认 60 秒）
  final bool enableDebugLog;        // 调试日志（默认 false）
}

DiscoveredDevice

class DiscoveredDevice {
  final String deviceId;            // 设备 ID
  final String name;                // 广播名称
  final int rssi;                   // 信号强度 (dBm)
  final String? serialNumber;       // 序列号（如有）
  final bool isPaired;              // 是否已系统配对
}

DeviceInfo

class DeviceInfo {
  final String deviceId;            // 设备 ID
  final String? deviceModel;        // 型号
  final String? firmwareVersion;    // 固件版本
  final String? appVersion;         // APP 版本
  final int batteryLevel;           // 电量 0-100
  final bool isCharging;            // 是否充电中
  final int fileCount;              // 文件总数
  final int videoCount;             // 视频数
  final int photoCount;             // 照片数
}

ConnectionStateInfo

class ConnectionStateInfo {
  final ConnectionState state;      // 连接状态枚举
  final String? deviceName;         // 设备名
  final String? errorMessage;       // 错误信息
}

enum ConnectionState {
  disconnected, connecting, connected,
  disconnecting, reconnecting, failed,
}

FileTransferTask

class FileTransferTask {
  final String id;                  // 任务 ID
  final TransferDirection direction; // upload / download
  final TransferPhase phase;        // 传输阶段
  final double progress;            // 进度 0.0-1.0
  final int transferredBytes;       // 已传输字节
  final int totalBytes;             // 总字节
  final List<String> fileIds;       // 文件 ID 列表
  final String? errorMessage;       // 错误信息
}

enum TransferDirection { upload, download }

enum TransferPhase {
  pending, connecting, transferring,
  verifying, installing, completed, failed,
}

其他类型

类型	主要字段
`WiFiStatus`	`isConnected`, `ssid`, `ip`, `isHotspot`
`WiFiNetwork`	`ssid`, `signalStrength`, `isEncrypted`
`SoftAPInfo`	`ssid`, `ip`, `port`, `password`, `expiresIn`
`RecordingStatus`	`isRecording`, `durationSeconds`
`TranslationStatus`	`isActive`, `sourceLang`, `targetLang`
`TranslationResult`	`sourceText`, `targetText`, `sourceLang`, `targetLang`
`AIConfig`	`voiceAI`, `visualAI`, `voiceWake`
`QuickCenterConfig`	`triggerWords`, `viewportX/Y/W/H`
`GlassesFile`	`id`, `name`, `size`, `type`, `createdAt`
`TeleprompterState`	`currentLine`, `totalLines`, `isPlaying`, `charPosition`
`TeleprompterScrollInfo`	`scrollPosition`
`Reminder`	`id`, `title`, `time`, `repeatType`
`DisplaySettings`	`brightness`, `sleepTimeout`, `displayDistance`, RGB
`PairedDevice`	`deviceId`, `name`, `model`, `serialNumber`, `isClassicPaired`

附录: 枚举值速查

ConnectionState

值	说明
`disconnected`	未连接
`connecting`	连接中
`connected`	已连接
`disconnecting`	断开中
`reconnecting`	自动重连中
`failed`	连接失败

NavigationMode

值	说明
`walk`	步行导航
`drive`	驾车导航
`bike`	骑行导航

CastProtocol

值	说明
`dlna`	DLNA 投屏
`rtsp`	RTSP 流媒体

TransferDirection

值	说明
`upload`	上传（手机→眼镜）
`download`	下载（眼镜→手机）

FilesExpand file tree

API_REFERENCE.md

Latest commit

History

API_REFERENCE.md

File metadata and controls

XOS Glasses SDK — API Reference

目录

1. 核心生命周期

init()

dispose()

sdkVersion

setDebugMode()

2. 设备发现

startDiscovery()

stopDiscovery()

isScanning

onDeviceDiscovered

getSystemPairedDevices()

3. 配对管理

pair()

unpair()

hasPairedDevice

pairedDevice

4. 连接管理

connect()

connectToPairedDevice()

disconnect()

isConnected / isReconnecting / isConnectionFailed

onConnectionStateChanged

connectedDevice / deviceDisplayName

enableAutoReconnect() / disableAutoReconnect()

5. 设备信息

deviceInfo / onDeviceInfoChanged

getBatteryLevel()

isCharging()

getWiFiStatus() / onWiFiStatusChanged

getDeviceIP() / onDeviceIPChanged

getSoftAPInfo() / onSoftAPInfoChanged

6. 显示控制

setBrightness()

setSleepTimeout()

setDisplayDistance()

setRgbRatio()

setDesktopViewport() / resetDesktopViewport()

getDisplaySettings()

7. 音频控制

setVolume()

8. WiFi 管理

scanWiFiNetworks()

connectWiFi()

disconnectWiFi()

getSavedWiFiNetworks()

connectSavedWiFi()

forgetWiFiNetwork()

9. 蓝牙网络共享

enableBluetoothTethering() / disableBluetoothTethering()

isBluetoothTetheringEnabled()

10. 相机与录制

capturePhoto()

startRecording() / stopRecording()

getRecordingStatus() / onRecordingStatusChanged

launchCamera() / closeCamera()

11. 文件管理

fetchFileList()

fetchFileCount()

startDownload()

startUpload()

cancelTransfer()

onFileListReceived / onFileCountReceived / onTransferUpdated

12. 提词器

sendTeleprompterFile()

onTeleprompterSync

onTeleprompterScroll

13. 媒体投屏

startMediaCasting()

startScreenMirroring()

stopCasting()

14. 翻译

startTranslation()