Our stack defaults the route table size to 16, and it is defined in stack\config\ember-configuration-defaults.h:
#ifndef EMBER_ROUTE_TABLE_SIZE #ifdef EMBER_MIN_ROUTE_TABLE_SIZE #define EMBER_ROUTE_TABLE_SIZE EMBER_MIN_ROUTE_TABLE_SIZE #else #define EMBER_ROUTE_TABLE_SIZE 16 #endif #elif defined(EMBER_MIN_ROUTE_TABLE_SIZE) \ && EMBER_ROUTE_TABLE_SIZE < EMBER_MIN_ROUTE_TABLE_SIZE #error "EMBER_ROUTE_TABLE_SIZE is less than required by stack profile." #endif
If you want to change it, for an SoC project you may add EMBER_ROUTE_TABLE_SIZE under "Additional Macros" in the Includes tab when you open your project .isc file in Simplicity Studio. For an NCP-Host project, you can configure EZSP_CONFIG_ROUTE_TABLE_SIZE from the host side; see UG100.
Note that Zigbee specification requires a minimum route table size of 10.
When preparing EM35x devices for field deployments, it is often desirable to secure the flash contents of the EM35x chip to prevent accidental/unauthorized access or modification. This can be done using the chip’s memory protection (Read Protection and Write Protection) mechanism, described in the EM35x Datasheet in Sections 5.2.1 (Flash Memory) and 5.3 (Memory Protection Unit).
Below are some of the common questions that customers ask when considering this kind of protection for their devices:
Q: What kinds of protection are available and what is protected by them?
A: The chip offers Read Protection and Write Protection.
Read Protection, when enabled, disconnects all flash from everything else when the chip’s SerialWire/JTAG interface (SWJ) is connected to something. This effectively prevents reading of all flash memory on the device, including the full 128KB or 192KB of main flash block (which covers the bootloader area, application code & data areas, and SimEEPROM token area), plus the FIB (flash information block where Ember-programmed manufacturing tokens and low-level flash read/write routines are stored) and the CIB (customer information block where customer-programmable manufacturing tokens are stored). This also prevents the use of the SWJ bus for SerialWire and JTAG operations such as debugger access and flash programming. Since read protection can only be disabled by writing a specific, non-zero, non-0xFF value to a specific location, the act of erasing of the CIB memory page (where the read protection option byte is contained), whether intentional or accidental, will still leave the chip read-protected until the appropriate option byte is set to the appropriate value.
Write Protection, when enabled, prevents writing or erasing of the main flash block [MFB], either by external means or through execution of code from flash or RAM. Unlike read protection, write protection is enabled on a per-region basis with each region being 4 pages of flash or 8KB.
Q: What kind of protection does Ember recommend using for deployed devices into mass production?
A: For devices that are deployed into the field in scenarios where no further debug or advanced testing is required, Ember recommends enabling Read Protection (which is chip-wide) as well as Write Protection of the first 8KB region, which is the section of the MFB where the bootloader firmware resides.
Q: How do I enable these recommended protection settings using the ISA3 and ISA3 Utilities?
A: Enabling these settings requires the use of the ISA3 Utilities from the command line; InSight Desktop does not currently provide an interface for passing these options to the loader through its GUI.
Enabling Write Protection
To enable write protection of the first region of main flash (where the bootloader resides), clear (write 0) only Bit 0 of the first option byte for write protection (Option Byte 4) and leave all other bits set (erased state of 1) for a final bitmask of 0xFFFFFE (0xFFFFFFFE for any chips with 512 KB of flash). This can be accomplished with the “—programwrprot” option in em3xx_load or em3xx_buildimage such as:
em3xx_load.exe --programwrprot FFFFFE
Note that current Ember implementations are such that write protection of this first region is currently done automatically whenever read protection is enabled. However, setting the write protection mask explicitly to include this first flash region is recommended to ensure consistent results should this automatic behavior change in future tool/silicon revisions.
Enabling Read Protection
NOTE: Enabling read protection should always be the last operation you perform on the device with em3xx_load or em3xx_buildimage since setting this option effectively inhibits any future changes to the chip/image state until read protection is disabled (which, in turn, causes the MFB and CIB to be erased).
To enable read protection, Option Byte 0 of the CIB can be set to 0×00 (though any value other than the special value of 0xA5 will suffice). This can be done using the “—enablerdprot” flag in em3xx_load or em3xx_buildimage, such as:
em3xx_buildimage.exe --em357 --chipimage myimage.hex serial-uart-bootloader.s37 sensor.ebl --enablerdprot
This builds an EM357 chip image output file, myimage.hex, from the two input files, serial-uart-bootloader.s37 and sensor.ebl. At the same time, read protection is enabled in the CIB content of the HEX file by setting option byte 0 to the value 0×00. Programming this chip image (the HEX file) to a fresh device will ensure that it contains the necessary application code, bootloader code and read protection. Additional manufacturing token content in the CIB can be set using the “—cibtokenspatch” argument with a manufacturing tokens patch file (as explained by the “—cibtokenspatch-help” argument to em3xx_buildimage or em3xx_load).
Q: If I enable write protection, how will that affect the bootloader?
A: (Note that the following applies to all of the bootloader types offered by Ember.) By write-protecting the first 8KB portion of main flash, where the bootloader resides, you prevent accidental/unauthorized overwrites of the bootloader code and the chip’s reset vectors. However, if regions beyond this are write-protected, this will prevent the bootloader from writing the downloaded firmware image into the application area of the MFB, thus rendering it ineffective. This is why Ember recommends leaving write protection disabled for the remaining flash regions if a bootloader is used in the memory map.
If, for some reason, you wish to deploy a device that doesn’t allow bootloading, you may protect additional regions of the MFB. However, take care not to enable write protection over the area used for Simulated EEPROM, usually the last 8KB region of the MFB (or the last 32KB in some EZSP network coprocessor designs), as this will prevent the stack from writing to the network and security-related tokens that it requires as part of normal operation.
Q: What about the areas that aren't covered by the write protection settings? Aren't they vulnerable to writes from an external debugger/programmer then?
A: Yes, areas that are not covered by write protection are potentially vulnerable to erasure and writing from an external debugger/programmer or from errant code executing flash-writing routines, even if read protection is enabled. Read protection will prevent reading of the flash, but the erasing and writing occurs through a flash interface controller, which is never disconnected and is capable of working without needing to read. (Note that Ember’s programming tools will prohibit writing/erasing of the flash when read protection is found to be active, which prevents accidental or malicious corruption of flash data when using Ember’s tools.) Therefore, the safest and most secure mode of operation is to write protect all sensitive areas of flash, except the Simulated EEPROM which must remain writable, and enable read protection. (As discussed above, write-protecting flash regions covered by application code will inhibit updating of the code via the bootloader.)
Q: What happens if there is a failure, such as reset, while writing an option byte?
A: If the option bytes themselves were to somehow become corrupted, the chip has a means to detect this state and will only boot into deep sleep mode until the failure is corrected through erasing/reprogramming of the CIB memory page. When corruption is detected, the option bytes are assumed to be the erased state, which will activate read protection. Ember’s em3xx_load tool can detect this failure/corruption, and using the “—fixobfail” argument with this tool will fix the issue.
Q: What kinds of debugging mechanisms will still be available on a device that has read and write protection enabled in the recommended configuration?
A: The DEI Port features (which are just TTL interfaces to the GPIOs) of the ISA3 and the PacketTrace Interface [PTI] features (which use alternate functions of the GPIOs for a digital, 2-wire protocol) of the ISA3 are still viable even when Read Protection is enabled. Additionally, normal digital I/O and serial controller usage remain possible when read protection and/or write protection are enabled.
Q: What about the Virtual UART interface (Serial 0 in InSight Desktop Console)?
A: Since the Virtual UART mechanism is implemented on top of the ARM Cortex’s SerialWire protocol, which uses the SerialWire/JTAG [SWJ] bus, it isn’t available when read protection is enabled. Read protection and SWJ bus access are mutually exclusive. However, you can still utilize the physical UART of the chip (TXD and RXD pins, PB1 and PB2) if the chip’s running firmware enables it. These TTL signals can be routed through the DEI interface of the ISA3 for access as “Serial 1” in the InSight Desktop Console as illustrated on the EM35x Breakout Board hardware.
Q: If I enable read and write protection, can I disable them later?
A: Yes, it’s possible to disable read protection and/or write protection using the ISA3 Utilities.
Disabling read protection is accomplished through the use of the “—disablerdprot” command argument with em3xx_load or em3xx_buildimage, which causes Option Byte 0 to be set to the special value of 0xA5. Any other state for Option Byte 0 causes read protection to remain active. Note that disabling this feature on an actual chip (with em3xx_load) will cause its MFB and CIB (besides Option Byte 0) to be fully erased back to 0xFF bytes.
Disabling write protection is accomplished using the “—programwrprot” command argument to set the write protection option bytes back to an all-0xFF state, such as “em3xx_load —programwrprot FFFFFF”. (Note that a “programmed” state of 0xFFFFFF is handled differently than an erased [unprogrammed] state, since checksum values for each option byte are also programmed by the ISA3 Utilities when an option bye is programmed. Once an option byte is programmed, the CIB must be erased before that option byte’s value can be changed.
Q: After disabling read protection, is anything NOT erased?
A: Yes, the FIB (where Ember-programmed manufacturing tokens are stored) is left intact after read protection has been disabled. The MFB and CIB are not preserved when read protection has been disabled. Although the chip’s automatic erasure during deactivation of read protection only affects the MFB (where stack and application tokens reside along with bootloader and stack/application firmware), the act of patching the option bytes in the CIB to deactivate read protection requires that the entire CIB page be erased and re-written (as erasures can only occur on a per-page basis), and since the existing CIB content is unreadable until the unprotected state (value 0xA5 for Option Byte 0) is written, the newly written CIB page resulting from the CIB patching process must consist of fully erased bytes (other than Option Byte 0), meaning that none of the original CIB content can be preserved.
Q: What is Zigbee?
A: Please check out the introduction at Zigbee Alliance website: http://www.zigbee.org/what-is-zigbee/
Q: What is EmberZNet?
A: EmberZNet is the implementation of Zigbee by Silicon Labs. It consists of the core Zigbee stack, Zigbee Cluster Library support, and an Application Framework. With the aid of AppBuilder in Simplicity Studio, you can easily create a Zigbee application that you can run on one of our development kit.
Q: How do I download the stack?
A: Please refer to this KBA on access to Silicon Labs wireless mesh networking stacks.
Once you have obtained stack access privilege, run software update in Simplicity Studio while you are logged in, and you can download the stack under the SDKs tab.
Q: Is EmberZNet free to use?
A: Yes, provided that you have first obtained stack access privilege through one of our qualifying development kits, as explained by the KBA mentioned above.
Q: How do I make a coordinator and/or router?
A: The easiest is to start with our Z3Gateway and Z3Light sample apps. To gain deeper understanding of Zigbee, check out our extensive user guides and online training content.
Q: How do I create and/or join a Zigbee network?
Q: What is a bootloader and do I need one?
A: Please refer to UG103.6. Usually, if you need in-the-field upgradeablitly, then you will need a bootloader.
Q: Are chips preloaded with a bootloader?
A: Unless you obtained the IC from a third-party vendor who has programmed a bootloader on it, you can assume it isn't preloaded with a bootloader.
Q: How do I customize a sample app to make it my own?
A: Most easily through custom callbacks. You can also extend AppBuilder by adding your own custom clusters and plugins. Under our online training content, see the module on "Extending App Builder: Customizing ZCL".
Q: What is a callback?
A: You can find an explanation of a callback in any computer programming reference. But simply put, in the context of EmberZNet and our App Framework, a callback provides an opportunity to insert any executable code under specific conditions, for example, when the stack initializes or when the stack status changes, etc.
Q: What is the best way to quickly get familiar with the app framework and the stack?
A: The best way is to start with our development kits, sample applications, and quick start guide. If you are proficient with software development and/or embedded programming, but have no or minimal experience in wireless protocol stack and haven't used Simplicity Studio before, you may expect a few hours to a day's time to play with your new dev kit and set up your first Zigbee network. After that, you can explore our online training content, Knowledge Base, and documentation under your EmberZNet installation, to continue to gain further knowledge. Please also visit our community forum to connect with fellow developers and ask questions.
Q: What is the difference between customizable network coprocessor(NCP) Applications and ZCL Application Framework V2? When to use which?
A: If you intend to make a customizable NCP application for your NCP+Host architecuture, please choose customizable network coprocessor(NCP) Applications when you start to create the new project. If you intend to make a host application, or SoC application, please choose ZCL Application Framework V2 when you start to create the new project. For the difference between NCP and SoC, please refer to "Design Choices" in UG103.3.
Here are some steps you can follow to build an EZSP-SPI host application on a Raspberry Pi to interact with an EFR32MG1 or EFR32MG12 device (on our dev kit) running a pre-built NCP-SPI image (or an xNCP image built with SPI signal assignment compatible with our dev kit) of the latest EmberZNet stack, which is v5.9.1 at the time of this article. If you have custom hardware or a custom-built NCP image with non-default SPI pins, make adjustments accordingly.
1. Create a new Silicon Labs AppBuilder Project in Simplicity Studio v4 of type "ZCL Application Framework V2", and choose the host (as apposed to SoC) flavor of the latest EmberZNet stack.
2. Choose a sample application, such as Z3Gateway, or start with a blank application and configure it appropriately.
3. Under "HAL configuration" tab of your project, choose EFR32-EZSP and Unix host under Platform configuration. Leave the "Api" field blank. Under the "Plugins" tab, select "EZSP SPI" and deselect EZSP UART.
4. Generate the host app, and build it on your Raspberry Pi.
5. Program your EFR32 device with the EZSP-SPI image. For example, you may use a pre-built NCP image for the BRD4153A radio module from:
6. Make hardware connections between the WSTK expansion header, and the Raspberry Pi expansion header:
Refer to this article on GPIOs used for the pre-built EFR32MG NCP images:
Refer to UG151 on the WSTK expansion header.
On the RasPi side:
(Note: these are exactly the same as our SPI host set up for Silicon Labs Thread, so you can reference AN912 table 2).
7. Use these example commands to configure SPI GPIOs, and launch the host app, on your Raspberry Pi (note that they are different from SPI host set up for Silicon Labs Thread).
//Configure GPIO on the pi
sudo echo 8 > /sys/class/gpio/export && sleep 0.5
sudo echo 22 > /sys/class/gpio/export && sleep 0.5
sudo echo 23 > /sys/class/gpio/export && sleep 0.5
sudo echo 24 > /sys/class/gpio/export && sleep 0.5
sudo echo high > /sys/class/gpio/gpio8/direction && sleep 0.5
sudo echo in > /sys/class/gpio/gpio22/direction && sleep 0.5
sudo echo falling > /sys/class/gpio/gpio22/edge && sleep 0.5
sudo echo high > /sys/class/gpio/gpio23/direction && sleep 0.5
sudo echo high > /sys/class/gpio/gpio24/direction && sleep 0.5
//Command to launch host app