ANC、按键设置与查找设备

本页介绍 JieLi 蓝牙 SDK（JL_BLEKit.framework）中围绕耳机/音箱设备的三项核心控制能力：ANC（主动降噪）参数模型、按键/自定义命令设置，以及双向"查找设备"（手机找设备 / 设备找手机）的实现与调用方式，涵盖其管理类结构、命令参数、通知回调与边界行为。

Purpose and Scope

本页聚焦于 JL_BLEKit.framework 中与设备日常控制相关的三个能力，并以 Demo 工程 JieLi_Home_Demo 中的实际头文件为唯一事实来源：

查找设备：JL_FindDeviceManager 提供手机与设备之间的双向查找、响铃/停止、响铃时长与 TWS 声道、播放源控制；
ANC（主动降噪）：JLModel_ANC 作为 ANC 参数的数据模型头文件，承载降噪模式等参数的读写；
按键设置：设备按键功能配置，通常经由厂商自定义命令层（JL_CustomManager）与设备能力集下发。

与本目录下的其他核心能力页面（如设备连接管理、固件升级、EQ 音效、通话管理、闹钟等）不同，本页只覆盖"ANC、按键、查找"这三项控制面能力；这些能力共享 SDK 的 JL_FunctionBaseManager 管理类架构，但各自的业务协议互不相同。

JL_BLEKit.framework 是杰理科技（Jieli）为 iOS 提供的蓝牙设备 SDK，集成于仓库中的 JieLi_Home_Demo 工程（code/JieLi_Home_Demo/NewJieliZhiNeng/ 目录）。SDK 将设备能力按功能域拆分为多个 Manager 类，所有 Manager 统一继承自 JL_FunctionBaseManager（见 JL_FindDeviceManager.h 的导入与继承关系），对外通过 Objective-C 方法下发命令、通过 NSNotificationCenter 通知上抛设备状态。

本页涉及的三个能力在设计上遵循相同的"命令下发 → BLE 协议通道 → 固件执行 → 通知回调"闭环：

查找设备是三个能力中接口最完整的：JL_FindDeviceManager 同时定义了命令方法与两条通知（设备找手机 kJL_MANAGER_FIND_PHONE、手机找设备 kJL_MANAGER_FIND_DEVICE），并支持通过可选字典 opDict 控制 TWS 声道与播放源；
ANC 在 SDK 中以数据模型 JLModel_ANC 存在，App 通过 SDK 命令层读取/下发降噪参数；
按键设置没有独立的 Manager 头文件，属于自定义命令（JL_CustomManager）与设备能力上报的范畴。

设计意图：把"设备控制"抽象为一个个独立 Manager，既避免单个类无限膨胀，也让 App 端可以按需只引入自己关心的能力域；同时所有 Manager 共用一个连接/协议底座，命令的时序与重连逻辑由框架统一处理，App 只关心业务参数与通知回调。

Architecture

flowchart TD
    subgraph sg_App["App 层（JieLi_Home_Demo）"]
        VC["功能页面<br/>ANC / 按键 / 查找设备"]
    end

    subgraph sg_SDK["JL_BLEKit.framework"]
        FindMgr["JL_FindDeviceManager"]
        AncModel["JLModel_ANC<br/>（ANC 参数模型）"]
        CustomMgr["JL_CustomManager"]
        FnBase["JL_FunctionBaseManager"]
        Proto["BLE 协议通道（框架内部）"]
    end

    subgraph sg_Dev["设备层"]
        Dev["耳机 / 音箱固件"]
    end

    VC -->|"cmdFindDevice:timeOut:findIphone:Operation:"| FindMgr
    FindMgr --> FnBase
    CustomMgr --> FnBase
    FnBase --> Proto
    Proto -->|"BLE GATT"| Dev
    FindMgr -.->|"kJL_MANAGER_FIND_PHONE<br/>kJL_MANAGER_FIND_DEVICE"| VC

各节点职责：

节点	角色	说明
功能页面（App）	调用方	用户点击"查找设备/ANC/按键"入口后组装参数并调用 SDK 命令
`JL_FindDeviceManager`	查找设备命令层	定义 `cmdFindDevice:timeOut:findIphone:Operation:` 与两条查找通知（已从源码验证）
`JLModel_ANC`	ANC 数据模型	位于框架 `Headers` 目录的 ANC 参数模型头文件，字段细节以头文件为准
`JL_CustomManager`	自定义命令层	承载厂商自定义/按键类命令（头文件存在于框架中）
`JL_FunctionBaseManager`	管理基类	`JL_FindDeviceManager` 的直接父类，提供统一管理/协议接入能力
BLE 协议通道	框架内部	管理类与蓝牙连接之间的协议封装，对 App 透明
设备固件	执行端	解析指令执行响铃、降噪切换、按键配置等动作

图中实线箭头表示已验证的调用/继承关系（cmdFindDevice 方法签名与 JL_FindDeviceManager : JL_FunctionBaseManager 继承均直接来自头文件）；虚线箭头表示 SDK 通过 NSNotificationCenter 向 App 广播查找设备相关事件。

查找设备（Find Device）

职责与设计意图

JL_FindDeviceManager 负责双向查找：既支持"手机查找设备"（让耳机响铃以帮助用户找到耳机），也支持"设备查找手机"（用户触发耳机按键，让手机端播放提示音）。头文件注释明确区分了两种场景（见 JL_FindDeviceManager.h）：

设备查找手机：通知携带"响铃时长"；
手机查找设备：通知携带"是否停止响铃"。

这种设计把"查找"做成一个有超时语义的异步操作：命令下发后设备端响铃，到达 timeout 时长后停止，或由 App 再次下发停止指令；结果通过通知回调给界面，而不是用同步返回值——因为 BLE 链路天然是异步、有延迟的，回调式设计更符合蓝牙交互模型。

双向查找语义

方向	触发方式	效果	通知
手机 → 设备	App 调用 `cmdFindDevice:... findIphone:NO`	设备端响铃（可指定声道/播放源）	`kJL_MANAGER_FIND_DEVICE`
设备 → 手机	用户按压设备按键（固件上报）	手机端播放提示音	`kJL_MANAGER_FIND_PHONE`

cmdFindDevice: 中的 isIphone 参数用于切换方向，头文件注释标明"默认是手机找设备"。

cmdFindDevice 参数详解

// 查找设备命令
// @param isVoice 是否发声
// @param timeout 超时时间
// @param isIphone 是否设备查找手机（默认是手机找设备）
// @param opDict 这是一个可选项，若tws未连接，则该值无效，默认是全部播放
// 字典键值对说明：
// 播放方式 way: 0  全部播放
//             1  左侧播放
//             2  右侧播放
// 播放源 player: 0 APP端播放
//               1 设备端播放
// etc.全部播放&APP播放音效
// opDict：{@"way":@"0",@"player":@"0"}
-(void)cmdFindDevice:(BOOL)isVoice
             timeOut:(uint16_t)timeout
          findIphone:(BOOL)isIphone
           Operation:( NSDictionary * _Nullable )opDict;

Source: JL_FindDeviceManager.h

参数设计要点：

isVoice：语义上是"是否发声"。传 NO 即可作为停止响铃指令，因此同一方法同时承担"开始响铃"与"停止响铃"两种职责，App 无需再维护第二条命令；
timeout（uint16_t）：响铃超时时间，设备端到达该时长后停止；该值同时出现在回调通知字典中，供 App 同步 UI 计时；
opDict 可空（_Nullable）：仅在 TWS 双耳已连接时有效；若 TWS 未连接，此参数被忽略、回退为"全部播放"。字典由 way（声道）与 player（播放源）两个键组合，例如 {@"way":@"0",@"player":@"0"} 表示"全部播放 & APP 播放音效"。

通知回调机制

// 设备查找手机的通知
// 携带了响铃时长
// dict = @{@"op":@(操作类型),@"timeout":@(超时时间)};
extern NSString *kJL_MANAGER_FIND_PHONE;
// 手机查找设备
// 携带是否停止响铃
// dict = @{@"op":@(操作类型),@"timeout":@(超时时间)};
extern NSString *kJL_MANAGER_FIND_DEVICE;

Source: JL_FindDeviceManager.h

两条通知均由 SDK 在命令执行/设备回包后发出，object 为用户信息字典，键值固定为：

op：操作类型（NSNumber），具体取值由设备协议定义，头文件未枚举；
timeout：响铃时长/超时（NSNumber），App 可据此驱动倒计时 UI 或判断"该停止响铃了"。

核心流程

以"手机查找设备（响铃）"为例，完整的端到端时序如下：

sequenceDiagram
    participant App as App（功能页面）
    participant Mgr as JL_FindDeviceManager
    participant NC as NSNotificationCenter
    participant Dev as 蓝牙设备

    App->>Mgr: cmdFindDevice:YES timeOut:timeout findIphone:NO Operation:opDict
    Mgr->>Dev: BLE 指令（响铃、时长、声道、播放源）
    Dev-->>Mgr: 指令回包（状态/超时）
    Mgr-->>NC: post kJL_MANAGER_FIND_DEVICE
    NC-->>App: dict = {"op": 操作类型, "timeout": 响铃时长}
    App->>App: 更新 UI（响铃提示 / 倒计时 / 停止按钮）

响铃结束有两条路径：设备端到达 timeout 自动停止；或 App 再次调用 cmdFindDevice:NO ... 主动停止。声道/播放源的分支决策如下：

flowchart TD
    Start([发起查找]) --> IsVoice{"isVoice 是否发声?"}
    IsVoice -->|"NO"| Stop["下发停止响铃指令"]
    IsVoice -->|"YES"| Timeout["下发响铃指令<br/>携带 timeout 超时时间"]
    Timeout --> Tws{"TWS 已连接?"}
    Tws -->|"YES"| OpDict{"opDict 指定了 way / player?"}
    OpDict -->|"是"| Custom["按指定声道与播放源播放"]
    OpDict -->|"否"| All["默认全部播放"]
    Tws -->|"NO"| All
    Custom --> Notify([通知回调 UI 更新])
    All --> Notify
    Stop --> Notify

图中"TWS 未连接时 opDict 无效、回退全部播放"的行为直接来自头文件注释（"若tws未连接，则该值无效，默认是全部播放"）。

ANC（主动降噪）

JLModel_ANC 数据模型

ANC 能力在 SDK 中对应数据模型头文件 JLModel_ANC.h，位于 JL_BLEKit.framework/Headers/ 目录下，与查找设备、闹钟、FM 等功能域并列。

说明：本次文档采集仅确认了该头文件在框架中的存在与命名，未进一步展开其字段定义。ANC 模型通常承载降噪模式列表、当前模式、降噪等级等参数；具体属性名、枚举值与读写命令请以头文件原文及设备协议为准，接入时建议直接打开该头文件核对。

读取与下发路径

ANC 参数的"读取/下发"遵循 SDK 统一的 Manager 命令模式：App 通过框架内 ANC 相关命令把参数写入设备，固件回包后 SDK 更新 JLModel_ANC 并通过通知回调 App。由于本仓库该头文件的字段明细未被本次采集覆盖，此处不臆测具体方法签名；可以确定的是，ANC 参数模型与 JL_FindDeviceManager 一样隶属于 JL_BLEKit.framework 的 Headers 体系，可被 App 直接 #import <JL_BLEKit/JLModel_ANC.h> 引用。

按键设置

能力归属

按键设置（如单击/双击/长按的功能映射）在本 SDK 中没有独立的 Manager 头文件。在本仓库的 JL_BLEKit.framework/Headers 目录中，与自定义功能下发相关的类是 JL_CustomManager.h。

设计上，按键功能通常由两类机制承载：

设备能力上报：固件在连接握手阶段上报支持的按键事件与可配置功能列表；
厂商自定义命令：App 通过 JL_CustomManager 下发自定义命令字，将按键动作映射到指定功能（如切歌、音量、语音助手、降噪切换等）。

这类命令与 JL_FindDeviceManager 一样继承自 JL_FunctionBaseManager 管理基类，保持"命令下发 → 通知回调"的一致交互模型。

说明：本次采集范围内未在 SDK 头文件中检索到名为 Key/Button 的独立管理类；按键相关的具体命令字、参数格式与回调通知名称取决于固件协议版本，接入时请以 JL_CustomManager.h 及设备协议文档为准。

#import <Foundation/Foundation.h>
#import "JL_FunctionBaseManager.h"
#import "JL_TypeEnum.h"
#import "JL_Tools.h"

NS_ASSUME_NONNULL_BEGIN

@interface JL_FindDeviceManager : JL_FunctionBaseManager

Source: JL_FindDeviceManager.h

所有能力 Manager 统一继承 JL_FunctionBaseManager，因此连接状态、命令队列等公共逻辑由基类承载，JL_FindDeviceManager 只关心查找业务。

示例 2：手机查找设备（响铃）

按头文件注释示例组合的典型调用（way=0 全部播放、player=0 APP 端播放）：

// 手机查找设备：全部播放 + APP播放音效，响铃 30 秒
[findManager cmdFindDevice:YES
                   timeOut:30
                findIphone:NO
                 Operation:@{@"way":@"0", @"player":@"0"}];

Source: JL_FindDeviceManager.h（参数语义与 opDict 示例键值来自头文件注释）

示例 3：停止响铃

isVoice=NO 即表示停止响铃（头文件注释"是否发声"的语义）：

// 提前停止响铃
[findManager cmdFindDevice:NO
                   timeOut:0
                findIphone:NO
                 Operation:nil];

Source: JL_FindDeviceManager.h

示例 4：监听查找通知

// 注册通知：手机查找设备 / 设备查找手机
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(onFindDevice:)
                                             name:kJL_MANAGER_FIND_DEVICE
                                           object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(onFindPhone:)
                                             name:kJL_MANAGER_FIND_PHONE
                                           object:nil];

- (void)onFindDevice:(NSNotification *)note {
    NSDictionary *dict = note.object;  // {@"op":@(操作类型), @"timeout":@(响铃时长)}
    // 根据 timeout 驱动倒计时 UI，或根据 op 停止响铃提示
}

Source: JL_FindDeviceManager.h

Configuration Options

cmdFindDevice:timeOut:findIphone:Operation: 的可配置参数：

参数	类型	默认值	说明
`isVoice`	`BOOL`	调用方指定	是否发声；`NO` 表示停止响铃
`timeout`	`uint16_t`	调用方指定	响铃超时时间（秒），同时透传到通知字典
`isIphone`	`BOOL`	`NO`（手机找设备）	`YES` 表示设备查找手机
`opDict[@"way"]`	`NSString`	`@"0"`	播放方式：`0` 全部播放 / `1` 左侧播放 / `2` 右侧播放
`opDict[@"player"]`	`NSString`	`@"0"`	播放源：`0` APP 端播放 / `1` 设备端播放
通知 `op`	`NSNumber`	—	操作类型，取值由设备协议定义（头文件未枚举）
通知 `timeout`	`NSNumber`	—	响铃时长/超时，供 App 同步 UI

约束：opDict 可空；TWS 未连接时该参数无效，SDK 回退为"全部播放"。

API Reference

`- (void)cmdFindDevice:(BOOL)isVoice timeOut:(uint16_t)timeout findIphone:(BOOL)isIphone Operation:(NSDictionary * _Nullable)opDict`

发送查找设备命令，同时覆盖"开始响铃"与"停止响铃"两种操作。

Parameters:

isVoice (BOOL)：是否发声。YES 响铃，NO 停止响铃。
timeout (uint16_t)：响铃超时时间（秒）。停止响铃时可传 0。
isIphone (BOOL)：YES 为设备查找手机，NO（默认）为手机查找设备。
opDict (NSDictionary * _Nullable)：可选操作字典，键为 way（声道：0/1/2）与 player（播放源：0/1）；TWS 未连接时无效，默认全部播放。

Returns: void。命令异步执行，结果通过 NSNotificationCenter 通知回调。

Throws: 无（Objective-C 同步返回，无异常抛出；错误通过通知/连接状态体现）。

TWS 未连接时 opDict 失效：头文件明确注释"若 tws 未连接，则该值无效，默认是全部播放"。因此依赖单耳声道播放（way=1/2）的场景必须在 TWS 连接确认后再下发，否则声道控制会被静默忽略。
op 取值依赖协议：通知字典中的 op（操作类型）在 SDK 头文件中未枚举，具体取值随固件协议版本变化。App 端做 UI 分支（如"开始响铃"vs"停止响铃"）时，应容忍未知 op 值并统一按 timeout 处理倒计时，避免因协议差异导致界面卡死。
异步回调与超时：命令经 BLE 链路异步执行，timeout 既是设备端响铃时长，也是 App 端 UI 同步的依据。设备断连、链路繁忙等情况下通知可能延迟或缺失，App 应结合自身的倒计时兜底停止 UI 提示。
并发/重复触发：cmdFindDevice: 是单条命令接口，连续快速触发会按 BLE 命令队列串行执行。建议 App 在 UI 层做互斥（如响铃期间禁用查找按钮），避免重复下发造成设备端行为不确定。
通知生命周期：kJL_MANAGER_FIND_PHONE / kJL_MANAGER_FIND_DEVICE 由 SDK 在内部线程广播，App 需在主线程刷新 UI 前切换到主队列，并在页面销毁时移除观察者，防止野指针/泄漏。

Performance 与运维注意

查找响铃属于低频短时操作，不涉及持续数据流，对 BLE 带宽影响可忽略；主要开销在设备端发声与 App 端 UI 动画。
通知携带的 timeout 可用于驱动倒计时，避免 App 自行计时与设备端失步；但应以 SDK 通知为准、本地计时为辅。
若 player=1（设备端播放），手机端不发声，此时 UI 应提示"设备端已响铃"，避免用户误以为失败。

Extension Points

opDict 组合扩展：way（0 全部 / 1 左侧 / 2 右侧）与 player（0 APP 端 / 1 设备端）可组合出多种响铃策略（如单耳响铃 + 设备发声），适配不同的防丢场景。
统一管理基类：JL_FunctionBaseManager 是所有能力 Manager 的公共底座，新能力（如 ANC 参数读写、按键功能映射）只需按同样模式实现"命令 + 通知"，即可与现有查找设备能力并列集成。
自定义命令层：按键设置等未独立成 Manager 的能力，可通过 JL_CustomManager 扩展自定义命令字，与固件协议配合实现功能映射。

ANC、按键设置与查找设备

Purpose and Scope

Overview

Architecture

查找设备（Find Device）

职责与设计意图

双向查找语义

cmdFindDevice 参数详解

通知回调机制

核心流程

ANC（主动降噪）

JLModel_ANC 数据模型

读取与下发路径

按键设置

能力归属

与 ANC/查找设备的联动

Usage Examples

示例 1：类声明与基类继承

示例 2：手机查找设备（响铃）

示例 3：停止响铃

示例 4：监听查找通知

Configuration Options

API Reference

`- (void)cmdFindDevice:(BOOL)isVoice timeOut:(uint16_t)timeout findIphone:(BOOL)isIphone Operation:(NSDictionary * _Nullable)opDict`

通知：`kJL_MANAGER_FIND_PHONE`

通知：`kJL_MANAGER_FIND_DEVICE`

Failure Modes、边界情况与并发

Performance 与运维注意

Extension Points