N32WB031 API函数使用说明
<div align="left">此贴目的是让使用者能够快速熟悉N32WB03x系列蓝牙SOC芯片的API函数的使用方式，以减少开发前期的准备时间，降低开发难度。</div><p> </p>
<div align="left">包含以下几个小节：蓝牙应用模块 蓝牙安全加密模块 软件定时器 蓝牙睡眠模块 硬件延迟模块 蓝牙程序编程建议</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
</p>
<div align="left">一、蓝牙应用模块</div>
<p> </p>
<div align="left">1.1、ns_ble_stack_init</div>
<div align="left"> 功能：蓝牙协议栈初始化，注册蓝牙消息回调和用户自定义消息回调。</div>
<div align="left"> 语法：void ns_ble_stack_init(struct ns_stack_cfg_t const* p_handler);</div>
<div align="left"> 参数： p_handler：蓝牙应用回调函数配置,详细参考结构体ns_stack_cfg_t定义；</div>
<div align="left"> 返回值：无</div>
<div align="left"> 使用示例： </div>
<div align="left"> struct ns_stack_cfg_t app_handler;</div>
<div align="left"> app_handler.ble_msg_handler = app_ble_msg_handler; //user ble msg handler</div>
<div align="left"> app_handler.user_msg_handler = app_user_msg_handler; //user custom msg handler</div>
<div align="left"> ns_ble_stack_init(&app_handler);</div>
<div align="left"> </div>
<div align="left">1.2、ns_ble_gap_init</div>
<div align="left"> 功能：蓝牙通用参数配置，比如蓝牙mac地址，名称，角色，连接参数等，详情参考结构体struct ns_gap_params_t的定义。</div>
<div align="left"> 语法：voidns_ble_gap_init(structns_gap_params_t const* p_dev_info);</div>
<div align="left"> 参数： p_dev_info：蓝牙通用参数结构体指针。</div>
<div align="left"> 返回值：无</div>
<div align="left"> 使用示例：</div>
<div align="left"> struct ns_gap_params_t dev_info = {0};</div>
<div align="left"> memcpy(dev_info.mac_addr.addr, "\x01\x02\x03\x04\x05\x06" , BD_ADDR_LEN);</div>
<div align="left"> dev_info.mac_addr_type = GAPM_STATIC_ADDR;</div>
<div align="left"> dev_info.appearance = 0;</div>
<div align="left"> dev_info.dev_role = GAP_ROLE_PERIPHERAL;</div>
<div align="left"> dev_info.dev_name_len = sizeof(CUSTOM_DEVICE_NAME)-1;</div>
<div align="left"> memcpy(dev_info.dev_name, CUSTOM_DEVICE_NAME, dev_info.dev_name_len);</div>
<div align="left"> dev_info.dev_conn_param.intv_min = MSECS_TO_UNIT(MIN_CONN_INTERVAL,MSECS_UNIT_1_25_MS);</div>
<div align="left"> dev_info.dev_conn_param.intv_max = MSECS_TO_UNIT(MAX_CONN_INTERVAL,MSECS_UNIT_1_25_MS);</div>
<div align="left"> dev_info.dev_conn_param.latency = SLAVE_LATENCY;</div>
<div align="left"> dev_info.dev_conn_param.time_out = MSECS_TO_UNIT(CONN_SUP_TIMEOUT,MSECS_UNIT_10_MS);</div>
<div align="left"> dev_info.conn_param_update_delay = FIRST_CONN_PARAMS_UPDATE_DELAY;</div>
<div align="left"> ns_ble_gap_init(&dev_info);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.3、ns_ble_add_prf_func_register<br style="overflow-wrap:break-word; word-break:break-all" />
功能：注册服务（profile）添加函数，后续系统将调用注册好的服务添加函数，添加相应的服务。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：boolns_ble_add_prf_func_register(ns_ble_add_prf_func_t func);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： func：添加服务（profile）函数, 函数实现方式参考例程函数app_dis_add_dis ；<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：true：注册成功。false：注册失败。<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例： ns_ble_add_prf_func_register(app_dis_add_dis);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.4、ns_ble_prf_task_register<br style="overflow-wrap:break-word; word-break:break-all" />
功能：注册服务（profile）的子任务事件到蓝牙应用事件回调列表；<br style="overflow-wrap:break-word; word-break:break-all" />
语法：bool ns_ble_prf_task_register(struct prf_task_t *prf);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： prf：服务（profile）子任务结构体指针，详情参考结构体prf_task_t<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：true：注册成功。false：注册失败；<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
struct prf_task_t prf;</p>
<div align="left"> prf.prf_task_id = TASK_ID_DISS;</div>
<div align="left"> prf.prf_task_handler = &app_dis_handlers;</div>
<div align="left"> ns_ble_prf_task_register(&prf);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.5、prf_get_itf_func_register<br style="overflow-wrap:break-word; word-break:break-all" />
功能：注册服务（profile）任务接口函数获取函数；<br style="overflow-wrap:break-word; word-break:break-all" />
语法：bool prf_get_itf_func_register(struct prf_get_func_t *prf); <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数： prf：服务任务接口获取函数的指针；<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：true：注册成功。false：注册失败；<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
struct prf_get_func_t get_func;</p>
<div align="left"> get_func.task_id = TASK_ID_DISS;</div>
<div align="left"> get_func.prf_itf_get_func = diss_prf_itf_get;</div>
<div align="left"> prf_get_itf_func_register(&get_func);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.6、ns_ble_adv_init<br style="overflow-wrap:break-word; word-break:break-all" />
功能：初始化ble蓝牙广播参数并初始化;<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_adv_init(struct ns_adv_params_t const* p_adv_init);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： p_adv_init：广播初始化参数结构体指针;<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
struct ns_adv_params_t user_adv = {0};</p>
<div align="left"> //init advertising data</div>
<div align="left"> user_adv.adv_data_len = ADVERTISE_DATA_LEN;</div>
<div align="left"> memcpy(user_adv.adv_data,ADVERTISE_DATA,ADVERTISE_DATA_LEN);</div>
<div align="left"> user_adv.scan_rsp_data_len = ADV_SCNRSP_DATA_LEN;</div>
<div align="left"> memcpy(user_adv.scan_rsp_data,ADV_SCNRSP_DATA,ADV_SCNRSP_DATA_LEN);</div>
<div align="left"> user_adv.attach_appearance = false;</div>
<div align="left"> user_adv.attach_name = true;</div>
<div align="left"> user_adv.ex_adv_enable = false;</div>
<div align="left"> user_adv.adv_phy = PHY_1MBPS_VALUE;</div>
<div align="left"> user_adv.directed_adv.enable = false;</div>
<div align="left"> user_adv.fast_adv.enable = true;</div>
<div align="left"> user_adv.fast_adv.duration = CUSTOM_ADV_FAST_DURATION;</div>
<div align="left"> user_adv.fast_adv.adv_intv = CUSTOM_ADV_FAST_INTERVAL;</div>
<div align="left"> ser_adv.slow_adv.enable = true;</div>
<div align="left"> user_adv.slow_adv.duration = CUSTOM_ADV_SLOW_DURATION;</div>
<div align="left"> user_adv.slow_adv.adv_intv = CUSTOM_ADV_SLOW_INTERVAL;</div>
<div align="left"> user_adv.ble_adv_msg_handler = app_ble_adv_msg_handler;</div>
<div align="left"> ns_ble_adv_init(&user_adv);</div>
<div align="left"> </div>
<p>1.7、ns_ble_adv_start<br style="overflow-wrap:break-word; word-break:break-all" />
功能：开始（使能）蓝牙广播<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_adv_start(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_adv_start();<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.8、ns_ble_adv_stop<br style="overflow-wrap:break-word; word-break:break-all" />
功能：停止蓝牙广播<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_adv_stop(void); <br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_adv_stop();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.9、ns_ble_adv_data_set<br style="overflow-wrap:break-word; word-break:break-all" />
功能：设置广播数据包的内容<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_adv_data_set(uint8_t* p_dat, uint16_t len);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： p_dat：设置的广播包数据。 len：设置的广播包数据的长度；<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_adv_data_set(CUSTOM_USER_ADVERTISE_DATA,CUSTOM_USER_ADVERTISE_DATA_LEN);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.10、ns_ble_scan_rsp_data_set<br style="overflow-wrap:break-word; word-break:break-all" />
功能：设置广播扫描回应数据包的内容<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_scan_rsp_data_set(uint8_t* p_dat, uint16_t len);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： p_dat：设置的广播扫描回应包数据。 len：设置的广播扫描回应包数据的长度;<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_scan_rsp_data_set(CUSTOM_USER_ADV_SCNRSP_DATA,CUSTOM_USER_ADV_SCNRSP_DATA_LEN);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.11、ns_ble_ex_adv_data_set<br style="overflow-wrap:break-word; word-break:break-all" />
功能：设置扩展广播数据包的内容<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_ex_adv_data_set(uint8_t* p_dat, uint16_t len);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： p_dat：设置扩展广播包数据，注意这里不可以使用局部变量的指针。 len：设置扩展广播包数据的长度。<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
const staticuint8_t ex_adv[] = {"\x29\xff""1234567890123456789012345678901234567890"};</p>
<div align="left"> ns_ble_ex_adv_data_set((uint8_t*) ex_adv, sizeof(ex_adv)-1);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.12、ns_ble_scan_init<br style="overflow-wrap:break-word; word-break:break-all" />
功能：初始化蓝牙BLE扫描功能的参数；<br style="overflow-wrap:break-word; word-break:break-all" />
语法：voidns_ble_scan_init(structns_scan_params_t *p_init);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： p_init：扫描功能参数结构体指针，详细参考结构体ns_scan_params_t内部定义；<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：</p>
<div align="left"> struct ns_scan_params_t init = {0};</div>
<div align="left"> static const uint8_t target_name[] = {"NS_RDTS_SERVER"};</div>
<div align="left"> init.type = SCAN_PARAM_TYPE;</div>
<div align="left"> init.dup_filt_pol = SCAN_PARAM_DUP_FILT_POL;</div>
<div align="left"> init.connect_enable = SCAN_PARAM_CONNECT_EN;</div>
<div align="left"> init.prop_active_enable = SCAN_PARAM_PROP_ACTIVE;</div>
<div align="left"> init.scan_intv = SCAN_PARAM_INTV;</div>
<div align="left"> init.scan_wd = SCAN_PARAM_WD;</div>
<div align="left"> init.duration = SCAN_PARAM_DURATION;</div>
<div align="left"> init.filter_type = SCAN_FILTER_BY_NAME;</div>
<div align="left"> init.filter_data = (uint8_t*)&target_name;</div>
<div align="left"> ns_ble_scan_init(&init);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.13、ns_ble_start_scan<br style="overflow-wrap:break-word; word-break:break-all" />
功能：开启蓝牙BLE扫描功能<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_start_scan(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_start_scan();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.14、ns_ble_stop_scan<br style="overflow-wrap:break-word; word-break:break-all" />
功能：停止蓝牙BLE扫描功能<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_stop_scan(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_stop_scan();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.15、ns_ble_start_init<br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机主动发起蓝牙BLE连接。注意仅供主机设备调用<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_start_init(uint8_t *addr, uint8_t addr_type);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： addr：将连接的从设备地址。 addr_type：将连接的设备地址类型，扫描返回的信息包含地址类型<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_start_init("\x11\x11\x11\x11\x11\x11",GAPM_STATIC_ADDR);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.16、ns_ble_update_param<br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机主动发起蓝牙BLE连接参数更新请求<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_update_param(structgapc_conn_param *conn_param);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： conn_param：连接参数结构体指针<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
struct gapc_conn_param conn_param;</p>
<div align="left"> conn_param.intv_min = 12; //15ms</div>
<div align="left"> conn_param.intv_max = 12; //15ms</div>
<div align="left"> conn_param.latency = 5;</div>
<div align="left"> conn_param.time_out = 500; //5000ms</div>
<div align="left"> ns_ble_update_param(&conn_param);</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.17、ns_ble_mtu_set <br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机主动发起蓝牙BLE mtu参数更新请求。应注意用户数据包有效数据长度比MTU小3字节。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_mtu_set(uint16_t mtu);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： mtu：蓝牙BLE mtu值，最大值为517;<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_mtu_set(247); //set mtu as 247<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.18、ns_ble_phy_set <br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机主动发起蓝牙BLE PHY参数更新请求<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_phy_set(enum gap_phy_val phy);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： phy：蓝牙BLE phy参数值，可选参数参考enum gap_phy_val声明。<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_phy_set(GAP_PHY_125KBPS); //set phy as coded 125kbps<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.19、ns_ble_active_rssi <br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机主动发起蓝牙BLE rssi读取请求。读取的值通过蓝牙事件回调函数的APP_BLE_GAP_RSSI_IND消息返回。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_active_rssi(uint32_t interval);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： interval：蓝牙BLE rssi读取间隙，时间单位毫秒，输入0值时只读取一次。<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
void app_ble_msg_handler(struct ble_msg_t const *p_ble_msg)</p>
<div align="left"> {</div>
<div align="left"> switch(p_ble_msg->msg_id)</div>
<div align="left"> {</div>
<div align="left"> case APP_BLE_OS_READY:</div>
<div align="left"> NS_LOG_INFO("APP_BLE_OS_READY\r\n");</div>
<div align="left"> break;</div>
<div align="left"> case APP_BLE_GAP_CONNECTED:</div>
<div align="left"> app_ble_connected();</div>
<div align="left"> ns_ble_active_rssi(40); //enable rssi read every 1000ms</div>
<div align="left"> break;</div>
<div align="left"> case APP_BLE_GAP_DISCONNECTED:</div>
<div align="left"> app_ble_disconnected();</div>
<div align="left"> break;</div>
<div align="left"> caseAPP_BLE_GAP_RSSI_IND:</div>
<div align="left"> NS_LOG_INFO("rssi:%d\r\n",p_ble_msg->msg.p_gapc_rssi->rssi); //打印rssi</div>
<div align="left"> break;</div>
<div align="left"> default:</div>
<div align="left"> break;</div>
<div align="left"> }</div>
<div align="left"> }</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
1.20、ns_ble_disconnect <br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机主动发起蓝牙BLE断开连接请求。成功断开连接会通过蓝牙事件回调函数的APP_BLE_GAP_DISCONNECTED消息返回。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_disconnect(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_disconnect();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.21、 ns_ble_dle_set<br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机请求设置DLE参数。如需变更，建议使用示例代码的参数。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_ble_dle_set(uint16_t tx_octets, uint16_t tx_time);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： tx_octets：单个链路数据通道PDU的最大数据量。 tx_time：单个链路数据通道PDU的发送时间最大微秒数。<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_ble_dle_set(251, 2120);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
1.22、rf_tx_power_set <br style="overflow-wrap:break-word; word-break:break-all" />
功能：主机或从机设置射频信号发射功率;<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void rf_tx_power_set(rf_tx_power_t pwr);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： pwr：设置的射频信号发射功率，可选参数如下结构体定义，<br style="overflow-wrap:break-word; word-break:break-all" />
typedef enum</p>
<div align="left"> {</div>
<div align="left"> TX_POWER_0_DBM = 0, /* 0 dBm */</div>
<div align="left"> TX_POWER_Neg2_DBM, /* -2 dBm */</div>
<div align="left"> TX_POWER_Neg4_DBM, /* -4 dBm */</div>
<div align="left"> TX_POWER_Neg8_DBM, /* -8 dBm */</div>
<div align="left"> TX_POWER_Neg15_DBM, /* -12 dBm */</div>
<div align="left"> TX_POWER_Neg20_DBM, /* -20 dBm */</div>
<div align="left"> TX_POWER_Pos2_DBM, /* +2 dBm */</div>
<div align="left"> TX_POWER_Pos3_DBM, /* +3 dBm */</div>
<div align="left"> TX_POWER_Pos4_DBM, /* +4 dBm */</div>
<div align="left"> TX_POWER_Pos6_DBM, /* +6 dBm */</div>
<div align="left"> }rf_tx_power_t;</div>
<p> 返回值：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
rf_tx_power_set(TX_POWER_Pos4_DBM);<br style="overflow-wrap:break-word; word-break:break-all" />
</p>
<div align="left">二、安全加密模块</div>
<p>2.1、ns_sec_init <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：初始化蓝牙安全加密模块。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_sec_init(struct ns_sec_init_t const* init);<br style="overflow-wrap:break-word; word-break:break-all" />
参数： init：蓝牙安全模块初始化参数结构体指针。详情参考结构体ns_sec_init_t内部定义。<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all" />
使用示例：<br style="overflow-wrap:break-word; word-break:break-all" />
struct ns_sec_init_t sec_init={0};</p>
<div align="left"> sec_init.rand_pin_enable = false;</div>
<div align="left"> sec_init.pin_code = 123456;</div>
<div align="left"> sec_init.pairing_feat.auth = ( SEC_PARAM_BOND | (SEC_PARAM_MITM<<2) | (SEC_PARAM_LESC<3) |</div>
<div align="left"> (SEC_PARAM_KEYPRESS<<4) );</div>
<div align="left"> sec_init.pairing_feat.iocap = SEC_PARAM_IO_CAPABILITIES;</div>
<div align="left"> sec_init.pairing_feat.key_size = SEC_PARAM_KEY_SIZE;</div>
<div align="left"> sec_init.pairing_feat.oob = SEC_PARAM_OOB;</div>
<div align="left"> sec_init.pairing_feat.ikey_dist = SEC_PARAM_IKEY;</div>
<div align="left"> sec_init.pairing_feat.rkey_dist = SEC_PARAM_RKEY;</div>
<div align="left"> sec_init.pairing_feat.sec_req = SEC_PARAM_SEC_MODE_LEVEL;</div>
<div align="left"> sec_init.bond_enable= BOND_STORE_ENABLE;</div>
<div align="left"> sec_init.bond_db_addr = BOND_DATA_BASE_ADDR;</div>
<div align="left"> sec_init.bond_max_peer = MAX_BOND_PEER;</div>
<div align="left"> sec_init.bond_sync_delay = 5000;</div>
<div align="left"> sec_init.ns_sec_msg_handler = NULL;</div>
<div align="left"> ns_sec_init(&sec_init)；</div>
<p><br style="overflow-wrap:break-word; word-break:break-all" />
2.2、ns_sec_get_bond_status <br style="overflow-wrap:break-word; word-break:break-all" />
功能：返回是否已绑定了的状态。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：bool ns_sec_get_bond_status(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回：ture：已绑定。false：未绑定。<br style="overflow-wrap:break-word; word-break:break-all" />
示例：<br style="overflow-wrap:break-word; word-break:break-all" />
bool bond_status = ns_sec_get_bond_status();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
2.3、ns_sec_get_iocap <br style="overflow-wrap:break-word; word-break:break-all" />
功能：返回设备的接口能力参数，供蓝牙相关库调用，一般用户代码不需要调用。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：uint8_t ns_sec_get_iocap(void); <br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回：设备的接口能力参数，是函数ns_sec_init初始化设置进去的值。<br style="overflow-wrap:break-word; word-break:break-all" />
示例：<br style="overflow-wrap:break-word; word-break:break-all" />
uint8_t io_cap = ns_sec_get_iocap();<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
2.4、ns_sec_bond_db_erase_all <br style="overflow-wrap:break-word; word-break:break-all" />
功能：擦除所有已绑定的设备。因为擦除flash会阻塞运行，建议不要在已连接状态下执行，必须影响连接的可能性。<br style="overflow-wrap:break-word; word-break:break-all" />
语法：void ns_sec_bond_db_erase_all(void);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all" />
示例：<br style="overflow-wrap:break-word; word-break:break-all" />
ns_sec_bond_db_erase_all();<br style="overflow-wrap:break-word; word-break:break-all" />
</p>
<div align="left">三、软件定时器</div>
<p>3.1、ns_timer_create <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：创建一个软件定时器，在延迟delay毫秒数后调用fn这个函数。如需循环定时器可以在回调处理处再次创建 一个定时器。注意需要在协议栈初始化好后，即APP_BLE_OS_READY消息发出之后才能使用该API函数。 语法：timer_hnd_t ns_timer_create(const uint32_t delay, timer_callback_t fn);<br style="overflow-wrap:break-word; word-break:break-all" />
参数：delay:延迟的时间,单位是1毫秒。<br style="overflow-wrap:break-word; word-break:break-all" />
fn：延迟delay毫秒后的回调函数。<br style="overflow-wrap:break-word; word-break:break-all" />
返回值：定时器的id<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：timer_hnd_t timer_id = ns_timer_create(1000,my_timer_callback);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
3.2、ns_timer_modify <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：修改指定一个定时器的延时时间 <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：timer_hnd_t ns_timer_modify(const timer_hnd_t timer_id,const uint32_t delay);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：timer_id:需要修改的定时器id<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
delay：修改后的延迟时间，单位为1毫秒<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：修改后的定时器id<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：timer_id= ns_timer_modify(timer_id,2000);<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
3.3、ns_timer_cancel <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：取消指定的一个定时器<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void ns_timer_cancel(const timer_hnd_t timer_id);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：timer_id:需要取消的定时器id<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：ns_timer_cancel(timer_id);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
3.4、ns_timer_cancel_all <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：取消所有已经创建的定时器<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void ns_timer_cancel_all(void);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：ns_timer_cancel_all();<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
</p>
<div align="left">四、蓝牙睡眠模块</div>
<div align="left">4.1、ns_sleep</div>
<div align="left"> 功能：蓝牙睡眠功能进入函数，函数会基于蓝牙协议栈工作状态，如果没有需要执行的任务则自动进入睡眠状态，</div>
<div align="left"> 在定时任务或者硬件中断唤醒后恢复系统状态。一般调用于main函数主循环，调度函数rwip_schedule后面。</div>
<div align="left"> 语法：void ns_sleep(void);</div>
<p> 参数：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：ns_sleep();</p>
<div align="left">4.2、ns_sleep_lock_acquire</div>
<div align="left"> 功能：蓝牙睡眠模式锁请求，即申请系统不进入睡眠模式。比如开启某些高速外设（如串口）不希望系统进入睡眠而关掉</div>
<div align="left"> 它，可以通过请求睡眠模式锁禁止系统进入睡眠。</div>
<div align="left"> 语法：uint8_t ns_sleep_lock_acquire(void);</div>
<p> 参数：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：true：请求锁成功。false：请求锁失败。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：</p>
<div align="left"> if(ns_sleep_lock_acquire())</div>
<div align="left"> {</div>
<div align="left"> //require sleep lock success</div>
<div align="left"> }</div>
<p> </p>
<div align="left">4.3、ns_sleep_lock_release</div>
<div align="left"> 功能：蓝牙睡眠模式锁释放，当所有的睡眠模式锁释放后，系统可以在没有任务挂起时将进入睡眠模式。</div>
<div align="left"> 语法：uint8_t ns_sleep_lock_release(void);</div>
<p> 参数：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
返回值：true：释放锁成功。false：释放锁失败，目前没有可以释放的锁。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：</p>
<div align="left"> if(ns_sleep_lock_release())</div>
<div align="left"> {</div>
<div align="left"> //release sleep lock success</div>
<div align="left"> }</div>
<div align="left"> </div>
<div align="left">4.4、进入和退出睡眠模式的虚函数</div>
<div align="left"> __weak void app_sleep_prepare_proc(void);</div>
<div align="left"> 功能：预设的虚函数，用于给用户重新实现进入睡眠之前需要做任务。</div>
<div align="left"> __weak void app_sleep_resume_proc(void)</div>
<p> 功能：用于给用户重新实现睡眠唤醒之后需要做任务，比如可以重新初始化因为睡眠关闭的硬件外设，例如使能GPIO的时钟。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
</p>
<div align="left">五、硬件延迟模块</div>
<p> 5.1、delay_cycles <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：延迟等待指定数量的cycles返回; 语法：void delay_cycles(uint32_t ui32Cycles);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：ui32Cycles：需要等待的cycles数量，一个cycles的时间约为(10/110) 微秒;<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：delay_cycles(1000);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
5.2、delay_n_us<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：延迟等待指定数量的微秒<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void delay_n_us(uint32_t val);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：val：需要等待的微秒数;<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：delay_n_us(1000);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
5.3、delay_n_10us <br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：延迟等待指定数量的10微秒<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void delay_n_10us(uint32_t val);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：val：需要等待的10微秒数;<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：delay_n_10us(1000);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
5.4、delay_n_100us<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：延迟等待指定数量的100微秒<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void delay_n_100us(uint32_t val);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：val：需要等待的100微秒数<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：delay_n_100us(1000);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
5.5、delay_n_ms<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
功能：延迟等待指定数量的毫秒<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
语法：void delay_n_ms(uint32_t val);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
参数：val：需要等待的毫秒数<br style="overflow-wrap:break-word; word-break:break-all" />
返回：无<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
示例：delay_n_ms(1000);<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
</p>
<div align="left">六、蓝牙程序编程建议</div>
<p> 6.1、不要连续执行占用时间太长的代码，将会阻碍蓝牙消息处理。建议尽可实现用户代码粹片化，每个任<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
务消息或轮询只占用小片时间。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
6.2、不要在中断服务函数执行太长时间，避免阻碍蓝牙消息处理，建议通过挂起消息，定时器或者标志位<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
的方式在任务或轮询里实现逻辑代码。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
6.3、不要在中断服务函数调用硬件外设。睡眠后如果中断事件挂起，中断<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
服务函数将会在app_sleep_resume_proc之前调用，外设在唤醒后还没初始化，如在中断服务函<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
数调用硬件外设，则会因为外设未初始化而导致出错。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
6.4、包含蓝牙的工程中断服务函数注意需要通过ModuleIrqRegister函数注册，并且用户代码的中断优先级<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
只能使用2和3（蓝牙协议栈使用0和1）。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
6.5、注意进入低功耗sleep模式下，高速外设（如USART）将被关闭，需要在唤醒后程序初始化才能使用。<br style="overflow-wrap:break-word; word-break:break-all; color:#444444;Microsoft Yahei", Simsun; white-space:normal; background-color:#f2f9fd" />
6.6、用户的逻辑代码推荐在任务回调函数里面实现，可以是消息事件回调或者定时任务回调。<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
<br style="overflow-wrap:break-word; word-break:break-all" />
</p>
<p>N32WB031 API函数这么多，看晕了</p>
火辣西米秀 发表于 2023-4-26 22:14
N32WB031 API函数这么多，看晕了
<p>说实在话，我也还没有学完，放上来，可以查询。官方会有示例，按示例逐条学习就行了。不必要全部记住，只要能查就行了。</p>
<p>楼主，您知道N32WB031的蓝牙从机模式最多支持多少主机吗？我看例程是三个，可以更多吗？</p>
页:
[1]