XBee zigbee 使用指南---XBee API模式介绍

（http://www.bitconn.com/form_1/ 登记后，购买XBee模块，送USB评估底板及相关中文资料，或者免费申请借用评估套件）

目录

API模式的优点

API框架结构

          起始符

          长度

          帧数据

          校验和

计算API帧的校验和

验证给定API框架的校验和

支持的框架

帧实例

操作模式配置

XBee框架交互

AT命令：配置本地XBee设备

                 发送请求/接收数据包：发送和接收无线数据

                 远程AT命令：远程配置XBee模块

                 源路由：创建并获取数据包的路由

---

API模式

API模式提供了结构化的接口，在该接口中，数据通过串行接口以有组织的数据包和确定的顺序进行通信。这使您可以在设备之间建立复杂的通信，而不必定义自己的协议。

默认情况下，XBee设备配置为在透明模式下工作：通过串行输入接收的所有数据都排队等待进行无线电传输，以无线方式接收的数据将按接收到的方式精确地发送到串行输出，而没有其他信息。

因此，在透明模式下工作的设备有一些限制：

1. 要在透明模式下读取或写入设备的配置，必须首先将设备转换为命令模式。
2. 如果设备需要将消息传输到其他设备，则必须更新其配置以建立新的目的地。设备必须进入命令模式才能设置目标。
3. 在透明模式下运行的设备无法识别其接收到的无线消息的来源。如果需要区分来自不同设备的数据，则发送设备必须包括所有设备已知的额外信息，以便以后可以提取。为此，您必须定义一个健壮的协议，其中包括您认为传输中需要的所有信息。

为了最小化透明模式的限制，设备提供了一种称为应用程序编程接口（API）的替代模式。API模式提供了结构化的接口，在该接口中，数据通过串行接口以有组织的数据包和确定的顺序进行通信。这使您无需定义自己的协议即可在模块之间建立复杂的通信。

API模式提供了一种执行以上所列操作的简便方法：

1. 由于有不同的框架用于不同的目的（例如配置和通信），因此可以在不进入命令模式的情况下配置设备。
2. 由于数据目标是API框架结构的一部分，因此您可以使用API​​模式将消息传输到多个设备。
3. API框架包括消息的来源，因此很容易识别数据来自何处。

API模式的优点

• 在网络中配置本地和远程XBee设备。
• 管理到一个或多个目的地的无线数据传输。
• 标识每个接收到的数据包的源地址。
• 接收每个传输数据包的成功/失败状态。
• 获取任何接收到的数据包的信号强度。
• 执行高级网络管理和诊断。
• 执行高级功能，例如远程固件更新，ZDO，ZCL等。

API框架结构

API模式下的结构化数据包称为帧。它们通过设备的串行接口发送和接收，并且包含无线消息本身以及一些额外的信息，例如数据的目标/源或信号质量。

当设备处于API模式时，所有通过串行接口进入和离开模块的数据都包含在框架中，这些框架定义了设备内的操作或事件。

API框架具有以下结构：

开始 定界符	长度		帧数据								校验和
1	2	3	4	5	6	7	8	9	...	ñ	n + 1
0x7E	MSB	LSB	特定于API的结构								单字节

注意 MSB代表最高有效字节，而LSB代表最低有效字节。

XBee会静默丢弃在开始定界符之前通过串行接口接收的任何数据。如果未正确接收到帧，或者校验和失败，则数据也将被丢弃，并且模块会通过回复另一个帧来指示失败的性质。

起始符

起始定界符是帧的第一个字节，由指示数据帧开始的特殊位序列组成。它的值始终为0x7E。这允许容易地检测新的输入帧。

长度

长度字段指定帧数据字段中包含的字节总数。它的两个字节的值不包括起始定界符，长度和校验和。

帧数据

该字段包含已接收或将要发送的信息。框架数据是根据API框架的目的构造的：

开始 定界符	长度		帧数据								校验和
			帧 类型	数据
1	2	3	4	5	6	7	8	9	...	ñ	n + 1
0x7E	MSB	LSB	API 帧 类型	特定于帧类型的数据							单 字节

注意 MSB代表最高有效字节，而LSB代表最低有效字节。

• 帧类型是API框架类型标识符。它确定API框架的类型并指示如何在“数据”字段中组织信息。
• 数据包含数据本身。此处包含的信息及其顺序取决于“帧类型”字段中定义的帧类型。

校验和

校验和是帧的最后一个字节，有助于测试数据完整性。它是通过获取之前的所有API帧字节（不包括前三个字节（开始定界符和长度））的哈希总和来计算的。

注意通过串行接口发送的校验和不正确的帧将永远不会被模块处理，并且数据将被忽略。

计算API帧的校验和

1. 添加数据包的所有字节，但起始定界符0x7E和长度（第二个和第三个字节）除外。
2. 根据结果​​，仅保留最低的8位。
3. 从0xFF减去该数量。

示例：校验和计算

要计算给定帧的校验和：

启动定界符	长度		框架数据															校验和
			镜框类型	数据
7E	00	0F	17	01	00	13	A2	00	40	AD	14	2E	FF	FE	02	44	42	-

1. 添加除开始定界符和长度之外的所有字节：17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE + 02 + 44 + 42 = 481
2. 从结果中，仅保留最低的8位：81。
3. 减去0xFF产生的结果：FF-81 = 7E

在此示例中，0x7E是帧的校验和。

验证给定API框架的校验和

1. 添加所有字节，包括校验和（不包括定界符和长度）。
2. 如果校验和正确，则总和最右边的最后两位将等于FF。

示例：校验和验证

在上面的示例中，我们要验证校验和为7E。

启动定界符	长度		框架数据															校验和
			镜框类型	数据
7E	00	0F	17	01	00	13	A2	00	40	AD	14	2E	FF	FE	02	44	42	7E

1. 添加所有数据字节和校验和：17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE + 02 + 44 + 42 + 7E = 4FF
2. 由于4FF的最后两个最右位是FF，因此校验和正确。

支持的框架

对API框架类型的支持取决于您使用的XBee的类型。该套件中包含的802.15.4 XBee模块支持以下API框架：

传输数据帧通过串行输入发送，数据将无线传输到远程XBees：

API ID	框架名称	描述
0x08	AT指令	在本地XBee上查询或设置参数
0x09	AT命令队列参数值	在本地XBee上查询或设置参数，而无需应用更改
0x10	传送要求	将无线数据传输到指定的目的地
0x11	显式寻址命令框架	允许为无线数据传输指定Zigbee应用程序层字段（端点和群集ID）
0x17	远程AT命令请求	在指定的远程XBee模块上查询或设置参数
0x21	创建源路线	在模块中创建源路由
0x24	注册加入设备	在信任中心注册模块

接收数据帧通过串行输出接收，数据从远程XBees无线接收：

API ID	框架名称	描述
0x88	AT指令回应	显示对先前AT命令帧的响应
0x8A	调制解调器状态	显示事件通知，例如重置，关联，取消关联等。
0x8B	传输状态	指示无线数据传输成功或失败
0x90	接收数据包	通过串行接口发送无线接收的数据（AO = 0）
0x91	明确的接收指标	启用显式模式（AO 0）时，将无线接收的数据发送到串行接口
0x92	IO数据样本接收指示器	通过串行接口发送无线接收的IO数据
0x94	XBee传感器读取指示器	将无线接收的传感器样本（通过Digi 1-wire传感器适配器）发送出串行接口
0x95	节点标识指示器	禁用显式模式（AO = 0）时显示收到的节点标识消息
0x97	远程AT命令响应	显示对先前远程AT命令请求的响应
0x98	扩展调制解调器状态	显示启用“详细加入”（DC10）时在关联期间发生的情况
0XA0	无线固件更新状态	提供固件更新传输尝试的状态指示
0xA1	路由器记录指示器	在Zigbee路由记录命令后显示多条路由希望
0xA3	多对一路线请求指示器	表示收到多对一路由请求
0xA5	加入通知状态	表示模块尝试加入，重新加入或离开网络

有关其中某些框架的结构的更多信息，请参见《XBee / XBee-PRO Zigbee射频模块用户指南》。

帧实例

以下发送和接收的API帧示例以十六进制格式表示。

示例：0x10-发送请求

以下帧是具有以下特征的发送请求帧：

7E 00 13 10 01 00 13 A2 00 40 DA 9D 23 A6 B9 00 00 48 65 6C 6C 6F 0C

• 帧ID为0x01，因此发送方将接收带有发送结果的“发送状态”帧。
• 目标XBee具有64位地址00 13 A2 00 40 DA 9D 23和16位地址A6 B9。
• 它没有指定任何选项。
• 要发送的数据为“ Hello”（48 65 6C 6C 6F）。

框架领域		偏移量	例	描述
起始符		0	0x7E
长度		MSB 1	0x00	长度和校验和之间的字节数
		LSB 2	0x13
帧数据	帧类型	3	0x10	0x10-表示这是一个发送请求帧
	帧号	4	0x01	标识主机的数据帧，使其与后续的发送状态（0x8B）帧相关。   将帧ID设置为“ 0”将禁用响应帧。
	64位目标地址	MSB 5	0x00	设置为目标XBee的64位地址 还支持以下地址： 0x0000000000000000-协调器地址 0x000000000000FFFF-广播地址 0xFFFFFFFFFFFFFFFF-未知地址，如果目标的64位地址未知
		6	0x13
		7	0xA2
		8	0x00
		9	0x40
		10	0xDA
		11	0x9D
		LSB 12	0x23
	16位目的地址	MSB 13	0xA6	设置为目标XBee的16位地址（如果知道）。 还支持以下地址： 0x0000-协调器地址 0xFFFE-如果目标的16位地址未知，或者发送广播，则取消确认地址
		LSB 14	0xB9
	广播半径	15	0x00	设置广播传输可能发生的最大跳数。如果设置为“ 0”，则广播半径将设置为最大跃点值。
	选项	16	0x00	支持的传输选项的位域   支持的值包括： 0x01-禁用重试 0x20-启用APS加密（如果EE = 1） 0x40-为此目的地使用扩展的传输超时 所有其他位必须设置为0。  启用APS加密会将RF有效负载字节的最大数量减少4（低于NP报告的值）。  设置扩展超时位会使堆栈为目标地址设置扩展传输超时。
	射频数据	MSB 14	0x48	最多255个字节的数据发送到目标XBee
		15	0x65
		...	0x6C
		17	0x6C
		LSB 18	0x6F
校验和		22	0x6E	帧数据字节的哈希和

例如：0x91-显式的接收指标

以下框架是具有以下特征的“显式接收指示器”框架：

7E 00 17 91 00 13 A2 00 40 DA 9D 05 00 00 E8 E8 00 11 C1 05 01 48 65 6C 6C 6F 61

• 发送该数据的XBee模块具有64位地址00 13 A2 00 40 DA 9D 05和16位地址00 00。
• 发起传输源的终点是E8和目标端点是E8。
• 数据寻址到的群集ID是00 11。
• 数据寻址到的配置文件ID为C1 05。
• 因为接收选项值为01，所以确认了该数据包。
• 接收到的数据“ Hello”为（48 65 6C 6C 6F）。

框架领域		偏移量	例	描述
起始符		0	0x7E
长度		MSB 1	0x00	长度和校验和之间的字节数
		LSB 2	0x17
帧数据	帧类型	3	0x91	0x91-表示这是一个显式Rx指示器帧
	64位源地址	MSB 4	0x00	发件人的64位地址   如果发件人的64位地址未知，则设置为0xFFFFFFFFFFFFFFFFFF（未知的64位地址）
		5	0x13
		6	0xA2
		7	0x00
		8	0x40
		9	0xDA
		10	0x9D
		LSB 11	0x05
	16位源网络地址	MSB 12	0x00	发件人的16位地址
		LSB 13	0x00
	源端点	14	0xE8	发起传输的源的端点
	目的端点	15	0xE8	消息发送到的目的地的端点
	簇ID	16	0x00	邮件发送到的群集ID
		17	0x11
	profile ID	18	0xC1	邮件发送到的个人资料ID
		19	0x05
	接收选项	20	0x01	支持的传输选项的位域 支持的值包括： 0x01-数据包已确认 0x02-数据包是广播数据包 0x20-使用APS加密对数据包进行加密 0x40-启用扩展超时发送的数据包
	收到数据	MSB 21	0x48	从源XBee接收的最多255个字节的数据
		22	0x65
		...	0x6C
		24	0x6C
		25 LSB	0x6F
校验和		26	0x61	帧数据字节的哈希和

操作模式配置

API Enable（AP）参数将XBee模块配置为使用基于帧的API而不是默认的透明模式进行操作。它允许您在两种受支持的API模式和默认透明操作之间进行选择。

模式	AP值	描述
Transparent	0	API模式已禁用，模块以透明模式运行
API 1	1	API模式，没有转义字符
API 2	2	带有转义字符的API模式

API 1和API 2之间的唯一区别是API 2操作模式要求帧使用转义字符（字节）。

串行XBee通信的配置（无论是透明的，API非转义的（API 1）还是API转义的（API 2））都不会阻止XBee模块之间的无线通信。由于仅API帧的有效负载部分是通过空中传输的，因此接收XBee模块将根据其AP设置更改数据包信息，从而允许API非转义模块成功与以API转义或透明模式工作的其他模块进行通信。

注意在透明模式下工作的设备以及设置为非转义API（API 1）操作的模块可以与配置为在转义模式（API 2）下工作的设备进行通信。

API转义的操作模式（API 2）

API非转义（API 1）操作仅依靠起始定界符和长度字节来区分API帧。如果数据包中的字节丢失，则长度计数将关闭，并且下一个API帧（数据包）也将丢失。API转义（API 2）操作涉及在API帧中转义字符序列，以提高可靠性，尤其是在嘈杂的RF环境中。

两种API模式的基本帧结构都相同，但是在API转义（API 2）模式下，如果需要，必须转义除起始定界符以外的所有字节。在API 2模式下必须转义以下数据字节：

• 0x7E：开始定界符
• 0x7D：转义字符
• 0x11：XON
• 0x13：XOFF

API 2模式保证接收到的所有0x7E字节都是起始定界符：此字符不能是任何其他帧字段（长度，数据或校验和）的一部分，因为必须对其进行转义。

逃脱角色：

1. 插入转义字符0x7D。
2. 将其后面附加要转义的字节，并与0x20进行XOR运算。

在API 2模式下，length字段在帧中不包含任何转义字符，并且校验和是使用非转义数据计算的。

示例：转义API框架

要以API 2模式表达以下API非转义帧：

启动定界符	长度		框架数据															校验和
			镜框类型	数据
7E	00	0F	17	01	00	13	A2	00	40	AD	14	2E	FF	FE	02	4E	49	6D

0x13字节必须转义：

1. 插入一个0x​​7D。
2. 将字节0x13与0x20异或：13×20 = 33。

这就是生成的帧。请注意，长度和校验和与非转义帧相同。

启动定界符	长度		框架数据																校验和
			镜框类型	数据
7E	00	0F	17	01	00	7D	33	A2	00	40	AD	14	2E	FF	FE	02	4E	49	6D

XBee框架交互

现在您已经了解了API模式的工作原理和API框架的结构，下一步是了解执行某些常见操作（如配置XBee模块或传输无线数据）时如何交换框架。

以下部分提供了使用XCTU的示例。您可以使用XCTU控制台的Frames解释器工具查看详细的API框架结构。

AT命令：配置本地XBee设备

要查询或设置本地XBee的值（即，通过串行接口直接连接到智能设备（如微控制器或PC）的设备），必须使用AT参数和命令。这些是在“透明/命令”模式下可用的相同AT参数和命令，但包含在AT命令（0x08）帧中。包含操作结果的响应将在AT命令响应（0x88）帧中发送回去。

下图显示了发送AT命令（0x08）或AT命令队列参数值（0x09）请求时在串行接口上​​发生的API帧交换。

在API帧交换期间，将发生以下过​​程：

1. 通过串行输入将AT命令（0x08）帧发送到设备。该框架包含本地XBee设备上的配置指令或查询参数。
2. XBee设备处理命令并通过其串行输出返回AT命令响应（0x88）。如果AT命令帧的帧ID为0，则不发送此响应。

发送请求/接收数据包：发送和接收无线数据

传输请求帧封装了带有其远程目标和一些传输选项的数据。XBee模块接收的无线数据与远程发送器和接收选项一起包含在“接收数据包”帧中。

另外两个帧使用显式寻址。它们要求您指定应用程序层寻址字段（端点，群集ID，配置文件ID）。

有关显式寻址的更多信息，请参见深入Zigbee通信一章。

下图显示了在将无线数据传输到另一个XBee模块时，在串行接口上​​进行的API交换。

 

1. 智能设备（主机）通过串行输入将发送请求（0x10）或显式寻址命令帧（0x11）发送到XBee A，以将数据发送到XBeeB。
2. XBee A将帧中的数据无线传输到配置为同一帧中目标的模块；在这种情况下，目的地是XBeeB。
3. 远程XBee B模块接收无线数据，并根据API选项（AO）设置的值，通过串行输出发送接收数据包（0x90）或显式Rx指示器（0x91）。这些帧包含通过无线方式接收的数据以及传输该数据的XBee模块的源地址，在本例中为XBeeA。
4. 远程XBee B模块将具有状态的无线确认数据包发送到发送方XBeeA。
5. 发送方XBee A模块通过其串行输出发送传输状态（0x8B），并将传输状态发送至XBeeB。

除非在传输请求中将帧ID设置为“ 0”，否则始终在无线数据传输结束时发送传输状态（0x8B）帧。如果数据包无法传递到目的地，则传输状态帧将指示失败原因。

要使用显式帧发送数据：

• 源端点和目标端点必须为E8。
• 集群ID必须为0011。
• 配置文件ID必须为C105。

要接收显式帧，必须将API Options（AO）参数配置为API Explicit Rx Indicator-0x91 [1]。如果此设置为API Rx Indicator-0x90 [0]，则将接收到接收数据包（0x90），而不是显式Rx指示器（0x91）。

远程AT命令：远程配置XBee模块

在API模式下工作还允许您无线配置远程XBee模块。可以在本地发出的任何AT命令或参数也可以无线发送以在远程XBee模块上执行。

下图显示了发送远程AT命令请求（0x17）以远程读取或设置XBee参数时在串行接口上​​发生的API帧交换。

1. 智能设备（主机）通过串行输入将远程AT命令请求（0x17）发送到XBee A，以配置远程XBeeB。
2. XBee A将帧中的AT命令无线传输到同一帧中配置为目标的模块；在这种情况下，目的地是XBeeB。
3. XBee B接收AT命令并处理该命令，以将结果无线返回给发送方XBeeA。
4. XBee A通过其串行输出发送远程AT命令响应（0x97），并由XBee B处理AT命令的结果。如果远程AT命令帧的帧ID为'0'，则不发送此响应。

源路由：创建并获取数据包的路由

XBee模块还允许您在模块中创建和获取源路由。源路由指定数据包从源到目的地所经过的完整路由。在这种情况下，在发送数据（发送请求或显式寻址命令帧）之前，必须使用以下数据包的路由发送创建源路由（0x21）。

将源路由与多对一路由结合使用可获得最佳效果，因此，应在发送方模块中将多对一路由广播时间（AR）参数设置为FF以外的其他值。

下图显示了发送创建源路由（0x21）帧时在串行接口进行的API交换。

1. 智能设备（主机）通过串行输入将创建源路由（0x21）发送到XBee A，以指定以下数据到XBee B的路由。
2. 智能设备（主机）通过串行输入将发送请求（0x10）或显式寻址命令帧（0x11）发送到XBee A，以将数据发送到XBeeB。
3. 远程XBee B接收无线数据，并通过串行输出发送接收数据包（0x90）或显式Rx指示器（0x91）。该帧包含通过无线方式接收的数据以及传输该数据的XBee的源地址，在本例中为XBeeA。
4. 远程XBee B将路由记录发送到发送方XBee A，并遵循发送数据的路由。
5. 发送方XBee A通过其串行输出发送路由记录指示符（0xA1），其中包含接收的路由记录所经过的节点的16位地址。
6. 发送方XBee A通过其串行输出发送传输状态（0x8B），并将传输状态发送至XBeeB。