Introduction

Quectel FC41D, FCM100D, FCM740D and FLMx40D modules support QuecOpen® solution. QuecOpen® is an embedded development platform based on RTOS system, which is intended to simplify the design and development of IoT applications. For more information on QuecOpen®, see Quick_Start_Guide.

This document is applicable to QuecOpen® solution based on SDK build environment. It introduces the BLE API and development example provided in SDK of FC41D, FCM100D, FCM740D and FLMx40D modules, as well as the procedures and code examples of Wi-Fi pairing via BLE.

Applicable Modules

Applicable Modules:

Module Family	Module
	FC41D
	FCM100D
	FCM740D
FLMx40D	FLM040D
	FLM140D
	FLM240D
	FLM340D

BLE API

Header File

ql_ble.h and ble_api_5_x, the header files of BLE API, are in the ql_components/qadpt/include and ql_kernel/driver/include directories respectively. Unless otherwise specified, all header files mentioned in this document are all in these directories.

API Overview

API Overview:

Function	Description
ql_ble_init()	Initializes BLE and uses the default BLE service.
ql_ble_create_db()	Initializes BLE and customizes the BLE service.
ql_ble_set_notice_cb()	Registers the BLE event callback function.
ql_ble_set_tx_power()	Sets the BLE RF Tx power.
ql_ble_get_idle_actv_idx_handle()	Gets the index of an idle BLE activity.
ql_ble_actv_state_get()	Gets the status of a specified BLE activity.
ql_ble_create_advertising()	Creates a BLE advertising.
ql_ble_set_adv_data()	Sets advertising data.
ql_ble_set_scan_rsp_data()	Sets scan response data.
ql_ble_start_advertising()	Starts BLE advertising.
ql_ble_adv_start()	Quickly starts BLE advertising.
ql_ble_stop_advertising()	Stops BLE advertising.
ql_ble_delete_advertising()	Deletes a BLE advertising.
ql_ble_create_scaning()	Creates a BLE scanning.
ql_ble_start_scaning()	Starts BLE scanning.
ql_ble_scan_start()	Quickly starts BLE scanning.
ql_ble_stop_scaning()	Stops BLE scanning.
ql_ble_delete_scaning()	Deletes a BLE scanning.
ql_ble_update_param()	Update connection parameters.
ql_ble_gatts_disconnect()	Server actively disconnects from the client.
ql_ble_gatt_mtu_changes()	Changes the MTU size.
ql_ble_gatt_mtu_get()	Gets the MTU size.
ql_ble_create_conn()	Creates a connection.
ql_ble_set_connect_dev_addr()	Sets the address of the BLE device to be connected.
ql_ble_gattc_register_discovery_callback()	Client registers the callback function for discovering the service of server.
ql_ble_gattc_register_event_recv_callback()	Client registers the event receiving callback function.
ql_ble_start_conn()	Starts a connection.
ql_ble_stop_conn()	Stops a connection.
ql_ble_gattc_disconnect()	Client actively disconnects from the server.
ql_ble_gattc_read_service_data_by_handle_req()	Client reads data from server through service handle.
ql_ble_gattc_write_service_data_req()	Client writes data to server through service handle.
ql_ble_gatts_send_ntf_value()	Server sends data to the client through notification.
ql_ble_gatts_send_ind_value()	Server sends data to the client through indication.
ql_ble_address_get()	Gets BLE MAC address.
ql_ble_gattc_ntf_enable()	Enables notification for a specified characteristic handle.
ql_ble_gattc_all_service_discovery()	Discovers all services of the server for client.
ql_ble_security_param_init()	Configures parameters for secure pairing.
ql_ble_security_req()	Sends a secure connection request.
ql_ble_bond_delete_all()	Deletes the information of all bound BLE devices.
ql_ble_delete_specified_bound_device()	Deletes a specified bound BLE device.
ql_ble_get_random_number()	Gets hardware random value.
ql_ble_get_idle_conn_idx_handle()	Gets the index of an idle BLE connection.
ql_ble_get_bonded_devices()	Gets the information of bound BLE devices.
ql_ble_is_device_bonded()	Determines whether the peer BLE device is a previously bound device.
ql_ble_set_device_name()	Sets BLE device name.
ql_ble_get_device_name()	Gets BLE device name.

API Description

ql_ble_init

This function initializes BLE and uses the default BLE service.

Prototype:

ql_errcode_bt_e ql_ble_init(void)

Parameter:

None

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_errcode_bt_e

The enumeration of function execution result codes is defined below:

typedef enum
{
  QL_BT_SUCCESS = 0,
  QL_BT_ERR_PROFILE,
  QL_BT_ERR_CREATE_DB,
  QL_BT_ERR_CMD_NOT_SUPPORT,
  QL_BT_ERR_UNKNOW_IDX,
  QL_BT_ERR_BLE_STATUS,
  QL_BT_ERR_BLE_PARAM,
  QL_BT_ERR_ADV_DATA,
  QL_BT_ERR_CMD_RUN,
  QL_BT_ERR_NO_MEM,
  QL_BT_ERR_INIT_CREATE,
  QL_BT_ERR_INIT_STATE,
  QL_BT_ERR_ATTC_WRITE,
  QL_BT_ERR_ATTC_WRITE_UNREGISTER,
} ql_errcode_bt_e

Member:

Member	Description
QL_BT_SUCCESS	Successful execution.
QL_BT_ERR_PROFILE	Profile error.
QL_BT_ERR_CREATE_DB	Failed to add the BLE service.
QL_BT_ERR_CMD_NOT_SUPPORT	The command is not supported.
QL_BT_ERR_UNKNOW_IDX	Unknown BLE activity index.
QL_BT_ERR_BLE_STATUS	Status error.
QL_BT_ERR_BLE_PARAM	Invalid parameter.
QL_BT_ERR_ADV_DATA	Incorrect advertising data format.
QL_BT_ERR_CMD_RUN	Failed to execute the command.
QL_BT_ERR_NO_MEM	Insufficient memory.
QL_BT_ERR_INIT_CREATE	Failed to create a connection task.
QL_BT_ERR_INIT_STATE	Connection status error.
QL_BT_ERR_ATTC_WRITE	Failed to write data.
QL_BT_ERR_ATTC_WRITE_UNREGISTER	The BLE service to which the data is written is not registered.

ql_ble_create_db

This function initializes BLE and customizes the BLE service.

Prototype:

ql_errcode_bt_e ql_ble_create_db (struct ql_ble_db_cfg* ble_db_cfg)

Parameter:

ble_db_cfg:

[In] BLE service list. See ql_ble_db_cfg for details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_db_cfg

The structure of BLE service list is defined below:

struct ql_ble_db_cfg
{
  uint16_t prf_task_id;
  uint8_t uuid[16];
  uint8_t att_db_nb;
  uint16_t start_hdl;
  ql_attm_desc_t* att_db;
  uint8_t svc_perm;
}

Parameter:

Type	Parameter	Description
uint16_t	prf_task_id	BLE service ID.
uint8_t	uuid	Service UUID.
uint8_t	att_db_nb	The number of attribute databases.
uint16_t	start_hdl	The start handle of service. If the value is 0, the handle is automatically allocated.
ql_attm_desc_t	att_db	Attribute database. See ql_attm_desc_t for details.
uint8_t	svc_perm	Service configuration.

ql_attm_desc_t

The structure of BLE attribute database is defined below:

typedef struct
{
  uint8_t uuid[16];
  uint16_t perm;
  uint16_t ext_perm;
  uint16_t max_size;
} ql_attm_desc_t

Parameter:

Type	Parameter	Description
uint8_t	uuid	UUID with 16 bytes.
uint16_t	perm	Permission setting.
uint16_t	ext_perm	Extended permission setting.
uint16_t	max_size	The maximum size of the attribute. Unit: byte.

ql_ble_set_notice_cb

This function registers the BLE event callback function.

Prototype:

ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)

Parameter:

func:

[In] BLE event callback function. See ble_notice_cb_t for
details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ble_notice_cb_t

This function is the BLE event callback function.

Prototype:

typedef void (*ble_notice_cb_t)(ble_notice_t notice, void *param)

Parameter:

notice:

[In] The type of BLE events. See ble_notice_t for details.

param:

[In] The parameter of BLE event.

ble_notice_t

The enumeration of BLE event types is defined below:

typedef enum
{
  BLE_5_STACK_OK,
  BLE_5_WRITE_EVENT,
  BLE_5_READ_EVENT,
  BLE_5_REPORT_ADV,
  BLE_5_MTU_CHANGE,
  BLE_5_CONNECT_EVENT,
  BLE_5_DISCONNECT_EVENT,
  BLE_5_ATT_INFO_REQ,
  BLE_5_CREATE_DB,
  BLE_5_TX_DONE,
  BLE_5_INIT_CONNECT_EVENT,
  BLE_5_INIT_DISCONNECT_EVENT,
  BLE_5_SDP_REGISTER_FAILED,
} ble_notice_t

Member:

Member	Description
BLE_5_STACK_OK	BLE protocol stack is ready.
BLE_5_WRITE_EVENT	The server receives the client write event.
BLE_5_READ_EVENT	The server receives the client read event.
BLE_5_REPORT_ADV	Scan result is returned.
BLE_5_MTU_CHANGE	MTU is changed.
BLE_5_CONNECT_EVENT	Connection event.
BLE_5_DISCONNECT_EVENT	Disconnection event
BLE_5_ATT_INFO_REQ	Request attribute information.
BLE_5_CREATE_DB	Profile is added successfully.
BLE_5_TX_DONE	Data is sent successfully.
BLE_5_INIT_CONNECT_EVENT	The client starts connecting to the server.
BLE_5_INIT_DISCONNECT_EVENT	The client disconnects from the server.
BLE_5_SDP_REGISTER_FAILED	SDP service registration failure event.

ql_ble_set_tx_power

This function sets the BLE RF Tx power.

Prototype:

ql_errcode_bt_e ql_ble_set_tx_power(int8_t tx_power)

Parameter:

tx_power:

[In] BLE RF Tx power. Range: -2-14. Default value: 6. Unit: dBm.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_get_idle_actv_idx_handle

This function gets the index of an idle BLE activity.

Prototype:

uint8_t ql_ble_get_idle_actv_idx_handle(void)

Parameter:

None

Return Value:

The index of the idle BLE activity.

ql_ble_actv_state_get

This function gets the status of a specified BLE activity.

Prototype:

ql_actv_state_t ql_ble_actv_state_get(uint8_t actv_idx)

Parameter:

actv_idx:

[In] The index of the BLE activity.

Return Value:

BLE activity status. See ql_actv_state_t for details.

ql_actv_state_t

The enumeration of BLE activity status is defined below:

typedef enum
{
  QL_ACTV_IDLE,
  QL_ACTV_ADV_CREATED,
  QL_ACTV_ADV_STARTED,
  QL_ACTV_SCAN_CREATED,
  QL_ACTV_SCAN_STARTED,
  QL_ACTV_INIT_CREATED,
  QL_ACTV_PER_SYNC_CREATED,
} ql_actv_state_t

Member:

Member	Description
QL_ACTV_IDLE	Idle status.
QL_ACTV_ADV_CREATED	Advertising is created.
QL_ACTV_ADV_STARTED	Advertising is started.
QL_ACTV_SCAN_CREATED	Scan activity is created.
QL_ACTV_SCAN_STARTED	Scanning is started.
QL_ACTV_INIT_CREATED	Connection is created.
QL_ACTV_PER_SYNC_CREATED	The periodic synchronization activity is created.

ql_ble_create_advertising

This function creates an BLE advertising.

Prototype:

ql_errcode_bt_e ql_ble_create_advertising(uint8_t actv_idx, unsigned char chnl_map, uint32_t intv_min, uint32_t intv_max, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the idle BLE activity obtained by ql_ble_get_idle_actv_idx_handle().

chnl_map:

[In] The selected advertising channel.

1 Channel 37

2 Channel 38

3 Channels 37 and 38

4 Channel 39

5 Channels 37 and 39

6 Channels 38 and 39

7 Channels 37, 38 and 39

intv_min:

[In] The minimum advertising interval. Range: 32-16384. Unit: 0.625 ms. Time range: 20 ms-10.24 s.

intv_max:

[In] The maximum advertising interval. Range: 32-16384. Unit: 0.625 ms. Time range: 20 ms-10.24 s.

callback:

[In] The callback function for the command of creating BLE activity. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

NOTE

Currently this function only supports the creation of non-directed connectable advertising. There is no advertising filtering, and the advertising mode is 1 Mbps PHY.

ql_ble_set_adv_data

This function sets advertising data.

Prototype:

ql_errcode_bt_e ql_ble_set_adv_data(uint8_t actv_idx, unsigned char* adv_buff, unsigned char adv_len, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_advertising().

adv_buff:

[In] Advertising data, which should be written according to the advertising data rules.

adv_len:

[In] The length of advertising data. Unit: byte.

callback:

[In] The callback function for the command of setting advertising data. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_set_scan_rsp_data

This function sets scan response data.

Prototype:

ql_errcode_bt_e ql_ble_set_scan_rsp_data(uint8_t actv_idx, unsigned char* scan_buff, unsigned char scan_len, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_advertising().

scan_buff:

[In] Scan response data, which should be written according to the advertising data rules.

scan_len:

[In] The length of scan response data. Unit: byte.

callback:

[In] The callback function for the command of setting scan response data. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_start_advertising

This function starts BLE advertising.

Prototype:

ql_errcode_bt_e ql_ble_start_advertising(uint8_t actv_idx, uint16_t duration, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_advertising().

duration:

[In] The duration of advertising. Unit: 10 ms. 0 indicates not to actively stop broadcasting.

callback:

[In] The callback function for the command of starting advertising. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_adv_start

This function quickly starts BLE advertising.

Prototype:

ql_errcode_bt_e ql_ble_adv_start(uint8_t actv_idx, struct adv_param *adv, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the idle BLE activity obtained by ql_ble_get_idle_actv_idx_handle().

adv:

[In] Advertising parameter. See adv_param for details.

callback:

[In] The callback function for the command of quickly starting BLE advertising. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

adv_param

The structure of advertising parameter is defined below:

struct adv_param
{
  uint8_t advData[MAX_ADV_DATA_LEN];
  uint8_t advDataLen;
  uint8_t respData[MAX_ADV_DATA_LEN];
  uint8_t respDataLen;
  uint8_t channel_map;
  uint16_t interval_min;
  uint16_t interval_max;
  uint16_t duration;
}

Parameter:

Type	Parameter	Description
uint8_t	advData	Advertising data. Maximum length: 31 bytes.
uint8_t	advDataLen	The length of advertising data. Unit: byte.
uint8_t	respData	Scan response data. Maximum length: 31 bytes.
uint8_t	respDataLen	The length of scan response data. Unit: byte.
uint8_t	channel_map	Advertising channel.
uint16_t	interval_min	The minimum advertising interval. Range: 32-16384. Unit: 0.625 ms. Time range: 20 ms-10.24 s.
uint16_t	interval_max	The maximum advertising interval. Range: 32-16384. Unit: 0.625 ms. Time range: 20 ms-10.24 s.
uint16_t	duration	The duration of advertising. Unit: 10 ms. 0 indicates not to actively stop broadcasting.

ql_ble_stop_advertising

This function stops BLE advertising.

Prototype:

ql_errcode_bt_e ql_ble_stop_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_advertising().

callback:

[In] The callback function for the command of stop advertising. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_delete_advertising

This function deletes a BLE advertising.

Prototype:

ql_errcode_bt_e ql_ble_delete_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_advertising().

callback:

[In] The callback function for the command of deleting BLE advertising. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_create_scaning

This function creates a BLE scanning.

Prototype:

ql_errcode_bt_e ql_ble_create_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the idle BLE activity obtained by ql_ble_get_idle_actv_idx_handle().

callback:

[In] The callback function for the command of creating BLE scanning. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_start_scaning

This function starts BLE scanning.

Prototype:

ql_errcode_bt_e ql_ble_start_scaning(uint8_t actv_idx, uint16_t scan_intv, uint16_t scan_wd, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_scaning().

scan_intv:

[In] Scan interval. Range: 18-4096. Unit: 0.625 ms. Time range: 11.25 ms-2560 ms.

scan_wd:

[In] Scan window. Range: 17-4096. Unit: 0.625 ms. Range: 10.625 ms-2560 ms.

callback:

[In] The callback function for the command of staring BLE scanning. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

NOTE

Currently, the scan started by this function works in 1 Mbps mode without the filtering of duplicate advertising packets, and it does not stop actively.

ql_ble_scan_start

This function quickly starts scanning.

Prototype:

ql_errcode_bt_e ql_ble_scan_start(uint8_t actv_idx, struct scan_param *scan, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the idle BLE activity obtained by ql_ble_get_idle_actv_idx_handle().

scan:

[In] Scan parameter. See scan_param for details.

callback:

[In] The callback function for the command of quickly staring scanning. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

scan_param

The structure of scan parameter is defined below:

struct scan_param
{
  uint8_t filter_en;
  uint8_t channel_map;
  uint16_t interval;
  uint16_t window;
}

Parameter:

Type	Parameter	Description
uint8_t	filter_en	Select the scan filtering policy. See ql_scan_dup_filter_e for details.
uint8_t	channel_map	Scan channel.
uint16_t	interval	Scan interval. Range: 18-4096. Unit: 0.625 ms. Time range: 11.25 ms-2560 ms.
uint16_t	window	Scan window. Range: 17-4096. Unit: 0.625 ms. Range: 10.625 ms-2560 ms.

ql_scan_dup_filter_e

The enumeration of scan filtering policies is defined below:

typedef enum tag_scan_dup_filter_policy
{
  QL_SCAN_FILT_DUPLIC_DIS = 0x00,
  QL_SCAN_FILT_DUPLIC_EN,
  QL_SCAN_FILT_DUPLIC_EN_PER_PERIOD,
} ql_scan_dup_filter_e

Member:

Member	Description
QL_SCAN_FILT_DUPLIC_DIS	Disable scanning filtering.
QL_SCAN_FILT_DUPLIC_EN	Enable scanning filtering.
QL_SCAN_FILT_DUPLIC_EN_PER_PERIOD	Enable the filtering of duplicate data packets during each scan period.

ql_ble_stop_scaning

This function stops BLE scanning.

Prototype:

ql_errcode_bt_e ql_ble_stop_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_scaning().

callback:

[In] The callback function for the command of stopping scanning. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_delete_scaning

This function deletes a BLE scanning.

Prototype:

ql_errcode_bt_e ql_ble_delete_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_scaning().

callback:

[In] The callback function for the command of deleting BLE scanning. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_update_param

This function updates connection parameters.

Prototype:

ql_errcode_bt_e ql_ble_update_param(uint8_t conn_idx, uint16_t intv_min, uint16_t intv_max, uint16_t latency, uint16_t sup_to, ble_cmd_cb_t callback)

Parameter:

conn_idx:

[In] Connection index.

intv_min:

[In] The minimum connection interval. Range: 6-3200. Unit: 1.25 ms. Time range: 7.5 ms-4 s.

intv_max:

[In] The maximum connection interval. Range: 6-3200. Unit: 1.25 ms. Time range: 7.5 ms-4 s.

latency:

[In] Number of ignorable connection intervals on the server. It must comply with (1 + latency) × intv_max × 2 × 1.25 < sup_to × 10.

sup_to:

[In] Connection timeout period. Range: 10-3200. Unit: 10 ms. Time range: 100 ms-32 s.

callback:

[In] The callback function for the command of updating connection parameters. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gatts_disconnect

This function is used by the server to actively disconnect from the client.

Prototype:

ql_errcode_bt_e ql_ble_gatts_disconnect(uint8_t conn_idx, ble_cmd_cb_t callback)

Parameter:

conn_idx:

[In] Connection index.

callback:

[In] The callback function for the command of server actively disconnecting from the client. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gatt_mtu_changes

This function changes the MTU size.

Prototype:

ql_errcode_bt_e ql_ble_gatt_mtu_changes(uint8_t conn_idx, uint16_t mtu_size, ble_cmd_cb_t callback)

Parameter:

conn_idx:

[In] Connection index.

mtu_size:

[In] The updated MTU size. Unit: byte.

callback:

[In] The callback function for the command of changing the MTU size. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gatt_mtu_get

This function gets the MTU size.

Prototype:

uint16_t ql_ble_gatt_mtu_get(uint8_t conn_idx)

Parameter:

conn_idx:

[In] Connection index.

Return Value:

The bytes of MTU.

ql_ble_create_conn

This function creates a connection.

Prototype:

ql_errcode_bt_e ql_ble_create_conn(uint8_t actv_idx, unsigned short con_interval, unsigned short con_latency, unsigned short sup_to, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the idle BLE activity obtained by ql_ble_get_idle_actv_idx_handle().

con_interval:

[In] Connection interval. Unit: 1.25 ms.

con_latency:

[In] Number of ignorable connection intervals on the server. It must comply with (1 + latency) × intv_max × 2 × 1.25 < sup_to × 10.

sup_to:

[In] Connection timeout period. Unit: 10 ms.

callback:

[In] The callback function for the command of creating connection. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_set_connect_dev_addr

This function sets the address of the BLE device to be connected.

Prototype:

ql_errcode_bt_e ql_ble_set_connect_dev_addr(unsigned char actv_idx, struct ql_bd_addr *bdaddr, unsigned char addr_type)

Parameter:

actv_idx:

[In] The index of the BLE advertising, which usually corresponds to the BLE advertising created by ql_ble_create_conn().

bdaddr:

[In] MAC address of the peer device to be connected. See ql_bd_addr for details.

addr_type:

[In] The address type of peer device.

0 Public address

1 Random address

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_bd_addr

The structure of MAC address is defined below:

struct ql_bd_addr
{
  uint8_t addr[BD_ADDR_LEN];
}

Parameter:

Type	Parameter	Description
uint8_t	addr	The MAC address of the target BLE device. Length: 6 bytes.

ql_ble_gattc_register_discovery_callback

This function is used by the client to register the callback function for discovering the service of server.

Prototype:

ql_errcode_bt_e ql_ble_gattc_register_discovery_callback(app_sdp_callback cb)

Parameter:

cb:

[In] The callback function for discovering the service of server. See app_sdp_callback for details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

app_sdp_callback

This function is the callback function for discovering the service of server, which reports the service discovery results.

Prototype:

typedef void (*app_sdp_callback)(unsigned char conidx, uint16_t chars_val_hdl, unsigned char uuid_len, unsigned char *uuid)

Parameter:

conidx:

[Out] Connection index.

chars_val_hdl:

[Out] Service handle.

uuid_len:

[Out] UUID length. Unit: byte.

uuid:

[Out] UUID.

NOTE

The handle and UUID of the server service are returned through this callback function in turn and can be stored for later use.

ql_ble_gattc_register_event_recv_callback

This function is used by the client to register the event receiving callback function.

Prototype:

ql_errcode_bt_e ql_ble_gattc_register_data_recv_callback(app_sdp_charac_callback cb)

Parameter:

cb:

[In] Event receiving callback function. See app_sdp_charac_callback for details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

app_sdp_charac_callback

This function is the event receiving callback function, which is used by the client to receive the event reported by the server.

Prototype:

typedef void (*app_sdp_charac_callback)(CHAR_TYPE type, uint8 conidx, uint16_t hdl, uint16_t len, uint8 *data)

Parameter:

type:

[Out] Event type. See CHAR_TYPE for details.

conidx:

[Out] Connection index.

hdl:

[Out] Service handle.

len:

[Out] The length of data. Unit: byte.

data:

[Out] data.

CHAR_TYPE

The enumeration of event types is defined below:

typedef enum
{
  CHARAC_NOTIFY,
  CHARAC_INDICATE,
  CHARAC_READ,
  CHARAC_READ_DONE,
  CHARAC_WRITE_DONE,
} CHAR_TYPE

Member:

Member	Description
CHARAC_NOTIFY	The event of receiving the data sent from server through notification.
CHARAC_INDICATE	The event of receiving the data sent from server through indication.
CHARAC_READ	The event of reading data.
CHARAC_READ_DONE	The event of finishing reading data.
CHARAC_WRITE_DONE	The event of finishing writing data.

NOTE

The enumeration is defined in ql_kernel/driver/ble_5_x_rw/ble_pub/app/api/app_sdp.h.

ql_ble_start_conn

This function starts a connection.

Prototype:

ql_errcode_bt_e ql_ble_start_conn(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_conn().

callback:

[In] The callback function for the command of starting a connection. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_stop_conn

This function stops a connection.

Prototype:

ql_errcode_bt_e ql_ble_stop_conn(uint8_t actv_idx, ble_cmd_cb_t callback)

Parameter:

actv_idx:

[In] The index of the BLE activity, which usually corresponds to the BLE activity created by ql_ble_create_conn().

callback:

[In] The callback function for the command of stopping a connection. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gattc_disconnect

This function is used by the client to actively disconnect from the server.

Prototype:

ql_errcode_bt_e ql_ble_gattc_disconnect(uint8_t conn_idx, uint8_t reason)

Parameter:

conn_idx:

[In] Connection index.

reason:

[In] The reason for the disconnection.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gattc_read_service_data_by_handle_req

This function is used by the client to read data from the server through service handle.

Prototype:

ql_errcode_bt_e ql_ble_gattc_read_service_data_by_handle_req(uint8_t conidx, uint16_t handle, ble_cmd_cb_t callback)

Parameter:

conidx:

[In] Connection index.

handle:

[In] The specified service handle.

callback:

[In] The callback function for the command of reading data through service handle. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gattc_write_service_data_req

This function is used by client to write data to the server through service handle.

Prototype:

ql_errcode_bt_e ql_errcode_bt_e ql_ble_write_service_data_req(uint8_t conidx, uint16_t handle, uint16_t data_len, uint8_t *data, ble_cmd_cb_t callback)

Parameter:

conidx:

[In] Connection index.

handle:

[In] The specified service handle.

data_len:

[In] The length of data. Unit: byte.

data:

[In] Data.

callback:

[In] The callback function for the command of writing data through service handle. This callback function is not supported currently and can be set to NULL.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gatts_send_ntf_value

This function is used by the server to send data to the client through notification.

Prototype:

ql_errcode_bt_e ql_ble_gatts_send_ntf_value(uint32_t len, uint8_t *buf, uint16_t prf_id, uint16_t att_idx)

Parameter:

len:

[In] The length of data. Unit: byte.

buf:

[In] data.

prf_id:

[In] Service ID.

att_idx:

[In] Generally, it is the corresponding feature value serial number with the notification feature value attribute permission when adding a service.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gatts_send_ind_value

This function is used by the server to send data to the client through indication.

Prototype:

ql_errcode_bt_e ql_ble_gatts_send_ind_value(uint32_t len, uint8_t *buf, uint16_t prf_id, uint16_t att_idx)

Parameter:

len:

[In] The length of data. Unit: byte.

buf:

[In] data.

prf_id:

[In] Service ID.

att_idx:

[In] Generally, it is the corresponding feature value serial number with the indication feature value attribute permission when adding a service.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_address_get

This function gets BLE MAC address.

Prototype:

ql_errcode_bt_e ql_ble_address_get(uint8_t *mac_addr)

Parameter:

mac_addr:

[Out] BLE MAC address.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gattc_ntf_enable

This function enables notification for a specified characteristic handle.

Prototype:

ql_errcode_bt_e ql_ble_gattc_ntf_enable(uint8_t conidx, uint16_t handle, bool ntf)

Parameter:

conidx:

[In] Connection index.

handle:

[In] Characteristic handle in the service table.

ntf:

[In] Enable or disable notification for a specified characteristic handle.

0 Disable

1 Enable

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_gattc_all_service_discovery

This function discovers all services of the server for client.

Prototype:

ql_errcode_bt_e ql_ble_gattc_all_service_discovery(uint8_t conidx)

Parameter:

conidx:

[In] Connection index.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_security_param_init

This function configures parameters for secure pairing.

Prototype:

ql_errcode_bt_e ql_ble_security_param_init(ql_ble_security_param_t *param)

Parameter:

param:

[In] Parameters for secure pairing. See ql_ble_security_param_t for details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_security_param_t

The structure of parameters for secure pairing is defined below:

typedef struct
{
  bool ble_secure_conn;
  ql_ble_io_cap_e io_cap;
  bool bond_auth;
  uint32_t password;
} ql_ble_security_param_t

Parameter:

Type	Parameter	Description
bool	ble_secure_conn	Enable or disable secure connection mode. 0: Disable. 1: Enable.
ql_ble_io_cap_e	io_cap	Device input/output capability. See Chapter 2.3.37.2 for details.
bool	bond_auth	Enable or disable authentication when binding devices.
uint32_t	password	Pairing password. Range: 000000-999999.

ql_ble_io_cap_e

The enumeration of device input/output capabilities is defined below:

typedef enum
{
  QL_BLE_IO_CAP_DISPLAY_ONLY = 0x00,
  QL_BLE_IO_CAP_DISPLAY_YES_NO = 0x01,
  QL_BLE_IO_CAP_KEYBOARD_ONLY = 0x02,
  QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT = 0x03,
  QL_BLE_IO_CAP_KEYBOARD_DISPLAY = 0x04,
} ql_ble_io_cap_e

Member:

Member	Description
QL_BLE_IO_CAP_DISPLAY_ONLY	Only numbers within the range of 000000 to 999999 can be displayed.
QL_BLE_IO_CAP_DISPLAY_YES_NO	Display Yes/No buttons.
QL_BLE_IO_CAP_KEYBOARD_ONLY	Only numbers within the range of 000000 to 999999 can be entered.
QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT	No input and no display.
QL_BLE_IO_CAP_KEYBOARD_DISPLAY	Numbers in the range of 000000 to 999999 can be entered and displayed.

ql_ble_security_req

This function sends a secure connection request.

Prototype:

ql_errcode_bt_e ql_ble_security_req(uint8_t conidx)

Parameter:

conidx:

[In] Connection index.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_bond_delete_all

This function deletes the information of all bound BLE devices.

Prototype:

ql_errcode_bt_e ql_ble_bond_delete_all(void)

Parameter:

None

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_delete_specified_bound_device

This function deletes a specified bound BLE device.

Prototype:

ql_errcode_bt_e ql_ble_delete_specified_bound_device(uint8_t idx)

Parameter:

idx:

[In] Index of the bound device.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_get_random_number

This function gets hardware random value.

Prototype:

int ql_ble_get_random_number(void)

Parameter:

None

Return Value:

Hardware random value

ql_ble_get_idle_conn_idx_handle

This function gets the index of an idle BLE connection.

Prototype:

uint8_t ql_ble_get_idle_conn_idx_handle(void)

Parameter:

None

Return Value:

The index of the idle BLE connection

ql_ble_get_bonded_devices

This function gets the information of bound BLE devices.

Prototype:

ql_errcode_bt_e ql_ble_get_bonded_devices(uint8_t *bonded_total, ql_ble_bonded_device *bonded_device)

Parameter:

bonded_total:

[Out] Total number of bound devices.

bonded_device:

[Out] Information of bound BLE devices. See ql_ble_bonded_device for details.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_bonded_device

The structure of bound device information:

typedef struct
{
  uint8_t idx;
  uint8_t peer_addr_type;
  uint8_t peer_addr[6];
} ql_ble_bonded_device

Parameter:

Type	Parameter	Description
uint8_t	idx	Index of the bound device.
uint8_t	peer_addr_type	BLE address type of the peer device. 0: Public address. 1: Random address.
uint8_t	peer_addr	BLE address of the peer device.

ql_ble_is_device_bonded

This function determines whether the peer BLE device is a previously
bound device.

Prototype:

ql_errcode_bt_e ql_ble_is_device_bonded(uint8_t peer_addr_type, uint8_t *peer_addr)

Parameter:

peer_addr_type:

[In] BLE address type of the peer device.

0 Public address

1 Random address

peer_addr:

[In] BLE address of the peer device.

Return Value:

Function execution result code. See ql_errcode_bt_e for details.

ql_ble_set_device_name

This function sets BLE device name.

Prototype:

uint8_t ql_ble_set_device_name(uint8_t* name , uint8_t len)

Parameter:

name:

[In] Device name.

len:

[In] The length of the device name. Unit: byte.

Return Value:

The actual length of the device name

ql_ble_get_device_name

This function gets BLE device name.

Prototype:

uint8_t ql_ble_get_device_name(uint8_t* name, uint32_t buf_len)

Parameter:

name:

[Out] Device name.

buf_len:

[In] The length of the device name. Unit: byte.

Return Value:

The actual length of the device name

Examples

This chapter describes how to use the above BLE API and how to debug the sending and receiving of BLE data. To run the BLE demo program, you only need to enable CFG_ENABLE_QUECTEL_BLE_PERIPHERA or CFG_ENABLE_QUECTEL_BLE_CENTRAL in ql_application/quectel_demo/quectel_demo_config.h.

The BLE API code example file is ql_ble_demo.c, located in the ql_application/quectel_demo directory, where you can view the complete examples of BLE API.

BLE GATT Server

Steps

Step 1: Call the following function to register BLE event callback function.

ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)

Step 2: Call the following function to add a BLE service.

ql_errcode_bt_e ql_ble_create_db (struct ql_ble_db_cfg* ble_db_cfg)

Step 3: Call the following function to get the index of an idle BLE activity.

uint8_t ql_ble_get_idle_actv_idx_handle(void)

Step 4: Call the following function to get the status of a BLE activity.

ql_actv_state_t app_ble_actv_state_get(uint8_t actv_idx)

Step 5: Call the following function to start BLE advertising.

ql_errcode_bt_e ql_ble_adv_start(uint8_t actv_idx, struct adv_param *adv, ble_cmd_cb_t callback)

Step 6: Call the following function to send the data back to the client after the server connects to the client and receives the data sent from the client.

ql_ble_gatts_send_ntf_value(w_req->len, w_req->value, w_req->prf_id, QL_DEMO_IDX_FF03_VAL_VALUE)

Code Example

Define BLE service:

The example of BLE event callback function:

Set the BLE event callback function and initialize BLE:

Set advertising parameters and advertising data, and then start advertising:

The server receives data and sends the data back to the client:

The result is as follows:

BLE GATT Client

Steps

Step 1: Call the following function to register BLE event callback function.

ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)

Step 2: Call the following function to initialize BLE.

ql_errcode_bt_e ql_ble_init(void)

Step 3: Call the following function to get the index of an idle BLE activity.

uint8_t ql_ble_get_idle_actv_idx_handle(void)

Step 41: Call the following function to get the status of a BLE activity.

ql_actv_state_t app_ble_actv_state_get(uint8_t actv_idx)

Step 5: Call the following function to start BLE scanning.

ql_errcode_bt_e ql_ble_scan_start(uint8_t actv_idx, struct scan_param *scan, ble_cmd_cb_t callback)

Step 6: Call the following function to stop BLE scanning.

ql_errcode_bt_e ql_ble_stop_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Step 7: Call the following function to create a connection.

ql_errcode_bt_e ql_ble_create_conn(uint8_t con_idx, unsigned short con_interval, unsigned short con_latency, unsigned short sup_to, ble_cmd_cb_t callback)

Step 8: Call the following function to start the connection.

ql_errcode_bt_e ql_ble_start_conn(uint8_t con_idx,ble_cmd_cb_t callback)

Code Example

Set the BLE event callback function and initialize BLE:

Set scan parameters and start scanning:

The BLE_5_REPORT_ADV event that the callback function returns contains the scan result, namely the advertising data of the nearby devices. The target BLE device (the one whose advertising name is "test") can have its address and address type parsed out using
app_demo_ble_adv_report_deal(). Following the target device's scanning, the advertising stops.

Create a connection activity and start connecting:

The server receives data and sends the data back to the client:

The result is as follows:

Appendix References

Related Documents

Document Name
Quectel_FC41D&FCM100D&FCM740D&FLMx40D_QuecOpen(SDK)_Quick_Start_Guide

Terms and Abbreviations

Abbreviation	Description
AP	Access Point
API	Application Programming Interface
BLE	Bluetooth Low Energy
GATT	Generic Attribute Profile
ID	Identifier
IoT	Internet of Things
MAC	Medium Access Control
MTU	Maximum Transmission Unit
RTOS	Real Time Operating System
SDK	Software Development Kit
SDP	Service Discovery Protocol
Tx	Transmit
USB	Universal Serial Bus
UUID	Universally Unique Identifier

WiFi Development Guide

General API Development Guide