(http://www.bitconn.com/form_1/ 登记后,购买XBee模块,送USB评估底板及相关中文资料,或者免费申请借用评估套件)
目录
API模式
API模式提供了结构化的接口,在该接口中,数据通过串行接口以有组织的数据包和确定的顺序进行通信。这使您可以在设备之间建立复杂的通信,而不必定义自己的协议。
默认情况下,XBee设备配置为在透明模式下工作:通过串行输入接收的所有数据都排队等待进行无线电传输,以无线方式接收的数据将按接收到的方式精确地发送到串行输出,而没有其他信息。
因此,在透明模式下工作的设备有一些限制:
- 要在透明模式下读取或写入设备的配置,必须首先将设备转换为命令模式。
- 如果设备需要将消息传输到其他设备,则必须更新其配置以建立新的目的地。设备必须进入命令模式才能设置目标。
- 在透明模式下运行的设备无法识别其接收到的无线消息的来源。如果需要区分来自不同设备的数据,则发送设备必须包括所有设备已知的额外信息,以便以后可以提取。为此,您必须定义一个健壮的协议,其中包括您认为传输中需要的所有信息。
为了最小化透明模式的限制,设备提供了一种称为应用程序编程接口(API)的替代模式。API模式提供了结构化的接口,在该接口中,数据通过串行接口以有组织的数据包和确定的顺序进行通信。这使您无需定义自己的协议即可在模块之间建立复杂的通信。
API模式提供了一种执行以上所列操作的简便方法:
- 由于有不同的框架用于不同的目的(例如配置和通信),因此可以在不进入命令模式的情况下配置设备。
- 由于数据目标是API框架结构的一部分,因此您可以使用API模式将消息传输到多个设备。
- 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帧的校验和
- 添加数据包的所有字节,但起始定界符0x7E和长度(第二个和第三个字节)除外。
- 根据结果,仅保留最低的8位。
- 从0xFF减去该数量。
要计算给定帧的校验和:
启动定界符 | 长度 | 框架数据 | 校验和 | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
镜框类型 | 数据 | |||||||||||||||||
7E | 00 | 0F | 17 | 01 | 00 | 13 | A2 | 00 | 40 | AD | 14 | 2E | FF | FE | 02 | 44 | 42 | - |
- 添加除开始定界符和长度之外的所有字节:17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE + 02 + 44 + 42 = 481
- 从结果中,仅保留最低的8位:81。
- 减去0xFF产生的结果:FF-81 = 7E
在此示例中,0x7E是帧的校验和。
验证给定API框架的校验和
- 添加所有字节,包括校验和(不包括定界符和长度)。
- 如果校验和正确,则总和最右边的最后两位将等于FF。
在上面的示例中,我们要验证校验和为7E。
启动定界符 | 长度 | 框架数据 | 校验和 | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
镜框类型 | 数据 | |||||||||||||||||
7E | 00 | 0F | 17 | 01 | 00 | 13 | A2 | 00 | 40 | AD | 14 | 2E | FF | FE | 02 | 44 | 42 | 7E |
- 添加所有数据字节和校验和:17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE + 02 + 44 + 42 + 7E = 4FF
- 由于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位地址 还支持以下地址:
| |
6 | 0x13 | |||
7 | 0xA2 | |||
8 | 0x00 | |||
9 | 0x40 | |||
10 | 0xDA | |||
11 | 0x9D | |||
LSB 12 | 0x23 | |||
16位目的地址 | MSB 13 | 0xA6 | 设置为目标XBee的16位地址(如果知道)。 还支持以下地址:
| |
LSB 14 | 0xB9 | |||
广播半径 | 15 | 0x00 | 设置广播传输可能发生的最大跳数。如果设置为“ 0”,则广播半径将设置为最大跃点值。 | |
选项 | 16 | 0x00 | 支持的传输选项的位域
支持的值包括:
所有其他位必须设置为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 | 支持的传输选项的位域 支持的值包括:
| |
收到数据 | 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字节都是起始定界符:此字符不能是任何其他帧字段(长度,数据或校验和)的一部分,因为必须对其进行转义。
逃脱角色:
- 插入转义字符0x7D。
- 将其后面附加要转义的字节,并与0x20进行XOR运算。
在API 2模式下,length字段在帧中不包含任何转义字符,并且校验和是使用非转义数据计算的。
要以API 2模式表达以下API非转义帧:
启动定界符 |
长度 | 框架数据 |
校验和 | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
镜框类型 | 数据 | |||||||||||||||||
7E | 00 | 0F | 17 | 01 | 00 | 13 | A2 | 00 | 40 | AD | 14 | 2E | FF | FE | 02 | 4E | 49 | 6D |
0x13字节必须转义:
- 插入一个0x7D。
- 将字节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帧交换期间,将发生以下过程:
- 通过串行输入将AT命令(0x08)帧发送到设备。该框架包含本地XBee设备上的配置指令或查询参数。
- XBee设备处理命令并通过其串行输出返回AT命令响应(0x88)。如果AT命令帧的帧ID为0,则不发送此响应。
发送请求/接收数据包:发送和接收无线数据
传输请求帧封装了带有其远程目标和一些传输选项的数据。XBee模块接收的无线数据与远程发送器和接收选项一起包含在“接收数据包”帧中。
另外两个帧使用显式寻址。它们要求您指定应用程序层寻址字段(端点,群集ID,配置文件ID)。
有关显式寻址的更多信息,请参见深入Zigbee通信一章。
下图显示了在将无线数据传输到另一个XBee模块时,在串行接口上进行的API交换。
- 智能设备(主机)通过串行输入将发送请求(0x10)或显式寻址命令帧(0x11)发送到XBee A,以将数据发送到XBeeB。
- XBee A将帧中的数据无线传输到配置为同一帧中目标的模块;在这种情况下,目的地是XBeeB。
- 远程XBee B模块接收无线数据,并根据API选项(AO)设置的值,通过串行输出发送接收数据包(0x90)或显式Rx指示器(0x91)。这些帧包含通过无线方式接收的数据以及传输该数据的XBee模块的源地址,在本例中为XBeeA。
- 远程XBee B模块将具有状态的无线确认数据包发送到发送方XBeeA。
- 发送方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帧交换。
- 智能设备(主机)通过串行输入将远程AT命令请求(0x17)发送到XBee A,以配置远程XBeeB。
- XBee A将帧中的AT命令无线传输到同一帧中配置为目标的模块;在这种情况下,目的地是XBeeB。
- XBee B接收AT命令并处理该命令,以将结果无线返回给发送方XBeeA。
- XBee A通过其串行输出发送远程AT命令响应(0x97),并由XBee B处理AT命令的结果。如果远程AT命令帧的帧ID为'0',则不发送此响应。
源路由:创建并获取数据包的路由
XBee模块还允许您在模块中创建和获取源路由。源路由指定数据包从源到目的地所经过的完整路由。在这种情况下,在发送数据(发送请求或显式寻址命令帧)之前,必须使用以下数据包的路由发送创建源路由(0x21)。
将源路由与多对一路由结合使用可获得最佳效果,因此,应在发送方模块中将多对一路由广播时间(AR)参数设置为FF以外的其他值。
下图显示了发送创建源路由(0x21)帧时在串行接口进行的API交换。
- 智能设备(主机)通过串行输入将创建源路由(0x21)发送到XBee A,以指定以下数据到XBee B的路由。
- 智能设备(主机)通过串行输入将发送请求(0x10)或显式寻址命令帧(0x11)发送到XBee A,以将数据发送到XBeeB。
- 远程XBee B接收无线数据,并通过串行输出发送接收数据包(0x90)或显式Rx指示器(0x91)。该帧包含通过无线方式接收的数据以及传输该数据的XBee的源地址,在本例中为XBeeA。
- 远程XBee B将路由记录发送到发送方XBee A,并遵循发送数据的路由。
- 发送方XBee A通过其串行输出发送路由记录指示符(0xA1),其中包含接收的路由记录所经过的节点的16位地址。
- 发送方XBee A通过其串行输出发送传输状态(0x8B),并将传输状态发送至XBeeB。