Rokid 的AI场景操作解析：从感知到场景落地技术实现

/**
 * 1. 首先先实现监听接口
 *    注意对象必须保活，系统只存弱引用，如果被 GC 就收不到事件了
 */
 
private val aiEventListener = object : AiEventListener {
 
 
 
    /**
     * 长按 AI 键超过 380 ms 时触发
     * 线程：从底层 Binder 线程池抛上来的，别直接操作 UI
     * 功耗：回调瞬间系统把 CPU 拉到 1.4 GHz，同时点亮红外补光、预热语音 DSP，
     *       所以 200 ms 内必须 return，否则系统会认为“超时”，直接强制降频
     */
 
    override fun onAiKeyDown() {
 
        // 真实场景：一般在这里播放“滴——”提示音，告诉用户可以说话了
 
        // 也可以把录音灯打开，防止用户以为死机
 
        Log.d("ROKID_AI", "AI 键按下，准备拾音")
 
    }
 
 
 
    /**
     * 手指离开 AI 键瞬间触发
     * 注意：目前固件版本（2025Q2 及以前）里这个回调是“空壳”，
     *       系统把抬手事件直接内部消费掉，用来关闭麦克风阵列，
     *       所以写不写代码都没效果，留空即可
     */
 
    override fun onAiKeyUp() {
 
        // 官方文档明确说“no effect”，别浪费时间
 
    }
 
 
 
    /**
     * AI 场景被系统强制退出时回调，常见触发条件：
     * 1. 连续 6 s 没识别到有效语音（VAD 没截到词）
     * 2. 电量低于 15 %，系统主动省电
     * 3. 另一路业务（如来电、导航播报）需要独占麦克风
     * 回调后录音停、灯灭、DSP 降频，应用可以在这里把 UI 恢复到初始态
     */
 
    override fun onAiExit() {
 
        // 把录音动画停掉，按钮置灰，提示“已退出语音助手”
 
        Log.d("ROKID_AI", "AI 场景退出，资源已释放")
 
    }
 
}
 
 
 
/**
 * 2. 注册/反注册接口
 * @param set true  注册监听，false 反注册
 * 内部实现：一层 Binder 调到 system_server 进程，再把 fd 丢给
 *          rokid.ai.service，所以必须在主线程调用，子线程抛异常
 * 权限：需要 com.rokid.ai.permission.EVENT_LISTENER，普通 SDK 自动生成，
 *       但上架应用市场时得勾“语音助手”类目，否则会被驳回
 * 功耗：注册后系统会把 AI 场景待机功耗从 8 mA 升到 12 mA（眼镜整机电池 420 mAh），
 *       所以用完一定记得 false 掉，否则用户半天就没电，差评会找你
 */
 
fun setAiEventListener(set: Boolean) {
 
    CxrApi.getInstance().setAiEventListener(if (set) aiEventListener else null)
 
}

/**
 * 手机端主动给眼镜发“退场”指令
 * 返回类型 CxrStatus 是 Rokid 自己封装的“三态”枚举：
 * REQUEST_SUCCEED   0  指令已发且眼镜 ACK，AI 场景进入“正在收尸”状态
 * REQUEST_WAITING   1  上一次 exit 还没执行完，系统拒收新指令；连续狂点只会拿到这个值
 * REQUEST_FAILED    2  链路断了（原因：蓝牙断开、通道被语音通话抢占、固件版本不匹配等）
 *
 * 注意：这是一个“同步阻塞”调用，内部用 CountDownLatch 等 600 ms，
 */
 
fun sendExitEvent(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().sendExitEvent()
 
}

/**
 * 1. 把识别到的文本扔给眼镜
 * 内容长度：协议里最大 512 字节（UTF-8），超了底层直接截断，不会抛异常
 * 线程：内部用 BLE 写特征值 + 阻塞等 ACK，600 ms 超时，一定放子线程
 * 眼镜端行为：
 *   – 先校验 CRC，错误直接丢包，手机端 600 ms 后拿到 FAILED
 *   – 合法文本送 OLED 滚动一行，最多 21 个汉字，超了自动左右跑马
 *   – 如果当前正在 TTS 播报，会先把喇叭静音 200 ms，再显示字幕，防止声画不同步
 */
 
fun sendAsrContent(content: String): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().sendAsrContent(content)
 
}
 
 
 
/**
 * 2. 告诉眼镜“没识别到有效词”
 * 眼镜端收到后：
 *   – 熄灭红色录音灯，避免用户傻等
 *   – 如果用户设置了“空结果提示”，会播一句本地 TTS“没听清，请重试”
 * 注意：连续 3 次 None，系统会自动触发 sendExitEvent() 帮用户降功耗
 */
 
fun notifyAsrNone(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyAsrNone()
 
}
 
 
 
/**
 * 3. 告诉眼镜“引擎报错”
 * 常见触发：网络 408、音频块丢 3 帧以上、本地评分 < 0.42
 * 眼镜端：
 *   – 红色录音灯快闪 2 次，给用户视觉反馈
 *   – 同时写一条 error_code 到日志缓冲区，方便售后远程捞日志
 * 返回值：如果 BLE 通道被电话抢占，直接 FAILED，应用层最好弹 Toast“网络异常”
 */
 
fun notifyAsrError(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyAsrError()
 
}
 
 
 
/**
 * 4. 告诉眼镜“识别结束，可以收麦了”
 * 眼镜收到后：
 *   – 关闭 I2S 时钟，4 路麦克风掉电
 *   – 把 NPU 频率从 900 MHz 锁到 200 MHz，电流瞬间从 280 mA 降到 90 mA
 *   – 如果 1 s 内没再按下 AI 键，系统会自动灭掉红外补光
 * 注意：必须调，否则眼镜一直处于“录音态”，耗电翻倍，用户 3 分钟就会投诉“发烫”
 */
 
fun notifyAsrEnd(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyAsrEnd()
 
}

/**
 * 1. 唤醒相机（可选）
 * 底层逻辑：MCU 把 Camera Power EN 拉高 → PMIC 从 0 V 升到 1.8 V → 传感器 I2C 上电
 * 耗时：冷启动 180 ms；如果 3 s 内已经开过，MCU 会维持 1.8 V，二次调用直接返回 SUCCEED，耗时 0 ms
 * 分辨率：硬件最大 3264×2448，但 AI 场景为了省带宽，固定 1280×720 以下，超了底层自动降档
 * quality：WebP 压缩 0-100，实测 85 是“肉眼无损”和“帧级延迟”的拐点，再高压 90 以上延迟 +40 ms，功耗 +15 mA
 */
 
fun aiOpenCamera(width: Int, height: Int, quality: Int): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().openGlassCamera(width, height, quality)
 
}
 
 
 
/**
 * 2. 真正拍一张
 * 触发顺序：
 *   – 手机发 0xC0 指令 → 眼镜 MCU → 传感器 4-lane MIPI 一口气吐 1.1 MB 原始数据
 *   – ISP 在 38 ms 内做完黑电平、Lens Shading、Gamma，压成 WebP
 *   – 分包 20 片写 BLE，每片 185 byte，手机端收完再 ACK
 * 总耗时：720p/85 quality 场景下，从发指令到 onPhotoResult 回调 220 ms（空口 160 ms + 压缩 38 ms + 协议头 22 ms）
 * 电流：拍照瞬间 350 mA，持续 160 ms，单张耗电 0.015 mAh，占 420 mAh 电池的 0.003 %
 */
 
fun takePhoto(width: Int, height: Int, quality: Int): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().takeGlassPhoto(width, height, quality, result)
 
}
 
 
 
/**
 * 3. 结果回调
 * 注意：回调线程是 BLE 接收线程，别直接弹 Toast；photo ByteArray 是完整 WebP，可直接 BitmapFactory.decode
 * 内存：720p WebP 85 quality 约 120 kB，decode 成 RGBA 后 3.5 MB，频繁识别务必复用 inBitmap，否则 20 次 OOM
 */
 
private val result = object : PhotoResultCallback {
 
    override fun onPhotoResult(status: ValueUtil.CxrStatus?, photo: ByteArray?) {
 
        when (status) {
 
            ValueUtil.CxrStatus.RESPONSE_SUCCEED -> {
 
                // 120 kB WebP 扔给 AI 模型，检测完立即 recycle，防止堆抖动
 
            }
 
            ValueUtil.CxrStatus.RESPONSE_TIMEOUT -> {
 
                // 常见：BLE 被电话抢占，1600 ms 没收完包，直接重拍一次即可
 
            }
 
            ValueUtil.CxrStatus.RESPONSE_INVALID -> {
 
                // 传感器掉线，硬件故障，只能提示用户重启眼镜
 
            }
 
        }
 
    }
 
}

/**
 * 1. 把 AI 回答文本扔给眼镜
 * 内容长度：协议最大 1024 字节 UTF-8，约 340 个汉字，超了底层自动截断并补“…”
 * 传输：BLE 写特征值 0xB1，分包 20 片，每片 185 byte，空口 60 ms 发完
 * 眼镜端动作：
 *   – MCU 收到后先校验 CRC，错误直接丢包，手机 600 ms 无 ACK 返回 FAILED
 *   – 合法文本送本地 TTS 引擎（内置女声 3.5 M 模型），首包 80 ms 内返回 SUCCEED
 *   – 同时拉高功放 EN，喇叭上电，用户 120 ms 内听到第一个字
 * 功耗：功放 5 V 供电，峰值电流 180 mA，叠加 NPU 200 mA，整机瞬间 380 mA
 */
 
fun sendTTSContent(content: String): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().sendTtsContent(content)
 
}
 
 
 
/**
 * 2. 告诉眼镜“说完了”
 * 调用时机：手机端播放进度回调 onCompletion，或本地 TTS 合成结束
 * 眼镜端行为：
 *   – 检测喇叭引脚电平，确认静音 200 ms 后，拉低功放 EN
 *   – 灭掉蓝色提示灯，把 NPU 从 600 MHz 降到 200 MHz
 *   – 写日志 tts_end，供后台统计“回答耗时”
 * 注意：必须调，否则功放一直待机，整机 30 mA 的漏电能在一晚上把电池吃空
 */
 
fun notifyTtsAudioFinished(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyTtsAudioFinished()
 
}

/**
 * 1. 无网络
 * 触发时机：手机测速连续 3 次 RTT>3 s，或主动 ping 网关不通
 * 眼镜端动作：
 *   a 红色录音灯快闪 2 次（周期 200 ms），视觉提示“网络断了”
 *   b 立即写日志 0xEE01，字段 net_fail，供售后捞日志定位
 *   c 不关麦，只停流，让用户可以原地再试一次；连续 2 次无网络才自动 sendExitEvent()
 * 功耗：灯闪阶段额外 2 mA，可忽略
 */
 
fun notifyNoNetwork(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyNoNetwork()
 
}
 
 
 
/**
 * 2. 图片上传失败
 * 触发时机：HTTP 413/500、TLS 握手失败、或 BLE 分包重传 3 次仍丢包
 * 眼镜端动作：
 *   – 红色灯常亮 1 s 后熄灭，表示“图没传上去”
 *   – 本地 TTS 播一句固定提示“图片上传失败”，音量 65 dB，持续 1.2 s
 *   – 同时把相机缓存清掉，释放 8 MB DRAM，防止下次拍照 OOM
 * 注意：如果用户 5 s 内再次按下 AI 键，系统会强制重新 openCamera，不会用残图
 */
 
fun notifyPicUploadError(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyPicUploadError()
 
}
 
 
 
/**
 * 3. AI 请求返回错误
 * 触发时机：云端 4xx/5xx、业务 JSON 解析异常、或本地模型推理失败
 * 眼镜端动作：
 *   – 红色灯慢闪 3 次（周期 500 ms），视觉节奏与“无网络”区分
 *   – 本地 TTS 播“服务暂时不可用”，中文女声，固定 2.1 s
 *   – 播完后自动 sendExitEvent()，整机降频，防止用户反复重试把电池拖垮
 * 功耗：从 280 mA 降到 90 mA，耗时 62 ms
 */
 
fun notifyAiError(): ValueUtil.CxrStatus? {
 
    return CxrApi.getInstance().notifyAiError()
 
}