N32WB031 API函数使用说明

一路上

前言

介绍WB031几个部分（蓝牙应用模块  蓝牙安全加密模块  软件定时器 蓝牙睡眠模块 硬件延迟模块 蓝牙程序编程建议）；目的是让大家能够快速熟悉N32WB03x系列蓝牙SOC芯片的API函数的使用方式，以减少开发前期的准备时间，降低开发难度。

一、蓝牙应用模块

1.1、ns_ble_stack_init
   功能：蓝牙协议栈初始化，注册蓝牙消息回调和用户自定义消息回调。
   语法：void ns_ble_stack_init(struct ns_stack_cfg_t const* p_handler);
   参数：[in] p_handler：蓝牙应用回调函数配置,详细参考结构体ns_stack_cfg_t定义；
   返回值：无

   使用示例：      

1. struct ns_stack_cfg_t app_handler;
   
2.        app_handler.ble_msg_handler = app_ble_msg_handler; //user ble msg handler
   
3.        app_handler.user_msg_handler = app_user_msg_handler; //user custom msg handler
   
4.        ns_ble_stack_init(&app_handler);

复制代码

1.2、ns_ble_gap_init
   功能：蓝牙通用参数配置，比如蓝牙mac地址，名称，角色，连接参数等，详情参考结构体struct ns_gap_params_t的定义。
   语法：voidns_ble_gap_init(structns_gap_params_t const* p_dev_info);
   参数：[in] p_dev_info：蓝牙通用参数结构体指针。
   返回值：无

   使用示例：

1. struct ns_gap_params_t dev_info = {0};
   
2.        memcpy(dev_info.mac_addr.addr, "\x01\x02\x03\x04\x05\x06" , BD_ADDR_LEN);
   
3.        dev_info.mac_addr_type = GAPM_STATIC_ADDR;
   
4.        dev_info.appearance = 0;
   
5.        dev_info.dev_role = GAP_ROLE_PERIPHERAL;
   
6.        dev_info.dev_name_len = sizeof(CUSTOM_DEVICE_NAME)-1;
   
7.        memcpy(dev_info.dev_name, CUSTOM_DEVICE_NAME, dev_info.dev_name_len);
   
8.        dev_info.dev_conn_param.intv_min = MSECS_TO_UNIT(MIN_CONN_INTERVAL,MSECS_UNIT_1_25_MS);
   
9.        dev_info.dev_conn_param.intv_max = MSECS_TO_UNIT(MAX_CONN_INTERVAL,MSECS_UNIT_1_25_MS);
   
10.        dev_info.dev_conn_param.latency = SLAVE_LATENCY;
    
11.        dev_info.dev_conn_param.time_out = MSECS_TO_UNIT(CONN_SUP_TIMEOUT,MSECS_UNIT_10_MS);
    
12.        dev_info.conn_param_update_delay = FIRST_CONN_PARAMS_UPDATE_DELAY;
    
13.        ns_ble_gap_init(&dev_info);

复制代码

1.3、ns_ble_add_prf_func_register
   功能：注册服务（profile）添加函数，后续系统将调用注册好的服务添加函数，添加相应的服务。
   语法：boolns_ble_add_prf_func_register(ns_ble_add_prf_func_t func);
   参数：[in] func：添加服务（profile）函数, 函数实现方式参考例程函数app_dis_add_dis ；
   返回值：true：注册成功。false：注册失败。

   使用示例：

1. ns_ble_add_prf_func_register(app_dis_add_dis);

复制代码

1.4、ns_ble_prf_task_register
   功能：注册服务（profile）的子任务事件到蓝牙应用事件回调列表；
   语法：bool ns_ble_prf_task_register(struct prf_task_t *prf);
   参数：[in] prf：服务（profile）子任务结构体指针，详情参考结构体prf_task_t
   返回值：true：注册成功。false：注册失败；

   使用示例：

1. struct prf_task_t prf;
   
2.        prf.prf_task_id = TASK_ID_DISS;
   
3.        prf.prf_task_handler = &app_dis_handlers;
   
4.        ns_ble_prf_task_register(&prf);
   

复制代码

1.5、prf_get_itf_func_register
   功能：注册服务（profile）任务接口函数获取函数；
   语法：bool prf_get_itf_func_register(struct prf_get_func_t *prf);   
   参数：[in] prf：服务任务接口获取函数的指针；
   返回值：true：注册成功。false：注册失败；

   使用示例：

1. struct prf_get_func_t get_func;
   
2.        get_func.task_id = TASK_ID_DISS;
   
3.        get_func.prf_itf_get_func = diss_prf_itf_get;
   
4.        prf_get_itf_func_register(&get_func);

复制代码

1.6、ns_ble_adv_init
   功能：初始化ble蓝牙广播参数并初始化;
   语法：void ns_ble_adv_init(struct ns_adv_params_t const* p_adv_init);
   参数：[in] p_adv_init：广播初始化参数结构体指针;
   返回值：无

   使用示例：

1. struct ns_adv_params_t user_adv = {0};
   
2.             //init advertising data
   
3.            user_adv.adv_data_len = ADVERTISE_DATA_LEN;
   
4.            memcpy(user_adv.adv_data,ADVERTISE_DATA,ADVERTISE_DATA_LEN);
   
5.            user_adv.scan_rsp_data_len = ADV_SCNRSP_DATA_LEN;
   
6.            memcpy(user_adv.scan_rsp_data,ADV_SCNRSP_DATA,ADV_SCNRSP_DATA_LEN);
   
7.            user_adv.attach_appearance = false;
   
8.            user_adv.attach_name = true;
   
9.            user_adv.ex_adv_enable = false;
   
10.            user_adv.adv_phy  = PHY_1MBPS_VALUE;
    
11.            user_adv.directed_adv.enable = false;
    
12.            user_adv.fast_adv.enable = true;
    
13.            user_adv.fast_adv.duration = CUSTOM_ADV_FAST_DURATION;
    
14.            user_adv.fast_adv.adv_intv = CUSTOM_ADV_FAST_INTERVAL;
    
15.            ser_adv.slow_adv.enable = true;
    
16.            user_adv.slow_adv.duration = CUSTOM_ADV_SLOW_DURATION;
    
17.            user_adv.slow_adv.adv_intv = CUSTOM_ADV_SLOW_INTERVAL;
    
18.             user_adv.ble_adv_msg_handler = app_ble_adv_msg_handler;
    
19.            ns_ble_adv_init(&user_adv);

复制代码

1.7、ns_ble_adv_start
   功能：开始（使能）蓝牙广播
   语法：void ns_ble_adv_start(void);
   参数：无
   返回值：无

   使用示例：

1. ns_ble_adv_start();

复制代码

1.8、ns_ble_adv_stop
   功能：停止蓝牙广播
   语法：void ns_ble_adv_stop(void);   
   参数：无
   返回值：无

   使用示例：

1. ns_ble_adv_stop();

复制代码

1.9、ns_ble_adv_data_set
   功能：设置广播数据包的内容
   语法：void ns_ble_adv_data_set(uint8_t* p_dat, uint16_t len);
   参数：[in] p_dat：设置的广播包数据。[in] len：设置的广播包数据的长度；
   返回值：无

   使用示例：

1. ns_ble_adv_data_set(CUSTOM_USER_ADVERTISE_DATA,CUSTOM_USER_ADVERTISE_DATA_LEN);

复制代码

1.10、ns_ble_scan_rsp_data_set
   功能：设置广播扫描回应数据包的内容
   语法：void ns_ble_scan_rsp_data_set(uint8_t* p_dat, uint16_t len);
   参数：[in] p_dat：设置的广播扫描回应包数据。[in] len：设置的广播扫描回应包数据的长度;
   返回值：无

   使用示例：

1. ns_ble_scan_rsp_data_set(CUSTOM_USER_ADV_SCNRSP_DATA,CUSTOM_USER_ADV_SCNRSP_DATA_LEN);

复制代码

1.11、ns_ble_ex_adv_data_set
   功能：设置扩展广播数据包的内容
   语法：void ns_ble_ex_adv_data_set(uint8_t* p_dat, uint16_t len);
   参数：[in] p_dat：设置扩展广播包数据，注意这里不可以使用局部变量的指针。[in] len：设置扩展广播包数据的长度。
   返回值：无

   使用示例：

1. const staticuint8_t ex_adv[] = {"\x29\xff""1234567890123456789012345678901234567890"};
   
2.        ns_ble_ex_adv_data_set((uint8_t*) ex_adv, sizeof(ex_adv)-1);

复制代码

1.12、ns_ble_scan_init
   功能：初始化蓝牙BLE扫描功能的参数；
   语法：voidns_ble_scan_init(structns_scan_params_t *p_init);
   参数：[in] p_init：扫描功能参数结构体指针，详细参考结构体ns_scan_params_t内部定义；
   返回值：无

   使用示例：

1. struct ns_scan_params_t init = {0};
   
2.         static const uint8_t target_name[] = {"NS_RDTS_SERVER"};
   
3.         init.type = SCAN_PARAM_TYPE;
   
4.         init.dup_filt_pol = SCAN_PARAM_DUP_FILT_POL;
   
5.         init.connect_enable = SCAN_PARAM_CONNECT_EN;
   
6.         init.prop_active_enable = SCAN_PARAM_PROP_ACTIVE;
   
7.         init.scan_intv  = SCAN_PARAM_INTV;
   
8.         init.scan_wd = SCAN_PARAM_WD;
   
9.         init.duration = SCAN_PARAM_DURATION;
   
10.         init.filter_type = SCAN_FILTER_BY_NAME;
    
11.         init.filter_data = (uint8_t*)&target_name;
    
12.          ns_ble_scan_init(&init);

复制代码

1.13、ns_ble_start_scan
   功能：开启蓝牙BLE扫描功能
   语法：void ns_ble_start_scan(void);
   参数：无
   返回值：无

   使用示例：

1. ns_ble_start_scan();

复制代码

1.14、ns_ble_stop_scan
   功能：停止蓝牙BLE扫描功能
   语法：void ns_ble_stop_scan(void);
   参数：无
   返回值：无

   使用示例：

1. ns_ble_stop_scan();

复制代码

1.15、ns_ble_start_init
   功能：主机主动发起蓝牙BLE连接。注意仅供主机设备调用
   语法：void ns_ble_start_init(uint8_t *addr, uint8_t addr_type);
   参数：[in] addr：将连接的从设备地址。[in] addr_type：将连接的设备地址类型，扫描返回的信息包含地址类型
   返回值：无

   使用示例：

1. ns_ble_start_init("\x11\x11\x11\x11\x11\x11",GAPM_STATIC_ADDR);

复制代码

1.16、ns_ble_update_param
   功能：主机或从机主动发起蓝牙BLE连接参数更新请求
   语法：void ns_ble_update_param(structgapc_conn_param *conn_param);
   参数：[in] conn_param：连接参数结构体指针
   返回值：无

   使用示例：

1. struct gapc_conn_param conn_param;
   
2.          conn_param.intv_min = 12; //15ms
   
3.          conn_param.intv_max = 12; //15ms
   
4.          conn_param.latency = 5;
   
5.          conn_param.time_out = 500; //5000ms
   
6.          ns_ble_update_param(&conn_param);

复制代码

1.17、ns_ble_mtu_set  
   功能：主机或从机主动发起蓝牙BLE mtu参数更新请求。应注意用户数据包有效数据长度比MTU小3字节。
   语法：void ns_ble_mtu_set(uint16_t mtu);
   参数：[in] mtu：蓝牙BLE mtu值，最大值为517;
   返回值：无

   使用示例：

1. ns_ble_mtu_set(247); //set mtu as 247

复制代码

1.18、ns_ble_phy_set  
   功能：主机或从机主动发起蓝牙BLE PHY参数更新请求
   语法：void ns_ble_phy_set(enum gap_phy_val phy);
   参数：[in] phy：蓝牙BLE phy参数值，可选参数参考enum gap_phy_val声明。
   返回值：无

   使用示例：

1. ns_ble_phy_set(GAP_PHY_125KBPS); //set phy as coded 125kbps

复制代码

1.19、ns_ble_active_rssi  
   功能：主机或从机主动发起蓝牙BLE rssi读取请求。读取的值通过蓝牙事件回调函数的APP_BLE_GAP_RSSI_IND消息返回。
   语法：void ns_ble_active_rssi(uint32_t interval);
   参数：[in] interval：蓝牙BLE rssi读取间隙，时间单位毫秒，输入0值时只读取一次。
   返回值：无

   使用示例：

1. void app_ble_msg_handler(struct ble_msg_t const *p_ble_msg)
   
2.             {
   
3.                switch(p_ble_msg->msg_id)
   
4.                {
   
5.                    case APP_BLE_OS_READY:
   
6.                       NS_LOG_INFO("APP_BLE_OS_READY\r\n");
   
7.                    break;
   
8.                    case APP_BLE_GAP_CONNECTED:
   
9.                       app_ble_connected();
   
10.                       ns_ble_active_rssi(40); //enable rssi read every 1000ms
    
11.                    break;
    
12.                    case APP_BLE_GAP_DISCONNECTED:
    
13.                       app_ble_disconnected();
    
14.                    break;
    
15.                    caseAPP_BLE_GAP_RSSI_IND:
    
16.                        NS_LOG_INFO("rssi:%d\r\n",p_ble_msg->msg.p_gapc_rssi->rssi); //打印rssi
    
17.                    break;
    
18.                    default:
    
19.                    break;
    
20.               }
    
21.             }

复制代码

1.20、ns_ble_disconnect  
   功能：主机或从机主动发起蓝牙BLE断开连接请求。成功断开连接会通过蓝牙事件回调函数的APP_BLE_GAP_DISCONNECTED消息返回。
   语法：void ns_ble_disconnect(void);
   参数：无
   返回值：无

   使用示例：

1. ns_ble_disconnect();

复制代码

1.21、 ns_ble_dle_set
   功能：主机或从机请求设置DLE参数。如需变更，建议使用示例代码的参数。
   语法：void ns_ble_dle_set(uint16_t tx_octets, uint16_t tx_time);
   参数：[in] tx_octets：单个链路数据通道PDU的最大数据量。[in] tx_time：单个链路数据通道PDU的发送时间最大微秒数。
   返回值：无

   使用示例：

1. ns_ble_dle_set(251, 2120);

复制代码

1.22、rf_tx_power_set  
   功能：主机或从机设置射频信号发射功率;
   语法：void rf_tx_power_set(rf_tx_power_t pwr);
   参数：[in] pwr：设置的射频信号发射功率，可选参数如下结构体定义，

1. typedef enum
   
2.           {
   
3.              TX_POWER_0_DBM = 0, /* 0 dBm */
   
4.              TX_POWER_Neg2_DBM, /* -2 dBm */
   
5.              TX_POWER_Neg4_DBM, /* -4 dBm */
   
6.              TX_POWER_Neg8_DBM, /* -8 dBm */
   
7.              TX_POWER_Neg15_DBM, /* -12 dBm */
   
8.              TX_POWER_Neg20_DBM, /* -20 dBm */
   
9.              TX_POWER_Pos2_DBM, /* +2 dBm */
   
10.              TX_POWER_Pos3_DBM, /* +3 dBm */
    
11.              TX_POWER_Pos4_DBM, /* +4 dBm */
    
12.              TX_POWER_Pos6_DBM, /* +6 dBm */
    
13.           }rf_tx_power_t;

复制代码

  返回值：无

   使用示例：

1. rf_tx_power_set(TX_POWER_Pos4_DBM);

复制代码

二、安全加密模块

2.1、ns_sec_init   
   功能：初始化蓝牙安全加密模块。
   语法：void ns_sec_init(struct ns_sec_init_t const* init);
   参数：[in] init：蓝牙安全模块初始化参数结构体指针。详情参考结构体ns_sec_init_t内部定义。
   返回：无

   使用示例：

1. struct ns_sec_init_t sec_init={0};
   
2.        sec_init.rand_pin_enable = false;
   
3.        sec_init.pin_code = 123456;
   
4.        sec_init.pairing_feat.auth = ( SEC_PARAM_BOND | (SEC_PARAM_MITM<<2) | (SEC_PARAM_LESC<3) |
   
5.                            (SEC_PARAM_KEYPRESS<<4) );
   
6.        sec_init.pairing_feat.iocap = SEC_PARAM_IO_CAPABILITIES;
   
7.        sec_init.pairing_feat.key_size = SEC_PARAM_KEY_SIZE;
   
8.        sec_init.pairing_feat.oob = SEC_PARAM_OOB;
   
9.        sec_init.pairing_feat.ikey_dist = SEC_PARAM_IKEY;
   
10.        sec_init.pairing_feat.rkey_dist = SEC_PARAM_RKEY;
    
11.        sec_init.pairing_feat.sec_req = SEC_PARAM_SEC_MODE_LEVEL;
    
12.        sec_init.bond_enable= BOND_STORE_ENABLE;
    
13.        sec_init.bond_db_addr = BOND_DATA_BASE_ADDR;
    
14.        sec_init.bond_max_peer = MAX_BOND_PEER;
    
15.        sec_init.bond_sync_delay = 5000;
    
16.        sec_init.ns_sec_msg_handler = NULL;
    
17.        ns_sec_init(&sec_init)；

复制代码

2.2、ns_sec_get_bond_status   
   功能：返回是否已绑定了的状态。
   语法：bool ns_sec_get_bond_status(void);
   参数：无
   返回：ture：已绑定。false：未绑定。

   示例：

1. bool bond_status = ns_sec_get_bond_status();

复制代码

2.3、ns_sec_get_iocap   
   功能：返回设备的接口能力参数，供蓝牙相关库调用，一般用户代码不需要调用。
   语法：uint8_t ns_sec_get_iocap(void);   
   参数：无
   返回：设备的接口能力参数，是函数ns_sec_init初始化设置进去的值。

   示例：

1. uint8_t io_cap = ns_sec_get_iocap();

复制代码

2.4、ns_sec_bond_db_erase_all   
   功能：擦除所有已绑定的设备。因为擦除flash会阻塞运行，建议不要在已连接状态下执行，必须影响连接的可能性。
   语法：void ns_sec_bond_db_erase_all(void);
   参数：无
   返回：无

   示例：

1. ns_sec_bond_db_erase_all();

复制代码

三、软件定时器

3.1、ns_timer_create            
   功能：创建一个软件定时器，在延迟delay毫秒数后调用fn这个函数。如需循环定时器可以在回调处理处再次创建一个定时器。注意需要在协议栈初始化好后，即APP_BLE_OS_READY消息发出之后才能使用该API函数。   语法：timer_hnd_t ns_timer_create(const uint32_t delay, timer_callback_t fn);
   参数：delay:延迟的时间,单位是1毫秒。
       fn：延迟delay毫秒后的回调函数。
   返回值：定时器的id

   示例：

1. timer_hnd_t timer_id = ns_timer_create(1000,my_timer_callback);

复制代码

3.2、ns_timer_modify   
   功能：修改指定一个定时器的延时时间                                   
   语法：timer_hnd_t ns_timer_modify(const timer_hnd_t timer_id,const uint32_t delay);
   参数：timer_id:需要修改的定时器id
            delay：修改后的延迟时间，单位为1毫秒
   返回值：修改后的定时器id

   示例：

1. timer_id= ns_timer_modify(timer_id,2000);

复制代码

3.3、ns_timer_cancel   
   功能：取消指定的一个定时器
   语法：void ns_timer_cancel(const timer_hnd_t timer_id);
   参数：timer_id:需要取消的定时器id
   返回值：无

   示例：

1. ns_timer_cancel(timer_id);

复制代码

3.4、ns_timer_cancel_all   
   功能：取消所有已经创建的定时器
   语法：void ns_timer_cancel_all(void);
   参数：无
   返回值：无

   示例：

1. ns_timer_cancel_all();

复制代码

四、蓝牙睡眠模块

4.1、ns_sleep
   功能：蓝牙睡眠功能进入函数，函数会基于蓝牙协议栈工作状态，如果没有需要执行的任务则自动进入睡眠状态，在定时任务或者硬件中断唤醒后恢复系统状态。一般调用于main函数主循环，调度函数rwip_schedule后面。
   语法：void ns_sleep(void);
   参数：无
   返回值：无

   示例：

1. ns_sleep();

复制代码

4.2、ns_sleep_lock_acquire
   功能：蓝牙睡眠模式锁请求，即申请系统不进入睡眠模式。比如开启某些高速外设（如串口）不希望系统进入睡眠而关掉它，可以通过请求睡眠模式锁禁止系统进入睡眠。
   语法：uint8_t ns_sleep_lock_acquire(void);
   参数：无
   返回值：true：请求锁成功。false：请求锁失败。

   示例：

1. if(ns_sleep_lock_acquire())
   
2.          {
   
3.             //require sleep lock success
   
4.          }

复制代码

4.3、ns_sleep_lock_release
   功能：蓝牙睡眠模式锁释放，当所有的睡眠模式锁释放后，系统可以在没有任务挂起时将进入睡眠模式。
   语法：uint8_t ns_sleep_lock_release(void);
   参数：无
   返回值：true：释放锁成功。false：释放锁失败，目前没有可以释放的锁。

   示例：

1. if(ns_sleep_lock_release())
   
2.          {
   
3.            //release sleep lock success
   
4.          }

复制代码

4.4、进入和退出睡眠模式的虚函数
   __weak void app_sleep_prepare_proc(void);
   功能：预设的虚函数，用于给用户重新实现进入睡眠之前需要做任务。
   __weak void app_sleep_resume_proc(void)
   功能：用于给用户重新实现睡眠唤醒之后需要做任务，比如可以重新初始化因为睡眠关闭的硬件外设，例如使能GPIO的时钟。

五、硬件延迟模块

  5.1、delay_cycles      
   功能：延迟等待指定数量的cycles返回;    语法：void delay_cycles(uint32_t ui32Cycles);
   参数：ui32Cycles：需要等待的cycles数量，一个cycles的时间约为(10/110) 微秒;
   返回：无

   示例：

1. delay_cycles(1000);

复制代码

  5.2、delay_n_us
   功能：延迟等待指定数量的微秒
   语法：void delay_n_us(uint32_t val);
   参数：val：需要等待的微秒数;
   返回：无

   示例：

1. delay_n_us(1000);

复制代码

  5.3、delay_n_10us      
   功能：延迟等待指定数量的10微秒
   语法：void delay_n_10us(uint32_t val);
   参数：val：需要等待的10微秒数;
   返回：无

   示例：

1. delay_n_10us(1000);

复制代码

  5.4、delay_n_100us
   功能：延迟等待指定数量的100微秒
   语法：void delay_n_100us(uint32_t val);
   参数：val：需要等待的100微秒数
   返回：无

   示例：

1. delay_n_100us(1000);

复制代码

  5.5、delay_n_ms
   功能：延迟等待指定数量的毫秒
   语法：void delay_n_ms(uint32_t val);
   参数：val：需要等待的毫秒数
   返回：无

   示例：

1. delay_n_ms(1000);

复制代码

六、蓝牙程序编程建议

6.1、不要连续执行占用时间太长的代码，将会阻碍蓝牙消息处理。建议尽可实现用户代码粹片化，每个任务消息或轮询只占用小片时间。

6.2、不要在中断服务函数执行太长时间，避免阻碍蓝牙消息处理，建议通过挂起消息，定时器或者标志位的方式在任务或轮询里实现逻辑代码。

6.3、不要在中断服务函数调用硬件外设。睡眠后如果中断事件挂起，中断服务函数将会在app_sleep_resume_proc之前调用，外设在唤醒后还没初始化，如在中断服务函数调用硬件外设，则会因为外设未初始化而导致出错。

6.4、包含蓝牙的工程中断服务函数注意需要通过ModuleIrqRegister函数注册，并且用户代码的中断优先级只能使用2和3（蓝牙协议栈使用0和1）。

6.5、注意进入低功耗sleep模式下，高速外设（如USART）将被关闭，需要在唤醒后程序初始化才能使用。

6.6、用户的逻辑代码推荐在任务回调函数里面实现，可以是消息事件回调或者定时任务回调。