CXR SDK实战指南：跨设备AR应用开发

前言

当"屏幕"从二维平面扩展到三维空间，当应用不再被框在 16:9 的矩形里，而是漂浮在客厅、会议室甚至你的视野中央，开发范式也随之被重塑。在这个过程中，CXR SDK为开发者提供了完整的跨设备AR应用开发解决方案：

CXR-M（移动端SDK）：用于移动设备（如手机、平板）与AR眼镜进行通信和控制的软件开发工具包
CXR-S（眼镜端SDK）：用于AR眼镜设备端实现功能和与移动端通信的软件开发工具包

过去几年，我们见证了AR眼镜从概念走进生产线，也目睹了开发者面对新硬件时的手足无措：环境配置碎片化、跨设备协同复杂、性能瓶颈隐蔽、调试手段匮乏。CXR SDK为开发者提供了完整的解决方案：

CXR-M（移动端）确保移动设备能高效地发送指令和接收数据
CXR-S（眼镜端）负责眼镜端的功能实现和与移动端的无缝通信

你将从本文获得什么

一条可落地的复现路线（Windows 10 环境）
CXR-M移动端与CXR-S眼镜端SDK的正确集成方式
手机与AR眼镜跨设备通信的最小可用Demo
工程化与性能优化清单，以及我在复现过程中的取舍与思考

注：本文将详细介绍如何正确使用CXR SDK（包括CXR-M和CXR-S）构建跨设备AR应用，确保技术描述的准确性和专业性

我的开发思路与取舍

在接触AR设备开发之前，我主要做传统移动端开发。跨设备AR开发最大的挑战不是技术复杂度，而是设备间的状态同步 和通信协议的稳定性。我的解决思路是：

先打通通信链路，再优化渲染效果 - 确保命令能正确传递比视觉效果更重要
模块化设计 - 将通信、渲染、UI分离，便于后续扩展和维护
渐进式实现 - 从基础功能开始，逐步扩展到复杂交互场景

环境配置与工具安装

CXR SDK开发环境的搭建是一个简单但关键的过程。首先需要安装以下核心开发工具：

1、开发工具要求与安装

Android Studio配置

要求版本≥2023.1.1
确保安装了Kotlin插件
配置Android SDK API Level 28+

Visual Studio Code配置（可选）

推荐版本≥1.80.0
推荐安装以下扩展：Kotlin扩展、Android扩展

3、项目创建方式

CXR SDK项目创建主要通过Android Studio完成：

打开Android Studio，点击"新建项目"
选择"Empty Activity"模板
填写项目名称、包名等基本信息
确保选择Kotlin作为开发语言
点击"完成"创建项目

项目结构与开发流程

1、项目架构详解

一个标准的CXR SDK项目包含以下结构：

复制代码

cxr-project/
├── app/
│   ├── build.gradle.kts    # 应用依赖配置
│   ├── src/main/
│   │   ├── AndroidManifest.xml  # 权限配置
│   │   ├── java/com/example/cxrremotecontrol/  # Kotlin/Java源码
│   │   └── res/           # 资源文件
├── build.gradle.kts       # 项目级Gradle配置
├── settings.gradle.kts    # 仓库配置
└── gradle.properties      # Gradle属性配置

## 开发与调试实战

### 1、Android Studio调试技巧

**基础调试配置**

1. 连接Android设备或启动模拟器
2. 在Android Studio中点击"运行"按钮
3. 使用Logcat查看应用日志

**常见调试命令**

```bash
# 查看设备日志
adb logcat | grep CXR

# 安装应用到设备
adb install -r app-debug.apk

# 清理应用数据
adb shell pm clear com.example.cxrremotecontrol

open "https://jsar.netlify.app/playground?url=http://localhost:8080/main.xsml"

2、实时重载与热更新

JSAR DevTools 把"写代码→看效果"压缩成一秒循环：只要一保存，场景自动热重载，眼镜里即刻呈现最新画面；若脚本出错，IDE 内立刻用红线标出堆栈，无需摘头显也能一次定位；同时左上角实时滚动帧率与内存曲线，性能瓶颈一目了然。三大能力合一，让 AR 开发像网页刷新一样简单，真正"所写即所见，所错即所标，所慢即所显"。

JSAR开发工具与CXR SDK的区别与关系

在开始实践之前，我们需要明确JSAR开发工具链和CXR SDK的区别与关系：

JSAR开发工具链

定位：一套完整的AR应用开发环境和工具集
主要功能：项目创建、代码编辑、调试、预览、打包部署
使用场景：用于开发AR眼镜上运行的应用界面和交互逻辑

CXR SDK

定位：两套独立的软件开发工具包
- CXR-M：移动端SDK，用于手机等移动设备
- CXR-S：眼镜端SDK，用于AR眼镜设备
主要功能：实现设备间通信、数据传输、功能调用
使用场景：当需要手机与AR眼镜之间进行通信和协同工作时使用

正确的技术选型

开发AR眼镜应用界面：使用JSAR开发工具链
实现手机控制AR眼镜：使用CXR-M（移动端）+ CXR-S（眼镜端）SDK组合

CXR-M SDK移动端集成实战

基于官方文档，我实现了完整的Android端集成。以下是关键配置和代码：

Maven仓库配置（settings.gradle.kts）：

kotlin 复制代码

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://maven.rokid.com/repository/maven-public/") }
        google()
        mavenCentral()
    }
}

依赖配置（app/build.gradle.kts）：

kotlin 复制代码

android {
    defaultConfig {
        minSdk = 28  // CXR-M SDK要求
        targetSdk = 34
    }
}

   dependencies {
    // CXR-M SDK核心依赖
    implementation("com.rokid.cxr:client-m:1.0.1-20250812.080117-2")
    
    // 网络通信依赖（SDK推荐版本）
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:okhttp:4.9.3")
    implementation("com.squareup.okhttp3:logging-interceptor:4.9.1")
    implementation("com.squareup.okio:okio:2.8.0")
    implementation("com.google.code.gson:gson:2.10.1")
    
    // Kotlin标准库
    implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.0")
}

权限配置（AndroidManifest.xml）：

xml 复制代码

<!-- CXR-M SDK 所需权限 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<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.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.INTERNET" />

动态权限申请（MainActivity.kt）：

kotlin 复制代码

class MainActivity : AppCompatActivity() {
    companion object {
        private const val REQUEST_CODE_PERMISSIONS = 100
    }
    
    // Android 12+ 蓝牙权限适配
    private val requiredPermissions = 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()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        requestPermissions()
        setupUI()
    }
    
    private fun requestPermissions() {
        val permissionsToRequest = requiredPermissions.filter {
            ContextCompat.checkSelfPermission(this, it) != PackageManager.PERMISSION_GRANTED
        }
        
        if (permissionsToRequest.isNotEmpty()) {
            ActivityCompat.requestPermissions(this, permissionsToRequest.toTypedArray(), REQUEST_CODE_PERMISSIONS)
        }
    }
}

我的踩坑经验：

Android 12+ 蓝牙权限变化 ：新增了 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 权限，必须同时申请
Maven仓库访问：国内网络可能需要配置代理，建议使用阿里云镜像加速
minSdk版本：CXR-M SDK要求最低API 28，低于此版本无法编译

kts 复制代码

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.jsarremotecontrol"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.jsarremotecontrol"
        minSdk = 28
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("com.google.android.material:material:1.11.0")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
    
    // CXR-M SDK
    implementation("com.rokid.cxr:client-m:1.0.1-20250812.080117-2")
    
    // 网络通信依赖
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:okhttp:4.9.3")
    implementation("com.squareup.okhttp3:logging-interceptor:4.9.1")
    implementation("com.squareup.okio:okio:2.8.0")
    implementation("com.google.code.gson:gson:2.10.1")
    
    // Kotlin
    implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.0")
    
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.5")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

CXR-M SDK移动端集成实战

CXR-M SDK是专门为移动设备设计的SDK，用于与AR眼镜进行通信和控制。以下是关键配置和代码：

Maven仓库配置（settings.gradle.kts）：

kotlin 复制代码

pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        maven {
            url = uri("https://maven.rokid.com/repository/maven-public/")
        }
        mavenCentral()
    }
}

依赖导入（build.gradle.kts）：

kotlin 复制代码

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

跨设备通信Demo：手机与AR眼镜协同工作

以下是一个完整的跨设备通信方案，包括移动端和眼镜端的实现：

A. 移动端UI与通信实现

布局文件（activity_main.xml）：

xml 复制代码

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="16dp">

    <TextView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="CXR 远程控制"
        android:textSize="20sp"
        android:textStyle="bold"
        android:gravity="center"
        android:layout_marginBottom="24dp" />

    <TextView
        android:id="@+id/tv_angle"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="旋转角度: 0°"
        android:textSize="16sp"
        android:layout_marginBottom="8dp" />

    <SeekBar
        android:id="@+id/seek_angle"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:max="360"
        android:layout_marginBottom="16dp" />

    <Button
        android:id="@+id/btn_connect"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="连接设备"
        android:layout_marginBottom="8dp" />

    <Button
        android:id="@+id/btn_send"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="发送角度"
        android:layout_marginBottom="16dp" />

    <TextView
        android:id="@+id/tv_status"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="状态: 未连接"
        android:textSize="14sp"
        android:background="#f0f0f0"
        android:padding="8dp" />

</LinearLayout>

CXR-M SDK通信实现（MainActivity.kt核心部分）：

kotlin 复制代码

import com.rokid.cxr.client.m.CXRClientM
import com.rokid.cxr.client.m.listener.ConnectionListener
import com.rokid.cxr.client.m.listener.DataListener

class MainActivity : AppCompatActivity() {
    private lateinit var angleSeekBar: SeekBar
    private lateinit var angleTextView: TextView
    private lateinit var connectBtn: Button
    private lateinit var sendBtn: Button
    private lateinit var statusTextView: TextView
    
    private var cxrClient: CXRClientM? = null
    private var isConnected = false

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        initViews()
        setupListeners()
        initCXRClient()
        requestPermissions()
    }
    
    private fun initCXRClient() {
        // 初始化CXR-M SDK
        cxrClient = CXRClientM.getInstance()
        
        // 设置连接监听器
        cxrClient?.setConnectionListener(object : ConnectionListener {
            override fun onConnected() {
                runOnUiThread {
                    isConnected = true
                    connectBtn.text = "断开连接"
                    updateStatus("已连接到眼镜设备")
                }
            }
            
            override fun onDisconnected() {
                runOnUiThread {
                    isConnected = false
                    connectBtn.text = "连接设备"
                    updateStatus("设备已断开连接")
                }
            }
            
            override fun onConnectionFailed(errorCode: Int, errorMessage: String) {
                runOnUiThread {
                    isConnected = false
                    connectBtn.text = "连接设备"
                    updateStatus("连接失败: $errorMessage")
                }
            }
        })
        
        // 设置数据监听器
        cxrClient?.setDataListener(object : DataListener {
            override fun onDataReceived(data: ByteArray) {
                val message = String(data)
                runOnUiThread {
                    updateStatus("收到消息: $message")
                }
            }
        })
    }
    
    private fun setupListeners() {
        angleSeekBar.setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
            override fun onProgressChanged(seekBar: SeekBar?, progress: Int, fromUser: Boolean) {
                angleTextView.text = "旋转角度: ${progress}°"
            }
            override fun onStartTrackingTouch(seekBar: SeekBar?) {}
            override fun onStopTrackingTouch(seekBar: SeekBar?) {}
        })
        
        connectBtn.setOnClickListener {
            if (isConnected) {
                disconnect()
            } else {
                connect()
            }
        }
        
        sendBtn.setOnClickListener {
            sendAngle()
        }
    }
    
    private fun connect() {
        try {
            cxrClient?.connect()
            updateStatus("正在连接眼镜设备...")
            
        } catch (e: Exception) {
            updateStatus("连接异常: ${e.message}")
        }
    }
    
    private fun sendAngle() {
        if (!isConnected) {
            updateStatus("请先连接设备")
            return
        }
        
        val angle = angleSeekBar.progress
        val message = """{"cmd":"rotate","y":$angle,"timestamp":${System.currentTimeMillis()}}"""
        
        webSocket?.send(message)
        updateStatus("已发送角度: ${angle}°")
    }
    
    private fun updateStatus(message: String) {
        statusTextView.text = "状态: $message"
    }
}

Android应用运行界面，显示滑杆、连接按钮、状态文本：

B. 眼镜端实现（使用CXR-S SDK）

CXR-S SDK眼镜端集成配置：

kotlin 复制代码

// settings.gradle.kts
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        maven {
            url = uri("https://maven.rokid.com/repository/maven-public/")
        }
        mavenCentral()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.rokid.cxr:cxr-service-bridge:1.0-20250519.061355-45")
}

android {
    defaultConfig {
        minSdk = 28
    }
}

CXR-S SDK眼镜端实现代码：

kotlin 复制代码

import com.rokid.cxr.service.bridge.CXRServiceBridge
import com.rokid.cxr.service.bridge.listener.CXRConnectionListener
import com.rokid.cxr.service.bridge.listener.CXRDataListener

class CXRRemoteControlService : Service() {
    private lateinit var cxrBridge: CXRServiceBridge
    private lateinit var modelController: ModelController
    
    override fun onCreate() {
        super.onCreate()
        initCXRService()
        initModelController()
    }
    
    private fun initCXRService() {
        // 初始化CXR-S SDK
        cxrBridge = CXRServiceBridge.getInstance()
        
        // 设置连接监听器
        cxrBridge.setConnectionListener(object : CXRConnectionListener {
            override fun onConnected() {
                Log.d("CXRService", "已连接到移动端")
                // 发送连接成功消息给移动端
                cxrBridge.sendData("眼镜端已就绪".toByteArray())
            }
            
            override fun onDisconnected() {
                Log.d("CXRService", "与移动端断开连接")
            }
        })
        
        // 设置数据监听器
        cxrBridge.setDataListener(object : CXRDataListener {
            override fun onDataReceived(data: ByteArray) {
                try {
                    val message = String(data)
                    Log.d("CXRService", "收到消息: $message")
                    
                    // 解析消息并执行相应操作
                    if (message.startsWith("rotate:")) {
                        val angle = message.substring(7).toFloatOrNull() ?: 0f
                        modelController.rotateToAngle(angle)
                        
                        // 发送确认消息给移动端
                        cxrBridge.sendData("已设置角度: $angle".toByteArray())
                    }
                } catch (e: Exception) {
                    Log.e("CXRService", "消息处理失败: ${e.message}")
                }
            }
        })
        
        // 启动服务
        cxrBridge.start()
    }
    
    private fun initModelController() {
        // 初始化模型控制器，用于控制AR场景中的3D模型
        modelController = ModelController()
    }
    
    override fun onBind(intent: Intent?): IBinder? {
        return null
    }
    
    override fun onDestroy() {
        super.onDestroy()
        // 停止CXR服务
        cxrBridge.stop()
    }
}
  private wsManager: WebSocketManager
  private modelController: ModelController
  private isRunning = false

  constructor() {
    this.scene = this.createScene()
    this.wsManager = new WebSocketManager('ws://192.168.1.100:12345/ctrl')
    this.modelController = new ModelController(this.scene)
  }

  async start(): Promise<void> {
    try {
      console.log('启动JSAR远程控制应用...')
      
      // 加载3D模型
      await this.modelController.loadModel('models/robot.glb')
      
      // 连接WebSocket
      await this.wsManager.connect()
      
      // 设置消息处理
      this.wsManager.onMessage((data) => {
        this.handleMessage(data)
      })
      
      // 启动渲染循环
      this.startRenderLoop()
      
      this.isRunning = true
      console.log('应用启动成功')
      
    } catch (error) {
      console.error('应用启动失败:', error)
    }
  }

  private handleMessage(data: any) {
    console.log('处理消息:', data)
    
    if (data.cmd === 'rotate' && typeof data.y === 'number') {
      this.modelController.rotateToAngle(data.y)
    }
  }

  private startRenderLoop() {
    const render = () => {
      if (this.isRunning) {
        this.modelController.update()
        requestAnimationFrame(render)
      }
    }
    render()
  }
}

// 应用入口
async function main() {
  const app = new JSARRemoteControlApp()
  
  try {
    await app.start()
  } catch (error) {
    console.error('应用运行失败:', error)
  }
}

main().catch(console.error)

// 注意：上述代码是使用WebSocket作为通信方式的简化实现
// 在实际应用中，当需要与AR眼镜设备进行通信时，应使用CXR-S SDK（眼镜端）和CXR-M SDK（移动端）的组合方案

C. CXR SDK通信协议设计与实现

CXR SDK设备间通信协议：

json 复制代码

{
  "cmd": "rotate",           // 命令类型
  "y": 180,                 // 旋转角度 (0-360)
  "timestamp": 1640995200000, // 时间戳
  "seq": 12345              // 序列号（可选）
}

通信实现流程：

移动端通过CXR-M SDK与眼镜端建立连接
移动端发送控制指令到眼镜端
眼镜端通过CXR-S SDK接收指令并执行相应操作
眼镜端返回执行结果给移动端

数据传输优化：

使用二进制格式传输数据，提高传输效率
实现数据压缩，减少传输数据量
采用请求-响应机制，确保数据可靠传输

D. 开发阶段通信协议设计与鲁棒性思考

消息协议设计：

json 复制代码

{
  "cmd": "rotate",           // 命令类型
  "y": 180,                 // 旋转角度 (0-360)
  "timestamp": 1640995200000, // 时间戳
  "seq": 12345              // 序列号（可选）
}

我的设计原则：

极简JSON协议：先保证互通，后续可优化为二进制格式
时间戳防重：避免网络延迟导致的重复命令
序列号保序：确保命令按正确顺序执行
错误处理：所有网络操作都有超时和重试机制

性能优化策略：

命令去抖：相同角度命令在100ms内只执行一次
平滑插值：模型旋转使用缓动函数，避免突兀跳跃
连接池管理：WebSocket连接复用，减少握手开销
内存管理：及时清理不用的3D资源，避免内存泄漏

我的踩坑经验：

Android WebSocket超时：OkHttp默认超时时间过短，需要设置为0（无限超时）
JSAR场景API变化：官方API可能更新，需要根据最新文档调整代码
网络地址配置：开发时用localhost，真机测试需要改为实际IP地址
权限时序：Android权限申请必须在WebSocket连接之前完成

工程化与性能优化实战

1、CXR SDK依赖管理

Gradle版本锁定策略：

kotlin 复制代码

// gradle/libs.versions.toml
[versions]
kotlin = "2.1.0"
androidx-appcompat = "1.6.1"
androidx-constraintlayout = "2.1.4"
cxr-m = "1.0.1-20250812.080117-2"
cxr-s = "1.0-20250519.061355-45"

[libraries]
kotlin-stdlib = { group = "org.jetbrains.kotlin", name = "kotlin-stdlib", version.ref = "kotlin" }
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "androidx-appcompat" }
androidx-constraintlayout = { group = "androidx.constraintlayout", name = "constraintlayout", version.ref = "androidx-constraintlayout" }
cxr-m-sdk = { group = "com.rokid.cxr", name = "client-m", version.ref = "cxr-m" }
cxr-s-sdk = { group = "com.rokid.cxr", name = "cxr-service-bridge", version.ref = "cxr-s" }

依赖管理最佳实践：统一管理版本号，避免依赖冲突。使用libs.versions.toml文件集中管理所有依赖版本，确保CXR SDK与其他库的兼容性。

2、性能监控与优化

CXR SDK性能监控：

kotlin 复制代码

import android.util.Log
import java.util.concurrent.TimeUnit

class CXRPerformanceMonitor {
    private var startTime = 0L
    private var messageCount = 0
    private var totalLatency = 0L
    
    fun start() {
        startTime = System.currentTimeMillis()
    }
    
    fun recordMessageReceived() {
        messageCount++
    }
    
    fun recordLatency(latencyMs: Long) {
        totalLatency += latencyMs
    }
    
    fun logPerformanceMetrics() {
        val elapsedTime = System.currentTimeMillis() - startTime
        val messagesPerSecond = if (elapsedTime > 0) {
            (messageCount * 1000.0 / elapsedTime).toInt()
        } else 0
        
        val avgLatency = if (messageCount > 0) {
            totalLatency / messageCount
        } else 0
        
        Log.d("CXRPerformance", "消息吞吐量: $messagesPerSecond 条/秒")
        Log.d("CXRPerformance", "平均延迟: $avgLatency ms")
    }
}

3、CXR SDK错误处理与容错机制

设备连接错误处理：

kotlin 复制代码

import android.os.Handler
import android.os.Looper
import android.util.Log
import com.rokid.cxr.client.m.CXRClientM

class CXRFaultToleranceManager {
    private var cxrClient: CXRClientM? = null
    private var reconnectAttempts = 0
    private val maxReconnectAttempts = 5
    private val baseReconnectDelay = 1000L
    private val commandQueue = mutableListOf<ByteArray>()
    private var isOfflineMode = false
    
    constructor(cxrClient: CXRClientM) {
        this.cxrClient = cxrClient
    }
    
    fun handleConnectionFailure(errorCode: Int, errorMessage: String) {
        Log.e("CXRConnection", "连接失败: $errorMessage (错误码: $errorCode)")
        
        when (errorCode) {
            1001 -> Log.d("CXRConnection", "设备未找到，请确保眼镜设备已开启")
            1002 -> Log.d("CXRConnection", "蓝牙权限不足，请检查应用权限")
            1003 -> Log.d("CXRConnection", "网络连接超时，请检查网络设置")
            else -> Log.d("CXRConnection", "未知错误，请稍后重试")
        }
        
        attemptReconnect()
    }
    
    private fun attemptReconnect() {
        if (reconnectAttempts < maxReconnectAttempts) {
            reconnectAttempts++
            val delay = baseReconnectDelay * (1 shl reconnectAttempts) // 指数退避
            
            Log.d("CXRConnection", "尝试重连 ($reconnectAttempts/$maxReconnectAttempts)，延迟 ${delay}ms")
            
            Handler(Looper.getMainLooper()).postDelayed({
                cxrClient?.connect()
            }, delay)
        } else {
            // 达到最大重试次数，切换到离线模式
            switchToOfflineMode()
        }
    }
    
    private fun switchToOfflineMode() {
        isOfflineMode = true
        Log.w("CXRConnection", "已切换到离线模式，命令将被缓存")
    }
    
    fun sendDataWithRetry(data: ByteArray) {
        if (isOfflineMode) {
            // 离线模式下缓存命令
            commandQueue.add(data)
            Log.d("CXRConnection", "命令已缓存，等待网络恢复")
        } else {
            try {
                cxrClient?.sendData(data)
            } catch (e: Exception) {
                Log.e("CXRConnection", "发送数据失败: ${e.message}")
                // 缓存失败的命令
                commandQueue.add(data)
            }
        }
    }
    
    fun onConnectionRestored() {
        isOfflineMode = false
        reconnectAttempts = 0
        Log.d("CXRConnection", "连接已恢复，正在发送缓存的命令")
        
        // 发送缓存的命令
        while (commandQueue.isNotEmpty()) {
            val command = commandQueue.removeAt(0)
            try {
                cxrClient?.sendData(command)
                Log.d("CXRConnection", "已发送缓存命令")
            } catch (e: Exception) {
                Log.e("CXRConnection", "发送缓存命令失败: ${e.message}")
            }
        }
    }
}

我的容错策略：

指数退避重连：避免频繁重连造成资源浪费
命令缓存机制：网络中断时缓存用户操作
降级方案：关键功能不可用时提供替代方案
用户反馈：及时告知用户当前状态和问题

4、CXR SDK内存管理与资源优化

在AR应用开发中，内存管理至关重要，特别是对于资源受限的眼镜设备。以下是使用CXR SDK时的内存优化策略：

资源生命周期管理：

kotlin 复制代码

import android.util.Log
import java.util.WeakHashMap
import java.lang.ref.WeakReference
import com.rokid.cxr.client.m.CXRClientM

class CXRResourceManager {
    private val cxrClient: CXRClientM
    private val activeResources = WeakHashMap<String, WeakReference<Any>>()
    private val resourceUsageThreshold = 80 // 80%内存使用率阈值
    private val tag = "CXRResourceManager"
    
    constructor(cxrClient: CXRClientM) {
        this.cxrClient = cxrClient
    }
    
    fun registerResource(resourceId: String, resource: Any) {
        activeResources[resourceId] = WeakReference(resource)
        
        // 检查内存使用情况
        if (isMemoryUsageHigh()) {
            Log.w(tag, "内存使用率过高，触发资源清理")
            cleanupUnusedResources()
        }
    }
    
    fun releaseResource(resourceId: String) {
        val resourceRef = activeResources.remove(resourceId)
        if (resourceRef != null) {
            val resource = resourceRef.get()
            if (resource != null) {
                // 释放特定资源
                when (resource) {
                    is ByteArray -> { /* 处理字节数组资源 */ }
                    is AutoCloseable -> {
                        try {
                            resource.close()
                            Log.d(tag, "资源已关闭: $resourceId")
                        } catch (e: Exception) {
                            Log.e(tag, "关闭资源失败: ${e.message}")
                        }
                    }
                }
            }
        }
    }
    
    fun cleanupUnusedResources() {
        val keysToRemove = mutableListOf<String>()
        
        for ((key, ref) in activeResources) {
            if (ref.get() == null) {
                keysToRemove.add(key)
                Log.d(tag, "清理未使用资源: $key")
            }
        }
        
        keysToRemove.forEach {
            activeResources.remove(it)
        }
    }
    
    private fun isMemoryUsageHigh(): Boolean {
        val runtime = Runtime.getRuntime()
        val usedMemory = (runtime.totalMemory() - runtime.freeMemory()) / 1024 / 1024
        val maxMemory = runtime.maxMemory() / 1024 / 1024
        val usagePercentage = (usedMemory * 100) / maxMemory
        
        Log.d(tag, "内存使用: $usedMemory MB / $maxMemory MB ($usagePercentage%)")
        
        return usagePercentage > resourceUsageThreshold
    }
    
    fun onDeviceDisconnect() {
        // 设备断开连接时释放所有资源
        Log.d(tag, "设备断开连接，释放所有资源")
        activeResources.clear()
    }
}

踩坑指南与最佳实践

1、常见问题与解决方案

问题1：Android权限申请失败

kotlin 复制代码

// 错误做法：一次性申请所有权限
ActivityCompat.requestPermissions(this, allPermissions, REQUEST_CODE)

// 正确做法：分批申请，先申请关键权限
val criticalPermissions = arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
val optionalPermissions = arrayOf(Manifest.permission.BLUETOOTH_SCAN)

ActivityCompat.requestPermissions(this, criticalPermissions, REQUEST_CODE_CRITICAL)
// 关键权限通过后再申请可选权限

问题2：WebSocket连接不稳定

kotlin 复制代码

// 错误做法：连接失败后立即重试
private fun connect() {
    webSocket = client.newWebSocket(request, listener)
}

// 正确做法：添加心跳检测和重连机制
private fun startHeartbeat() {
    heartbeatTimer = Timer()
    heartbeatTimer.scheduleAtFixedRate(object : TimerTask() {
        override fun run() {
            if (isConnected) {
                webSocket?.send("""{"type":"ping"}""")
            }
        }
    }, 0, 30000) // 30秒心跳
}

问题3：JSAR场景API变化

typescript 复制代码

// 错误做法：硬编码API调用
const model = scene.createEntity('model')

// 正确做法：添加API兼容性检查
function createEntityCompat(scene: any, id: string) {
    if (typeof scene.createEntity === 'function') {
        return scene.createEntity(id)
    } else if (typeof scene.addEntity === 'function') {
        return scene.addEntity(id)
    } else {
        throw new Error('不支持的场景API')
    }
}

2、调试技巧

Android端调试：

kotlin 复制代码

// 使用Timber进行分级日志
Timber.d("WebSocket连接成功")
Timber.w("网络延迟较高: ${latency}ms")
Timber.e("连接失败", exception)

// 使用Stetho进行网络调试
if (BuildConfig.DEBUG) {
    Stetho.initializeWithDefaults(this)
}

JSAR端调试：

typescript 复制代码

// 添加调试面板
class DebugPanel {
    private panel: HTMLElement
    
    constructor() {
        this.panel = document.createElement('div')
        this.panel.style.cssText = `
            position: fixed; top: 10px; right: 10px;
            background: rgba(0,0,0,0.8); color: white;
            padding: 10px; font-family: monospace;
            z-index: 9999;
        `
        document.body.appendChild(this.panel)
    }
    
    update(fps: number, memory: number, connections: number) {
        this.panel.innerHTML = `
            FPS: ${fps}<br>
            Memory: ${memory}MB<br>
            Connections: ${connections}
        `
    }
}

3、测试策略

单元测试：

kotlin 复制代码

@Test
fun testMessageParsing() {
    val json = """{"cmd":"rotate","y":180,"timestamp":1640995200000}"""
    val message = MessageParser.parse(json)
    
    assertEquals("rotate", message.cmd)
    assertEquals(180, message.y)
    assertTrue(message.timestamp > 0)
}

集成测试：

kotlin 复制代码

@Test
fun testCrossDeviceCommunication() {
    // 启动WebSocket服务器
    val server = startTestServer()
    
    // 连接Android客户端
    val androidClient = connectAndroidClient()
    
    // 连接JSAR客户端
    val jsarClient = connectJSARClient()
    
    // 发送测试消息
    androidClient.send("""{"cmd":"rotate","y":90}""")
    
    // 验证JSAR端收到消息
    val receivedMessage = jsarClient.waitForMessage()
    assertEquals(90, receivedMessage.y)
}

总结与展望

在本实战指南中，我们详细探讨了如何使用CXR SDK开发跨设备AR应用，从环境搭建到性能优化，提供了一套完整的开发流程和最佳实践。通过本文的学习，你应该能够：

快速上手CXR SDK：掌握CXR-M移动端SDK和CXR-S眼镜端SDK的集成方法
实现跨设备通信：建立移动端与眼镜端之间稳定高效的数据传输机制
优化应用性能：通过专业的工程化手段提升应用的响应速度和资源利用效率
构建稳健的AR应用：应用错误处理、容错机制和内存管理策略确保应用稳定性

CXR SDK为开发者提供了一套完整、高效的AR应用开发解决方案，其优势在于：

原生性能：专为AR场景优化的底层实现，提供卓越的运行效率
稳定可靠：经过大规模实践验证的SDK，确保应用在各种场景下的稳定性
易用性：简洁明了的API设计，降低开发门槛，提高开发效率
全面支持：完整覆盖移动端和眼镜端的开发需求，实现无缝跨设备交互

未来，CXR SDK将继续演进，提供更多高级特性，包括更丰富的AR交互能力、更强大的计算机视觉功能和更智能的设备协同机制。我们期待与开发者一起，共同推动AR技术在各行业的创新应用。

希望本指南能够成为你开发跨设备AR应用的得力助手，祝你在AR开发之路上取得更多创新成果！

附录

完整项目结构

复制代码

CXR-Demo/
├── android-mobile-app/      # 移动端Android应用（CXR-M SDK）
│   ├── app/
│   │   ├── src/main/java/com/rokid/demo/
│   │   │   ├── MainActivity.kt        # 主活动
│   │   │   ├── CXRClientManager.kt    # CXR-M客户端管理
│   │   │   ├── CXRFaultToleranceManager.kt  # 容错机制
│   │   │   ├── CXRResourceManager.kt  # 资源管理
│   │   │   └── utils/
│   │   ├── build.gradle.kts
│   │   └── settings.gradle.kts
│   └── build.gradle.kts
└── android-glasses-app/     # 眼镜端Android应用（CXR-S SDK）
    ├── app/
    │   ├── src/main/java/com/rokid/demo/
    │   │   ├── MainActivity.kt        # 主活动
    │   │   ├── CXRServiceBridge.kt    # CXR-S服务桥接
    │   │   ├── CXRRemoteControlService.kt # 远程控制服务
    │   │   └── utils/
    │   ├── build.gradle.kts
    │   └── settings.gradle.kts
    └── build.gradle.kts

快速启动命令

构建和运行CXR SDK项目：

构建移动端应用

bash 复制代码

cd android-mobile-app
./gradlew assembleDebug

安装移动端应用

bash 复制代码

adb install app/build/outputs/apk/debug/app-debug.apk

构建眼镜端应用

bash 复制代码

cd android-glasses-app
./gradlew assembleDebug

安装眼镜端应用

bash 复制代码

adb install app/build/outputs/apk/debug/app-debug.apk

参考资源

CXR SDK 官方文档：
- CXR-M 移动端 SDK 文档：https://custom.rokid.com/prod/rokid_web/57e35cd3ae294d16b1b8fc8dcbb1b7c7/pc/cn/2786298057084a82b170bf725aef6b5d.html
- CXR-S 眼镜端 SDK 文档：https://custom.rokid.com/prod/rokid_web/57e35cd3ae294d16b1b8fc8dcbb1b7c7/pc/cn/9d9dea4799ca4dd2a1176fedb075b6f2.html
技术栈版本：
- Android SDK: API 28+
- Kotlin: 2.1.0
- CXR-M SDK: 1.0.1
- CXR-S SDK: 1.0.1

免责声明

本文中的代码片段与模板仅为教学目的，实际接口以官方最新 SDK 为准。若版本变更，请以 Maven 仓库与 Release Note 为权威来源。作者不对因使用本文内容而产生的任何问题承担责任。