1.9 蓝牙遥控器接入产品文档

# 蓝牙遥控器接入产品文档

开发前须知

遥控器内置BLE芯片，通过按键触发mibeacon广播将指令发送给小米WiFi&BLE双模模组，模组接收指令后执行动作。

遥控器固件上需要有自己的PID,以规范使用和方便被控设备端识别，请在小米IOT开发者平台上申请model后获得PID。（遥控器model不需要上线，每个新产品申请一个配套的遥控器model，命名为xxxxx遥控器）

遥控器按键定义

1.触发配对模式的按键：

按住combo键触发配对时，需要在广播报文里声明遥控器的身份信息，作为接收端是否配对的验证依据；

调用ble_fastpair_event函数发起配对，遥控器配对状态会最多持续5秒钟；

不同类型设备上的遥控器因按键设置不同，可灵活按如下处理：

有开关按键和模式键：开关按键+模式按键同时按住3秒钟进入配对模式；

有开关键无模式键：开关键+（固件协议定义的）第一指令按键同时按住3秒钟进入配对模式；

无开关键：优先以固件定义的头两个指令的组合键按住3秒钟进入配对模式；

注：遥控器触发配对后可以在遥控器的led上闪烁，同时配对成功了，建议由设备端进行交互提示（比如灯闪烁一下）。

2.发送操作指令的按键：

说明：除mibeacon中通用信息外，实际要使用的按键指令包括两部分组成（16进制）：操作类型（一个字节）+键值（两个字节）；

操作类型：理论上支持0x00起至0xFF，除标准设定值外，厂商可根据使用情况进行扩展；扩展部分请先和对应的米家产品经理沟通；

键值：理论上支持0x0000起至0xFFFF，除标准设定值外，厂商可根据使用情况进行扩展；扩展部分请先和对应的米家产品经理沟通；

Combo模组操作步骤

模组版本

每个Combo模组最多存储10个遥控器信息，支持遥控器的模组版本号如下：

ESP32模组：2.0.1版本及以上

MT7697模组：2.0.2版本及以上

RTL8720模组：2.0.2版本及以上

注意：8720 2.0.1版本未包含遥控器功能

串口开发

以使用1.0开发方式（外置MCU，使用串口与模组通信）为例。

当米家模组收到某个新的遥控器的配对广播时，外置MCU通过串口get_down查询消息格式如下：

ble_fastpair [MAC] [object ID] [product ID] [RSSI]

示例：down ble_fastpair 11:22:33:44:55:66 4097 69 -74

其中object ID为待配对事件ID，例如按键事件4097(0x1001)。

外置MCU根据需求判断是否要与该遥控器配对，如果确认要进行配对则发送命令，格式如下：

ble_fastpair set [MAC] [object ID] [product ID] [yes/no]

示例：ble_fastpair set 11:22:33:44:55:66 4097 69 1

其中[yes/no]字段中，0表示no，非零值表示yes（如果选择不配对，也可以选择忽略消息，不发送命令）。

米家模组收到确认配对命令后即执行相应操作，并通过串口返回执行结果，格式如下：

ble_fastpair_rsp [MAC] [status]

示例：down ble_fastpair_rsp 11:22:33:44:55:66 succ

其中[status]表示执行结果，"succ"表示成功，"timeout"表示超时未完成，"fail"表示未知错误。

此外，如果发送mibeacon的遥控器已经与米家模组配对完成，则米家模组直接发送已完成消息，格式如下：

ble_fastpair_rsp [MAC] done

示例：down ble_fastpair_rsp 11:22:33:44:55:66 done

配对完成后，可通过周期发送get_down命令获取遥控器发送数据，格式如下：

down ble_event 11:22:33:44:55:66 4097,020000

可以使用串口指令ble_event list查询已配对设备，另外可通过三种方式删除遥控器信息：

删除指定设备：ble_event delete [MAC] [object ID]

删除所有设备：ble_event reset

重置模组：restore

SDK开发

模组收到Beacon后，均统一作处理，为了处理遥控器相关事件，需先注册回调函数，函数原型如下：

int mible_hooks_register(mible_hooks_t *p_hooks);

三个回调函数功能说明如下：

在上述确认是否进行配对（fastpair_check）的过程中，应用层可获取遥控器的多项信息，例如MAC、信号强度等，若应用层确认与该遥控器配对，需调用如下函数：

int mible_fastpair_update(mible_addr_t address, uint16_t product_id, uint16_t object_id, bool permit);

其中参数permit表示是否确认配对该遥控器。

重置模组会删除所有设备信息，此外可通过以下函数删除配对信息：

int mible_prph_reset(void); // 删除所有设备

int mible_prph_delete(mible_addr_t address, uint16_t object_id); // 删除指定设备

Realtek 8762示例代码

在工程Options -> C++ -> Define 中修改产品PRODUCT_ID

// 初始化按键GPIO，定义按键中断
driver_init();

// 发送快速配对广播包，修改宏ADV_FAST_PAIR_TIME和ADV_INTERVAL_TIME可定义快速配对广播时长与间隔
ble_fastpair_event();

// 发送加密按键obj，修改宏OBJ_ADV_TIMEOUT_MS和OBJ_ADV_INTERVAL_MS可定义按键广播时长与间隔
mibeacon_obj_enque_oneshot();

ESP32示例代码

// 定义hooks并注册回调
static mible_hooks_t remote_hooks;
int remote_demo_init(void)
{
    int ret;
    memset(&remote_hooks, 0, sizeof(mible_hooks_t));
    remote_hooks.get_object = demo_get_object;
    remote_hooks.fastpair_check = demo_fastpair_check;
    remote_hooks.fastpair_report = demo_fastpair_report;
    ret = mible_hooks_register(&remote_hooks);

    return ret;
}

static void demo_get_object(mible_addr_t addr, mibeacon_object_t *p_object)
{
    // 按键obj处理 (add your code here)
    LOG_INFO_TAG(MIBLE_LOG_TAG, "ble_event %02x:%02x:%02x:%02x:%02x:%02x %d,%02x%02x%02x",
               addr[5], addr[4], addr[3],addr[2], addr[1], addr[0], 
               p_object->id,p_object->data[0],p_object->data[1],p_object->data[2]);
}

static void demo_fastpair_report(mible_addr_t addr, fastpair_state_t state)
{
    // 快速配对返回结果 成功返回FASTPAIR_STATE_SUCC (add your code here)
    LOG_INFO_TAG(MIBLE_LOG_TAG, "ble_fastpair_rsp %02x:%02x:%02x:%02x:%02x:%02x state: %d",
               addr[5], addr[4], addr[3],addr[2], addr[1], addr[0], state);
    switch (state) {
        case FASTPAIR_STATE_SUCC:
            break;
        case FASTPAIR_STATE_TIMEOUT:
            break;
        case FASTPAIR_STATE_EXISTED:
            break;
        case FASTPAIR_STATE_FAIL:
        default:
            break;
    }
}

static void demo_fastpair_check(mible_addr_t addr, uint16_t product_id,uint16_t object_id, int8_t rssi)
{
    // 检查pid与obj_id, 启动配对 (add your code here)
    LOG_INFO_TAG(MIBLE_LOG_TAG, "ble_fastpair %02x:%02x:%02x:%02x:%02x:%02x %d,%d,%d",
               addr[5], addr[4], addr[3],addr[2], addr[1], addr[0], 
               object_id, product_id, rssi);
    mible_fastpair_update(addr, product_id, object_id, true);
}