（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。
