N32WB031 API函数使用说明

N32BLE 发表于 2022-6-10 07:41

本帖最后由 N32BLE 于 2022-7-15 08:57 编辑

#技术资源#
此贴目的是让使用者能够快速熟悉N32WB03x系列蓝牙SOC芯片的API函数的使用方式，以减少开发前期的准备时间，降低开发难度。
包含以下几个小节：蓝牙应用模块蓝牙安全加密模块软件定时器蓝牙睡眠模块硬件延迟模块蓝牙程序编程建议

一、蓝牙应用模块
1.1、ns_ble_stack_init 功能：蓝牙协议栈初始化，注册蓝牙消息回调和用户自定义消息回调。语法：void ns_ble_stack_init(struct ns_stack_cfg_t const* p_handler); 参数： p_handler：蓝牙应用回调函数配置,详细参考结构体ns_stack_cfg_t定义；返回值：无使用示例：          struct ns_stack_cfg_t app_handler;    app_handler.ble_msg_handler = app_ble_msg_handler; //user ble msg handler    app_handler.user_msg_handler = app_user_msg_handler; //user custom msg handler    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); 参数： p_dev_info：蓝牙通用参数结构体指针。返回值：无使用示例：    struct ns_gap_params_t dev_info = {0};    memcpy(dev_info.mac_addr.addr, "\x01\x02\x03\x04\x05\x06" , BD_ADDR_LEN);    dev_info.mac_addr_type = GAPM_STATIC_ADDR;    dev_info.appearance = 0;    dev_info.dev_role = GAP_ROLE_PERIPHERAL;    dev_info.dev_name_len = sizeof(CUSTOM_DEVICE_NAME)-1;    memcpy(dev_info.dev_name, CUSTOM_DEVICE_NAME, dev_info.dev_name_len);    dev_info.dev_conn_param.intv_min = MSECS_TO_UNIT(MIN_CONN_INTERVAL,MSECS_UNIT_1_25_MS);    dev_info.dev_conn_param.intv_max = MSECS_TO_UNIT(MAX_CONN_INTERVAL,MSECS_UNIT_1_25_MS);    dev_info.dev_conn_param.latency = SLAVE_LATENCY;    dev_info.dev_conn_param.time_out = MSECS_TO_UNIT(CONN_SUP_TIMEOUT,MSECS_UNIT_10_MS);    dev_info.conn_param_update_delay = FIRST_CONN_PARAMS_UPDATE_DELAY;    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);
参数： func：添加服务（profile）函数, 函数实现方式参考例程函数app_dis_add_dis ；
返回值：true：注册成功。false：注册失败。
使用示例：                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);
参数： prf：服务（profile）子任务结构体指针，详情参考结构体prf_task_t
返回值：true：注册成功。false：注册失败；
使用示例：
   struct prf_task_t prf;    prf.prf_task_id = TASK_ID_DISS;    prf.prf_task_handler = &app_dis_handlers;    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);
参数： prf：服务任务接口获取函数的指针；
返回值：true：注册成功。false：注册失败；
使用示例：
   struct prf_get_func_t get_func;    get_func.task_id = TASK_ID_DISS;    get_func.prf_itf_get_func = diss_prf_itf_get;    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);
参数： p_adv_init：广播初始化参数结构体指针;
返回值：无
使用示例：
      struct ns_adv_params_t user_adv = {0};          //init advertising data       user_adv.adv_data_len = ADVERTISE_DATA_LEN;       memcpy(user_adv.adv_data,ADVERTISE_DATA,ADVERTISE_DATA_LEN);       user_adv.scan_rsp_data_len = ADV_SCNRSP_DATA_LEN;       memcpy(user_adv.scan_rsp_data,ADV_SCNRSP_DATA,ADV_SCNRSP_DATA_LEN);       user_adv.attach_appearance = false;       user_adv.attach_name = true;       user_adv.ex_adv_enable = false;       user_adv.adv_phy= PHY_1MBPS_VALUE;       user_adv.directed_adv.enable = false;       user_adv.fast_adv.enable = true;       user_adv.fast_adv.duration = CUSTOM_ADV_FAST_DURATION;       user_adv.fast_adv.adv_intv = CUSTOM_ADV_FAST_INTERVAL;       ser_adv.slow_adv.enable = true;       user_adv.slow_adv.duration = CUSTOM_ADV_SLOW_DURATION;       user_adv.slow_adv.adv_intv = CUSTOM_ADV_SLOW_INTERVAL;          user_adv.ble_adv_msg_handler = app_ble_adv_msg_handler;       ns_ble_adv_init(&user_adv);
1.7、ns_ble_adv_start
功能：开始（使能）蓝牙广播
语法：void ns_ble_adv_start(void);
参数：无
返回值：无
使用示例：
   ns_ble_adv_start();

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

1.9、ns_ble_adv_data_set
功能：设置广播数据包的内容
语法：void ns_ble_adv_data_set(uint8_t* p_dat, uint16_t len);
参数： p_dat：设置的广播包数据。 len：设置的广播包数据的长度；
返回值：无
使用示例：
   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);
参数： p_dat：设置的广播扫描回应包数据。 len：设置的广播扫描回应包数据的长度;
返回值：无
使用示例：
   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);
参数： p_dat：设置扩展广播包数据，注意这里不可以使用局部变量的指针。 len：设置扩展广播包数据的长度。
返回值：无
使用示例：
   const staticuint8_t ex_adv[] = {"\x29\xff""1234567890123456789012345678901234567890"};
   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);
参数： p_init：扫描功能参数结构体指针，详细参考结构体ns_scan_params_t内部定义；
返回值：无
使用示例：
   struct ns_scan_params_t init = {0};    static const uint8_t target_name[] = {"NS_RDTS_SERVER"};    init.type = SCAN_PARAM_TYPE;    init.dup_filt_pol = SCAN_PARAM_DUP_FILT_POL;    init.connect_enable = SCAN_PARAM_CONNECT_EN;    init.prop_active_enable = SCAN_PARAM_PROP_ACTIVE;    init.scan_intv= SCAN_PARAM_INTV;    init.scan_wd = SCAN_PARAM_WD;    init.duration = SCAN_PARAM_DURATION;    init.filter_type = SCAN_FILTER_BY_NAME;    init.filter_data = (uint8_t*)&target_name;       ns_ble_scan_init(&init);
1.13、ns_ble_start_scan
功能：开启蓝牙BLE扫描功能
语法：void ns_ble_start_scan(void);
参数：无
返回值：无
使用示例：
   ns_ble_start_scan();

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

1.15、ns_ble_start_init
功能：主机主动发起蓝牙BLE连接。注意仅供主机设备调用
语法：void ns_ble_start_init(uint8_t *addr, uint8_t addr_type);
参数： addr：将连接的从设备地址。 addr_type：将连接的设备地址类型，扫描返回的信息包含地址类型
返回值：无
使用示例：
   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);
参数： conn_param：连接参数结构体指针
返回值：无
使用示例：
      struct gapc_conn_param conn_param;
      conn_param.intv_min = 12; //15ms       conn_param.intv_max = 12; //15ms       conn_param.latency = 5;       conn_param.time_out = 500; //5000ms       ns_ble_update_param(&conn_param);
1.17、ns_ble_mtu_set
功能：主机或从机主动发起蓝牙BLE mtu参数更新请求。应注意用户数据包有效数据长度比MTU小3字节。
语法：void ns_ble_mtu_set(uint16_t mtu);
参数： mtu：蓝牙BLE mtu值，最大值为517;
返回值：无
使用示例：
      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);
参数： phy：蓝牙BLE phy参数值，可选参数参考enum gap_phy_val声明。
返回值：无
使用示例：
      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);
参数： interval：蓝牙BLE rssi读取间隙，时间单位毫秒，输入0值时只读取一次。
返回值：无
使用示例：
      void app_ble_msg_handler(struct ble_msg_t const *p_ble_msg)
         {             switch(p_ble_msg->msg_id)             {                case APP_BLE_OS_READY:                   NS_LOG_INFO("APP_BLE_OS_READY\r\n");                break;                case APP_BLE_GAP_CONNECTED:                   app_ble_connected();                   ns_ble_active_rssi(40); //enable rssi read every 1000ms                break;                case APP_BLE_GAP_DISCONNECTED:                   app_ble_disconnected();                break;                caseAPP_BLE_GAP_RSSI_IND:                   NS_LOG_INFO("rssi:%d\r\n",p_ble_msg->msg.p_gapc_rssi->rssi); //打印rssi                break;                default:                break;          }          }
1.20、ns_ble_disconnect
功能：主机或从机主动发起蓝牙BLE断开连接请求。成功断开连接会通过蓝牙事件回调函数的APP_BLE_GAP_DISCONNECTED消息返回。
语法：void ns_ble_disconnect(void);
参数：无
返回值：无
使用示例：
   ns_ble_disconnect();

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

1.22、rf_tx_power_set
功能：主机或从机设置射频信号发射功率;
语法：void rf_tx_power_set(rf_tx_power_t pwr);
参数： pwr：设置的射频信号发射功率，可选参数如下结构体定义，
   typedef enum
      {          TX_POWER_0_DBM = 0, /* 0 dBm */          TX_POWER_Neg2_DBM, /* -2 dBm */          TX_POWER_Neg4_DBM, /* -4 dBm */          TX_POWER_Neg8_DBM, /* -8 dBm */          TX_POWER_Neg15_DBM, /* -12 dBm */          TX_POWER_Neg20_DBM, /* -20 dBm */          TX_POWER_Pos2_DBM, /* +2 dBm */          TX_POWER_Pos3_DBM, /* +3 dBm */          TX_POWER_Pos4_DBM, /* +4 dBm */          TX_POWER_Pos6_DBM, /* +6 dBm */       }rf_tx_power_t; 返回值：无
使用示例：
      rf_tx_power_set(TX_POWER_Pos4_DBM);

二、安全加密模块2.1、ns_sec_init
功能：初始化蓝牙安全加密模块。
语法：void ns_sec_init(struct ns_sec_init_t const* init);
参数： init：蓝牙安全模块初始化参数结构体指针。详情参考结构体ns_sec_init_t内部定义。
返回：无
使用示例：
   struct ns_sec_init_t sec_init={0};    sec_init.rand_pin_enable = false;    sec_init.pin_code = 123456;    sec_init.pairing_feat.auth = ( SEC_PARAM_BOND | (SEC_PARAM_MITM<<2) | (SEC_PARAM_LESC<3) |                         (SEC_PARAM_KEYPRESS<<4) );    sec_init.pairing_feat.iocap = SEC_PARAM_IO_CAPABILITIES;    sec_init.pairing_feat.key_size = SEC_PARAM_KEY_SIZE;    sec_init.pairing_feat.oob = SEC_PARAM_OOB;    sec_init.pairing_feat.ikey_dist = SEC_PARAM_IKEY;    sec_init.pairing_feat.rkey_dist = SEC_PARAM_RKEY;    sec_init.pairing_feat.sec_req = SEC_PARAM_SEC_MODE_LEVEL;    sec_init.bond_enable= BOND_STORE_ENABLE;    sec_init.bond_db_addr = BOND_DATA_BASE_ADDR;    sec_init.bond_max_peer = MAX_BOND_PEER;    sec_init.bond_sync_delay = 5000;    sec_init.ns_sec_msg_handler = NULL;    ns_sec_init(&sec_init)；
2.2、ns_sec_get_bond_status
功能：返回是否已绑定了的状态。
语法：bool ns_sec_get_bond_status(void);
参数：无
返回：ture：已绑定。false：未绑定。
示例：
   bool bond_status = ns_sec_get_bond_status();

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

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

四、蓝牙睡眠模块4.1、ns_sleep 功能：蓝牙睡眠功能进入函数，函数会基于蓝牙协议栈工作状态，如果没有需要执行的任务则自动进入睡眠状态，在定时任务或者硬件中断唤醒后恢复系统状态。一般调用于main函数主循环，调度函数rwip_schedule后面。语法：void ns_sleep(void); 参数：无
返回值：无
示例：ns_sleep();
4.2、ns_sleep_lock_acquire 功能：蓝牙睡眠模式锁请求，即申请系统不进入睡眠模式。比如开启某些高速外设（如串口）不希望系统进入睡眠而关掉    它，可以通过请求睡眠模式锁禁止系统进入睡眠。语法：uint8_t ns_sleep_lock_acquire(void); 参数：无
返回值：true：请求锁成功。false：请求锁失败。
示例：
      if(ns_sleep_lock_acquire())       {          //require sleep lock success       }
4.3、ns_sleep_lock_release 功能：蓝牙睡眠模式锁释放，当所有的睡眠模式锁释放后，系统可以在没有任务挂起时将进入睡眠模式。语法：uint8_t ns_sleep_lock_release(void); 参数：无
返回值：true：释放锁成功。false：释放锁失败，目前没有可以释放的锁。
示例：
      if(ns_sleep_lock_release())       {       //release sleep lock success       }
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) 微秒;
返回：无
示例：delay_cycles(1000);
5.2、delay_n_us
功能：延迟等待指定数量的微秒
语法：void delay_n_us(uint32_t val);
参数：val：需要等待的微秒数;
返回：无
示例：delay_n_us(1000);
5.3、delay_n_10us
功能：延迟等待指定数量的10微秒
语法：void delay_n_10us(uint32_t val);
参数：val：需要等待的10微秒数;
返回：无
示例：delay_n_10us(1000);
5.4、delay_n_100us
功能：延迟等待指定数量的100微秒
语法：void delay_n_100us(uint32_t val);
参数：val：需要等待的100微秒数
返回：无
示例：delay_n_100us(1000);
5.5、delay_n_ms
功能：延迟等待指定数量的毫秒
语法：void delay_n_ms(uint32_t val);
参数：val：需要等待的毫秒数
返回：无
示例：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、用户的逻辑代码推荐在任务回调函数里面实现，可以是消息事件回调或者定时任务回调。

七毛钱 发表于 2022-6-13 16:52

不错不错，好好看看

yangxiaor520 发表于 2022-6-13 19:12

蓝牙支持音频嘛？

N32BLE 发表于 2022-6-14 07:14

yangxiaor520 发表于 2022-6-13 19:12
蓝牙支持音频嘛？

N32WB031系列不支持音频流数据传输，感谢关注国民技术。

chzfmx 发表于 2023-3-22 08:43

最新的SDK怎么获取

niceguy 发表于 2023-3-22 09:05

chzfmx 发表于 2023-3-22 08:43
最新的SDK怎么获取

参考这个帖子哦，https://bbs.21ic.com/icview-3228806-1-1.html
就是这个地址：ftp://58.250.18.138/Nations%20Products%20File/4-Wireless%20RF%20Products/

chzfmx 发表于 2023-3-22 09:53

niceguy 发表于 2023-3-22 09:05
参考这个帖子哦，https://bbs.21ic.com/icview-3228806-1-1.html
就是这个地址：ftp://58.250.18.138/Nat ...

谢谢

HORSE7812 发表于 2023-10-12 20:52

mark

周桂峰 发表于 2024-1-15 13:50

使用主机发起连接的函数没管用，ns_ble_start_init，这是怎么回事呢？有没有已经能够成功连接从机的主机代码？

页: [1]

21ic电子技术开发论坛's Archiver

N32WB031 API函数使用说明