The ECC Libraries are a separate package that enable elliptic curve cryptography within the EmberZNet stack. They are mainly for SE networks for use during the Certificate Based Key Establishment procedure (CBKE). By default these are not shipped with the EmberZNet stack and must be added manually.

Even with the Simplicity Studio v4 automatic installation of components, the ECC Libraries require manual installation.

Downloading the ECC libraries

The first step is downloading the ECC Libraries. This can be done via the support portal system. Log into your Silicon Labs account and follow the link to Software Releases. At this point you will need to know the version of the EmberZNet stack you want the ECC Libraries for, this chart should help you find the version:

Once you have found the release name, click on it to reveal the Software Release Details. Look at the section Associated Content. If ECC access is enabled on your account, you should have a title in the section that includes ECC, such as EmberZNet-5.9.1.9-ECC or EmberZNet-ECC-v5.8.1. For the newer releases, after EmberZnet 7.0, the name will be Smart-Energy-CommsHub-Apps-SiSDK24.2.1.  Click on the content. It will take you a preview and download page. Click Download zip in the upper left corner of the page.

Adding the ECC libraries to your stack

Once you have downloaded the ECC libraries, you will need to find the zip file on your machine and open it. If you do not have a zip extractor, a free one can be downloaded from 7zip. When you open the zip file, you will find a number of files. These can be extracted directly into our file structure at the root of your EmberZnet installation.

app     documentation       hal   stack   submodules
build   em35x-ezsp-images   phy   tool

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\znet\vA.B.C.D
(where A.B.C.D is the version number)

app   hardware   platform   protocol

C:\SiliconLabs\SimplicityStudio\v4\developer\stacks\znet\vA.B.C.D
(where A.B.C.D is the version number)

C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\vX.Y

C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\vX.Y

C:\Users\%USERNAME%\SimplicityStudio\SDKs\gecko_sdk

This will merge them into the folder within your stack release.

Adding the ECC libraries to your project

After the ECC library is installed, once you build a project you will need to be sure the ECC libraries are enabled for use. When picking the ECC163k or 283k1 plugins, you will need to point the plugin to the correct library. This will be located at:

.\protocol\zigbee_X.Y\SoC-Libraries\SOME_LIBRARY_FILE.a

This file will need to match your part and ECC version.

If you require ECC library access, please open a ticket on the portal to request it.

Here are the steps you can follow to build an EZSP-SPI host application on a Raspberry Pi to interact with an EFR32MG12 device (on our dev kit) running an NCP-SPI image (or an xNCP image built with SPI signal assignment compatible with our dev kit) of the latest EmberZNet stack, which is v7.2.0 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. Start the New Project Wizard in Simplicity Studio v5.  Select Linux 32 Bit as the target device and Makefile IDE as the Toolchain.  Click Next.

2. Select the Zigbee Host Gateway as the example project as shown below and click Next.

3. Select Copy contents and click Finish to create the project as shown below. 

5. To configure the Z3Gateway host for EZSP SPI operation, install the "EZSP SPI" software component and uninstall the "EZSP UART" software component as shown below.

6.  The Z3Gateway host project files are generated in the specified project Location given at step 3.  Upload the entire contents of the Z3Gateway project directory to the Raspberry Pi , and build it under Z3Gateway directory by issuing the command - "make -f Z3Gateway.Makefile".  The built Z3Gateway executable can be found in "./build/debug/" directory.

7. To create the NCP-SPI project for the example BRD4161A radio board, open the New Project Wizard in Simplicity Studio v5 as shown below and press Next.



8. Select and create the "Zigbee - NCP ncp-spi" example project.
 

9. Build and program the EFR32 radio board such as BRD4161A with the generated NCP-SPI image. 
 

10.  After the NCP-SPI image has been successfully programmed, the radio board (e.g. BRD4161A) can now be removed from the WSTK Main board and connected to the Raspberry Pi's 40-pin GPIO Header using the Wireless Expansion Board BRD8016A. 
 

Here is the list of required Raspberry Pi's pins for the NCP-SPI operation.

nHOST_INT: GPIO22

nRESET: GPIO23

nWAKE: GPIO24

SPI_nCS: SPI0_CE0_N

SPI_MISO: SPI0_MISO

SPI_MOSI: SPI0_MOSI

SPI_CLK: SPI0_SCLK
 

More information about Raspberry Pi's SPI connection for the BRD8016A can be found in ug291-exp4320a-user-guide.  The connector pins for BRD4161A radio board used as an example here can be found in  the ug260-brd4161a-user-guide and the corresponding BRD4161A-A02-schematic . Detailed descriptions of Silicon Lab's EZSP SPI host interface and SPI Driver default configurations, like SPI Driver clock speed, can be found in an711-ezsp-spi-host-interfacing-guide .


Please note that different radio boards and custom designs may require different EFR32 pin mappings for the NCP SPI operation.  Pin Tool from Simplicity Studio v5, shown below, can be used to configure EFR32 pins.

 

11. Modify the "/boot/config.txt" file to enable the SPI on the Raspberry Pi as follows. Since the GPIO 8 is used by the SPI kernel driver as the CS pin by default, we need to add "dtoverlay=spi0-1cs,cs0_pin=26" to move the SPI kernel driver CS to pin 26. 

// Add the following config to the /boot/config.txt on the Raspberry Pi to enable and configure the SPI
dtparam=spi=on
dtoverlay=spi0-1cs,cs0_pin=26
 

12. After the Raspberry Pi has been configured and rebooted, issue the following command to start the Z3Gateway host app.

//Command to launch host app
pi@raspberrypi:~/Z3Gateway $ ./build/debug/Z3Gateway

The packet handoff component enables applications to access Zigbee messages at various points during their transit through the Zigbee stack. Primarily used for debugging, it also allows for the dropping, mangling, or modification of packets, enabling a variety of custom behaviors. Additionally, erroneous or unwanted messages can be intercepted and altered before the stack processes them.

Warning: Dropping, mangling or otherwise interfering with incoming or outgoing packets may affect Zigbee compliance and interoperability with other Zigbee certified devices. This is for expert users and to be used with great care.

Important Note: The packet handoff callbacks are called directly from the Zigbee stack and in case of RTOS based applications they will not pass through the IPC Layer to the application thread, but instead must be handled within the Zigbee stack thread. 

How to enable

The Packet Handoff Component can be enabled from the Software Components tab of the Project Configurator (open .slcp file of your project). You can find the component in Zigbee > Utility > Packet Handoff.
 

When this component is installed, it offers the option to allow all or different types of Zigbee or raw 15.4 packets which can be selected. Additionally you also provide a buffer size to store the flat packet buffers.

APIs

When including the packet handoff plugin, it is possible to select which of the packet types described further down will be handed to the following two callbacks:

EmberPacketAction emberAfIncomingPacketFilterCallback(EmberZigbeePacketType packetType,
                                                      uint8_t* packetData,
                                                      uint8_t* size_p,
                                                      void *data);

EmberPacketAction emberAfOutgoingPacketFilterCallback(EmberZigbeePacketType packetType,
                                                      uint8_t* packetData,
                                                      uint8_t* size_p,
                                                      void* data);

PacketType  represents the type of packet received. See * ::EmberZigbeePacketType.

packetData A flat buffer containing the packet contents. The buffer starts with the command id followed by the payload.

size_p a pointer to the size of the packet data

data This is a pointer to auxiliary data for the command. This depends on the packet type.

Packet Types

The table below lists all packet types used by the packet handoff feature and whether they are supported on the incoming and outgoing side. It also shows any corresponding auxiliary data and indicates what field first byte of the handed over payload comprises of.

Packet Actions

Both the incoming and the outgoing callbacks use an 'EmberPacketAction' as the return type. The following definitions are available for this. They are defined in ember-types.h.

Supported Packet Actions per Packet Type

Note: Any unknown or unsupported return value provided through the callbacks is treated as EMBER_ACCEPT_PACKET.

Example:

This is an example that is included in the app.c of Zigbee SoC application or in zigbeed:

// packetHandoff
EmberPacketAction emberAfIncomingPacketFilterCallback (EmberZigbeePacketType packetType, int8u *packetData, int8u *size_p, void *data){

  switch (packetType)
    {
    //case <packetType>:
      //code
      //break;
    case EMBER_ZIGBEE_PACKET_TYPE_APS_DATA: // APS packet
      syslog(LOG_INFO, "APS_DATA ----> %u", packetType);
      break;
    default:
      break;
    }

  syslog(LOG_INFO, "Packet data bytes ---->");
  for (int i = 0; i < *size_p; ++i)
    {
      syslog(LOG_INFO, "%x", packetData[i]);
    }
  // Depending on your use case you can change the EmberPacketAction you return
  return EMBER_ACCEPT_PACKET; 
}

(x)NCP support

The packet handoff plugin as described above is only available in SoC mode. This is to avoid overloading the serial lines between the host and NCP with these intermediary packet types.

When building an xNCP the following two callbacks are available on the NCP

 

 EmberPacketAction sli_zigbee_af_packet_handoff_incoming_callback(EmberZigbeePacketType packetType,
                                                EmberMessageBuffer packetBuffer, 
                                                                  uint8_t index,
                                                                    void *data); 

EmberPacketAction sli_zigbee_af_packet_handoff_outgoing_callback(EmberZigbeePacketType packetType,             
                                                EmberMessageBuffer packetBuffer, 
                                                                  uint8_t index,  
                                                                    void *data);

packetType is one of the packet types described below

packetBuffer is a message buffer containing the complete message as it is handled by the stack

index is a pointer to the first byte in the packet buffer which represents the start of the defined packet type

data is auxiliary data which differs depending on the corresponding packet type