常见问题 ​

K900SDK 和 XYSDK 是什么关系？ ​

K900SDK 是 K900 对外文档名称，iOS 集成模块为 XingYiGlassesSDK，也称 XYSDK；Android 集成模块为 ksdk，两者接口分别维护。

如何获取 SDK？ ​

首版尚未提供验证后的公开下载包，请通过官网联系我们获取。下载与环境说明见K900SDK 集成。

SmartXYSDK 可以使用这些接口吗？ ​

不能据此推断。SmartXYSDK 是独立 SDK，资料准备完成后单独编写。

是否必须先申请 App Key？ ​

现有 K900 本地 BLE 接入材料未确认该前置条件。Demo 的云端 AI 服务需要单独配置对应服务的凭证。

为什么连接成功还收不到数据？ ​

外设连接成功时，特征发现和通知订阅可能还未完成。查看蓝牙生命周期，并检查是否有页面覆盖单例回调。

如何反馈文档问题？ ​

记录页面链接、章节、SDK/固件版本、预期与实际行为。

Android 从哪里开始接入？ ​

先完成 Android 集成，再使用 快速开始建立 Service、连接眼镜并查询电量。不要直接复用 iOS 示例或 Demo 的全部系统权限。

开发指南 ​

通过 iOS 或 Android SDK 将应用连接到形意智能眼镜，完成设备控制、多媒体传输与升级。

选择 SDK ​

进入 iOS SDK → · 进入 Android SDK →

• K900SDK：K900 眼镜，实际模块名 XingYiGlassesSDK（XYSDK）。
• SmartXYSDK：独立 SDK，文档准备中。

推荐接入流程 ​

获取匹配的 SDK 与 Demo → 配置工程和权限 → 注册回调 → 扫描并连接 → 确认通信就绪 → 调用设备功能 → 处理结果与异常。

K900 本地 BLE 接入资料中未确认存在开发者账号或 App Key 前置条件。若使用 Demo 的第三方 AI 服务，单独配置该服务的凭证。

文档范围 ​

本中心包含 iOS 与 Android K900SDK 集成文档；SmartXYSDK 预留入口。每个功能页均区分源码已核对行为与待真机验证事项。

功能发布记录 ​

2026-10-09 · Android K900SDK 文档 ​

新增 Android 集成、快速开始、蓝牙生命周期、拍照传图、Wi-Fi 文件、LC3、OTA、API、错误排查和 Demo 说明。使用 ksdk-release.aar 集成，API 对应交付包接口，提供中文版 Word 对接文档。

首次发布 ​

开发者中心提供 SDK 平台目录。iOS 下包含 K900SDK 与 SmartXYSDK，Android 保留后续接入入口。

K900SDK 提供集成与功能流程、完整 API参考、错误排查、Demo 使用说明和中英文对接文档。

Android SDK ​

Android K900SDK 通过 ksdk-release.aar 接入，为应用提供蓝牙设备控制、图片与媒体传输、AI 图片接收和升级能力。

进入 K900SDK Android 文档 →

• 下载与集成：Gradle、依赖和系统权限。
• 快速开始：连接、就绪与电量查询。
• API参考：Android 方法与实际发送参数。

接口按交付 SDK 使用，设备功能需匹配相应固件。iOS 使用独立接口，见 iOS SDK。

AI拍照与传图 ​

通过 sendAIImg() 请求眼镜拍照，使用 AiFileListener 接收 SDK 组装后的图片数据。图片可用于 App 的图像识别或其他 AI 业务。

接入流程 ​

完成设备连接 → 确认通信就绪 → 注册图片回调 → 请求拍照 → 接收并保存图片 → 处理业务结果。

接口与回调 ​

1. 注册图片回调 ​

在业务 Service 内、请求拍照前注册回调：

registerAiFileListener(bytes -> {
    if (bytes == null || bytes.length == 0) return;
    byte[] image = bytes.clone();
    // 将 image 交给文件保存或图像处理模块。
    // 异步处理与界面通知由 App 的工作队列和主线程完成。
});

SDK 在达到其文件结束条件后调用图片监听。App 仍需检查图片可解码、保存是否成功，并为整个拍照任务设置超时。收到回调后复制数据，避免在蓝牙回调中执行文件写入或网络请求。

2. 请求拍照 ​

CmdSendManager.getInstance().sendAIImg();

同一设备上按顺序处理拍照任务；上一个任务完成或取消后，再开始下一个。方法返回为 void，不能据此显示“图片接收成功”。

3. 保存和处理 ​

将接收数据写入 App 指定目录，检查文件可读取、图片可解码，再更新界面或提交给 AI 服务。云端服务的网络、账号与凭证由 App 独立配置。

传输状态接口的调用形式如下，state 和 index 应来自实际传输状态：

CmdSendManager.getInstance().sendFileTransmitState(state, index);

该 AAR 的方法只有两个参数，没有 cmdType 参数。确认时机和索引语义按设备传图协议使用，不能在收到任意 BLE 通知时直接发送完成确认。

4. 结束会话 ​

停止新任务、取消业务超时、清空待处理图片，并调用 registerAiFileListener(null) 释放监听。断开连接时将未完成拍照任务置为中断，重新连接后重新发起。

普通拍照与媒体下载 ​

sendTakePhoto(int photoType, String fileName) 控制普通拍照；照片保存于眼镜后，通过 Wi-Fi与文件传输获取。当前交付 AAR 没有 sendTakeBlePhoto() 或 BleFileParser，普通拍照不能套用其他版本的 BLE 文件接收流程。

LC3实时音频传输 ​

接入条件 ​

当前交付的 ksdk-release.aar 不提供 LC3 开关方法或实时音频接收回调，因此本版本不能通过 SDK 接入 LC3 实时音频。

需要该功能时，应使用包含 LC3 传输接口的 Android SDK，并匹配支持该协议的 K900 固件。开始接入前确认以下信息：

iOS 的 LC3 方法及其他 Android 版本的接口不适用于当前 AAR。升级 SDK 后，应使用新版本文档提供的接口与回调。

录音文件 ​

本版本支持 sendAudioRecord(String fileName) 控制眼镜录音，通过 Wi-Fi 接收录音文件。该流程为录音文件传输，不能用于实时 LC3 数据接收。调用参数见 API参考，文件获取见 Wi-Fi与文件传输。

AI 状态同步 ​

本版本使用 sendAISound(int state) 同步 AI 业务状态，消息体字段为 type：

AI 状态同步不启用 LC3 音频采集。不要使用其他版本的 sendAiSound() 或 Constant.AI_STATE_* 名称。

API参考 ​

本页列出 ksdk-release.aar 的指令调用方式、请求参数和回复处理要求。SDK 使用 CmdSendManager 发送指令，结果通过 CmdDealManager.BleCmdRecvListener 异步返回。

调用约定 ​

完成初始化、通道绑定和就绪确认后调用接口。方法返回类型为 void，不表示设备已执行成功。接收回调签名：

void onBleCmdRecv(Cmd cmd, JSONObject body);

发送协议的 C 为命令，B 为 JSON 字符串，无参数时 B=""。SDK 自动封装传输帧，App 不需要手工拼接。按回复命令和业务字段判断结果，并为每项业务设置超时。

指令目录 ​

指令详情 ​

查询系统是否准备好 ​

指令：cs_syrd。

调用方式：

CmdSendManager.getInstance().sendGetSystemReady();

无调用参数。

请求消息体：B=""。

回复：sr_syrd。ready：1 表示系统就绪。

获取电量 ​

指令：cs_batv。

调用方式：

CmdSendManager.getInstance().sendGetBatteryVol();

无调用参数。

请求消息体：B=""。

回复：sr_batv。pt：电量百分比；vt：电压（mV）。

查询版本 ​

指令：cs_syvr。

调用方式：

CmdSendManager.getInstance().sendGetSystemVersion();

无调用参数。

请求消息体：B=""。

回复：sr_syvr。app、sys、dpj：版本字符串。

心跳指令 ​

指令：cs_hrt。

调用方式：

CmdSendManager.getInstance().sendHeart();

无调用参数。

请求消息体：B=""。

回复：sr_hrt。pt：电量百分比；ready：系统就绪状态，1 为就绪。

设置亮度 ​

指令：cs_brt。

调用方式：

CmdSendManager.getInstance().sendBright(brightValue);

回复命令：sr_brt。按外层状态处理应答；业务字段以设备协议为准。

请求眼镜打开wifi热点 ​

指令：cs_opap。

调用方式：

CmdSendManager.getInstance().requestServerOpenHotspot();

无调用参数。

请求消息体：B=""。

回复：sr_apsr。succ、ssid、pwd：热点开启结果与连接信息。

向眼镜请求wifi关闭 ​

指令：cs_csap。

调用方式：

CmdSendManager.getInstance().closeHotspot();

无调用参数。

请求消息体：B=""。

回复命令：sr_csap。按外层状态处理应答；业务字段以设备协议为准。

关设备 ​

指令：cs_shut。

调用方式：

CmdSendManager.getInstance().shutDevice();

无调用参数。

请求消息体：B=""。

回复命令：sr_shut。按外层状态处理应答；业务字段以设备协议为准。

通知眼镜唤醒 ​

指令：cs_ivww。

调用方式：

CmdSendManager.getInstance().sendIvwwWakeup();

无调用参数。

请求消息体：B=""。

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

重启设备 ​

指令：cs_rebt。

调用方式：

CmdSendManager.getInstance().rebootDevice();

无调用参数。

请求消息体：B=""。

回复命令：sr_rebt。按外层状态处理应答；业务字段以设备协议为准。

唤醒系统 ​

指令：cs_wku。

调用方式：

CmdSendManager.getInstance().sendWakeup();

无调用参数。

请求消息体：B=""。

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

休眠系统 ​

指令：cs_slp。

调用方式：

CmdSendManager.getInstance().sendSleep();

无调用参数。

请求消息体：B=""。

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

请求文件传输 ​

指令：cs_asfl。

调用方式：

CmdSendManager.getInstance().askFile(fileType);

回复命令：sr_asfl。按外层状态处理应答；业务字段以设备协议为准。

设置时间指令 ​

指令：cs_stm。

调用方式：

CmdSendManager.getInstance().sendSetTime(curTime);

回复命令：sr_stm。按外层状态处理应答；业务字段以设备协议为准。

拍照 ​

指令：cs_pho。

调用方式：

CmdSendManager.getInstance().sendTakePhoto(photoType, fileName);

回复：sr_pho。succ；成功读取 phonum、vdonum、adonum；失败读取 state。

连拍 ​

指令：cs_ctph。

调用方式：

CmdSendManager.getInstance().sendContinuePhoto();

无调用参数。

回复：sr_ctph。succ；成功读取 phonum、vdonum、adonum；失败读取 state。

控制录像 ​

指令：cs_vdo。

调用方式：

CmdSendManager.getInstance().sendVideoRecord(videoType, fileName);

回复：sr_vdo。succ；成功读取 phonum、vdonum、adonum；失败读取 state。

控制录音 ​

指令：cs_ado。

调用方式：

CmdSendManager.getInstance().sendAudioRecord(fileName);

回复：sr_ado。succ；成功读取 phonum、vdonum、adonum；失败读取 state。

报告某个文件接收完 ​

指令：cs_flrv。

调用方式：

CmdSendManager.getInstance().sendFileRecv(fileType, fname);

回复：sr_flrv。ftype：文件类型；fname：文件名。

设置音量 ​

指令：cs_vol。

调用方式：

CmdSendManager.getInstance().sendVolume(volume);

回复命令：sr_vol。按外层状态处理应答；业务字段以设备协议为准。

清空眼镜的多媒体 ​

指令：cs_clst。

调用方式：

CmdSendManager.getInstance().sendClearAllMedia();

无调用参数。

调用方式：

CmdSendManager.getInstance().sendClearPhotoMedia();

无调用参数。

调用方式：

CmdSendManager.getInstance().sendClearVideoMedia();

无调用参数。

调用方式：

CmdSendManager.getInstance().sendClearAudioMedia();

无调用参数。

回复：sr_clst。ftype：清除的文件类型。

查询存储信息 ​

指令：cs_gtst。

调用方式：

CmdSendManager.getInstance().sendGetStorageInfo();

无调用参数。

请求消息体：B=""。

回复：sr_gtst。total_size、free_size、phonum、vdonum、adonum。

获取眼镜多媒体的设置 ​

指令：cs_gmst。

调用方式：

CmdSendManager.getInstance().sendGetMediaSettings();

无调用参数。

请求消息体：B=""。

回复：sr_gmst。pw、ph：照片尺寸；vw、vh：视频尺寸；vq：视频质量；vs：视频时长；as：录音时长。

设置拍照参数 ​

指令：cs_phst。

调用方式：

CmdSendManager.getInstance().sendSetPhotoParam(width, height);

回复命令：sr_phst。按外层状态处理应答；业务字段以设备协议为准。

设置录像参数 ​

指令：cs_vdst。

调用方式：

CmdSendManager.getInstance().sendSetVideoParam(width, height, quantity, record_seconds);

回复命令：sr_vdst。按外层状态处理应答；业务字段以设备协议为准。

设置录音参数 ​

指令：cs_adst。

调用方式：

CmdSendManager.getInstance().sendSetAudioParam(record_seconds);

回复命令：sr_adst。按外层状态处理应答；业务字段以设备协议为准。

发送翻译内容 ​

指令：cs_trns。

调用方式：

CmdSendManager.getInstance().sendTrans(content);

回复命令：sr_trns。按外层状态处理应答；业务字段以设备协议为准。

是否开启图像算法 ​

指令：cs_phoalg。

调用方式：

CmdSendManager.getInstance().sendSetPhoalg(enable);

回复命令：sr_phoalg。按外层状态处理应答；业务字段以设备协议为准。

是否开启视频防抖 ​

指令：cs_vdoeis。

调用方式：

CmdSendManager.getInstance().sendSetVdoeis(enable);

回复命令：sr_vdoeis。按外层状态处理应答；业务字段以设备协议为准。

获取图像算法/视频防抖开关状态 ​

指令：cs_algeis。

调用方式：

CmdSendManager.getInstance().sendAlgeis();

无调用参数。

外层字段：W=1。

请求消息体：B=""。

回复：sr_algeis。phoalgenable、vdoeisenable：按字符串处理。

设置BT蓝牙名称 ​

指令：cs_btna。

调用方式：

CmdSendManager.getInstance().sendSetBTName(name);

回复命令：sr_btna。按外层状态处理应答；业务字段以设备协议为准。

设置智能交互开关 ​

指令：cs_swit。

调用方式：

CmdSendManager.getInstance().sendSetSwit(type, enable);

回复命令：sr_swit。按外层状态处理应答；业务字段以设备协议为准。

获取智能交互开关 ​

指令：cs_swst。

调用方式：

CmdSendManager.getInstance().sendSwst();

无调用参数。

请求消息体：B=""。

回复：sr_swst。status：智能交互开关位状态。

AI拍照传图 ​

指令：cs_aiph。

调用方式：

CmdSendManager.getInstance().sendAIImg();

无调用参数。

外层字段：W=1。

请求消息体：B=""。

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

同步 AI 状态 ​

指令：cs_sound。

调用方式：

CmdSendManager.getInstance().sendAISound(state);

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

文件状态同步 ​

指令：cs_flts。

调用方式：

CmdSendManager.getInstance().sendFileTransmitState(state, index);

外层字段：W=1。

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

手机发送热点信息 ​

指令：cs_wfsta。

调用方式：

CmdSendManager.getInstance().sendWifiSTA(ssid, pwd);

外层字段：W=1。

回复：sr_wfsta。ip：用于文件连接的眼镜地址。

设置Ble蓝牙名称 ​

指令：cs_blna。

调用方式：

CmdSendManager.getInstance().sendSetBleName(bleName);

该接口未约定独立的业务回复字段。App 应结合相应设备事件和超时判断业务状态。

获取BT蓝牙名称 ​

指令：cs_gbtna。

调用方式：

CmdSendManager.getInstance().sendBTName();

无调用参数。

请求消息体：B=""。

回复命令：sr_gbtna。按外层状态处理应答；业务字段以设备协议为准。

获取Mac地址 ​

指令：cs_btaddr。

调用方式：

CmdSendManager.getInstance().sendMacAdress();

无调用参数。

请求消息体：B=""。

回复命令：sr_btaddr。按外层状态处理应答；业务字段以设备协议为准。

使用限制 ​

• sendClearAudioMedia() 的请求类型为全部媒体（0xFF），不得用于“仅删除录音”。清除照片、视频分别使用相应接口；清除操作应由用户发起。
• sendFileTransmitState(boolean state, int index) 只有两个参数。
• sendAISound(int state) 的方法名区分大小写。
• sendBTName() 发送 cs_gbtna；sendMacAdress() 发送 cs_btaddr。

核心接口 ​

设备事件 ​

ss_avpg 通知录音或录像进度，包含 type、total、current；sr_inst 通知安装状态，包含 ftype、fname、state。事件应由设备管理对象统一分发，不能把任意设备事件视为当前请求成功。

蓝牙连接与生命周期 ​

连接阶段 ​

扫描 → 选择 BLE 地址 → GATT 连接 → MTU 协商 → 服务与特征发现 → 通知订阅 → 就绪探测 → 业务指令。

BluetoothLEService 在 GATT 建链后立即发出 STATE_CONNECTED，随后才处理 MTU 和服务发现。onBleConnected / onConnectStateChange(true) 不保证业务通道已经可写。SDK 没有独立的“全部通知订阅成功”回调，发送业务指令前应在有限超时内探测 cs_syrd 并等待 ready=1，如 快速开始。

扫描与地址 ​

扫描失败先检查权限、蓝牙和位置开关、眼镜广播状态。A2DP 属于经典蓝牙音频连接，BLE 连接成功不代表通话或音乐通道已连接。

指令与图片接收 ​

• onBleRecvData(byte[])：转给 CmdDealManager.deal() 解析控制命令，不能逐个 BLE 通知直接当作完整 JSON。
• registerAiFileListener()：注册 AI 图片监听，在 onAiFileResult(byte[]) 中处理图片。

AI 图片处理见 AI拍照与传图。同一单例、同一控制器应由一个设备管理层拥有，页面通过业务事件订阅。

心跳与重连 ​

CmdSendManager.init() 启动心跳：首次约 2 秒后发送，默认间隔 30 秒。setHeartTime(seconds) 应在 init() 前设置且大于 0；已创建的调度器不会自动采用后改值。未绑定 IBluetooth 时发送不会到达设备。

断开时立即将就绪状态置为 false，移除待发送任务并清理待回复请求。重连重新探测就绪。重连策略应结合用户主动断开、蓝牙关闭和权限撤销管理重试，避免无间隔扫描。

释放顺序 ​

1. 停止业务请求、就绪探测、文件发送线程与超时任务。
2. cancelScan()、disconnect()，清空业务连接状态。
3. CmdSendManager.destroy() 停止心跳，setBluetooth(null) 清除发送通道。
4. registerServiceListener(null)、registerAiFileListener(null)，替换解析监听为 null；CmdDealManager 当前没有独立销毁接口。
5. 调用 FileSaver.close()，关闭业务文件；销毁 Socket，释放 Wi-Fi 网络绑定。
6. 解绑并停止业务 Service；BleBaseService.onDestroy() 会释放控制器。

收到回调后更新界面切换主线程；文件落盘与解码放在工作线程，并保持同一数据流顺序。

自主管理 BLE ​

App 已有 BLE 管理模块时，可自行负责扫描、连接、服务发现和通知订阅，并将发送通道接入 SDK。该方式不使用 BleBaseService，前台通知与连接生命周期由 App 管理。

IBluetooth transport = new IBluetooth() {
    @Override public void write(byte[] data) {
        // 将完整指令帧交给 App 的 BLE 发送队列。
        // 按协商后的 MTU 分包，串行写入 K900 指令特征。
    }
};
CmdSendManager.getInstance().init(context.getApplicationContext());
CmdSendManager.getInstance().setBluetooth(transport);
CmdDealManager.getInstance().init(context.getApplicationContext(), listener);
// 收到指令通知后，将原始字节按顺序交给 SDK 解析：
CmdDealManager.getInstance().deal(receivedBytes);

示例使用 com.xy.ksdk.api.cmd.IBluetooth；listener 为 BleCmdRecvListener。注册监听后再连接，完成通知订阅后探测系统就绪。不得在 write() 中发送未经处理的超 MTU 数据，也不得并行调用 GATT 写入。该方式的 AI 图片协议接收需由 App 的 BLE 模块另外实现；CmdDealManager 仅负责控制指令解析。

摄像头参数 ​

当前交付 AAR 不提供手动曝光、白平衡、ISO、摄像头参数范围或视频 ROI 接口。需要这些功能时，应获取支持相应功能的 SDK 与固件。

本版本支持通过 sendSetPhotoParam(width, height) 设置照片尺寸、sendSetVideoParam(width, height, quantity, record_seconds) 设置录像参数。调用参数见 API参考。

Demo使用说明 ​

k900_android-demo.zip 为 Android 示例工程，演示设备连接、媒体传输、设置和升级功能。获取方式见 下载与集成。

运行步骤 ​

1. 解压 Demo，在 Android Studio 打开工程根目录。
2. 用交付目录中的 ksdk-release.aar 替换 app/libs/ksdk-release.aar。
3. 配置本机 Android SDK 和自己的调试签名，完成 Gradle Sync。
4. 选择 Android 真机编译运行，获得蓝牙和所用网络权限。
5. 扫描并选择 K900，确认系统就绪后查询电量和版本。
6. 分别测试拍照、录音、媒体下载和匹配设备的升级流程。

Demo 工程配置使用 AGP 7.1.3、Gradle 7.2、compile / target SDK 30。升级构建工具或目标 SDK 时，同时适配权限、Manifest 和前台服务；AAR 接入不要求宿主固定使用这些 Demo 构建版本。

Demo 内置 AAR 与独立交付 AAR 的接口存在差异，例如 sendSetWifiOpen() 只出现在 Demo 内置版本中。本指南采用独立 AAR；替换后使用不存在接口的 Demo 页面需同步移除或改为本版本支持的流程，不能保留两个 AAR 解决冲突。

功能代码位置 ​

以下路径相对于 app/src/main/java/com/lhs/bt/：

依赖与业务代码 ​

EventBus、媒体数据库、界面库和日志模块用于组织 Demo 业务，App 可使用自己的管理方式。SDK 的连接、发送和接收监听由一个设备管理对象统一持有，页面通过该对象获取状态。

验收步骤 ​

完成 AAR 导入、授权、扫描连接、电量与版本查询，再检查图片接收、Wi-Fi 文件保存和断线重连。升级功能使用匹配当前设备版本的升级包，并在重连后读取版本确认结果。

检查用户拒绝权限、取消热点连接、眼镜断开和 App 结束会话时的状态与资源释放。

错误码与排查 ​

指令状态与业务状态 ​

Cmd.state 对应协议外层 S，业务回调按对应指令的状态约定处理结果，配套示例以非 0 作为指令失败。部分回复还在 B 中使用 succ、state 等业务字段，应按该指令分别处理，不能只检查外层状态。

解析器用 optInt 读取 S，缺失时默认 0；如果需要严格确认成功，在宿主协议层补充字段存在性检查。空或解析失败的消息体可能返回 null，访问前先判断。

拍摄相关状态 ​

以下为 Constant.TAKEN_STATE_* 拍摄状态，用于相应业务回复，不作为全部指令的通用错误码：

常见问题 ​

联调记录 ​

记录 SDK 版本、手机系统与 target SDK、固件版本、调用时间、命令码、连接阶段及已脱敏的状态字段。按该指令的回复字段处理结果；发送超时、设备失败和文件保存失败分别展示。

Wi-Fi与文件传输 ​

Wi-Fi 用于照片、视频、录音批量传输及升级包发送。控制命令走 BLE，文件通道使用 Netty 与 protobuf FileBody.FileMessage。

建立文件通道 ​

1. 保持 BLE 通信就绪，调用 requestServerOpenHotspot()。
2. 处理 sr_apsr：检查 succ，成功时读取 ssid、pwd。失败时停止流程。
3. 初始化 WifiConnector，调用 connect(ssid, pwd)，等待系统连接确认及 onWifiConnectResult；授权拒绝或 onWifiConnectTimeout 时允许取消和重试。
4. 网络连接成功后，在工作线程用 SocketManager.connectServer(ip) 建立文件通道。热点模式可参考 WifiConnector.getServerIP()；STA 模式使用设备回复中的 IP。
5. 等待 SocketListener.onFileConnectState(true)，再发起获取或发送。

SocketManager socket = new SocketManager(context);
socket.registerListener(new SocketListener() {
    @Override public void onFileConnectState(boolean connected) {
        if (connected) {
            CmdSendManager.getInstance().askFile(CmdType.CMD_TYPE_ALL_MEDIA);
        }
    }
    @Override public void onFileReceive(FileBody.FileMessage file) {
        FileSaver.getInstance().write(file);
    }
});
// 在工作线程、网络就绪后执行；serverIp 是本次会话确认的眼镜 IP。
socket.connectServer(serverIp);

示例需导入 com.xy.ksdk.api.wifi.*、com.xy.ksdk.api.cmd.*、com.xy.ksdk.protos.FileBody。connectServer() 的返回值不能替代异步连接状态。文件端口为 6001，不要猜测固定 IP。

接收和保存 ​

在接收前调用 FileSaver.getInstance().init(context, listener)，实现 FileSaverListener：

FileSaver 按末包触发完成并自动发送接收确认。App 应同时检查收到的文件大小和完整性，不将末包到达直接作为业务文件有效的依据；结束会话调用 FileSaver.close() 关闭文件。

文件类型：照片 0x31、视频 0x32、录音 0x34、全部媒体 (byte)0xFF。0x33 在本 AAR 中为音乐类型，不用于请求眼镜录音。文件完成后核对实际大小、可读取性与会话完整性，再更新媒体列表。清空媒体指令会删除眼镜中的文件，按用户操作发起。

STA 网络 ​

使用手机热点时，先开启手机热点，再调用 sendWifiSTA(ssid, pwd) 将热点信息发送给眼镜。设备返回 sr_wfsta 的 ip 后，使用该地址建立文件连接。热点凭据仅用于本次连接，日志中不得输出密码。

本 AAR 不提供 sendConnectWifi() 或手机端 NettyServer。使用 STA 传输时，App 需确保手机与眼镜位于可互通的网络，并使用设备本次回复的地址。

结束传输 ​

停止发送线程 → socket.destroy() → WifiConnector.getInstance().unregisterNetwork() → 根据业务调用 closeHotspot()。WifiConnector 在 Android 10+ 路径中使用 bindProcessToNetwork(network)，释放后才能恢复进程默认路由；传输期间云端请求可能无法通过无互联网的眼镜热点。

WifiConnector 没有完整的销毁接口，应由统一设备管理对象初始化一次并持有 App 上下文，避免反复初始化和持有 Activity。会话结束时释放网络请求及绑定。

不同系统上的扫描、热点确认、SSID 读取与网络绑定须真机核验，权限见 下载与集成。

概述 ​

K900SDK 是面向 K900 眼镜的 Android 开发工具包，用于在 App 中接入设备连接、控制指令、AI 图片接收、文件传输及升级功能。集成文件为 ksdk-release.aar，后续示例使用 SDK 的实际类名和方法名。

主要能力 ​

SDK 提供设备通信接口。App 负责界面展示、文件保存、业务状态管理和 AI 服务对接。

接入顺序 ​

1. 按 下载与集成添加 AAR、依赖和权限。
2. 按 快速开始注册回调、扫描连接并查询电量。
3. 管理通信就绪、断开重连和回调生命周期。
4. 按功能章节接入业务，在 API参考中查询参数与返回内容。

使用 Android 真机调试，结合 Demo使用说明检查基础流程。

版本与功能范围 ​

本交付 AAR 的 Constant.SDK_VERSION 为 1.1，配套协议文档版本为 1.0.7；两者分别表示 SDK 与协议文档版本。以交付包公开接口为准。

当前 AAR 不提供普通 BLE 拍照、LC3 实时音频传输和手动摄像头参数接口。需要这些能力时，获取包含相应接口的 SDK 与匹配固件；不能直接调用其他版本或 iOS 的方法。LC3 接入条件见 LC3实时音频传输。

文档说明 ​

功能章节介绍调用顺序和完成条件；API 参考集中说明接口与参数；错误码与排查用于分析连接、设备回复和传输异常。接口返回不表示设备业务执行成功，结果由回调和设备状态确认。

下载与集成 ​

本页介绍 ksdk-release.aar 在 Android App 中的集成方式。完成依赖和权限配置后，按 快速开始建立设备连接。

对接文档 ​

下载中文版 Android SDK 对接文档

获取 SDK ​

通过官网联系我们获取 K900 Android SDK 和配套 Demo。交付文件如下：

本页使用交付目录中的独立 ksdk-release.aar。Demo 的 app/libs/ 中也有同名 AAR；运行 Demo 时，将该文件替换为本次使用的 SDK，保持 App 和文档对应同一接口版本。不要同时引入多个 SDK AAR。

环境要求 ​

SDK 已包含 protobuf 生成类。使用 AAR 时不需要导入 ksdk 源码模块，不需要配置 protoc 或 protobuf 代码生成插件。

添加 SDK ​

1. 将 ksdk-release.aar 复制到 App 模块的 app/libs/ 目录。
2. 在仓库配置中启用 google() 和 mavenCentral()。
3. 在 App 模块的 build.gradle 中添加本地 AAR 及运行时依赖：

android {
    defaultConfig {
        minSdkVersion 21
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    implementation files('libs/ksdk-release.aar')
    implementation 'io.netty:netty-all:4.1.68.Final'
    implementation 'com.google.protobuf:protobuf-javalite:3.18.1'
    implementation 'androidx.appcompat:appcompat:1.3.0'
}

本地 AAR 不会自动解析 Maven 传递依赖，必须在宿主工程中声明。宿主已使用 AppCompat 时，保持同一兼容版本。

SDK 内置 OTA 界面还使用以下依赖；接入该界面时增加：

dependencies {
    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.0.0'
    implementation 'com.nbsp:materialfilepicker:1.9.1'
}

MaterialFilePicker 需要配置包含该版本的依赖源，按交付说明配置。Demo 的日志示例使用 SLF4J 1.7.25，界面使用 Material、ConstraintLayout、EventBus 和 Glide；这些依赖由 Demo 的 build.gradle 管理。

4. 执行 Gradle Sync，检查 App 可以导入 SDK 类。
5. 编译并在真机运行 App。启用混淆时，先验证 SDK 连接、指令解析、文件传输和 OTA 路径；保留 protobuf 消息类及 SDK 内置 Activity 的必要规则。

导入 SDK ​

import com.xy.bt.api.BleBaseService;
import com.xy.ksdk.api.cmd.CmdSendManager;
import com.xy.ksdk.api.cmd.CmdDealManager;

权限配置 ​

在 App 的 AndroidManifest.xml 中声明下列权限。权限需在运行时获得用户授权后，才能初始化蓝牙、启动扫描和连接设备。新权限需使用支持相应 API 的 compile SDK。

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

• Android 6–11：扫描前申请位置运行时权限，并检查系统位置服务。
• 面向 Android 12 及以上：扫描与连接分别申请 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT。SDK 初始化时也会访问蓝牙，授权应先完成。
• 使用 Wi-Fi 扫描或读取需要位置授权的信息时，保留位置权限。若 App 确认完全不从蓝牙扫描推导位置，可以按官方要求评估 neverForLocation，并真机验证广告过滤是否影响眼镜发现。

参阅 Android 蓝牙权限。Manifest 声明不能替代运行时申请，用户拒绝时应停止相应流程并展示恢复入口。

Wi-Fi 文件传输增加：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" />

面向 Android 13 及以上、管理附近 Wi-Fi 连接时申请 NEARBY_WIFI_DEVICES；扫描、扫描结果等 API 仍可能需要位置权限。参阅 Android Wi-Fi 权限。根据目标系统额外核对局域网访问要求。

App 使用手机相机或麦克风时，另外申请 CAMERA 或 RECORD_AUDIO。眼镜采集数据不使用手机相机。文件优先保存到 App 专属目录；导出到公共媒体目录时使用 MediaStore。

Service 与 OTA 界面 ​

继承 BleBaseService 创建业务 Service，并在 application 内声明。以下类名与 快速开始示例一致：

<service
    android:name="com.example.k900.K900Service"
    android:exported="false" />

BluetoothLEService 为 SDK 内部对象，不注册为 Android Service。A2DP 业务 Service 由 App 按自身包名声明。

使用内置单片机升级界面时，在 application 内声明：

<activity android:name="com.xy.ota.view.OtaUIActivity"
    android:exported="false" android:screenOrientation="portrait" />
<activity android:name="com.xy.ota.view.ScanActivity"
    android:exported="false" android:screenOrientation="portrait" />

前台服务适配 ​

BleBaseService 的父类在启动时调用 startForeground()。前台服务必须提供有效的小图标通知；本交付 AAR 的默认通知未设置小图标，不能视为已完成所有目标系统的前台服务适配。使用该 Service 方案前，需使用提供有效通知的适配 SDK 版本；也可由 App 自行管理 BLE 连接并通过 IBluetooth 接入指令发送，见 蓝牙连接与生命周期。

面向 Android 14 及以上、使用设备连接前台服务时，增加 FOREGROUND_SERVICE_CONNECTED_DEVICE，并为业务 Service 设置 android:foregroundServiceType="connectedDevice"。参阅 Android 前台服务类型。从可见 Activity 启动 Service，按目标系统处理后台启动限制。

集成检查 ​

• AAR 仅引入一次，SDK 类可正常导入，App 编译成功。
• 蓝牙和 Wi-Fi 权限在使用前获得授权，拒绝授权时可取消操作。
• 扫描并选择眼镜，确认通信就绪后可以读取电量和版本。
• 使用文件传输时，可以连接眼镜热点、接收文件并恢复原网络。
• 结束设备会话后停止扫描、断开连接并释放监听和传输资源。

OTA升级 ​

SDK 包含 Wi-Fi 发送升级文件与单片机蓝牙升级界面两类入口。升级包必须与目标硬件、芯片和固件匹配。

Wi-Fi 升级文件 ​

先按 Wi-Fi与文件传输建立文件通道，确认 onFileConnectState(true) 后在业务层发送：

FileSender sender = new FileSender(context, socket);
sender.setFilePath(CmdType.CMD_TYPE_VERSION_OTA, verifiedPackagePath);
sender.setListener((type, path, percent) -> {
    // 文件发送进度；更新界面时切换主线程。
});
sender.start();

示例需导入 FileSender 和 CmdType，verifiedPackagePath 为已检查可读取且匹配本设备的文件。FileSender 继承 Thread，每次传输创建新实例；FileSender 未提供可靠的业务取消接口，interrupt() 不保证传输已经结束。App 应防止重复启动发送任务，在传输失败或超时后停止新请求、释放连接并检查线程退出状态。

升级结果 ​

文件发送到 100% 表示发送进度，不能作为设备安装成功的依据。处理 sr_inst 安装状态事件，其中 ftype 表示文件类型，fname 表示文件名，state 表示设备安装状态；安装状态取值按匹配固件的升级协议处理。

系统差分 OTA 包必须对应设备当前系统版本。升级应用时使用高于当前版本的 APK，系统升级使用匹配当前版本的差分 ZIP，单片机升级使用匹配型号的 BIN。升级前检查电量，升级过程中保持眼镜供电。

流程应为：读取当前版本 → 校验升级包与升级条件 → 传输 → 等待设备升级状态 → 必要时等待重启 → 重连 → sendGetSystemVersion() → 核对 app / sys / dpj 目标版本。

升级中避免并行拍照、媒体下载和重复发送包。设备断连不直接判定升级失败，结合升级阶段和重连版本核验；恢复规则按固件升级协议实现。

单片机蓝牙升级 ​

单片机 BIN 包通过 SDK 内置升级界面处理。在 Manifest 中声明 OTA Activity 并添加界面依赖后，打开界面：

Intent intent = new Intent(context, OtaUIActivity.class);
intent.putExtra("filepath", verifiedBinPath);
intent.putExtra("bleaddr", bleAddress);
// context 为非 Activity 上下文时增加此标志。
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
context.startActivity(intent);

导入 com.xy.ota.view.OtaUIActivity。verifiedBinPath 为匹配设备的可读 BIN 路径，bleAddress 为升级目标 BLE 地址；按升级界面的扫描流程选择目标，避免发送给其他设备。

内置升级界面与 Wi-Fi FileSender 为不同流程，不能将系统 ZIP 包送入单片机升级入口。升级完成并重连后，读取版本确认实际结果。

快速开始 ​

本页用“连接眼镜并读取电量”说明基础接入。先完成 下载与集成和运行时权限授权，开启手机蓝牙，使用 K900 真机。

1. 建立业务 Service ​

以下示例采用 BleBaseService 方案。先完成 Service 与前台通知适配，再启动该 Service。扫描结果保存在设备管理层，界面通过绑定 Service 获取实例，并显示设备供用户选择。示例只在就绪状态下查询电量。

package com.example.k900;

import android.bluetooth.BluetoothDevice;
import android.os.Handler;
import android.os.Looper;
import android.util.Log;
import com.xy.bt.api.BleBaseService;
import com.xy.ksdk.api.cmd.CmdDealManager;
import com.xy.ksdk.api.cmd.CmdSendManager;

public class K900Service extends BleBaseService {
    private final Handler main = new Handler(Looper.getMainLooper());
    private boolean connected;
    private boolean ready;
    private int attempts;
    private final Runnable probe = new Runnable() {
        @Override public void run() {
            if (!connected || ready) return;
            if (++attempts > 10) {
                Log.w("K900", "设备就绪超时");
                return;
            }
            CmdSendManager.getInstance().sendGetSystemReady();
            main.postDelayed(this, 3000);
        }
    };

    @Override public void onCreate() {
        super.onCreate();
        // 生命周期统一由一个设备管理 Service 持有。
        CmdSendManager.getInstance().init(getApplicationContext());
        CmdDealManager.getInstance().init(getApplicationContext(), (cmd, body) -> {
            main.post(() -> {
                if (!connected || cmd.state != 0 || body == null) return;
                if ("sr_syrd".equals(cmd.cmd) || "sr_hrt".equals(cmd.cmd)) {
                    if (body.optInt("ready", 0) == 1 && !ready) {
                        ready = true;
                        main.removeCallbacks(probe);
                        CmdSendManager.getInstance().sendGetBatteryVol();
                    }
                } else if ("sr_batv".equals(cmd.cmd)) {
                    Object value = body.opt("pt");
                    if (value instanceof Number) {
                        double percent = ((Number) value).doubleValue();
                        if (percent >= 0 && percent <= 100) {
                            Log.i("K900", "电量：" + percent + "%");
                            // 通知界面更新电量。
                        }
                    }
                }
            });
        });
    }

    @Override protected void onDeviceFound(String btAddress,
            BluetoothDevice bleDevice, short rssi) {
        // 按 bleDevice.getAddress() 去重，将 BLE 设备交给界面选择。
        // btAddress 为广播中解析的经典蓝牙地址，不用于 BLE connect。
    }

    public void connectSelected(BluetoothDevice device) {
        cancelScan();
        connect(device.getAddress());
    }

    @Override protected void onConnectStateChange(boolean value) {
        main.post(() -> {
            connected = value;
            ready = false;
            attempts = 0;
            main.removeCallbacks(probe);
            CmdSendManager.getInstance().setBluetooth(value ? mController : null);
            // 已连接后仍须等待 MTU、服务发现与通知订阅。
            if (value) main.postDelayed(probe, 1000);
        });
    }

    @Override protected void onBleRecvData(byte[] data) {
        if (data != null && data.length > 0) {
            CmdDealManager.getInstance().deal(data);
        }
    }

    @Override public void onDestroy() {
        connected = false;
        ready = false;
        main.removeCallbacksAndMessages(null);
        cancelScan();
        CmdSendManager.getInstance().destroy();
        CmdSendManager.getInstance().setBluetooth(null);
        // 当前解析管理器无 destroy 接口；替换 listener 释放业务引用。
        CmdDealManager.getInstance().init(getApplicationContext(), null);
        super.onDestroy();
    }
}

Manifest 中的类名应与实际包名一致。就绪探测最多执行 10 次，超时后停止探测并通知界面重试。用户取消或设备断开时立即停止探测。

2. 启动并绑定 ​

在可见 Activity 中、权限获批后启动 Service。以下 context 为 Activity 上下文，connection 为宿主的 ServiceConnection：

Intent intent = new Intent(context, K900Service.class);
ContextCompat.startForegroundService(context, intent);
context.bindService(intent, connection, Context.BIND_AUTO_CREATE);

在 onServiceConnected 中，继承的 Binder 可获取业务实例：

K900Service service = (K900Service)
        ((BleBaseService.LocalBinder) binder).getService();
service.startScan();

代码需导入 Intent、Context、ContextCompat 和 BleBaseService。解绑不会自动停止已启动的 Service，结束设备会话时还需调用 stopService(intent)。

3. 选择并连接 ​

收到 onDeviceFound 后，保存对应 BluetoothDevice。用户选择时调用 service.connectSelected(device)。扫描会自动在约 10 秒后结束；没有结果时可在用户重试后再扫描。

连接参数为 BLE 地址，不要把回调中的经典蓝牙 btAddress 传给 connect()。

4. 就绪与查询 ​

sendGetSystemReady() 对应 cs_syrd。收到 sr_syrd 或 sr_hrt 的 ready=1 后，示例调用 sendGetBatteryVol()（cs_batv）。这同时验证了命令通道能收到业务回复。

电量回复示例：

{"C":"sr_batv","S":0,"B":"{\"pt\":81,\"vt\":4192}"}

Android CmdDealManager 将 S 解析为 cmd.state 整数，将字符串 B 转换为回调的 JSONObject body。pt 表示电量百分比；vt 在现有设备协议中表示电压。指令状态与业务字段的处理见 API参考。

5. 结束会话 ​

停止扫描、断开连接、清除就绪探测与业务监听，解绑并停止 Service。界面之间切换时让统一设备管理对象继续持有会话；具体释放顺序见 蓝牙连接与生命周期。

iOS SDK ​

选择设备对应的 SDK，查看集成方法、调用流程和接口说明。

首次接入 K900，请依次阅读「下载与集成」「快速开始」「蓝牙连接与生命周期」。

AI拍照与传图 ​

AI 拍照用于获取眼镜拍摄的图片，供 App 进行图像识别等 AI 业务处理。本页介绍拍照指令的发送方式，以及指令回复和 BLE 文件数据的接收方式。

拍照接口 ​

根据业务需要选择一种接口发起拍照。

接入流程 ​

注册接收回调 → 建立设备连接 → 通信通道就绪 → 发送拍照指令 → 接收设备回复与文件数据 → 处理图片

发送指令前，完成蓝牙连接与生命周期中的连接与回调配置。指令回复与文件数据通过不同回调接收，由 App 的设备管理对象统一分发。

注册接收回调 ​

接收指令回复 ​

XYBleManager *ble = [XYBleManager sharedInstance];
ble.receiveDataBlock = ^(XYBleRespondModel *response) {
    NSLog(@"回复指令：%@，状态：%@，数据：%@",
          response.cmd, response.status, response.data);
    // 根据回复指令分发业务处理。
};

该回调由所有控制指令共用，具体回复码及字段分别见 sendAiph 和 sendTakeBlePhoto。

接收文件数据 ​

设备通过 BLE 文件通道返回数据时，SDK 负责分包校验和组包。完整文件接收完毕后，通过 fileReceiveDataBlock 返回文件内容，App 无需再次拼接数据包。

以下代码演示接收文件并尝试解码图片：

#import <UIKit/UIKit.h>
#import <XingYiGlassesSDK/XingYiGlassesSDK.h>

XYBleManager *ble = [XYBleManager sharedInstance];
ble.fileReceiveDataBlock = ^(NSData *fileData) {
    NSData *imageData = [fileData copy];
    if (imageData.length == 0) {
        return;
    }

    dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
        UIImage *image = [UIImage imageWithData:imageData];
        if (!image) {
            NSLog(@"接收的文件无法解码为图片");
            return;
        }

        // imageData 可用于保存图片或提交到 App 的 AI 服务。
        dispatch_async(dispatch_get_main_queue(), ^{
            // 在此将 image 显示到 App 界面。
            NSLog(@"图片尺寸：%.0f × %.0f", image.size.width, image.size.height);
        });
    });
};

fileData 为完整文件内容，不包含文件名、请求标识或指令名称。该回调由 BLE 文件传输功能共用，App 应结合当前业务状态分发数据，避免同时发起多个需要通过此回调接收结果的任务。

图片格式和尺寸从实际返回的数据中读取。图片解码、保存与 AI 服务调用由 App 处理。

发送拍照指令 ​

sendAiph ​

通信通道就绪并注册接收回调后，调用：

[[XYBleManager sharedInstance] sendAiph];

SDK 发送的请求内容：

{"C":"cs_aiph","B":"","W":1}

sendTakeBlePhoto ​

使用 sendTakeBlePhoto:width:height:quality: 指定拍照参数。图片通过 BLE 文件通道返回，接收方式见上方“接收文件数据”。

- (void)sendTakeBlePhoto:(NSString *)pictureName
                  width:(NSInteger)width
                 height:(NSInteger)height
                quality:(NSInteger)quality;

以下为调用方式，参数由业务调用方传入：

[[XYBleManager sharedInstance] sendTakeBlePhoto:pictureName
                                        width:width
                                       height:height
                                      quality:quality];

SDK 发送 cs_bleph 指令，将图片名称、宽度、高度和质量编码为 JSON 字符串放入请求的 B 字段。参数取值应符合设备支持的拍照配置。

发起拍照前保存本次任务的图片名称。收到 fileReceiveDataBlock 后，将完整图片数据交给当前任务处理；回调本身不返回图片名称。该接口返回 void，调用结束不表示图片接收完成。

两种拍照接口共用页面前述接收回调，无需分别重复注册。具体请求参数和返回说明见 API参考。

指令回复 ​

sendAiph 回复 ​

无响应。

sendTakeBlePhoto 回复 ​

无响应。

完整指令说明分别见 cs_aiph 和 cs_bleph。

接收状态与会话管理 ​

• 指令回复用于处理设备返回的状态，文件回调用于获取接收完成的文件内容，两者分别处理。
• BLE 文件接收回调提供完整文件数据，不提供逐包进度或独立的错误参数。App 可管理等待超时，并在断线时结束当前接收任务。
• SDK 在断线后清理未完成的文件数据。重新连接后，重新发起业务流程。
• 回调由设备管理对象统一注册，避免在功能页面中反复赋值。会话结束时清理该对象持有的任务与回调。

LC3实时音频传输 ​

K900SDK 支持通过 BLE 接收眼镜采集的 LC3 编码音频。App 使用 SDK 控制音频传输，并通过回调获取数据，进行解码、播放、保存或语音业务处理。

接入流程 ​

建立设备连接 → 注册音频回调 → 开启音频传输 → 接收与处理数据 → 停止传输 → 结束音频会话

开始前，完成下载与集成和蓝牙连接与生命周期中的配置，确保通信通道就绪。音频回调应在开启传输前注册。

接口与回调 ​

开始和停止接口均无参数，返回值为 void。音频数据通过 lc3ReceiveDataBlock 持续返回，方法返回值不表示数据接收结果。

1. 注册音频接收回调 ​

由 App 的设备管理对象注册回调，并将音频数据交给音频处理模块。

#import <XingYiGlassesSDK/XingYiGlassesSDK.h>

// 在音频会话初始化时创建队列。
dispatch_queue_t audioQueue = dispatch_queue_create(
    "com.app.glasses.audio", DISPATCH_QUEUE_SERIAL);

XYBleManager *ble = [XYBleManager sharedInstance];
ble.lc3ReceiveDataBlock = ^(NSData *lc3Data) {
    if (lc3Data.length == 0) {
        return;
    }
    NSData *audioData = [lc3Data copy];

    dispatch_async(audioQueue, ^{
        // 将 audioData 交给音频处理模块，完成帧处理与 LC3 解码。
        // 解码后的 PCM 数据可用于播放、保存或语音服务。
    });
};

回调数据为流式音频内容，不是累计文件。异步处理前复制数据，使用同一音频处理队列消费数据，并控制缓冲区大小。界面更新切换到主线程执行。

2. 开启音频传输 ​

通信通道就绪且音频处理模块准备完成后，调用：

[[XYBleManager sharedInstance] sendEnableLC3:YES];

开启后，通过 lc3ReceiveDataBlock 获取眼镜传来的音频数据。控制指令的回复由 receiveDataBlock 接收，具体字段见 API参考。

3. 处理音频数据 ​

App 根据业务需要，将接收到的数据送入 LC3 解码器，转换为 PCM 后进行后续处理。

LC3 编码数据需要解码后才能作为 PCM 使用，也不能直接作为完整 WAV 文件播放。SDK 提供控制与数据接收接口，解码器、播放器和语音服务由 App 的音频模块接入。

4. 停止音频传输 ​

结束音频业务时，调用：

[[XYBleManager sharedInstance] sendEnableLC3:NO];

同时结束 App 的音频接收任务，处理剩余缓存并停止相关播放或语音服务。已进入处理队列的数据应结合会话状态处理，避免写入下一次会话。

音频会话管理 ​

• 音频回调由设备管理对象统一维护，重复赋值会替换原有处理逻辑。
• 设备断线时，结束当前音频任务并清理未完成的缓存。重新连接后，重新初始化音频处理状态并开启传输。
• 结束音频会话时，停止传输，并在不再接收音频后清理对应回调。

[XYBleManager sharedInstance].lc3ReceiveDataBlock = nil;

清理回调仅停止 App 的回调处理，不能替代向眼镜发送停止传输指令。

与 AI 语音交互配合 ​

接入语音交互时，可通过 receiveDataBlock 处理设备唤醒及交互事件，再根据业务状态管理音频会话。

主动事件按指令名称分发，状态字段按各事件的定义处理。AI 状态同步与 LC3 传输控制分别调用，具体参数和回复说明见 API参考。

配套工程的音频接收与业务组织方式见 Demo使用说明。

API 参考 ​

本页统一列出 K900SDK 的控制指令、设备事件与公开接口，提供方法声明、调用方式、参数和返回说明。

阅读与调用方式 ​

控制指令由 XYBleManager 发送，解析后的回复通过 receiveDataBlock 返回。BLE 文件、Wi-Fi 文件和 LC3 音频使用各自的数据回调。

返回值为 void 的控制方法通过回调获取执行结果。同类请求按业务顺序处理，涉及拍照、删除、关机或升级的请求，应确认执行结果后再决定是否重发。

XYBleRespondModel.status 以字符串形式返回设备状态。状态值的含义以对应指令为准；设备主动事件按各自的返回字段处理。

指令索引 ​

心跳指令 ​

指令码： cs_hrt

方法与调用 ​

同步心跳包。

- (void)openHeart;

该方法无需参数。

[[XYBleManager sharedInstance] openHeart];

返回说明 ​

回复示例

{
  "C": "sr_hrt",
  "S": 0,
  "B": {
    "vt": 4382,
    "pt": 97,
    "ready": 1,
    "charg": 0
  }
}

设置时间指令 ​

指令码： cs_stm

方法与调用 ​

设置时间。

- (void)sendSetTime;

该方法无需参数。

[[XYBleManager sharedInstance] sendSetTime];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_stm",
  "S": 0,
  "B": ""
}

获取电量 ​

指令码： cs_batv

方法与调用 ​

获取电量。

- (void)sendGetBatteryVol;

该方法无需参数。

[[XYBleManager sharedInstance] sendGetBatteryVol];

返回说明 ​

回复示例

{
  "C": "sr_batv",
  "S": 0,
  "B": {
    "vt": 4381,
    "pt": 97
  }
}

查询版本 ​

指令码： cs_syvr

方法与调用 ​

获取版本。

- (void)sendGetSystemVersion;

该方法无需参数。

[[XYBleManager sharedInstance] sendGetSystemVersion];

返回说明 ​

回复示例

{
  "C": "sr_syvr",
  "S": 0,
  "B": "{\"app\":\"1.0.21\",\"sys\":\"S7_20250905\",\"dpj\":\"0.26.9.3\"}"
}

查询存储信息 ​

指令码： cs_gtst

方法与调用 ​

获取存储信息。

- (void)sendGetStorageInfo;

该方法无需参数。

[[XYBleManager sharedInstance] sendGetStorageInfo];

返回说明 ​

回复示例

{
  "C": "sr_gtst",
  "S": 0,
  "B": "{\"phonum\":3,\"vdonum\":1,\"adonum\":0,\"free_size\":25370648576,\"total_size\":25603411968}"
}

关闭设备 ​

指令码： cs_shut

方法与调用 ​

设备关机。

- (void)shutDevice;

该方法无需参数。

[[XYBleManager sharedInstance] shutDevice];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_shut",
  "S": 0
}

重启设备 ​

指令码： cs_rebt

方法与调用 ​

设备重启。

- (void)rebootDevice;

该方法无需参数。

[[XYBleManager sharedInstance] rebootDevice];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_rebt",
  "S": 0
}

拍照 ​

指令码： cs_pho

方法与调用 ​

拍照。

- (void)sendTakePhoto:(NSString *)pictureName;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendTakePhoto:pictureName];

返回说明 ​

回复示例

{
  "C": "sr_pho",
  "S": 0,
  "B": "{\"succ\":true,\"state\":0,\"type\":0,\"phonum\":4,\"vdonum\":1,\"adonum\":0}"
}

连拍 ​

指令码： cs_ctph

方法与调用 ​

连拍。

- (void)sendContinuePhoto;

该方法无需参数。

[[XYBleManager sharedInstance] sendContinuePhoto];

返回说明 ​

回复示例

{
  "C": "sr_ctph",
  "S": 5,
  "B": "{\"succ\":false,\"state\":5,\"phonum\":5,\"vdonum\":1,\"adonum\":0}"
}

开始录像 ​

指令码： cs_vdo

方法与调用 ​

录像。

- (void)sendVideoRecord:(NSString *)videoName;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendVideoRecord:videoName];

使用说明： 录制过程中通过 ss_avpg 接收进度事件，录制结果通过 sr_vdo 返回。

返回说明 ​

回复示例

{
  "C": "sr_vdo",
  "S": 0,
  "B": "{\"succ\":true,\"state\":0,\"type\":0,\"phonum\":5,\"vdonum\":2,\"adonum\":0}"
}

停止录像 ​

指令码： cs_stvd

方法与调用 ​

停止视频录制。

- (void)sendStopVideoRecord;

该方法无需参数。

[[XYBleManager sharedInstance] sendStopVideoRecord];

返回说明 ​

回复示例

{
  "C": "sr_vdo",
  "S": 0,
  "B": "{\"succ\":true,\"state\":0,\"type\":0,\"phonum\":5,\"vdonum\":2,\"adonum\":0}"
}

开始录音 ​

指令码： cs_ado

方法与调用 ​

录音。

- (void)sendAudioRecord:(NSString *)audioName;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendAudioRecord:audioName];

使用说明： 录制过程中通过 ss_avpg 接收进度事件，录制结果通过 sr_ado 返回。

返回说明 ​

回复示例

{
  "C": "sr_ado",
  "S": 0,
  "B": "{\"succ\":true,\"state\":0,\"phonum\":5,\"vdonum\":2,\"adonum\":1}"
}

停止录音 ​

指令码： cs_stad

方法与调用 ​

停止音频录制。

- (void)sendStopAudioRecord;

该方法无需参数。

[[XYBleManager sharedInstance] sendStopAudioRecord];

返回说明 ​

回复示例

{
  "C": "sr_ado",
  "S": 0,
  "B": "{\"succ\":true,\"state\":0,\"phonum\":5,\"vdonum\":2,\"adonum\":1}"
}

开启眼镜热点 ​

指令码： cs_opap

方法与调用 ​

开启Wifi热点。

- (void)requestServerOpenHotspotWithOpenType:(NSInteger )openType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] requestServerOpenHotspotWithOpenType:openType];

返回说明 ​

回复示例

{
  "C": "sr_apsr",
  "S": 0,
  "B": "{\"succ\":true,\"ssid\":\"Ble_18b9a4\",\"pwd\":\"00001111\"}"
}

关闭眼镜热点 ​

指令码： cs_csap

方法与调用 ​

关闭Wifi热点。

- (void)closeHotspot;

该方法无需参数。

[[XYBleManager sharedInstance] closeHotspot];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_csap",
  "S": 0,
  "B": ""
}

请求文件传输 ​

指令码： cs_asfl

方法与调用 ​

请求文件传输。

- (void)askFile:(XYFileType )fileType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] askFile:fileType];

使用说明： 使用 XYFileType 指定请求的文件类型。发送指令后，眼镜自动通过 Socket 传输文件，文件数据通过 XYSocketManager.receiveDataBlock 接收。

返回说明 ​

无响应。

清空眼镜的多媒体 ​

指令码： cs_clst

方法与调用 ​

请求清空多媒体。

- (void)sendClearAllMedia:(XYFileType )fileType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendClearAllMedia:fileType];

使用说明： 清空操作执行后，先查询设备状态，再决定是否重新发起。

返回说明 ​

回复示例

{
  "C": "sr_clst",
  "S": 0,
  "B": "{\"ftype\":-1}"
}

获取眼镜多媒体的设置 ​

指令码： cs_gmst

方法与调用 ​

获取多媒体设置。

- (void)sendGetMediaSettings;

该方法无需参数。

[[XYBleManager sharedInstance] sendGetMediaSettings];

返回说明 ​

回复示例

{
  "C": "sr_gmst",
  "S": 0,
  "B": "{\"pw\":1280,\"ph\":720,\"vw\":1920,\"vh\":1080,\"vq\":1,\"vs\":30,\"as\":60}"
}

设置拍照参数 ​

指令码： cs_phst

方法与调用 ​

设置拍照参数。

- (void)sendSetPhotoParam:(XYPhotoArgumentType )photoArgumentType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetPhotoParam:photoArgumentType];

返回说明 ​

回复示例

{
  "C": "sr_phst",
  "S": 0,
  "B": "{\"succ\":true,\"w\":1280,\"h\":720}"
}

设置录像参数 ​

指令码： cs_vdst

方法与调用 ​

设置录像参数。

- (void)sendSetVideoParam:(XYVideoArgumentSizeType )videoArgumentSizeType videoArgumentQualityType:(XYVideoArgumentQualityType )videoArgumentQualityType videoArgumentDurationType:(XYVideoArgumentDurationType )videoArgumentDurationType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetVideoParam:videoArgumentSizeType videoArgumentQualityType:videoArgumentQualityType videoArgumentDurationType:videoArgumentDurationType];

返回说明 ​

回复示例

{
  "C": "sr_vdst",
  "S": 0,
  "B": "{\"succ\":true,\"w\":1920,\"h\":1080,\"q\":1,\"s\":30}"
}

设置录音参数 ​

指令码： cs_adst

方法与调用 ​

设置录音参数。

- (void)sendSetAudioParam:(XYAudioArgumentDurationType )audioArgumentType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetAudioParam:audioArgumentType];

返回说明 ​

回复示例

{
  "C": "sr_adst",
  "S": 0,
  "B": "{\"succ\":true,\"s\":60}"
}

状态回传 ​

事件码： sr_stat

设备通过 receiveDataBlock 上报该事件。

事件数据 ​

事件示例

{
  "C": "sr_stat",
  "S": 0,
  "B": "{\"type\":\"sys\",\"state\":1,\"msg\":\"systen booting..\"}"
}

通知眼镜唤醒 ​

指令码： cs_ivww

方法与调用 ​

唤醒。

- (void)sendWakeUp;

该方法无需参数。

[[XYBleManager sharedInstance] sendWakeUp];

返回说明 ​

回复示例

{
  "C": "sr_ivww",
  "S": 0,
  "B": {
    "lang": "unknow",
    "src": 0
  }
}

手机发送热点信息 ​

指令码： cs_wfsta

方法与调用 ​

设置手机wifi。

- (void)sendWifiSTA:(NSString *)ssid pwd:(NSString *)pwd ip:(NSString *)ip;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendWifiSTA:ssid pwd:pwd ip:ip];

返回说明 ​

无响应。

是否开启图像算法 ​

指令码： cs_phoalg

方法与调用 ​

设置开启关闭图像算法。

- (void)sendSetPhoalg:(BOOL )isOn;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetPhoalg:isOn];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_phoalg",
  "S": 0,
  "B": ""
}

是否开启视频防抖 ​

指令码： cs_vdoeis

方法与调用 ​

设置开启关闭视频防抖。

- (void)sendSetVdoeis:(BOOL )isOn;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetVdoeis:isOn];

返回说明 ​

无业务回复参数。

回复示例

{
  "C": "sr_vdoeis",
  "S": 0,
  "B": ""
}

获取图像算法/视频防抖开关状态 ​

指令码： cs_algeis

方法与调用 ​

获取图像算法/视频防抖开关状态。

- (void)sendAlgeis;

该方法无需参数。

[[XYBleManager sharedInstance] sendAlgeis];

返回说明 ​

无响应。

获取智能交互开关 ​

指令码： cs_swst

方法与调用 ​

获取智能交互开关状态。

- (void)sendSwst;

该方法无需参数。

[[XYBleManager sharedInstance] sendSwst];

返回说明 ​

回复示例

{
  "C": "sr_swst",
  "S": 0,
  "B": {
    "status": 65023
  }
}

设置智能交互开关 ​

指令码： cs_swit

方法与调用 ​

设置智能交互开关。

- (void)sendSetSwit:(NSInteger )type isOn:(BOOL )isOn;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSetSwit:type isOn:isOn];

返回说明 ​

回复示例

{
  "C": "sr_swit",
  "S": 0,
  "B": {
    "type": 1,
    "switch": 1
  }
}

AI拍照传图 ​

指令码： cs_aiph

方法与调用 ​

AI拍照。

- (void)sendAiph;

该方法无需参数。

[[XYBleManager sharedInstance] sendAiph];

使用说明： 该方法无需参数。图片数据的接收方式见 AI拍照与传图。

返回说明 ​

无响应。

设置 Wi-Fi 开关 ​

指令码： cs_wfop

方法与调用 ​

设置wifi开关。

- (void)sendWifiWfop:(NSString *)ssid pwd:(NSString *)pwd isOn:(BOOL )isOn;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendWifiWfop:ssid pwd:pwd isOn:isOn];

返回说明 ​

无响应。

同步AI状态 ​

指令码： cs_sound

方法与调用 ​

同步AI状态。

- (void)sendSound:(XYAIStatusType )statusType;

调用时传入对应的业务参数：

[[XYBleManager sharedInstance] sendSound:statusType];

使用说明： 使用 XYAIStatusType 指定开始、对话中、停止或无声状态。

返回说明 ​

无响应。

获取佩戴状态 ​

指令码： cs_wrst

方法与调用 ​

获取佩戴状态。

- (void)sendGetWearState;

该方法无需参数。

[[XYBleManager sharedInstance] sendGetWearState];

返回说明 ​