.. _BLE遥控器&dongle应用说明:

遥控器应用介绍
===================================

    AW30N支持遥控器通过BLE连接dongle进行发送hid键值和音频数据功能，本章主要介绍遥控器模式和dongle模式参数配置和应用相关接口

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

遥控器模式（从机）简介
#########################

    该应用文件位置：
        * apps/app/src/mbox_flash/remotecontrol/rc_app.c
        * apps/app/src/mbox_flash/remotecontrol/rc_app.h
        * apps/app/src/mbox_flash/remotecontrol/rc_key.c

    用户在使用遥控器模式之前，确认app_modules.h中BLE_EN和RF_REMOTECONTROL_MODE_EN功能宏打开，并且开启bt_ble.h中的TRANS_DATA_HID_EN

        .. image:: ble_app_select.png
            :alt: "BLE方案选择 “
            :align: center
        .. centered:: BLE方案选择
    
    遥控器模式在首次上电之后会开启广播等待dongle(主机)搜索并建立连接，连接成功后用户可以通过按键发送hid命令和音频数据。保持连接期间会不断进出powerdown，在一段时间内无按键响应和语音发送流程后，会自动进入softoff休眠并断开蓝牙。如果用户不需要定时softoff功能可以在rc_app.h关闭。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

遥控器模式（从机）BLE相关参数配置
######################################################

    从机的BLE相关参数主要位于apps/app/bsp/common/bt_common/hid/modules/bt/ble_hogp.c和apps/app/bsp/common/bt_common/hid/modules/user_cfg.c

    在ble_hogp.c文件中可以配置BLE从机相关连接参数如图:

        .. image:: ble_hogp.png
            :alt: "从机连接参数配置 “
            :align: center
        .. centered:: 从机连接参数配置

    在user_cfg.c文件中可以配置BLE从机蓝牙名:

        .. image:: hid_user_cfg.png
            :alt: "从机蓝牙名配置 “
            :align: center
        .. centered:: 从机蓝牙名配置

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

遥控器模式（从机）相关变量和函数说明
######################################################

变量rev_fsm_mge rc_recv_ops
***************************************************************************
    .. note:: 该变量为接收状态机句柄，保存接收状态机中间状态和变量；

变量audio2rf_send_mge_ops remote_ops
***************************************************************************
    .. note:: 该变量管理遥控器发送端接口，包含发送函数、状态查询函数、可发送长度查询函数；

变量queue_obj g_remote_rf_queue
***************************************************************************
    .. note:: 该变量为发送端发送编码数据所使用的队列，编码初始化之后可通过该队列将数据传给蓝牙；

变量 enc_obj \*gp_rc_enc_obj
************************************************

    .. note:: 该变量为遥控器从机编码句柄，用于管理编码，编码器可以从中p_ibuf获取数据，编码后输出到p_obuf；

函数void rf_rc_app()
*******************************************

    .. note:: 遥控器模式主要运行函数，遥控器模式相关流程和主循环都在该函数中运行。

函数void rc_rf_loop()
*******************************************

    .. note:: 遥控器模式状态机循环，目前仅用于获取dongle回复的ack消息对应命令并且开关编码。

函数int vble_slave_init_api(void)
*********************************************

    .. note:: 遥控器(从机)蓝牙初始化接口，内部会初始化蓝牙模块等相关功能。

函数void audio2rf_send_register(void \*ops)
**********************************************

    .. note:: 该函数将音频流发送接口注册到编码输出回调，实现从机发送音频数据。从机发送音频默认使用ATT_CHARACTERISTIC_2a4d_02_VALUE_HANDLE，可在vble_gatt.c修改。其中参数：
        
        1、void \*ops：音频流发送接口集合，详细见结构体audio2rf_send_mge_ops，内部包含发送接口、蓝牙状态检查和获取蓝牙发送空间接口

函数int rc_get_vaild_len_api(void)
**********************************************

    .. note:: 通过该函数可获取蓝牙可发数空间。其中参数：
        
        | 1、返回值：
            可发送的数据长度。

函数int rc_check_status_api(void)
**********************************************

    .. note:: 通过该函数可获取蓝牙连接状态，内部通过vble_ioctl获取蓝牙连接状态，详细参考，vble_complete章节说明。其中参数：
        
        | 1、返回值：
            断连/未连接 返回0；
            已连接并且可以进行收发 返回1。

函数void rf_send_hid_key_api(int msg, u16 len)
*****************************************************

    .. note:: 该函数将小机按键对应的消息转换成hid键值，并且通过蓝牙发送到主机，内部完成转换后调用vble_slave_send_api函数发送键值。其中参数：

        | 1、int msg：按键对应的消息
        | 2、len：发送的键值长度，用户根据描述符决定。在遥控器+dongle应用中，描述符在apps/app/bsp/common/usb/device/hid.c中配置

    从机发送hid键值默认使用ATT_CHARACTERISTIC_2a4d_01_VALUE_HANDLE。可在vble_gatt.c修改。


函数void rf_controller_uninit()
**********************************************

    .. note:: 该函数函数实现关闭遥控器模式所有相关功能。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

dongle模式（主机）简介
#########################

    该应用文件位置：
        * apps/app/src/mbox_flash/remotecontrol/dongle.c
        * apps/app/src/mbox_flash/remotecontrol/rc_app.h

    用户在使用dongle模式之前，需要在app_modules.h中选择APP_DONGLE方案

        .. image:: ble_app_select.png
            :alt: "BLE应用配置 “
            :align: center
        .. centered:: BLE应用配置
    
    dongle模式在接入电脑主机USB上电之后先搜索与配对名相符的设备，连接成功后可以接收AW30遥控器发送hid命令和音频数据(opus编码格式)，hid的命令会通过USB直接转发到PC端，而音频数据会先进行解码成pcm数据，然后再通过usb_audio转发到PC端。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

dongle模式（主机）BLE相关参数配置
######################################################

    主机的BLE相关参数主要位于apps/app/bsp/common/bt_common/spp_and_le/examples/dongle/ble_dg_central.c和apps/app/bsp/common/bt_common/spp_and_le/modules/user_cfg.c

    在ble_hogp.c文件中可以配置BLE从机相关连接参数如图:

        .. image:: ble_dg_central.png
            :alt: "主机连接参数配置 “
            :align: center
        .. centered:: 主机连接参数配置

        .. image:: slave_name.png
            :alt: "配对从机名配置 “
            :align: center
        .. centered:: 配对从机名配置

    在user_cfg.c文件中可以配置BLE主机蓝牙名:

        .. image:: spp_user_cfg.png
            :alt: "主机蓝牙名配置 “
            :align: center
        .. centered:: 主机蓝牙名配置

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

dongle模式（主机）相关变量和函数说明
######################################################

变量rev_fsm_mge packet_recv
***************************************************************************
    .. note:: 该变量为接收状态机句柄，保存接收状态机中间状态和变量；

变量sound_stream_obj stream
***************************************************************************
    .. note:: 该变量为音频流数据源句柄，类似于文件句柄；

变量cbuffer_t dec_icbuf
***************************************************************************
    .. note:: 该变量为音频数据接收环形buf管理句柄，解码器从此获取数据；

变量cbuffer_t ack_cbuf
***************************************************************************
    .. note:: 该变量为通信传输队列环形buf管理句柄，用于通信中回复ack包；

变量queue_obj g_dongle_queue
***************************************************************************
    .. note:: 该变量为接收端回复发送端的START命令，发送ACK命令所使用的队列，该初始化之后可通过该队列将数据传给蓝牙；

变量audio2rf_send_mge_ops remote_ops
***************************************************************************
    .. note:: 该变量管理遥控器发送端接口，包含发送函数、状态查询函数、可发送长度查询函数；


函数void dongle_app()
*******************************************

    .. note:: dongle模式主要运行函数，dongle模式相关流程和主循环都在该函数中运行。

函数void dongle_rf_loop()
*******************************************

    .. note:: dongle模式状态机循环，目前仅用于获取从机遥控器的发送的编码消息开关对应格式的解码，并且发送ack回应包到从机。

函数void bt_usb_mic_hid_init()
********************************************

    .. note:: 该函数初始化usb_hid和usb_mic相关功能，其中会上传主机的描述符到PC，主从机的描述符一致时可以搭配遥控器实现遥控器通过hid控制电脑。

函数int vble_master_init_api(void)
*******************************************

    .. note:: dongle(主机)蓝牙初始化接口，内部会初始化蓝牙模块等相关功能。    

函数int vble_master_recv_cb_register(u32 slv_att_idx, void \*callback_fun)
******************************************************************************

    .. note:: 该函数实现将接收回调注册到特定的att_handle，实现多通路数据管理。其中参数：

        | 1、u32 slv_att_idx：att_handle序号，详细见vble_gatt.c。
        | 2、void \*callback_fun：att_handle对应的接收回调。

函数int rf_dongle_hid_callback(u8 \*rf_packet, u16 packet_len)
**************************************************************************

    .. note:: dongle模式hid键值的接收回调，将接收到的键值写入usb。其中参数：

        | 1、u8 \*rf_packet：蓝牙接收到的数据包
        | 2、packet_len：数据包长度

函数int rf_receiver_audio_callback(u8 \*rf_packet, u16 packet_len)
*****************************************************************************

    .. note:: dongle模式音频数据接收回调，将接收到的数据解析并传给解码器。其中参数：

        | 1、u8 \*rf_packet：蓝牙接收到的音频数据包
        | 2、packet_len：数据包长度