(This article was originally written in Chinese. To see an English version, please go to the bottom of the page and click on the Translate button.)

问题

如何使用Inter-Pan消息实现两个不同网络的设备之间的单跳通信？

答案

Inter-Pan消息可用于不同网络，同一信道的两个设备之间的单跳通信。Silicon Labs提供Inter-Pan Plugin，方便客户在此Plugin的基础上扩展，以在自己的应用中实现Inter-Pan消息的发送和接收。本文主要介绍如何搭建和测试Inter-Pan的功能，并以Z3Light sample（EmberZnet stack v5.10）为例，在WSTK+4151 无线板子上进行演示。

1. Inter-Pan Plugin的源码位于协议栈的C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v1.1\protocol\zigbee_5.10\app\framework\plugin\interpan

1. 在Z3Light sample中已经勾选该Inter-Pan Plugin。创建并编译该Z3Light sample，将固件以及对应的Bootloader烧录到两块WSTK 4151无线板。

1. 两块无线板启动之后会自动扫描网络并加入Centralized，如果没有网络可以加入，最后会建立自己Distributed网络。在此实验中，每个板子分别建立自己的Distributed网络，确保它们处于同一个信道即可。如果比较难建立同一信道上的不同网络，也可以分别加入两个同一信道不同PANID的网络。如下所示，两个板子分别建立好自己的网络。

AppBuilder MFG Code: 0x1002
node [(>)000B57FFFE07F6E3] chan [20] pwr [3]
panID [0xF052] nodeID [0xCBD9] xpan [0x(>)0D03351F0A0587C6]
stack ver. [5.10.0 GA build 36]
nodeType [0x02]
Security level [05]
network state [02] Buffs: 74 / 75

AppBuilder MFG Code: 0x1002
node [(>)000B57FFFE07F6E2] chan [20] pwr [3]
panID [0x2923] nodeID [0x390E] xpan [0x(>)87461289F0783C2F]
stack ver. [5.10.0 GA build 36]
nodeType [0x02]
Security level [05]
network state [02] Buffs: 75 / 75

1. 通过CLI命令测试Inter-Pan消息的发送和接收。在Simplicity Studio中，将两个设备对应的Console打开，在一个Console中输入如下命令：

plugin interpan fragment-test [panId:2] [eui64:8] [clusterId:2] [msgLen:2]

• Sends a message of specified length of random values to target device over inter-PAN.
  • panId - INT16U - The PAN ID that the target is located on
  • eui64 - IEEE_ADDRESS - The target's EUI64 (big endian)
  • clusterId - INT16U - The cluster ID that the sample message should contain
  • msgLen - INT16U - The length of the randomly-filled message to be sent across inter-PAN

plugin interpan fragment-test 0xFFFF {000B57FFFE07F6E3}  0x0000 10

其中第一个参数是目的设备的PANID，可以设置为0xFFFF。

第二个参数是目的设备的EUI64，可以设置为NULL代表广播消息，否则为单播。

第三个参数是目的设备的Cluster。

第四个参数是发送的消息的Playload长度。

1. 发送完上述命令，可在控制台中看到对应的输出信息：

发送端：

Z3LightSocV510MG1>Sending inter-PAN message of len 10 to (>)000B57FFFE07F6E3 with random values: T00000000:Inter-PAN TX (10) [A9 30 09 70 82 6D D1 A9 3B 14 ], 0x00
success (0x00)

接收端：

RX inter-PAN message (unicast):
  src pan id: 0x2923
  src long id: (>)000B57FFFE07F6E2
  profile id: 0x0109
  cluster id: 0x0000 (Basic)
ERR: Inter-PAN profile 0x0109, cluster 0x0000, command 0x09 not permitted

以上打印信息表明Inter-Pan消息发送成功。用户可根据自己的需求，构建自定义的消息。

1. 函数流程分析：

发送流程：

当输入plugin interpan fragment-test，最调用如下函数：

void emAfInterpanFragmentTestCommand(void)

|-- emberAfSendInterPan()

|-- emberAfInterpanSendMessageCallback()

    |-- makeInterPanMessage()

    |-- emAfPluginInterpanSendRawMessage()

        |-- emberSendRawMessage()

最核心的函数是emberSendRawMessage()，其在raw-message.h中定义。

/** @brief Sends the given message over the air without higher layer
 * network headers.
 *
 * The first two bytes are interpreted as the 802.15.4 frame control field.
 * If the Ack Request bit is set, the packet will be retried as necessary.
 * Completion is reported via ::emberRawTransmitCompleteHandler().
 * Note that the sequence number specified in this packet is not taken into
 * account by the MAC layer. The MAC layer overwrites the sequence number field
 * with the next available sequence number.
 *
 * @param message  The message to transmit.
 *
 * @return ::EMBER_SUCCESS if the message was successfully submitted to
 * the transmit queue, and ::EMBER_ERR_FATAL otherwise.
 */
EmberStatus emberSendRawMessage(EmberMessageBuffer message);

如果想发送广播消息， 可将emberAfSendInterPan()的参数改为如下格式：

EmberStatus status = emberAfSendInterPan( OxFFFF,
                     NULL,
                     EMBER_NULL_NODE_ID,
                     0,      // mcast id - unused
                     clusterId,
                     SE_PROFILE_ID, // GBCS only
                     messageLen,
                     testMessage);

接收流程：

当接收到Inter-Pan消息时，emberMacPassthroughFilterHandler()会被调用，其在raw-message.h中定义。

/** @brief This function is called when the stack has received a raw MAC message that has
 *    matched one of the application's configured MAC filters.
 *
 * @param macFilterMatchStruct This is a pointer to a structure containing information
 *   about the matching message, including the index of the filter that was matched,
 *   and the actual data of the message.
 */
void emberMacFilterMatchMessageHandler(const EmberMacFilterMatchStruct* macFilterMatchStruct);

emberMacFilterMatchMessageHandler()

    |-- emAfPluginInterpanProcessMessage()

        |-- emberAfPluginInterpanPreMessageReceivedCallback()

以上就是Inter-Pan消息的测试过程以及发送和接收流程的源码分析，更多信息请参考Inter-Pan Plugin的源码。

问题

为 EM35x 芯片启用读保护或写保护

回答

当为现场部署准备 EM35x 设备时，通常希望保护 EM35x 芯片的闪存内容，以防止意外/未授权的访问或修改。这可以通过使用芯片的内存保护（读保护和写保护）机制实现，相关内容在 5.2.1（闪存 ）和 5.3（存储器保护单元）章节的 EM35x 数据表中进行了介绍。

下面是客户在考虑为其设备进行此类保护时经常询问的问题：

问题：可以提供何种保护，它们保护什么？

回答：此芯片提供读保护和写保护。

启用读保护时，如果芯片的 SerialWire / JTAG 接口 (SWJ) 连接着某些器件，将断开所有其他器件的所有闪存。这样可有效防止读取设备上的任何闪存，包括主闪存块（其中覆盖了引导装载程序区、应用程序代码和数据区以及 SimEEPROM 令牌区），以及 FIB（存储 Ember 编程的制造令牌闪存信息块和低级别闪存读/写例程）和 CIB（存储客户可编程的制造令牌的客户信息块）的全部 128KB 或 192KB。这也避免了为 SerialWire 和 JTAG 操作（如调试器存取和闪存编程）使用 SWJ 总线。由于读保护只能通过在特定位置写入特定的非零非 0xFF 值禁用，擦除 CIB 内存页（其中包含读保护选项字节）的操作（无论是有意还是无意的）仍将使芯片保持读保护状态，直到相应的选项字节设置为相应的值。

启用写保护时，将防止通过外部手段或通过执行闪存或 RAM 中的代码写入或擦除主闪存块 [MFB]。与读保护不同，写保护将按区域启用，每个区域具有 4 页闪存或 8KB。

问题：Ember 建议对在批量生产中部署的设备使用何种保护？

回答：对于部署到现场中的设备，在不是必须进行进一步调试和高级测试的情况下，Ember 建议启用第一个 8KB 区域的读保护（这是芯片级）以及写保护，该区域是引导装载程序固件在 MFB 上的位置。

问题：如何使用 ISA3 和 ISA3 实用工具启用这些建议的保护设置？

回答：启用这些设置需要从命令行使用 ISA3 实用工具；InSight Desktop 目前不提供通过 GUI 将这些选项传送到装载程序的接口。

启用写保护

要启用主闪存的第一个区域的写保护（引导装载程序所在位置），为写保护（选项字节 4）仅清除第一个选项字节的 0 位（写入 0），所有其他位保持置位（擦除状态 1），最终的位掩码为 0xFFFFFE。这可以通过 em3xx_load 或 em3xx_buildimage 中的“—programwrprot”选项完成，例如：

em3xx_load.exe --programwrprot FFFFFE

注意，当前 Ember 的实施方式是无论是否启用读保护，都对第一个区域自动执行写保护。但是，建议明确设置写保护掩码以包含第一个闪存区域，从而确保万一在今后工具/硅修订版本中此自动行为发生变化，也能得出一致的结果。

启用读保护

注意：启用读保护应该总是在使用 em3xx_load 或 em3xx_buildimage 的设备上执行的最后一项操作，因为设置此选项会有效地禁止在将来对芯片/图像状态进行的任何改变，除非读保护被禁用（这样做将导致 MFB 和 CIB 被擦除）。

要启用读保护，可以将 CIB 的选项字节 0 设置为 0×00（虽然除特定值 0xA5 外的任何值都可以）。这可以通过使用 em3xx_load 或 em3xx_buildimage 中的 “—enablerdprot”标志来完成，例如：

em3xx_buildimage.exe --em357 --chipimage myimage.hex serial-uart-bootloader.s37 sensor.ebl --enablerdprot

这会从两个输入文件 serial-uart-bootloader.s37 和 sensor.ebl 构建一个 EM357 芯片图像输出文件 myimage.hex。同时，通过将选项字节 0 设置为值 0×00，在 HEX 文件的 CIB 内容中启用读保护。将此芯片图像（HEX 文件）编程到一个新的设备上，将确保它包含必要的应用程序代码、引导装载程序代码和读保护。使用“—cibtokenspatch”参数与一个制造令牌补丁文件可以设置 CIB 中的其他制造令牌内容（如 em3xx_buildimage 或 em3xx_load 中的“—cibtokenspatch-help”参数所解释的那样）。

问题：如果启用写保护，会如何影响引导装载程序？

回答：（请注意，以下内容适用于 Ember 提供的所有引导装载程序类型。） 通过对引导装载程序所在的主闪存的第一个 8KB 区进行写保护，可以防止对引导装载程序代码和芯片的复位向量的意外/未经授权的覆盖。但是，如果对此区域以外的区域进行写保护，会妨碍引导装载程序将下载的固件图像写入 MFB 的应用区域，从而使之失效。这就是如果在存储器映射中使用引导装载程序，Ember 建议使剩余闪存区域的写保护保持禁用状态的原因。

如果由于某种原因，您希望部署不允许引导加载的设备，可以保护 MFB 的其他区域。但是，注意不要对用于模拟 EEPROM 的区域启用写保护，这个区域通常是 MFB 的最后一个 8KB 区域（或在某些 EZSP 网络协处理器设计中是最后一个 32KB 区域），因为这会妨碍堆栈向网络和安全相关的令牌写入的正常操作。

问题：对于没有被写保护设置覆盖的区域，是什么情况？ 它们很容易从外部调试器/编程器写入吗？

回答：是的，未被写保护覆盖的区域可能很容易从外部调试器/编程器或从执行闪存写入例程的错误代码擦除和写入，即使启用了读保护。读保护会防止读取闪存，但擦除和写入是通过一个闪存接口控制器进行的，该控制器永不断开，无需读取即可运行。（请注意，当发现启用了读保护时，Ember 的编程工具将禁止对闪存的写入/擦除，以防止在使用 Ember 的工具时，闪存数据被意外或恶意的破坏。） 因此，最保险和最安全的操作方式是除了必须保持可写的模拟 EEPROM 以外，对闪存的所有敏感区域进行写保护，并且启用读保护。（如上面所讨论的那样，写保护应用程序代码覆盖的闪存区域将阻碍通过引导装载程序更新代码。）

问题：如果在写入一个选项字节时发生故障，比如复位，会发生什么？

回答：如果选项字节本身被以某种方式破坏，芯片具有一种检测这种状态的方法，并且只会引导至深度睡眠模式，直到通过对 CIB 内存页执行擦除/重新编程操作来解决故障。当检测到损坏时，选项字节被假定为已擦除状态，这将激活读保护。Ember 的 em3xx_load 工具可以检测这种故障/损坏，使用“—fixobfail”参数以及此工具可以修复此问题。

问题：在以建议的配置启用读保护和写保护的设备上，还有哪些可用的调试机制？

回答：即使启用了读保护，仍保留 ISA3 的 DEI Port 功能（就是到 GPIO 的 TTL 接口）和 ISA3 的 PacketTrace Interface [PTI] 功能（为数字双线协议使用 GPIO 的备用功能）。此外，在启用读保护和/或写保护时，仍可以保持正常的数字 I/O 和串行控制器的使用。

问题：虚拟 UART 接口（InSight Desktop Console 中的 Serial 0）怎么样？

回答：因为虚拟 UART 机制是在 ARM Cortex 的 SerialWire 协议顶层实施，而它使用 SerialWire/JTAG [SWJ] 总线，所以在启用读保护时此机制不可用。读保护和 SWJ 总线访问互不相容。不过，如果芯片的运行固件启用物理 UART（TXD 和 RXD 引脚，PB1 和 PB2），您仍然可以使用 UART。这些 TTL 信号可以通过 ISA3 的 DEI 接口路由以作为 InSight 桌面控制台的“串口 1”访问，如 EM35x 分线板硬件上所示。

问题：如果启用读保护和写保护，稍后可以将其禁用吗？

回答：是的，可以通过 ISA3 实用工具禁用读保护和/或写保护。

要禁用读保护时，可以使用“—disablerdprot”命令参数以及 em3xx_load 或 em3xx_buildimage 来完成，从而将选项字节 0 设置为特殊值 0xA5。选项字节 0 的其他任何状态都会使读保护处于激活状态。注意，在实际芯片上禁用此功能（使用 em3xx_load）将导致其 MFB 和 CIB（除选项字节 0 外）被完全擦除回 0xFF 字节。

要禁用写保护时，可以使用 “—programwrprot” 命令参数将写保护选项字节设置回全 0xFF 状态，例如“em3xx_load —programwrprot FFFFFF”。（注意，0xFFFFFF 的“编程”状态与擦除 [非编程] 状态的处理方式不同，因为在编程选项字节时，每个选项字节的校验和值也通过 ISA3 实用工具编程。一旦选项字节被编程，要更改该选项字节的值，必须先擦除 CIB。

问题：禁用读保护之后，有不被擦除的内容吗？

回答：有，禁用读保护之后，FIB（用于存储 Ember 编程的制造令牌）保持不变。禁用读保护之后，不保存 MFB 和 CIB。尽管在禁用读保护期间芯片的自动擦除仅影响 MFB（其中存放堆栈和应用程序令牌以及引导装载程序和堆栈/应用程序固件），要修补 CIB 中的选项字节以禁用读保护，需要擦除并重写整个 CIB 页（因为只能按页擦除），并且除非写入非保护状态（选择字节 0 具有值 0xA5）否则现有无法读取现有 CIB 内容，因此由于 CIB 修补过程导致的新写入的 CIB 页必须包含完全擦除的字节（选项字节 0 以外的字节），这意味着原始 CIB 内容均无法保存。

Question

How do I setup Custom MFG Tokens?

Answer

The first thing to do when setting you custom manufacturing tokens depends on whether or not you want to use a custom token header file. It does not matter if you choose to use a custom header file, or if you modify the generated token header file as it will be the only one used in the project. However, if you do decide to use your own custom header file you must define APPLICATION_MFG_TOKEN_HEADER to be your custom header file in your IAR preprocessor. When creating a custom token header file, token.h has helpful instructions. It is also important not to use inclusion guards (#ifndef/#define) in your application header files as the token reference scheme will not work with them. (If you are adding the define to App Builder, make sure to select the -D option).

Please note that if you do decide to modify the generated file you will need to be very careful not to overwrite it once modified. The main concern of it being overwritten is when you regenerate your project. At that point it will, by default, have the tokens file selected as being overwritten. Make sure to deselect it any time if you have made edits to the file that you want to keep.

General token definition found in token.h:
 

 * The most general format of a token definition is:
 *
 * @code
 * #define CREATOR_name 16bit_value
 * #define NVM3KEY_name 20bit_value
 * #ifdef DEFINETYPES
 *    typedef data_type type
 * #endif
 * #ifdef DEFINETOKENS
 *    DEFINE_*_TOKEN(name, type, ... ,defaults)
 * #endif
 * @endcode

Question

What are the different levels of debug in the EmberZNet and Silicon Labs Thread stacks, what features are enabled, and how do I access them?

Answer

Here is a summary of the three different debug options and how to access them.  

Note: The Packet Trace Interface (PTI) provided on PTI_FRAME and PTI_DATA (also called FRC_DFRAME and FRC_DOUT) pins is a separate peripheral configured in the HAL and isn't affected by the choice of debug levels below.

•NO DEBUG: Select this by disabling both the Debug Basic Library and the Debug Extended Library.  This causes the firmware not to use SWDIO or SWO at all for communications at runtime, but the Debug JTAG.  PTI ("Packet" events in Network Analyzer) will still be available if the peripheral is enabled, however.

•BASIC DEBUG:  This is the default behavior for new application configurations. This requires the Debug Basic Library plugin and the Debug JTAG plugin. Basic debug includes the following features:
1.node reset message ("Reset" events) with "ZnetVer" events to track stack version at init time
2.the assert output ("Assert" events)
3.core dump output ("CoreDump" events)
4.virtual UART input and output ("Printf" events) when "serial 0" port is enabled
5.basic node information request and response ("NodeInfo" events)

6.EZSP command and response transactions ("EZSP" events)

•FULL DEBUG :  This is a superset of Basic Debug functionality and requires adding the Debug Extended Library plugin to the above prerequisites of Basic Debug.  Added features in this mode include:
1.API call trace output ("APITrace" events)
2.debug error output (some additional "Printf" events)
3.debug printf output ("Debug" events) from emberDebugPrintf()