从零跑起 RokidDemo：开发小白也能搞定的入门实践

如果你第一次接触 Rokid 眼镜生态，RokidDemo 就是你的"手机端和眼镜端的桥"。它不是一个只能装起来的示例，而是一个能把手机和眼镜真正连在一起、做互动、做协同的基线工程。你能在它里边看到：

扫描发现 Rokid 眼镜，并完成蓝牙连接与鉴权
拉取眼镜的状态（电量、音量、亮度、充电）并在手机端展示与调节
打开眼镜相机拍照并把图片回传到手机端保存与入库
下发自定义界面到眼镜端（比如弹出一个文字提示）
发送全局消息/TTS 反馈
模拟遥控器按键，通过 HID 报文控制眼镜（方向、返回、音量）
把这些交互过程写入数据库，能分页查看记录

一句话：它就是你要做"手机+眼镜"协同应用时的起跑线。项目代码地址已经在github上了，这里感谢作者的代码样例：github.com/StudiousXia...

安装环境（Windows）

这个环节很关键，基本所有"构建失败""设备不识别"的坑都和环境有关。

安装Kotlin

由于整个项目代码环境是Kotlin环境，我们先本地IDE中安装好相关插件。

安装 Android Studio 和 OpenJDK 11

查看是否有安装环境

winget search --source winget Android | Select-String -Pattern "Android Studio|SDK|Platform Tools|OpenJDK"

安装OpenJDK.11

winget install -e --id Microsoft.OpenJDK.11 --accept-source-agreements --accept-package-agreements

安装AndroidStudio

winget install -e --id Google.AndroidStudio --accept-source-agreements --accept-package-agreements

安装PlatformTools

winget install -e --id Google.PlatformTools --accept-source-agreements --accept-package-agreements

自此基本环境就安装完成了。

安装 Android SDK 组件

确保安装这些：

Android SDK Platform 36（匹配项目 compileSdk 36）
Android SDK Build-Tools 35（或兼容版本）
Android SDK Platform-Tools（包含 adb）
Android SDK Command-line Tools (latest)（方便命令行管理）

启动Android SDK Studio后，我们进入设置页找到"SDK Tools"，找到相关的工具，点击下载即可，如图所示：

真机调试准备

手机开启"开发者选项"和"USB 调试"。

第一次连接时，手机会弹窗问是否允许 USB 调试，请选择允许并勾选"始终允许"。

Windows 某些设备会缺驱动，装 Google USB Driver。确保终端输入 adb devices 能看到设备。

项目技术细节

这一节把工程先跑起来，跟着做就能过构建。先做三步：设置 local.properties → 添加 Rokid 仓库 → 引入 client-m 依赖。

项目根目录有 local.properties，需要把 sdk.dir 指向你机器的 Android SDK 路径（常见是 C:\Users\你的用户名\AppData\Local\Android\Sdk）。

sdk.dir=C:\Users\yu\AppData\Local\Android\Sdk

仓库与依赖（Gradle）在顶层加仓库，在模块里加依赖，然后点 Gradle Sync。

scss 复制代码

// settings.gradle
pluginManagement {
  repositories {
    gradlePluginPortal()
    google()
    mavenCentral()
    maven { url 'https://maven.rokid.com/repository/maven-public' }
  }
}
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url 'https://maven.rokid.com/repository/maven-public' }
  }
}

scss 复制代码

// app/build.gradle
android {
    defaultConfig {
        minSdk = 28
    }
}
dependencies {
    implementation("com.rokid.cxr:client-m:1.0.1-20250812.080117-2")
}

检查：sdk.dir 路径有效，依赖能解析，Sync 无报错。

Manifest 权限与特性（Android 12+）

先把这些权限加到 AndroidManifest.xml，Android 12+ 还需要在运行时申请。

ini 复制代码

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

蓝牙相关权限在连接前先申请；前台服务能避免进程被系统回收。

构建与安装

现在把包编译到真机上。前置条件：adb devices 显示设备为 device。 windows的命令脚本已经在项目里了。

构建 Debug 包：

.\gradlew.bat assembleDebug -x lint

安装到设备：

.\gradlew.bat installDebug

启动入口 Activity：

adb shell am start -n com.blue.armobile/com.blue.glassesapp.feature.init.InitActivity

首次进入会弹权限提示，请授予存储与通知权限以免初始化阻塞。

添加相关的权限后，我们就可以正常进入手机端的应用界面了，如图所示：

设备链接

在开始之前，请先完成"SDK 导入"。我这里使用的是蓝牙扫描添加设备。

1 查找蓝牙设备

kotlin 复制代码

package com.rokid.cxrandroiddocsample.helpers
// imports 省略：请确保已引入 Bluetooth*、Scan*、LiveData、ActivityResultContracts 等相关类

class BluetoothHelper(
  val context: AppCompatActivity,
  val initStatus: (INIT_STATUS) -> Unit,
  val deviceFound: () -> Unit
) {
  companion object {
    const val TAG = "Rokid Glasses CXR-M"
    const val REQUEST_CODE_PERMISSIONS = 100
    // 必要权限：Android 12+ 需申请 BLUETOOTH_SCAN / BLUETOOTH_CONNECT
    private val REQUIRED_PERMISSIONS = mutableListOf(
      Manifest.permission.ACCESS_FINE_LOCATION,
      Manifest.permission.BLUETOOTH,
      Manifest.permission.BLUETOOTH_ADMIN,
    ).apply {
      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        add(Manifest.permission.BLUETOOTH_SCAN)
        add(Manifest.permission.BLUETOOTH_CONNECT)
      }
    }.toTypedArray()
    // 初始化阶段标记：用于引导 UI 与流程
    enum class INIT_STATUS { NotStart, INITING, INIT_END }
  }

  val scanResultMap: ConcurrentHashMap<String, BluetoothDevice> = ConcurrentHashMap()
  val bondedDeviceMap: ConcurrentHashMap<String, BluetoothDevice> = ConcurrentHashMap()
  private var adapter: BluetoothAdapter? = null
  private var manager: BluetoothManager? = null

  // 从 Adapter 拿到 BLE Scanner；设备不支持时抛错并提示授权
  private val scanner by lazy {
    adapter?.bluetoothLeScanner ?: run {
      showRequestPermissionDialog()
      throw Exception("Bluetooth is not supported!!")
    }
  }

  @SuppressLint("MissingPermission")
  // 监听蓝牙是否启用：启用后触发扫描；未启用则引导开启
  private val bluetoothEnabled: MutableLiveData<Boolean> = MutableLiveData<Boolean>().apply {
    this.observe(context) {
      if (this.value == true) {
        initStatus.invoke(INIT_STATUS.INIT_END)
        startScan()
      } else {
        showRequestBluetoothEnableDialog()
      }
    }
  }

  // 引导用户开启系统蓝牙开关
  private val requestBluetoothEnable = context.registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
  ) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
      adapter = manager?.adapter
    } else {
      showRequestBluetoothEnableDialog()
    }
  }

  private var adapterSetter: BluetoothAdapter? = null
    set(value) {
      field = value
      value?.let {
        if (!it.isEnabled) {
          requestBluetoothEnable.launch(Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE))
        } else {
          bluetoothEnabled.postValue(true)
        }
      }
    }

  private var managerSetter: BluetoothManager? = null
    set(value) {
      field = value
      initStatus.invoke(INIT_STATUS.INITING)
      value?.let { adapterSetter = it.adapter } ?: run { showRequestPermissionDialog() }
    }

  // 权限结果：成功则初始化 BluetoothManager；失败弹权限提示
  val permissionResult: MutableLiveData<Boolean> = MutableLiveData<Boolean>().apply {
    this.observe(context) {
      if (it == true) {
        managerSetter = context.getSystemService(AppCompatActivity.BLUETOOTH_SERVICE) as BluetoothManager
      } else {
        showRequestPermissionDialog()
      }
    }
  }

  // 扫描回调：按设备名缓存，发现设备回调 UI 刷新
  val scanListener = object : ScanCallback() {
    @SuppressLint("MissingPermission")
    override fun onScanResult(callbackType: Int, result: ScanResult?) {
      super.onScanResult(callbackType, result)
      result?.let { r ->
        r.device.name?.let {
          scanResultMap[it] = r.device
          deviceFound.invoke()
        }
      }
    }
    override fun onScanFailed(errorCode: Int) {
    }
  }

  fun checkPermissions() {
    initStatus.invoke(INIT_STATUS.NotStart)
    context.requestPermissions(REQUIRED_PERMISSIONS, REQUEST_CODE_PERMISSIONS)
    context.registerReceiver(
      bluetoothStateListener,
      IntentFilter(BluetoothAdapter.ACTION_STATE_CHANGED)
    )
  }

  @SuppressLint("MissingPermission")
  fun release() {
    context.unregisterReceiver(bluetoothStateListener)
    stopScan()
    permissionResult.postValue(false)
    bluetoothEnabled.postValue(false)
  }

  private fun showRequestPermissionDialog() { }
  private fun showRequestBluetoothEnableDialog() { }

  @SuppressLint("MissingPermission")
  @RequiresPermission(Manifest.permission.BLUETOOTH_SCAN)
  fun startScan() {
    scanResultMap.clear()
    try {
      // 使用 Service UUID 过滤 Rokid 眼镜
      scanner.startScan(
        listOf(
          ScanFilter.Builder()
            .setServiceUuid(ParcelUuid.fromString("00009100-0000-1000-8000-00805f9b34fb"))
            .build()
        ),
        ScanSettings.Builder().build(),
        scanListener
      )
    } catch (_: Exception) { }
  }

  @RequiresPermission(Manifest.permission.BLUETOOTH_SCAN)
  fun stopScan() { 
    // 停止扫描，释放回调
    scanner.stopScan(scanListener) 
  }

  val bluetoothStateListener = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
      val action = intent?.action
      if (action == BluetoothAdapter.ACTION_STATE_CHANGED) {
        val state = intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR)
        if (state == BluetoothAdapter.STATE_OFF) {
          initStatus.invoke(INIT_STATUS.NotStart)
          bluetoothEnabled.postValue(false)
        }
      }
    }
  }
}

2 初始化蓝牙获取蓝牙信息

kotlin 复制代码

fun initDevice(context: Context, device: BluetoothDevice){
  // 通过 CXR 初始化蓝牙模块，监听连接信息与状态
  CxrApi.getInstance().initBluetooth(context, device,  object : BluetoothStatusCallback{
    override fun onConnectionInfo(
      socketUuid: String?,
      macAddress: String?,
      rokidAccount: String?,
      glassesType: Int
    ) {
      // 成功返回 socketUuid 与 macAddress，用于后续 connectBluetooth
      socketUuid?.let { uuid ->
        macAddress?.let { address->
          connect(context, uuid, address)
        }
      }
    }
    // 蓝牙已建立数据通道
    override fun onConnected() { }
    // 蓝牙数据通道断开
    override fun onDisconnected() { }
    // 初始化失败，携带错误码
    override fun onFailed(p0: ValueUtil.CxrBluetoothErrorCode?) { }
  })
}

3 连接蓝牙模块

kotlin 复制代码

fun connect(context: Context, socketUuid: String, macAddress: String){
  // 使用初始化阶段返回的 socketUuid 与 macAddress 建立蓝牙通信链路
  CxrApi.getInstance().connectBluetooth(context, socketUuid, macAddress, object : BluetoothStatusCallback{
    override fun onConnectionInfo(
      socketUuid: String?,
      macAddress: String?,
      rokidAccount: String?,
      glassesType: Int
    ) { }
    // 连接成功
    override fun onConnected() { }
    // 连接断开
    override fun onDisconnected() { }
    // 连接失败，查看错误码定位问题
    override fun onFailed(p0: ValueUtil.CxrBluetoothErrorCode?) { }
  })
}

4 获取蓝牙通信模块连接状态

kotlin 复制代码

fun getConnectionStatus(): Boolean{
  // true：已连接；false：未连接
  return CxrApi.getInstance().isBluetoothConnected
}

5 反初始化蓝牙

kotlin 复制代码

fun deInit(){
  // 释放蓝牙通信模块，清理内部状态
  CxrApi.getInstance().deinitBluetooth()
}

6 蓝牙重连

kotlin 复制代码

fun reconnect(context: Context, socketUuid: String, macAddress: String){
  // 断开后使用同一 socketUuid 与 macAddress 尝试重连
  CxrApi.getInstance().connectBluetooth(context, socketUuid, macAddress, object : BluetoothStatusCallback{ })
}

Wi‑Fi 连接

kotlin 复制代码

fun initWifi(): ValueUtil.CxrStatus?{
  // 初始化 Wi‑Fi P2P 通信模块，蓝牙链路建立后再使用
  return CxrApi.getInstance().initWifiP2P(object : WifiP2PStatusCallback{ 
    override fun onConnected() { /* Wi‑Fi P2P 建立成功 */ }
    override fun onDisconnected() { /* Wi‑Fi P2P 断开 */ }
    override fun onFailed(errorCode: ValueUtil.CxrWifiErrorCode?) { /* 根据错误码处理 */ }
  })
}

kotlin 复制代码

fun getWiFiConnectionStatus(): Boolean{
  // true：Wi‑Fi P2P 已连接；false：未连接
  return CxrApi.getInstance().isWifiP2PConnected
}

kotlin 复制代码

private fun deinitWifi(){
  // 释放 Wi‑Fi P2P 模块
  CxrApi.getInstance().deinitWifiP2P()
}

扫描阶段只做发现与过滤，关键是拿到设备标识（名称、MAC 等）
initBluetooth 返回 socketUuid 与 macAddress，这两个是后续通信的入口参数
真正的数据链路在 connectBluetooth 建立，成功后才算可用
连接状态用 isBluetoothConnected 判断，断开要及时做 UI 与重试处理
Wi‑Fi P2P 作为大数据传输通道，建议在蓝牙稳定后再开启，避免耗电与不必要的失败

拍照录音

拍照（三种途径）

单机按键拍照：先设置分辨率，照片存入未同步媒体文件
AI 场景拍照：打开相机并拍照，经蓝牙返回 WebP 字节
唤起相机拍照：直接拿到照片路径，再做本地/同步处理

arduino 复制代码

// 单机按键：设置拍照分辨率
CxrApi.getInstance().setPhotoParams(width, height)

// AI 场景：打开相机 + 拍照（quality: 0~100）
CxrApi.getInstance().openGlassCamera(width, height, quality)
CxrApi.getInstance().takeGlassPhoto(width, height, quality, photoResultCallback)

// 直接唤起相机：返回照片路径
CxrApi.getInstance().takeGlassPhoto(width, height, quality, photoPathCallback)

photoResultCallback 返回状态与 WebP 字节；photoPathCallback 返回状态与存储路径。经蓝牙传输时建议选较小分辨率与合适质量，避免耗时与失败。

数据操作

数据操作前请确保设备处于蓝牙连接状态；同步媒体文件前需先初始化 Wi‑Fi 通信模块。

向眼镜端发送数据

kotlin 复制代码

val streamCallback = object : SendStatusCallback {
  override fun onSendSucceed() {}
  override fun onSendFailed(errorCode: ValueUtil.CxrSendErrorCode?) {}
}
CxrApi.getInstance().sendStream(ValueUtil.CxrStreamType.WORD_TIPS, bytes, fileName, streamCallback)

sendStream 用于向眼镜端发送流数据（如提词内容）；成功与失败通过回调告知，失败可根据错误码定位。

读取未同步媒体文件数量

kotlin 复制代码

val unSyncCallback = object : UnsyncNumResultCallback {
  override fun onUnsyncNumResult(status: ValueUtil.CxrStatus?, audioNum: Int, pictureNum: Int, videoNum: Int) {}
}
CxrApi.getInstance().getUnsyncNum(unSyncCallback)

返回音频、图片、视频三类未同步数量，可用于提醒或批量同步的前置判断。

监听眼镜端媒体文件更新

kotlin 复制代码

val mediaFileUpdateListener = object : MediaFilesUpdateListener { override fun onMediaFilesUpdated() {} }
CxrApi.getInstance().setMediaFilesUpdateListener(mediaFileUpdateListener)

当眼镜端媒体库有更新时触发；需要时设置，不用时移除，降低资源占用。

同步媒体文件（需 Wi‑Fi）

kotlin 复制代码

val syncCallback = object : SyncStatusCallback {
  override fun onSyncStart() {}
  override fun onSingleFileSynced(fileName: String?) {}
  override fun onSyncFailed() {}
  override fun onSyncFinished() {}
}
CxrApi.getInstance().startSync(savePath, arrayOf(ValueUtil.CxrMediaType.PICTURE, ValueUtil.CxrMediaType.VIDEO), syncCallback)

同时同步多类型文件；保存路径需具备文件管理权限；开始与完成、单文件成功与失败均在回调通知。

scss 复制代码

CxrApi.getInstance().syncSingleFile(savePath, ValueUtil.CxrMediaType.PICTURE, fileName, syncCallback)
CxrApi.getInstance().stopSync()

同步指定单个文件与停止同步；单文件更适合"选择后同步"的场景。

常见问题与排障

依赖解析失败 → 未配置 Rokid 仓库 → 在 settings.gradle 添加 maven 仓库
蓝牙扫描失败 → 未申请运行时权限 → 申请 BLUETOOTH_SCAN/CONNECT
鉴权失败 → .lc 未打包或资源 ID 错误 → 放入 res/raw 并读取校验
构建错误 → compileSdk 与 SDK 不匹配 → 统一为 compileSdk 36
初始化卡住 → 未授予存储/通知权限 → 在首次启动时授予权限

总结

到这里你已经把环境、依赖、权限都配好，能连上眼镜并跑过音量/亮度、拍照、消息和数据记录。在这篇文章中，我们详细介绍了如何搭建与优化Rokid眼镜和手机端的协同应用。通过提供的示例代码和详细的安装步骤，读者能够快速上手，完成手机与眼镜的连接，并实现音量调节、拍照、信息推送等基础功能。关键的技术点包括环境配置、Android Studio的设置、以及如何进行设备连接与权限管理等。

通过实际的功能实现案例，如蓝牙连接、TTS反馈和远程控制等，我们进一步探讨了如何利用CXR SDK实现眼镜与手机的交互。这些功能不仅能帮助开发者更好地理解眼镜端与手机端的通讯机制，还能够为未来应用的扩展和优化奠定基础。