Application Setup (Build Time)#

In Zigbee EmberZNet SDK 6.x#

Common#

This section deals with instructions that are common to both System-on-SoC (SoC) and Host application configurations. Further details specific to each type of configuration are covered in the sections that follow. Note that a sample application for the Dual Band CoomsHub is available on request from Silabs support. It will be delivered as a side package for the stack. However, the steps in this section assume that you have wish to modify one of the example applications.

As a prerequisite to setting up an ECC-enabled device, first ensure that you have the ECC-enabled software content package for your EmberZNet PRO release. Access is granted by Silicon Labs Support upon request via the support portal, and the content packages can be found as ZIP files accompanying each EmberZNet PRO release in the Software Releases area of the Silicon Labs support portal. Once you’ve downloaded and extracted the content package, you are ready to follow the steps below.

Note: Because the ECC library is compiled with IAR, SE projects should also be compiled with IAR. Projects compiled with GCC may cause unexpected resets.

  1. Create a new project, as described in QSG106: Zigbee EmberZNet PRO Quick-Start Guide.

  2. On the Zigbee Stack tab, set one of the following:

    • If you are using unique, per-device link keys based on installation codes for joining devices, as should be the case for production deployments, set the Security option to "Smart Energy Security full (compliant)".

    • If you are using a single, global link key for all devices to join, as is often used in development/testing scenarios to reduce complexity, set the Security option to "Smart Energy Security test".

  3. Follow the directions in one of the sub-sections below for building either a System-on-Chip application, a Custom Network Coprocessor (NCP), or an EZSP Host application with ECC support.

  4. After completing the steps as per the subsections below, set up the remaining device configuration as appropriate, and generate the project.

  5. Populate callbacks in the generated project as necessary, and then build and load to the target device (after the certificate and installation codes have been programmed as described above).

Note: The certificate and installation code data only reside on the processor where the stack is being run, which is either the SoC processor itself in the SoC use case or the NCP, not the host processor, in the EZSP-enabled host/NCP use case.

System on Chip (SoC)#

Use these steps to configure an SoC-based Smart Energy application with ECC support.

  1. On the Plugins tab, in the Stack Libraries section, confirm the following settings:

    • Enable the CBKE 163k Library plugin.

    • If you intend to use the 283k1 ECC Curve (Smart Energy 1.2 or higher), then enable the Use CBKE 283k Library plugin.

    • If supporting OTA upgrades with image signature verification, enable the CBKE DSA Verify Library and, if supporting the 283k1 ECC curve, also enable the CBKE 283k1 DSA Verify Library.

    • Enable the CBKE Core Library plugin.

    • Enable the ECC 163k1 Library plugin, and then, in the Library path text entry box for the plugin options, enter the file path to the location of your non-283k1 ECC library file, typically named something like ecc-library-{platformName}.a.

    • Enable the ECC 283k1 Library plugin, and then, in the Library path text entry box for the plugin options, enter the file path to the location of your 283k1 ECC library file, typically named something like ecc-library-283k1-{platformName}.a.

    • Enable the Security Core Library plugin.

    • Enable the Security Link Keys Library plugins and set the Link Key Table Size according to your needs in the options area for this plugin.

  2. In the Plugins tab, in the Smart Energy section, enable the Key Establishment plugin, and then, in the Options area, select the appropriate choice in the SE Version list depending on whether your device should behave in an SE 1.2 fashion (in which both 163k1 and 283k1 ECC curves are required for CBKE) or a pre-1.2 SE 1.x fashion (in which only 163k1 ECC support is used for CBKE).

Note: Some older versions of AppBuilder do not support white space in the ECC library path, so you may need to relocate these files to satisfy this requirement.

Then enable the Smart Energy registration plugin. This will take care of the CBKE (certificate-based key establishment) process that will determine the link key.

Custom Network Coprocessor#

Use these steps to configure a custom EmberZNet PRO network coprocessor (NCP) via the Customizable Network Coprocessor Applications framework. Refer to AN1010, Building a Customized NCP Application, for more information about custom NCP design using this framework. Note that this is not the same as configuring a host application (which talks to an NCP via EZSP) for a Smart Energy device. That process is covered in the next section, EZSP Host.

There are different versions of the network coprocessor with and without ECC support compiled in. Access to the ECC version is granted by Silicon Labs Support upon request. The ECC version of the network coprocessor firmware contains support for both ECC 163k1 and ECC 283k1 curves. However, the curves can be utilized depend on the certificates that are installed on the coprocessor.

When configuring a custom NCP to support ECC-enabled Smart Energy operation, do the following in AppBuilder, Plugins tab:

  1. In the Stack Libraries section, enable the same library plugins and similar options as described in the section System on Chip (SoC). However, for libraries that are not being enabled, you must enable the corresponding "Stub Library" plugin, such as the CBKE 283k1 DSA Verify Stub Library plugin as a substitute for the CBKE 283k1 DSA Verify Library plugin.

  2. In the Command Handler section, enable the CBKE Library EZSP Command Handlers plugin.

EZSP Host#

Use these steps to configure an ECC-enabled host application, which is designed to talk to an ECC-enabled EmberZNet PRO NCP via EZSP. In AppBuilder, on the Plugins tab:

  1. In the Smart Energy section, enable the Key Establishment plugin, and then, in the options area, select the appropriate choice in the SE Version list depending on whether your device should behave in an SE 1.2 or later fashion (in which both 162k1 and 283k1 ECC curves are required for CBKE) or a pre-1.2 SE 1.x fashion (in which only 163k1 ECC support is used for CBKE).

  2. In the Utility section, enable the NCP Configuration plugin, and then, in the options area, set the Link Key Table Size according to your needs.

Note: This table size setting cannot exceed the maximum link key table size configured within your NCP firmware. If it does, an error will be detected and reported in the standard output stream of the host application during NCP initialization. If necessary, you can adjust the link key table size of the NCP using the Custom Network Processor method described in the previous section.

In Zigbee EmberZNet SDK 7.x#

Common#

This section deals with instructions that are common to both System-on-SoC (SoC) and Host application configurations. Further details specific to each type of configuration are covered in the sections that follow. Note that a sample of Smart Energy applications are available on request from Silicon Labs Support. It will be delivered as a side package for the stack. However, the steps in this section assume that you wish to modify one of the example applications.

As a prerequisite to setting up an ECC-enabled device, first ensure that you have the ECC-enabled software content package for your EmberZNet PRO release. Access is granted by Silicon Labs Support upon request via the support portal, and the content packages can be found as ZIP files accompanying each EmberZNet PRO release in the Software Releases area of the Silicon Labs Support portal. The side package contains Smart Energy sample applications and also ECC curves support, which needs to be extracted within the installed SDK. After you have downloaded and extracted the content package, you are ready to follow the steps below.

Note: Because the ECC library is compiled with IAR, SE projects should also be compiled with IAR. Projects compiled with GCC may cause unexpected resets.

  1. Create a new project, as described in QSG106: Zigbee EmberZNet PRO Quick-Start Guide.

  2. On the Software Components tab, set one of the following:

    • If you are using unique, per-device link keys based on installation codes for joining devices, as should be the case for production deployments, configure the Primary Network Security Type option to "Smart Energy Security full (compliant)" in the Zigbee device config component.

    • If you are using a single, global link key for all devices to join, as is often used in development/testing scenarios to reduce complexity, configure the Primary Network Security Type option to "Smart Energy Security test" in the Zigbee device config component.

  3. Follow the directions in one of the sub-sections below for building either a System-on-Chip application, a Custom Network Coprocessor (NCP), or an EZSP Host application with ECC support.

  4. After completing the steps as per the subsections below, set up the remaining device configuration as appropriate, and save the project.

  5. Populate callbacks in the generated project as necessary, and then build and load to the target device (after the certificate and installation codes have been programmed as described above).

Note: The certificate and installation code data only reside on the processor where the stack is being run, which is either the SoC processor itself in the SoC use case or the NCP, not the host processor, in the EZSP-enabled host/NCP use case.

System on Chip (SoC)#

Use these steps to configure an SoC-based Smart Energy application with ECC support.

  1. On the Software Components tab, in the Zigbee Stack component category section, confirm the following settings:

    • Enable CBKE 163k1 and/or CBKE 283k1 component(s) as intended for the application.

    • Enable the ECC 163k1 Support component.

    • If you intend to use the 283k1 ECC Curve (Smart Energy 1.2 or higher), then enable the CBKE 283k1 Support component.

    • If supporting OTA upgrades with image signature verification, enable the CBKE DSA Verify component and, if supporting the 283k1 ECC curve, also enable the CBKE 283k1 DSA Verify component.

    • Enable the CBKE Core component.

    • Enable the ECC 163k1 Support component. This component, ecc-163k1-library.a, is located in protocol/zigbee/build/ECC from the installed SDK location.

    • Enable the ECC 283k1 Support component. This component, ecc-283k1-library.a, is located in protocol/zigbee/build/ECC from the installed SDK location.

    • Enable the Security Link Keys component and configure the Link Key Table Size according to your needs.

  2. In the Software Components tab, in the Smart Energy component category, enable the Key Establishment component. This component defaults to use CBKE functions with 163k1 ECC curve support to behave as per pre-1.2 SE fashion, but you can also choose the 283k1 ECC curve support by selecting CBKE 283k1 component. Select the appropriate CBKE component(s) depending on whether your device should behave in an SE 1.2 fashion (in which both 163k1 and 283k1 ECC curves are required for CBKE) or a pre-1.2 SE 1.x fashion (in which only 163k1 ECC support is used for CBKE).

Note: If you select the appropriate CBKE component, then all the required components should be enabled as a part of dependency except the DSA Verify components. However, Silicon Labs recommends to visit components to make sure they are enabled and to change the default configurations to your needs.

Then enable the Smart Energy Registration component. This will take care of the CBKE (certificate-based key establishment) process that will determine the link key.

Custom Network Coprocessor#

Use these steps to configure a custom EmberZNet PRO network coprocessor (NCP) application. Refer to Building a Customized NCP Application for more information about custom NCP design using this framework. Note that this is not the same as configuring a host application (which talks to an NCP via EZSP) for a Smart Energy device. That process is covered in the next section, EZSP Host.

When configuring a custom NCP to support ECC-enabled Smart Energy operation, do the following in Simplicity Studio, Software components tab:

  1. In the Zigbee Stack Component category section, enable the same stack components and similar options as described in the section System on Chip (SoC).

Note: For reference, you can use the ‘ncp-uart-hw’ sample app from the SDK and make it an ECC-enabled NCP app for Smart Energy operations by adding required components described in this section.

EZSP Host#

Use these steps to configure an ECC-enabled host application, which is designed to talk to an ECC-enabled EmberZNet PRO NCP via EZSP. In Simplicity Studio, on the Software components tab:

  1. In the Smart Energy component category, enable the Key Establishment component. This component defaults to use CBKE functions with 163k1 ECC curve support to behave as per pre-1.2 SE fashion, but you can also choose the 283k1 ECC curve support by selecting the CBKE 283k1 component. Select the appropriate CBKE component(s) depending on whether your device should behave in an SE 1.2 fashion (in which both 163k1 and 283k1 ECC curves are required for CBKE) or a pre-1.2 SE 1.x fashion (in which only 163k1 ECC support is used for CBKE).

  2. In the Zigbee Utility component category, enable the NCP Configuration component, and then click the Configure button and set the Link Key Table Size according to your needs.

Note: This table size setting cannot exceed the maximum link key table size configured within your NCP firmware. If it does, an error will be detected and reported in the standard output stream of the host application during NCP initialization. If necessary, you can adjust the link key table size of the NCP using the Custom Network Processor method described in the previous section.