1

WM_W800_蓝牙系统架构及 API 描述
V1.1

北京联盛德微电子有限责任公司 (winner micro)
地址：北京市海淀区阜成路 67 号银都大厦 1802
电话：+86-10-62161900
公司网址：www.winnermicro.com

1文档修改记录
版本

修订时间

修订记录

作者

V1.0

2021/3/4[C]创建文档PengxgV1.1

2021/05/17

1，删除传统蓝牙相关内容

Pengxg2，

AT 指令设置广播内容、扫描

审核

响应内容。
3，

AT 指令设置广播参数目录文档修改记录 ...................................................................................................................................................... 2目录 ...................................................................................................................................................................... 2
1

2

引言 .............................................................................................................................................................. 6
1.1

编写目的.............................................................................................................................................6

1.2

预期读者.............................................................................................................................................6

1.3

术语定义.............................................................................................................................................6

1.4

参考资料.............................................................................................................................................6

W800 蓝牙系统 ............................................................................................................................................. 72

2.1

芯片蓝牙设计框图.............................................................................................................................7

2.2

W800 蓝牙系统框图............................................................................................................................7

2.3

NimBLE 介绍.......................................................................................................................................8

2.4

2.5

2.3.1

Nimble ...................................................................................................................................8

2.3.2

NimBLE 目录架构 ..................................................................................................................8应用层协议描述.................................................................................................................................92.4.1

GAP .........................................................................................................................................92.4.2

ATT .........................................................................................................................................92.4.3

GATT .....................................................................................................................................10

示例代码框架描述...........................................................................................................................13
2.5.1

3

API 描述 ..................................................................................................................................................... 13
3.1

蓝牙系统 API....................................................................................................................................133.2

控制器端 API....................................................................................................................................14

3.3

应用层协议 API................................................................................................................................15

3.4

3.5
4

蓝牙系统软件代码位置 .....................................................................................................13

3.3.1

GAP .......................................................................................................................................15

3.3.2

BLE server .........................................................................................................................163.3.3

BLE client .........................................................................................................................18

蓝牙辅助 WiFi 配网 API ..................................................................................................................193.4.1

应用流程示例 .....................................................................................................................20

3.4.2

辅助 WiFi 配网 Service 定义 ...........................................................................................20

用户实现自己的配网 service ........................................................................................................21

API 使用示例 ............................................................................................................................................. 21
4.1

蓝牙系统使能（退出） ...................................................................................................................21

4.2

开机运行（退出）demo server .....................................................................................................21

4.3

开机运行（退出）demo client .....................................................................................................224.4

开机运行多连接（退出）demo client .........................................................................................22

4.5

数据互发功能...................................................................................................................................22

4.6

多连接功能.......................................................................................................................................23

4.7

UART 透传功能..................................................................................................................................24

4.8

开机开启广播...................................................................................................................................24

4.9

4.8.1

默认广播数据配置 .............................................................................................................26

4.8.2

用户自定义广播数据设置 .................................................................................................27开机开启扫描...................................................................................................................................27

4.10 连接态下开启广播/扫描 .................................................................................................................29
4.10.1 处于 Slave 模式的连接态 .................................................................................................293

4.10.2 处于 Master 模式下的连接态 ...........................................................................................30
5

6

蓝牙 AT 指令 .............................................................................................................................................. 30
5.1

蓝牙 AT 指令简述.............................................................................................................................30

5.2

蓝牙系统 AT 指令.............................................................................................................................315.3

蓝牙控制器协议栈 AT 指令 .............................................................................................................325.4

蓝牙应用层 AT 指令.........................................................................................................................35
5.4.1

设备管理 AT 指令 ...............................................................................................................365.4.2

BLE 辅助 WiFi 配网 AT 指令 ..............................................................................................41

5.4.3

状态码定义： .....................................................................................................................41

蓝牙 AT 指令操作示例 .............................................................................................................................. 43
6.1

6.2

6.3

6.4

6.5

6.6

蓝牙系统使能与退出.......................................................................................................................43
6.1.1

使能蓝牙系统 .....................................................................................................................43

6.1.2

退出蓝牙系统 .....................................................................................................................43

开关蓝牙 demo 广播.........................................................................................................................44
6.2.1

使能蓝牙系统 .....................................................................................................................44

6.2.2

开启可连接广播示例 .........................................................................................................44

6.2.3

停止广播示例 .....................................................................................................................44

6.2.4

退出蓝牙系统 .....................................................................................................................44

开关蓝牙 demo 扫描.........................................................................................................................44
6.3.1

使能蓝牙系统 .....................................................................................................................44

6.3.2

开启扫描示例 .....................................................................................................................44

6.3.3

停止扫描示例 .....................................................................................................................44

6.3.4

退出蓝牙系统 .....................................................................................................................45

开关蓝牙 demo server ....................................................................................................................45
6.4.1

使能蓝牙系统 .....................................................................................................................45

6.4.2

使能 demo server ..............................................................................................................45

6.4.3

停止 demo server ..............................................................................................................45

6.4.4

退出蓝牙系统 .....................................................................................................................45

开关蓝牙 demo client ....................................................................................................................45
6.5.1

使能蓝牙系统 .....................................................................................................................45

6.5.2

使能 demo client ..............................................................................................................45

6.5.3

停止 demo client ..............................................................................................................45

6.5.4

退出蓝牙系统 .....................................................................................................................45

开关蓝牙多连接 demo client ........................................................................................................45
6.6.1

使能蓝牙系统 .....................................................................................................................45

6.6.2

使能多连接 demo client ..................................................................................................45
4

6.7

6.8

6.9

6.6.3

停止 demo client ..............................................................................................................45

6.6.4

退出蓝牙系统 .....................................................................................................................45

开关基于 BLE 的 UART 透传 .............................................................................................................46
6.7.1

使能蓝牙系统 .....................................................................................................................46

6.7.2

使能 UART 透传 Server/Client 端 ...................................................................................46

6.7.3

停止 UART 透传 ...................................................................................................................46

6.7.4

退出蓝牙系统 .....................................................................................................................46

使能辅助 WiFi 配网服务 .................................................................................................................46
6.8.1

开启蓝牙功能，使能配网服务 .........................................................................................46

6.8.2

退出辅助 WiFi 配网服务注销蓝牙系统 ...........................................................................46

W800 测试模式..................................................................................................................................46
6.9.1

W800 进入测试模式 ............................................................................................................46

6.9.2

W800 退出信令测试 ............................................................................................................47

5

2

引言

2.1 编写目的
本文档用于介绍 W800 蓝牙软件系统，硬件系统及其开发蓝牙应用参考，指导用户学习及理解 w800
的蓝牙开发。

2.2 预期读者蓝牙应用开发人员，蓝牙协议栈维护人员及测试相关人员

2.3 术语定义
序号

术语/缩略语

说明/定义

1

BT

BlueTooth2

BLE

Bluetooth Low Energy

3

HCI

Host Controller Interface

4

GAP

General Access Profile

5

IFS

Inter Frame Space

2.4 参考资料《W800 芯片产品规格书》《蓝牙 Core spec4.0 及 4.2》
《WM_W800_蓝牙系统架构以及 API 描述_V1.0》《蓝牙控制器 spec》

63

W800 蓝牙系统

3.1 芯片蓝牙设计框图RF Transciver
MemoryMCU
CK804(320MHz)ROM 16KB

SRAM
128KB

SRAM 160KB

FLASH
8M

SASC

WiFi
SubSystemBT
SubSystem

BBP
WiFi
BBP
Mac

BT

BLE

Sec

Modem

SASC

AHB BUS 1

BridgeAHB BUS 2
AHB ASYNC

AHB2APB

TIPC

DMA
8 Channel

Crypt

Peripheral

PMU
RTC

GPSEC

SDIO_HOST

POR

RSA

PSRAM

APB BUS

Peripheral
Clock &RST CTRL

I2C

I2S

LSPI

PWM

LCD

UART

WDOG

GPIO

RFCFG

SDIO_Slave

VDET
HSPI

Power Status
W800 Block Diagram

3.2 W800 蓝牙系统框图
W800 蓝牙系统可以分为应用程序部分、主机协议栈、控制器协议栈及蓝牙基带、射频构成。
蓝牙的射频部分和 WiFi 系统共用。

应用程序

API

主机协议栈

VHCI接口控制器协议栈

基带
/
射频

HCI接口
蓝牙系统结构图示
认证的 HCI 串口操作指令参见传统蓝牙非信令测试及 BLE 非信令测试文档。具体测试方法
如下图所示：

7

应用程序

API

主机协议栈

控制器协议栈

基带
/
射频

HCI接口
PAUSE状态蓝牙认证结构图示

综测仪

其中 W800 提供可配置的 UART 口，用于 HCI 指令的响应。综测仪通过 UART 口直接控制控制器。此时主机协议栈处于 freeze 状态。

3.3 NimBLE 介绍
3.3.1 NimBLE
NimBLE 是 Apache 基金会下一个开源的蓝牙 5.0 协议栈，具备完整的 Host 及 Controller层。资源占用少，支持蓝牙 5.0 特性，也支持 Mesh 等功能。
基于 FreeRTOS 和我们的 Controller，移植了 Host 层。
3.3.2 NimBLE 目录架构整个 nimble 协议栈共包含 4 个目录：/docs 文件夹包含了 nimble 协议栈的一些说明文档，后缀为.rst/ext

文件夹包含了 nimble/nimble 文件夹包含了整个协议栈使用的加密库nimble 协议栈代码实现/porting 文件夹包含了 W800 平台的相关实现8

3.4 应用层协议描述
基于我们的 Controller，NimBLE 协议栈支持的功能如下：➢ 隐私1.2(LE Privacy 1.2)
➢ 安全管理(SM),支持传统配对(LE Legacy Pairing),安全连接(LE Secure
Connections),特定秘钥分发(Transport Specific Key Distribution)➢ 链路层PDU数据长度扩展(LE Data Length Extension)➢ 多角色并发(主机(central)/从机(peripheral), server/client)➢ 同时广播和扫描➢ 低速定向广播(Low Duty Cycle Directed Advertising)➢ 连接参数请求(Connection parameters request procedure)➢ LE Ping➢ 完整的GATT客户端，服务端，以及子功能➢ 抽象的HCI接口层
3.4.1 GAPGAP 定义归纳了一系列的角色、模式、流程等概念，用户需要首先理解这些概念，然后
根据自己的开发需求，按照 GAP 规范去配置使用 BLE，从而实现BLE 设备的广播。如，用户如果需要开发一个收发 BLE 广播的应用程序，那么就需要设置 GAP 定义的相关模式，从而实现广播效果。
角色说明如下：应用角色

应用特性Broadcaster

用于发送不可连接广播，并对 Observer 发送的扫描请求做出响应，不能与Observer 建立连接Observer接收 Broadcaster 发送的广播，可以选择向 Broadcaster 发送扫描请求，并接收扫描响应

Peripheral

用于发送可连接广播，并根据接收到连接请求与 Central 建立连接Central接收可连接广播，并向 Peripheral 发送连接请求，并建立连接

3.4.2 ATT
已连接的 BLE 设备使用 ATT / GATT 规范来进行应用数据交换。
ATT 定义了角色、属性的概念，属性用来来保存数据
ATT角色
ATT 角色应用特性

ATT 服务器

服务器可定义一系列属性，供客户端访问

ATT 客户端

客户端可以使用 ATT 协议来发现、读、写服务器定义的属性

属性
属性逻辑结果如下
9

属性句柄

属性类型

属性值

属性权限

0x0000-UUID

0-N 字节

Read/Write/Indication/Notification

0xFFFF其中：
1）属性句柄由属性服务器分配；2）属性类型由用户定义或更高层规范指定；3）属性值由用户定义或更高层规范指定，用来保存应用数据；4）属性权限由用户定义或更高层规范指定
属性访问方法 - ATT 协议帧属性访问方法也就是 ATT 协议帧，在蓝牙规范中被称作 ATT PDU(protocol dataunit).
ATT PDU 被 ATT 客户端用来发现、读、写属性，或者被 ATT 服务器用来发送属性的notication、indication。
ATT PDU 的类型有如下 6 种：
ATT PDU 类型

描述

Commands

由客户端发送给服务器的 ATT PDU,服务器不会发送 response

Requests

由客户端发给属性服务器的 ATT PDU，服务器会发送 response 作为响应

Response服务器发给客户端作为 request 的响应

Notification

由服务器发给客户端，客户端不会发送 confirmation 做为响应

Indication

由服务器发给客户端，客户端需要发送 confirmation 做为响应Confirmation

由客户端发给服务器，做为 Indication 的响应

3.4.3 GATTGATT 是为了给应用程序或其他配置文件使用，以便于 ATT 客户端可以跟 ATT 服务器通信。
GATT 定义了使用 ATT 协议 PDU 的框架，这个框架定义了数据交换流程，也定义了应用
数据交换格式：服务(service)和特征(characteristics)。
通过 GATT 我们可以发现服务，并读/写或配置对端设备的特征。
GATT 角色
与 ATT 相同，GATT 也存在两种角色：
GATT 角色

角色描述
10

GATT 服务器定义服务和特征的 BLE 设备

GATT 客户端发送数据请求来访问服务与特征的 BLE 设备

GATT 角色是不固定的，只有当启动相应流程时，GATT 角色才被确定，流程结束时 GATT
角色释放。
其中：
GATT 客户端发送 commands 和 requests 给服务器，并且能接收来自服务器的 response，
indications 和 notifications；
GATT 服务器接收来自客户端的 commands 和 requests 并且发送 response，indication
和 notification 给客户端。
GATT 数据结构
GATT 配置文件指定了数据交换的结构。这个结构定义了基本的元素：服务(service)和特征(characteristics)。
所有服务和特征都包含在属性中，属性是承载 GATT 数据的容器。
GATT 数据结构如下图所示：11

对于 GATT 数据结构的说明：
1. 最顶层是一个 profile，可以理解为一个应用程序，这个应用程序由 1 个或多个服务组成；
2. 每一个服务由特征定义和服务引用组成；3. 特征包含一个特征值和特征值相关的其他信息；
4. 服务和特征都以属性的形式被 GATT 服务器存储。

12

3.5 示例代码框架描述
3.5.1 蓝牙系统软件代码位置

bleapp 目录即蓝牙示例代码，用户可以参考或基于此代码进行二次开发。
应用程序文件列表：No应用程序模块

说明1

wm_bt_app.c

主机协议栈主程序入口

2

wm_ble_gap.c

GAP 实现及相关 event 的上报处理4

wm_ble_server_wifi_prof.c

BLE 辅助配网服务通讯模块，负责传输层的实现5

wm_ble_server_wifi_app.c

BLE 辅助配网应用协议处理模块，负责应用层协议的实现6

wm_ble_client_api_demo.c

实现 api 创建 demo server 功能

7

wm_ble_server_api_demo.c

实现 api 创建 demo client 功能

8

wm_ble_client_api_multi_conn_demo.c 实现 api 创建 demo client，可支持连
接 7 个 demo server。

94

wm_ble_uart_if.c

实现基于 BLE 的 UART 透传示例

API 描述4.1 蓝牙系统 API
No

API 名称描述

1int运行蓝牙系统，该函数会依次使能主机协议炸

tls_bt_init(

和控制器协议栈。

uint8_t uart_idx)
13

2

int

停止蓝牙系统，改函数会依次注销主机协议栈

tls_bt_deinit(void)

和控制器协议栈。

4.2 控制器端 API
No

API 名称描述

1

tls_bt_status_t tls_bt_ctrl_enable(

初始化控制器端协议栈，分配内存及

tls_bt_hci_if_t *p_hci_if,创建任务等

tls_bt_log_level_t log_level)2

tls_bt_status_t tls_bt_ctrl_disable(void);

注销控制器协议栈

3

tls_bt_status_t tls_ble_set_tx_power(

设置 BLE 发射功率索引

tls_ble_power_type_t power_type,
int8_t power_level);4

读取指定工作类型的发送功率索引

int8_ttls_ble_get_tx_power(
uint8_t power_type);5读取控制器目前的状态，

tls_bt_ctrl_status_t
tls_bt_controller_get_status(void);

6

7

bool

用于判断主机能否向控制器发送指

wm_bt_vuart_host_check_send_available(void);

令

tls_bt_status_t

主机协议栈向控制器发送数据接口

tls_bt_vuart_host_send_packet (uint8_t *data, uint16_t len);8

tls_bt_status_t tls_bt_ctrl_if_register (议栈接收数据接口

const tls_bt_host_if_t *p_host_if);
910

注册控制器数据发送接口，即主机协

tls_bt_status_t

是否运行控制器在空闲时进入

tls_bt_ctrl_sleep (bool enable);sleep 模式bool

读取控制器是否处于 sleep 模式

tls_bt_ctrl_is_sleep (void);11

tls_bt_status_t tls_bt_ctrl_wakeup(void)

退出 sleep 模式

12

tls_bt_status_t进入蓝牙测试模式

enable_bt_test_mode(tls_bt_hci_if_t*p_hci_if)
13

退出蓝牙测试模式

tls_bt_status_t exit_bt_test_mode()144.3 应用层协议 API
4.3.1 GAP
设备管理层承担控制器的通用设置，如广播，扫描，设备名称修改等功能
4.3.1.1 GAP API 描述
No

API 名称描述

1.

int tls_ble_gap_init(void);

初始化默认广播、扫描参数；设置设备名称。
注意：该函数在蓝牙系统运行时自动调用。

2.

int tls_ble_gap_deinit(void);

释放资源。
注意：该函数在蓝牙系统注销时自动调用3.

int tls_ble_gap_set_adv_param(设置广播参数

uint8_t adv_type, uint32_t min, uint32_t
max,

uint8_tchn_map,

filter_policy,uint8_t

uint8_t*dir_mac,uint8_t

dir_mac_type)4.

int

启动、停止广播

tls_nimble_gap_adv(wm_ble_adv_type_ttype, int duration);5.

int

启动、停止扫描

tls_ble_gap_scan(wm_ble_scan_type_ttype, bool filter_duplicate);
6.

int tls_ble_gap_set_scan_param(

设置扫描参数

uint32_t intv, uint32_t window, uint8_t
filter_policy,

bool

limited,bool

passive, bool filter_duplicate);
6

int tls_ble_gap_set_name(设置设备名称const

注意：如果设备正在进行广播，并且广播参数

char*dev_name,uint8_t

update_flash);struct ble_hs_adv_fields
指定 name_is_complete. 那么设置名称后，广
播需停止并再次使能后，生效。

7

int

tls_ble_gap_get_name(char*dev_name);读取设备名称。
注意：该函数首先读取 Flash 中保存的设备名称，如果不存在，读取 ram 中的设备名称

8

int tls_ble_gap_set_data(

用于设置自定义的广播数据或者扫描响应内wm_ble_gap_data_t type,容

uint8_t *data, int data_len);15

9

int tls_ble_register_gap_evt(

用于注册 GAP 事件的上报函数

uint32_t evt_type,app_gap_evt_cback_t *evt_cback);
10

int tls_ble_deregister_gap_evt(

用于注销 GAP 事件的上报函数

uint32_t evt_type,app_gap_evt_cback_t *evt_cback);

4.3.2 BLE server
BLE server 承担 GATT 服务器角色，wm_ble_server_api_demo 模块提供了用户程序开发的
示例，示例功能描述为：1，

创建如下 service 列表功能，并启动广播；2，接收到对方连接后，更新 ATT 层 MTU 功能；3，接收到对方连接后，如果收到对方的 indication 功能后，持续发送特定的数据
到对方。
该模块提供两条对外的 API 分别为初始化及注销，具体代码如下：

16

17

4.3.2.1 BLE server API 描述
NimBLE 协议栈不支持在 GATT service 运行时，动态增加、注销 service 功能。所以，GATT service 必须配置完成后，方可使能 service 功能。
No

API 名称描述

1

int复位 GATT service 列表及释放资源。

ble_gatts_reset(void)；2int

配置 GATT service

ble_gatts_count_cfg(
const struct ble_gatt_svc_def *defs)；
3int

添加 GATT service

ble_gatts_add_svcs(
const struct ble_gatt_svc_def *svcs)
4

int启动 GATT server

ble_gatts_start(void)5

int

通过指定的 attr_handle 向某个 conn_handle

ble_gattc_indicate_custom(uint16_t

发送 indication 数据

conn_handle, uint16_t chr_val_handle,
struct os_mbuf *txom)
6

int

通过指定的 attr_handle 向某个 conn_handle

ble_gattc_notify_custom(uint16_t

发送 notification 数据

conn_handle, uint16_t chr_val_handle,
struct os_mbuf *txom)

4.3.3 BLE client
BLE client 承 担 GATT 客 户 端 角 色 ， 即 主 动 发 起 扫 描 ， 连 接 ， 通 讯 等 应 用 。
wm_ble_client_api_demo 模块提供了如下示例功能：
1，

发起扫描；

2，

根据广播数据中是否含有 FFFO 的 service 字段，并发起连接；3，

建立连接后读取对方 service 列表；4，

分析 service 列表，判断 characterise 是否含有 FFF1 字段，并使能 indication，
收到 indication 数据后打印

5，分别 servcie 列表，判断 characterise 是否含有 FFF2 字段，并发送 0Xaa,0xbb 字
节到对方。

参考该模块实现，用户可以开发自己的应用程序。
4.3.3.1 BLE client API 描述
No

API 名称

描述
18

1.

int

用于和对方设备建立 BLE 连

ble_gap_connect(

接uint8_t own_addr_type,
const ble_addr_t *peer_addr,
int32_t duration_ms,
const struct ble_gap_conn_params *conn_params,
ble_gap_event_fn *cb, void *cb_arg)

2.

int

建立连接后，读取 server 端

ble_gattc_disc_all_svcs(

service 列表

uint16_t conn_handle,
ble_gatt_disc_svc_fn *cb,void *cb_arg)

3

int

建立连接后，用于和对方交

ble_gattc_exchange_mtu(

互 ATT 层 MTU 功能

uint16_t

conn_handle,

ble_gatt_mtu_fn

*cb,

void

*cb_arg)4

int

用于向指定的 conn_handle

ble_gattc_write_flat(

及 attr_handle 发送数据uint16_t conn_handle, uint16_t attr_handle,
const void *data, uint16_t data_len,
ble_gatt_attr_fn *cb, void *cb_arg)

5int

用于向指定的 conn_handle

ble_gattc_read(

及 attr_handle 发起读操作

uint16_t conn_handle, uint16_t attr_handle,
ble_gatt_attr_fn *cb, void *cb_arg)

4.4 蓝牙辅助 WiFi 配网 API
BLE 辅助 WiFi 配网，作为 BLE server 的一个具体应用。wm_ble_server_wifi_prof 实现
BLE profile 的功能，负责数据的传输处理，wm_ble_server_wifi_cfg 处理具体通讯协议处理。这样的层次结构使得应用处理与具体传输层独立开来，逻辑层次调用更加清晰化。
这部分 API 相对简单，如下：NoAPI 名称描述
19

1

tls_wifi_set_oneshot_flag(flag)

当 flag 设置为 4 时，即启

flag 0: closed oneshot

动/停止 BLE 辅助 WiFi 配网

1: UDP（broadcast+multicast）（使用该模块前需使能蓝

2: AP+socket

牙系统）3: AP+WEBSERVER

注意：1，配网成功后，BLE

4: BT

的配网 service 会自动退出，广播关闭。如需再次配
网请再次调用此 API 即可。
2，如配网失败，用户可以再次配置

4.4.1 应用流程示例

APP

W800
1.广播

2.扫描发现设备
3.建立连接4.秘钥协商（发送公钥）
5.秘钥协商（返回秘钥）

6.发送配置信息
7.返回配置结果

4.4.2 辅助 WiFi 配网 Service 定义Service 定义：Service uuid： 0x1824
特征值 uuid：0x2ABC

Write & Indication

特征值描述 uuid: 2902
Write：

BleWiFi（手机 APP -> W800）Characteristic UUID：0x2ABC

Indication：BleWiFi（W800 -> 手机 APP）Characteristic UUID：0x2ABC

20

4.5 用户实现自己的配网服务
参考 wm_ble_server_demo_prof.c 示例，添加自定义的 service。
5

API 使用示例
W800 蓝牙功能，设备复位后默认是不使能的。如果用户想默认使用蓝牙，可以参考如下说明。
5.1 蓝牙系统使能（退出）步骤 1，在 tls_bt_entry()函数中调用打开蓝牙功能，关闭蓝牙系统调用 demo_bt_destroy;

步骤 2，蓝牙功能打开成功后，如下回调函数会被调用, 用户在此添加自己的应用程序；5.2 开机运行（退出）示例 server
在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_server_demo_api_init()；在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_server_demo_api_deinit()；应用程序
的退出功能，会在蓝牙系统退出时，自动释放。当然，蓝牙系统在运行时，用户也可以随时退出自己的应用程序。
21

5.3 开机运行（退出）示例 client
在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_client_demo_api_init()；在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_client_demo_api_deinit()；应用程序
的退出功能，会在蓝牙系统退出时，自动释放。当然，蓝牙系统在运行时，用户也可以随时退出自己的应用程序。
5.4 开机运行多连接（退出）示例 client
在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_client_multi_conn_demo_api_init()；在 4.1 节中步骤 2 标记的位置处，调用 wm_ble_client_multi_conn_demo_api_deinit()；
应用程序的退出功能，会在蓝牙系统退出时，自动释放。当然，蓝牙系统在运行时，用户
也可以随时退出自己的应用程序。
5.5 数据互发功能用两块 demo 板，分别运行 4.2 server demo 和 4.3 client demo，具体 demo 功能参见 3.3.2 和 3.3.3 描述。
连接成功后，server 端会不停的向 client 端以 indication 方式发送数据，时序图如
下所示：

22

Server

Client使能蓝牙使能蓝牙[demo_bt_enable][demo_bt_enable]

添加服务：0x1910

使能扫描[tls_ble_server_add_service ][tls_ble_server_add_characteristic ][tls_ble_server_add_descriptor ][tls_ble_scan]

使能广播[tls_ble_set_adv_data][tls_ble_adv]

创建连接[tls_ble_client_connect]

分析，使能

使能发送

[tls_ble_client_register_for_notification][tls_ble_client_write_characteristic]

循环发送

数据接收

[tls_ble_server_send_indication][ble_client_demo_api_notify_callback]Service ID:1902

Serverservice描述[Characteristic 0x2B11,GATT_CHAR_PROP_BIT_WRITE][Characteristic 0x2B10,GATT_CHAR_PROP_BIT_INDICATE][Descriptor 0x2902]

5.6 多连接功能
W800 蓝牙系统作为中央设备，最多支持连接 7 个外围设备。该功能的示例配置如下：
1，分别运行 7 个 BLE server 设备，配置模式参见 5.2

2，

运行 1 个支持多连接功能的 BLE client，配置模式参见 5.4
此时，client 会依次发起扫描，连接功能，直至连接成功 7 个 BLE server。

注意：限于控制器侧性能，Client 端发起连接时，连接参数必须使用如下间隔：23

5.7 UART 透传功能基于 BLE server 和 BLE client 的数据互发，实现了 UART 的透传功能。该功能的示
例配置如下:
1,Server 端，采用 UART1,默认属性（115200-8-N-1）透传：在 4.1 章节标记处调用
tls_ble_uart_init(BLE_UART_SERVER_MODE, 0x01, NULL)；
2,Client 端，采用 UART1,默认属性（115200-8-N-1）透传：在 4.1 章节标记处调用
tls_ble_uart_init(BLE_UART_CLIENT_MODE, 0x01, NULL)；
启动后，server 端开始广播，client 端扫描到广播后，连接 server 端，分析 server
端服务列表，并匹配后，BLE 通道建立。用户可以通过 UART1 进行数据传输。
5.8 开机开启广播步骤 1，在 tls_bt_entry()函数中调用打开蓝牙功能;步骤 2，蓝牙功能打开成功后，如下回调函数会被调用, 用户调用开启广播函数
tls_ble_demo_adv(1)；//可连接广播

24

25

5.8.1

默认广播数据配置

26

5.8.2 用户自定义广播数据设置

5.9 开机开启扫描步骤 1，在 tls_bt_entry()函数中调用打开蓝牙功能;步骤 2，蓝牙功能打开成功后，如下回调函数会被调用, 用户调用开启扫描函数

27

28

5.10 连接态下开启广播/扫描步骤 1，在 tls_bt_entry()函数中调用打开蓝牙功能，关闭蓝牙系统调用 demo_bt_destroy;连接态分为 Slave 模式下和 Master 模式下，下面分两种情况分别予以描述。；
5.10.1 处于 Slave 模式的连接态步骤 2，处于 Slave 模式下，参见 4.2 节。运行 Ble server 的 demo 示例，运行后，手机端发起扫描、连接操作，连接成功后，此时设备侧处于 Slave 模式，手机侧处于 Master 模式。

29

5.10.1.1 开启广播步骤 3，[注意]此时设备侧只支持不可连接的广播。
调用 tls_ble_gap_set_adv_param 设置广播类型为不可连接广播
调用 tls_nimble_gap_adv 开启广播
5.10.1.2 开启扫描
步骤 4 参见 4.4，直接调用开启扫描 API 即可。
demo_ble_scan(1);5.10.2 处于 Master 模式下的连接态
参见 4.3 开机运行 demo client 功能，client 同 server 建立连接后：1）可扫描操作；2）可发送不可连接的广播操作
6

蓝牙 AT 指令

6.1 蓝牙 AT 指令简述通过 AT 指令可以控制蓝牙系统，蓝牙 AT 指令共分为 4 类。主机、控制器部分用来配置主机协议栈和控制器协议栈，应用层部分用来配置蓝牙应用程序，测试部分用来配置蓝牙认证功能（该部分部分包含了应用层）。
蓝牙 AT 指令中的缩写含义为：
缩写

含义

CTRL

CONTROLLER

BLESC

BLE SERVICEBLESVBLE SERVERBLECBLE CLIENT

POW

POWER

STS

STATUSDESDESTORY

PRM

PARAM

FLT

FILTERCT

CREATECH

CHARACTERISTIC

STT

START

STP

STOP
30

DEL

DELETEDISDISCONNECT

SND

SEND

IND

INDICATIONCONN

CONNECTNTYNOTIFICATIONACC

ACCESSTESTTESTMODEEN

ENABLEGS

GETSTATUSTPS

TXPOWERSETTPGTXPOWERGET

6.2 蓝牙系统 AT 指令
6.2.1.1 AT+BTEN
功能：
使能蓝牙系统。
格式（ASCII）：
AT+BTEN=<uart_no>,<log_level><CR>+OK=<status><CR><LF><CR><LF>
参数：
uart_no: 串口索引号，定义如下：值1

含 义uart1 目前版本只支持 UART1

Log_level: 日志输出等级，定义如下：
值

含 义

0

关闭 log 输出1

输出 error 级别的 log

2输出 warn 级别的 log

3输出 api 级别的 log

31

4

输出 event 级别的 log

5输出 debug 级别的 log

6输出 verbose 级别的 log

返回：
status：指令响应结果

值

含 义

0

成功

Others>1

失败

6.2.1.2 AT+BTDES
功能：停止并注销蓝牙系统。
格式（ASCII）：
AT+BTDES<CR>+OK=<status><CR><LF><CR><LF>
参数：
参见 BTEN 参数描述
6.3 蓝牙控制器协议栈 AT 指令

6.3.1.1 AT+BTCTRLGS
功能：
获取控制状态。
格式（ASCII）：
AT+BTCTRLGS<CR>+OK=<status><CR><LF><CR><LF>
参数：
status：控制状态，返回格式定义如下：
TLS_BT_CTRL_IDLE=

TLS_BT_CTRL_ENABLED=(1<<0),(1<<1),32

TLS_BT_CTRL_SLEEPING =(1<<2),

TLS_BT_CTRL_BLE_ROLE_MASTER =(1<<3),

TLS_BT_CTRL_BLE_ROLE_SLAVE =(1<<4),

TLS_BT_CTRL_BLE_ROLE_END =(1<<5),

TLS_BT_CTRL_BLE_STATE_IDLE =(1<<6),

TLS_BT_CTRL_BLE_STATE_ADVERTISING =(1<<7),

TLS_BT_CTRL_BLE_STATE_SCANNING =(1<<8),

TLS_BT_CTRL_BLE_STATE_INITIATING =(1<<9),

TLS_BT_CTRL_BLE_STATE_STOPPING =(1<<10),TLS_BT_CTRL_BLE_STATE_TESTING =(1<<11),

6.3.1.2 AT+BTSLEEP
功能：
设置控制器空闲时 sleep 模式。当前版本暂不支持
格式（ASCII）：
AT+BTSLEEP=<cmd><CR>+OK<CR><LF><CR><LF>
参数：
cmd：控制命令，定义如下：
值

含义

0

禁止控制器进入sleep

1

允许控制器进入sleep

6.3.1.3 AT+BLETPS
功能：
配置 BLE 特定类型下发送功率。当前版本只支持默认功率设置
格式（ASCII）：
AT+BLETPS=<type>,<level><CR>+OK<CR><LF><CR><LF>
参数：
type：ble类型，定义如下：
33

值

含义

0

特定的连接handle

1

特定的连接handle

2

特定的连接handle

3

特定的连接handle

4

特定的连接handle

5

特定的连接handle

6

特定的连接handle

7

特定的连接handle

8

特定的连接handle

9

广播

10

扫描

11

默认功率

level：功率索引值。
值含义 dBm

1

1

2

4

3

7

4

10

5

13

6.3.1.4 AT+BLETPG
功能：获取 BLE 特定类型。当前版本只支持默认功率获取
格式（ASCII）：
AT+BLETPG=?<CR>+OK=<level><CR><LF><CR><LF>
参数：
type：ble类型，定义如下：
值

含义
34

0

特定的连接handle

1

特定的连接handle

2

特定的连接handle

3

特定的连接handle

4

特定的连接handle

5

特定的连接handle

6

特定的连接handle

7

特定的连接handle

8

特定的连接handle

9

广播

10

扫描

11

默认功率

level：功率索引值。参见 4.4.1.5

6.3.1.5 AT+BTTEST
功能：设置蓝牙测试模式。
格式（ASCII）：
AT+BTTEST=<mode><CR>+OK<CR><LF><CR><LF>
参数：
mode：测试模式，定义如下：
值

含义

0

退出蓝牙测试模式

1

进入蓝牙测试模式

6.4 蓝牙应用层 AT 指令

蓝牙应用层分为设备管理、BLE server 和 BLE client 三部分。
35

6.4.1 设备管理 AT 指令
6.4.1.1 AT+BLEADV
功能：
控制 BLE 广播发送和停止。
格式（ASCII）：
AT+BLEADV=<mode><CR>+OK<CR><LF><CR><LF>
参数：
mode：控制模式，定义如下：
值

含义

0

停止BLE广播

1

启动BLE广播

6.4.1.2 AT+BLEADATA
功能：
配置 BLE 广播内容。
格式（ASCII）：
AT+BLEADATA=<data><CR>+OK<CR><LF><CR><LF>
参数：
data：广播内容，为 HEX 格式。最大长度为 62 个字符，相当于 16 进制 31 个字节。
例如，设置广播数据为 0x02 0x01 0x06 0x03 0x09 0x31 0x32，
则设置指令为：AT+BLEADVDATA=02010603093132。
具体广播数据格式定义，参见响应 core specification 描述。

36

6.4.1.3 AT+BLEAPRM
功能：配置 BLE 广播参数。
格式（ASCII）：
AT+BLEAPRM=<adv_int_min>,<adv_int_max>,<adv_type>,<own_addr_type>,<channel_map>,[adv_filter_policy],[peer_addr_type],[peer_addr]<CR>+OK=<adv_int_min>,<adv_int_max>,<adv_type>,<own_addr_type>,<channel_map>,<adv_filter_policy>,<peer_addr_type>,<peer_addr><CR><LF><CR><LF>
参数：
adv_int_min：最小广播间隔，取值范围：0x0020 ~ 0x4000。注意当广播类型值大于
等于 3 时，取值范围：0Xa0~0x4000
adv_int_max：最大广播间隔，取值范围：0x0020 ~ 0x4000。注意当广播类型值大于
等于 3 时，取值范围：0Xa0~0x4000
adv_int_min 和 adv_int_max 填写 16 进制格式，如 10,FF 等
adv_type：广播类型，定义如下：
值

含义

1

ADV_TYPE_IND可扫描可连接非定向广播2

ADV_TYPE_DIRECT_IND_HIGH可连接快速定向广播

3

ADV_TYPE_SCAN_IND可扫描不可连接的非定向广播

4

ADV_TYPE_NONCONN_IND不可连接不可扫描非定向广播375ADV_TYPE_DIRECT_IND_LOW可连接慢速定向广播

own_addr_type：BLE地址类型，定义如下：（该值由协议栈根据privacy属性值自动
填充，AT指令默认填充0即可）
值

含义

0

BLE_ADDR_TYPE_PUBLIC

1

BLE_ADDR_TYPE_RANDOM

channel_map：广播信道，定义如下：
值

含义

1

ADV_CHNL_37

2

ADV_CHNL_38

4

ADV_CHNL_39

7

ADV_CHNL_ALL

adv_filter_policy：过滤器，定义如下：
值

含义

0

ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY

1

ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY

2

ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST3

ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST

peer_addr_type：对方BLE 地址类型，定义如下：
值

含义

0

PUBLIC1RANDOM

peer_addr：对方 BLE 地址。

38

6.4.1.4 AT+BLESCPRM
功能：
配置 BLE 扫描参数。
格式（ASCII）：
AT+BLESCPRM=<window>,<interval>,<scan_mode><CR>+OK<CR><LF><CR><LF>
参数：
windows：扫描窗口。[0x0004，0x4000],填写16进制格式，如10,FF等
interval：扫描间隔。[0x0004，0x4000]
scan_mode:扫描方式。[0,1] 被动扫描，主动扫描interval的值应大于等于windows，当interval等于windows时，意味控制器始终处于扫描状态，即扫描窗口一直处于打开状态。
6.4.1.5 AT+BLESCAN
功能：
启动或停止扫描。
格式（ASCII）：
AT+BLESCAN=<mode><CR>+OK<CR><LF><CR><LF>
参数：
mode：操作模式，定义如下：
值

含义

0

停止扫描

1

启动扫描

扫描结果如下图所示：39

6.4.1.6 AT+&BTNAME
功能：
设置/读取蓝牙名称。
格式（ASCII）：
设置 AT+&BTNAME=[!]<name><CR>读取 AT+&BTNAME
设置返回：+OK,<CR><LF><CR><LF>
读取返回：+OK=NAME,<CR><LF><CR><LF>
参数：
Name 蓝牙名称，ASCII 串。最大长度 16 字节。
6.4.1.7 AT+&BTMAC
功能：设置/读取蓝牙 MAC 地址。
格式（ASCII）：
设置 AT+&BTMAC=<MAC><CR>读取 AT+&BTMAC
设置返回：+OK,<CR><LF><CR><LF>
读取返回：+OK=MAC,<CR><LF><CR><LF>
参数： MAC 地址
设置示例：AT+&BTMAC=c00d308a0b08
6.4.1.8 AT+ BLESSCM
功能：
指定 BLE 在特定信道扫描。
格式（ASCII）：
AT+ BLESSCM=CH+OK
参数：CH 定义为：值含义

1

指定37信道扫描2

指定38信道扫描4

指定39信道扫描7

跳频，在37、38、39依次扫描（默认）40

6.4.2 BLE 辅助 WiFi 配网 AT 指令
6.4.2.1 AT+ONESHOT
功能：
启动或停止配网服务。
格式（ASCII）：
AT+ONESHOT=<mode><CR>+OK=<mode><CR><LF><CR><LF>
参数：
mode：操作模式，定义如下：

注意：

值

含义

0

停止配网

1

启动UDP配网2

启动SoftAP+Socket配网

3

启动SoftAP+WebServer配网

4

启动蓝牙配网

启 动蓝 牙

配网后，用户可以使用手机 APP 进行配置 WiFi 信息。配网成功后，配网服务自动注销，蓝牙关闭广播。如需再次配网请再次启动蓝牙配网。
6.4.3 状态码定义：
6.4.3.1 HCI Reason 码定义：Success

0x00

Unknown HCI Command

0x01

Unknown Connection Identifier

0x02

Hardware Failure

0x03

Page Timeout

0x04

Authentication Failure

0x05

PIN or Key Missing

0x06

Memory Capacity Exceeded

0x07

Connection Timeout

0x08

Connection Limit Exceeded

0x09

Synchronous

Connection

Limit

To

A

Device 0x0a

Exceeded
ACL Connection Already Exists

0x0b
41

Command Disallowed

0x0c

Connection Rejected due to Limited Resources

0x0d

Connection Rejected Due To Security Reasons

0x0e

Connection

RejectedduetoUnacceptable 0x0f

BD_ADDR
Connection Accept Timeout Exceeded

0x10

Unsupported Feature or Parameter Value

0x11

Invalid HCI Command Parameters

0x12

Remote User Terminated Connection

0x13

Remote Device Terminated Connection due to Low 0x14
Resources
Remote Device Terminated Connection due to 0x15
Power Off
Connection Terminated By Local Host

0x16

Repeated Attempts

0x17

Pairing Not Allowed

0x18

Unknown LMP PDU

0x19

Unsupported Remote Feature / Unsupported LMP 0x1a
FeatureSCO Offset Rejected

0x1b

SCO Interval Rejected

0x1c

SCO Air Mode Rejected

0x1d

Invalid LMP Parameters / Invalid LL Parameters 0x1e
Unspecified Error

0x1f

Unsupported LMP Parameter Value / Unsupported 0x20
LL Parameter Value
Role Change Not Allowed

0x21

LMP Response Timeout / LL Response Timeout

0x22

LMP Error Transaction Collision

0x23

LMP PDU Not Allowed

0x24

Encryption Mode Not Acceptable

0x25

Link Key cannot be Changed

0x26

Requested QoS Not Supported

0x27

Instant Passed

0x28

Pairing With Unit Key Not Supported

0x29
42

Different Transaction Collision

0x2aReserved

0x2b

QoS Unacceptable Parameter

0x2c

QoS Rejected

0x2d

Channel Classification Not Supported

0x2e

Insufficient Security

0x2f

Parameter Out Of Mandatory Range

0x30

Reserved

0x31

Role Switch Pending

0x32

Reserved

0x33

Reserved Slot Violation

0x34

Role Switch Failed

0x35

Extended Inquiry Response Too Large

0x36

Secure Simple Pairing Not Supported By Host

0x37

Host Busy – Pairing

0x38

Connection Rejected due to No Suitable Channel 0x39
Found
Controller Busy

0x3a

Unacceptable Connection Parameters

0x3b

Directed Advertising Timeout

0x3c

Connection Terminated due to MIC Failure

0x3d

Connection Failed to be Established

0x3e

MAC Connection Failed

0x3f

7

蓝牙 AT 指令操作示例

本章节结合具体示例，给出了蓝牙 AT 指令具体操作规范。黑色截图即 AT 指令的响应。
7.1 蓝牙系统使能与退出
7.1.1 使能蓝牙系统
AT+BTEN=1,0

7.1.2 退出蓝牙系统
AT+BTDES

43

7.2 开关示例广播7.2.1 使能蓝牙系统
AT+BTEN=1,0

7.2.2 开启可连接广播示例
AT+BLEDMADV=1

7.2.3 停止广播示例
AT+BLEDMADV=0

7.2.4 退出蓝牙系统
AT+BTDES
7.3 开关示例扫描7.3.1 使能蓝牙系统
AT+BTEN=1,0

7.3.2 开启扫描示例
AT+BLEDMSCAN=1

7.3.3 停止扫描示例
AT+BLEDMSCAN=044

7.3.4 退出蓝牙系统
AT+BTDES
7.4 开关示例 server
7.4.1 使能蓝牙系统
AT+BTEN=1,0

7.4.2 使能 demo server
AT+BLEDS=1
7.4.3 停止 demo server
AT+BLEDS=0
7.4.4 退出蓝牙系统
AT+BTDES
7.5 开关示例 client
7.5.1 使能蓝牙系统
AT+BTEN=1,0

7.5.2 使能示例 client
AT+BLEDC=1
7.5.3 停止示例 client
AT+BLEDC=0
7.5.4 退出蓝牙系统
AT+BTDES
7.6 开关多连接示例 client
7.6.1 使能蓝牙系统
AT+BTEN=1,0

7.6.2 使能多连接 demo client
AT+BLEDCMC=1
7.6.3 停止 demo client
AT+BLEDCMC=0
7.6.4 退出蓝牙系统
AT+BTDES
45

7.7 开关 UART 透传
7.7.1 使能蓝牙系统
AT+BTEN=1,0

7.7.2 使能 UART 透传 Server/Client 端
AT+BLEUM=1,1 //使能 UART 透传的 server 端，采用 UART1 透传
AT+BLEUM=2,1 //使能 UART 透传的 client 端，采用 UART1 透传
7.7.3 停止 UART 透传
AT+BLEUM=0,1 //关闭 server 端 UART 透传模式
AT+BLEUM=0,2 //关闭 client 端 UART 透传模式7.7.4 退出蓝牙系统
AT+BTDES

7.8 使能辅助 WiFi 配网服务7.8.1 开启蓝牙功能，使能配网服务
AT+BTEN=1,0//使能蓝牙系统

AT+ONESHOT=4//开启配网服务

此时可以用 APP 进行配网操作；注意配网成功后，系统会自动注销配网服务。

7.8.2 退出辅助 WiFi 配网服务注销蓝牙系统
AT+ONESHOT=0
AT+BTDES//退出配网服务
//退出蓝牙系统

7.9 W800 测试模式
W800 支持实时进入测试模式，客户可以用于测试 RF 性能及控制器功能测试和认证测试。
7.9.1 W800 进入测试模式
AT+BTTEST=1//进入蓝牙测试，此时可以用测试工具通过配置的 uart 口直接操作 controller。

46

7.9.2 W800 退出信令测试
AT+BTTEST=0//退出测试模式，此时主机协议栈控制 controller.

47