In general, you can customize a gecko bootloader for Z-Wave 700. We also have example OTA bootloader which is provided with s37 file. However, we don’t have a project to show the default configuration for this example bootloader. This KB will show you how to create a default OTA bootloader for ZGM130S with simplicity studio v5.
1 Create a bootloader project(bootloader-storage-internal-single-512k) for ZGM130S
The bootloader project is created by AppBuilder. The App Builder is included as part of the "Wireless Tools" package. Please make sure you install it following the steps below
Use the Update icon in Simplicity Studio to launch the Package Manager and then on the "Tools" tab make sure the following packages are installed: "Wireless Tools IDE Integration" and "Wireless Tools".
After that, you should be able to find “Silicon Labs AppBuilder Project” in ProjectàNew. If not, try to create new project in “Application Builder” under “Tools” on the main tab
Select the latest version of the Gecko Bootloader the application you are building and click Next.
Select ‘Internal Storage Bootloader (single image on 512kB device) and click Next
Name your project and click Next
Search for and select the ZGM130S Radio Board you are using under Boards and ZGM130S037HGN under Part and click Finish
2 Configure plugins
2.1 Enable LZ4 compression
The .isc configuration file will open and under the ‘Plugins’ tab check the GBL Compression (LZ4) option.
2.2 Enable encryption and signing
Click to highlight the option ‘Bootloader Core, provides API: core’ and under Options, select
“Require signed firmware upgrade files” and “Require encrypted firmware upgrade files” from the list.
3 Configure Storage
Click on the Storage tab and configure the Slot 0 as below, this slot is used for storing the GBL file when OTA.
4 Customize your configuration
Feel free to add other configuration what you want, such as enable “Application upgrade version check”, “secure boot” or “GPIO activation”.
Application upgrade version check
You can find this plugin in Plugins tab; this plugin checks the version number and product ID of the application upgrade before applying. Enable this plugin, a valid product ID and higher version number is necessary for OTA.
Secure Boot
The secure boot feature can be found within Bootloader Core under Plugins tab.
If “Secure Boot” is enabled, Gecko Bootloader checks the integrity and authenticity of the application image before executing it. If the integrity check fails, program control remains in the second stage bootloader. Note that, you must sign your application image if you enable Secure Boot, how to sign an Application for Secure Boot can be found in section 6.5.5 of UG162: https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf
GPIO activation
If the “GPIO Activation” plugin is enabled, the host device can keep this pin low/high (depending on configuration) through reset to make the device enter the bootloader. You can find this plugin in Plugins tab.
More features about Gecko bootloader can be found in UG266: https://www.silabs.com/documents/public/user-guides/ug266-gecko-bootloader-user-guide.pdf
5 Generation and Build
Please save your configuration and Generate it before building this project.
After that, you can flash generated bootloader-storage-internal-single-512k-combined.s37. The KB below shows how to do OTA.
You have a second MCU or other data files you want to OTA via Z-Wave. How can you reuse the Bootloader firmware to verify the signature and decrypt the data?
The code to verify and decrypt the file already exists in the bootloader and is known good. Reusing the existing bootloader code is smaller and safer than re-inventing the wheel - or in this case encryption.
The attached project is a modified Z-Wave Door Lock Key Pad sample application that demonstrates how to OTA code/data other than the Z-Wave firmware. OTA of the Z-Wave firmware works in the sample application already - but first the encryption keys MUST be generated. See https://www.silabs.com/community/wireless/z-wave/knowledge-base.entry.html/2019/04/09/z-wave_700_ota_ofe-i00M on how to generate the keys. See the two .BAT files in the comments section which will run all the necessary commands for you. They are also included in this .sls file in the KEYS directory. You MUST create your own project keys to OTA either the Z-Wave Firmware or any other data.
To OTA other types of files you need to start with a binary file. Most microprocessor development environments will output a binary file so use that instead of a HEX file. If you have an Intel hex or Mototola S record file, use a utility like SREC_CAT to convert it to a binary file. SREC_CAT can convert just about any file type into any other file type. If the file is more than 200K bytes, you will need to break the file into 200K or smaller files and OTA each, one at a time. Doing that is beyond the scope of this project. Note there is no need to encrypt the file. We will be using Commander to sign and encrypt it using the keys generated here.
Theory of Operation:
Changes to the SSv4 DoorlockKeyPad sample project are indicated with the comment "AKER" - search for these to find what changed. You can also diff the files with a fresh copy of the DoorLockKeyPad sample app from SSv4. Most of the code to support OTA of an external processor is in this file. A few changes have been made to ota_util.c in ZAF_CommandClasses_FirmwareUpdate but these are expected to be included in a future release of the SDK (currently tested on 7.13).
Commander is used to generate a pair of public and private keys. The private key is then programmed into every device to be OTAed. Commander then encrypts and signs the binary file and wraps it with bootloader tokens. The gbl file is downloaded, the signature checked and the encrypted data is then passed to a callback function 64 bytes at a time. You then have to store the data or pass it to the external MCU. This example simply prints the data out a UART.
Procedure:
Step 1: Generate the keys
There two .BAT files in the KEYS directory for this project. These are windows script files. For other platforms you can easily convert them to the platform specific commands. See the comments in the files for more details. In a windows shell type:
GenGblToken.bat
This will use Commander to generate a project set of keys in the files vendor_*.*. Only execute this command ONCE. The same keys are used for the duration of the project. If you change the keys then you cannot OTA the devices as the keys no longer match.
Step 2: Program the key into a devkit and every DUT
Each device manufactured must have the private key programmed into FLASH. Use the PgmToken.bat to program the key into a target device connected via USB. Note that EVERY unit manufactured must have these keys programmed into it.
Step 3: Generate the .gbl file
Create the .gbl file from the binary file using the following command:
commander gbl create <OTA_FileName>.gbl --metadata <BinaryFile> --sign vendor_sign.key --encrypt vendor_encrypt.key
The --metadata option will wrap the binary data with the necessary tokens for the bootloader to parse the data. Do not use the --compress option. If the data needs to be compressed, use your own algorithm for that. There are 3 sample binary files in the KEYS directory - a small .WAV audio file, a large .M4A audio file and a PNG image file. Use the command above to wrap the file with the necessary tokens for OTA.
Step 4: OTA the .gbl file
Use the PC Controller or other application to send the gbl file over Z-Wave. Once the entire file has been sent and the CRC checked to be good, the FinishFwUpdate function is called to begin processing the image. Note that in the PCC you have to first GET the Current Firmware, then select the Target: 1 to download the metadata. Then click on UPDATE and the OTA will begin. Connect a terminal to the VCOM port of the WSTK to view the data streaming down during the OTA. Once all the data is sent down, the signature is checked and the decrypted data is sent out the UART. This is where you would need to change the code to store the data instead of printing it out the UART.
Step 5: Verify the Signature and pass in the callback function
The bootloader_verifyImage() function is called and the metadataCallback function is passed in. bootloader_verifyImage first returns a zero if the signature matches. If the signature fails an error value is returned giving some details on why it failed. The time to verify the signature can be fairly long depending on the size of the image so the watchdog timer is disabled during the processing.
Step 6: MetadataCallback passes blocks of 64 bytes of the decrypted data
The function passed in to bootloader_verifyImage is called with a pointer to the data and the number of bytes in each block. The size of the block can vary up to 64 bytes. In this example the data is simply printed out the UART. In your application you would replace this function with code to store the data as needed on the other MCU or external NVM.
Step 7: Reboot
It is recommended to reboot after the image data has been stored to ensure the FLASH is cleaned up properly. The current demo however does not reboot.
Note: This is an SSv4 SDK 7.13 sample but the same concepts should work in SSv5. The changes to ota_util.c will be folded into the SDK in a future release but for now those changes are necessary.
CTUNE is used to adjust the load capacitance of Silicon Labs Wireless Gecko (EFR32™) portfolio devices crystal oscillator (HFXO).
The crystal frequency is 39 MHz for Z-Wave 700 platform, refer to INS14487 Z-Wave 700 Integration Guide for recommended crystal when using EFR32ZG14 SoC.
It is mandatory to calibrate the crystal for Z-Wave 700 product based on EFR32ZG14 device to ensure the frequency of each product is correct. All ZGM130S modules integrate internal 39 MHz crystal, and are calibrated during production.
The CTUNE calibration procedure is described in INS14498 Mandatory crystal adjustment for EFR32ZG14 based products. To be short:
1. Program a RailTest firmware which is built for EFR32ZG14. More info about how to create a RailTest project in Simplicity Studio for Z-Wave 700, please refer to KB - Create a RailTest project for ZGM130S.
2. Adjust CTUEN value by sending RailTest command 'setCtune 0xYYY' via UART interface. Please follow the procedure described in INS14283 Bing-up/test HW development, section 4.5.6 How to Fine-Tune the System Crystal Using RailTest.
3. Measure RF carrier wave (CW) frequency offset.
4. Repeat step 2 and 3 until the CW average frequency error is adjusted to be within +/-1 ppm for each product.
5. The CTUNE value is incorporated into the Z-Wave protocol. Once a valid CTUNE value is found for the specific product, write it into the CTUNE manufacturing token (TOKEN_MFG_CTUNE) in Flash memory, User Data page. This is can be done by using Simplicity Commander ctune set command.
$ commander ctune set <value>
More information using Simplicity Commander, see UG162 Simplicity Commander Reference Guide, section 6.16 CTUNE Commands.
Once the MicroRF firmware is loaded to a 500 series device, the serial interface can be used to issue commands.
Some example use cases are:
1. Use the rxsweep command to do a spectrum analysis (refer to table 3 in the above document to set the correct frequencies). For example for EU frequencies, set start freq to 86800kHz, stop frequency to 87000kHz, and bandwidth to >1000kHz.
:rxsweep
Enter start freq?
868000kHz
Enter stop freq?
870000kHz
Enter step size?
1000
2. Receive/demod frames (like a crude Zniffer)
:f
Enter freq?
869850kHz (h)ighside/(l)owside? h Baudrate 40k(4), 9.6k(9), 40k & 9.6k(b), 100k(1)?1
:rx a
3. Block a freq using the transmit carrier command
UZB7 not accessible on Windows 10 due to active Energy Saving Mode
Issue: Cases have been reported where new UZB7s are not connecting to the PC Controller when using Windows 10. If energy saving mode is active in Windows 10 then power to the 700 UZB sticks is cut after a short while (when no process is connected to the Serial API). If the UZB stick is accessed again (e.g. through PC Controller) Windows 10 will give it power but for some reason the stick wont boot correctly and is not accessible anymore.
A workaround for this issue is thereby provided until a fix has been released.
How to disable the power save option:
Open the Device Manager -> Ports (COM & LPT) -> Silicon Labs CP210x USB to UART Bridge (COMxx) -> Properties -> Power Management -> Uncheck the box "Allow the computer to turn off ..."
Once the power save option is disabled the UZB sticks will not go to sleep anymore and continue working. However, they still have to be re-plugged once after booting the computer.
Simplicity Commander supports defining custom token groups for reading and writing. Custom tokens work just like manufacturing tokens, but the definition and location of the tokens is configurable.
Here we provide a step-by-step example to illustrate creating a custom token group in the User Data Page of ZGM130S.
Creating Custom Token Group
To create a custom token group, user can use a custom token file with a special filename, tokens-<group name>-efr32.json. <group name> is the name of the custom token group and can be any string. This file must be placed in a specific location - the tokens folder in Simplicity Commander directory on Windows and Linux.
In Simplicity Commander installation directory, open the token folder, copy the existing example JSON file and rename it as tokens-myapp-efr32.json in the same folder.
Now, you can verify the custom token group name saw by Simplicity Commander using command below:
commander tokendump --help
The new custom token group should appear at the option --tokengroup <tokengroup> like this:
Defining Tokens
The address of User Data Page of ZGM130S is starting 0x0FE0_0000 throug 0x0FE0_007FF, total 2 KB. The first 1KB memory space is reserved for Z-Wave stack, user can use the remaining space from address 0x0FE0_0400 to 0x0FE0_07FF for application if desired.
The JSON file can be opened by common Editor tool, such as Nodepad++, Vim, etc. Referring to the existing example token file, we start to edit the myapp token file, define a token named as "MYAPP_SN_BYTE_USERDATA" in User Data Page with offset address 0x0400, the real address of this new token in Flash memory is 0x0FE0_0400.
[
{
"name": "MYAPP_SN_BYTE_USERDATA",
"page": "USERDATA",
"offset": "0x0400",
"sizeB": 8,
"description": "A 8-byte serial number located at the offset of 0x400 in the user data page. The user data page is not cleared on a device mass erase."
}
]
Reading Token from a Device
As we have define the location of the custom token in Flash memory, we can dump the current data from a device using Simplicity Commander, and store the data into a text file. In this example, the serial number of J-Link on my test board is 440143907.
Open the generated output file mytokens.txt, modify the value of the 8-byte custom token we defined above to have the desired content, for example, 0x01234567ABCDEF.
MYAPP_SN_BYTE_USERDATA: 0123456789ABCDEF
Then program the updated token text file into ZGM130S:
Verify the content of the custom token in Flash memory:
commander readmem --range 0x0FE00400:+8 -s 440143907
Reading 8 bytes from 0x0fe00400...
{address: 0 1 2 3 4 5 6 7 8 9 A B C D E F}
0fe00400: 01 23 45 67 89 AB CD EF -- -- -- -- -- -- -- --
DONE
More information, see UG162: Simplicity Commander Reference Guide, section 4 EFR32 Custom Tokens.
Below is an example using the custom serial number defined above in Z-Wave Application through the Manufacturer Specific Command Class, Device Specific Report command.
In Simplicity Studio, create SwitchOnOff application, open the SwitchOnOff.c, update the function CC_ManufacturerSpecific_DeviceSpecificGet_handler() to use the custom serial number.
/*
* This function will report a serial number in a binary format according to the specification.
* The serial number is the chip serial number and can be verified using the Simplicity Commander.
* The choice of reporting can be changed in accordance with the Manufacturer Specific
* Command Class specification.
*/
void CC_ManufacturerSpecific_DeviceSpecificGet_handler(device_id_type_t * pDeviceIDType,
device_id_format_t * pDeviceIDDataFormat,
uint8_t * pDeviceIDDataLength,
uint8_t * pDeviceIDData)
{
*pDeviceIDType = DEVICE_ID_TYPE_SERIAL_NUMBER;
*pDeviceIDDataFormat = DEVICE_ID_FORMAT_BINARY;
*pDeviceIDDataLength = 8;
//uint64_t uuID = SYSTEM_GetUnique();
//DPRINTF("\r\nuuID: %x", (uint32_t)uuID);
uint32_t *customSnAddr = (uint32_t *)0x0FE00400;
*(pDeviceIDData + 0) = (uint8_t)(*customSnAddr >> 0);
*(pDeviceIDData + 1) = (uint8_t)(*customSnAddr >> 8);
*(pDeviceIDData + 2) = (uint8_t)(*customSnAddr >> 16);
*(pDeviceIDData + 3) = (uint8_t)(*customSnAddr >> 24);
*(pDeviceIDData + 4) = (uint8_t)(*(customSnAddr + 1) >> 0);
*(pDeviceIDData + 5) = (uint8_t)(*(customSnAddr + 1) >> 8);
*(pDeviceIDData + 6) = (uint8_t)(*(customSnAddr + 1) >> 16);
*(pDeviceIDData + 7) = (uint8_t)(*(customSnAddr + 1)>> 24);
}
Compiling the update SwitchOnOff application and flash in the ZGM130S. Launch PC Controller, add the device and send the Device Specific Report command, from Zniffer, we can see the value of Device ID Data is the value of the custom token we created above.
In some cases, a solution may be running a zip client locally. In these cases, perhaps you wish to prevent zip traffic from leaving the gateway.
The quickest solution to keeping zip traffic on the gateway, is to take the default lan configuration, and simply delete the ethernet port from the br-lan, leaving all other configuration constant.
Make sure your zipgateway is configured for local-only mode
#reconfigure the zipgateway package
sudo dpkg-reconfigure zipgateway
On the 'Enable Wireless configuration of Z/IP Gateway' screen, select 'wired'
Remove your LAN interface from /etc/network/interfaces.d/br-lan created by the zipgateway package, for example in ubuntu my setup has ethernet interface 'enp0s3' change this to 'none':
auto br-lan
iface br-lan inet dhcp
bridge_stp on
# bridge_ports enp0s3 # <- The original line installed by zipgateway
bridge_ports none
bridge_fd 2
Restart networking
sudo systemctl restart networking
Restart zipgateway
sudo service zipgateway restart
Because the zipgateway controls ipv6 address assignment, a local zip client should now be able to use ipv6 addresses to control end nodes.
But what if you need IPv4 control? You will need to run a dhcp4 server on your gateway. In this example, I am using isc-dhcp-server
Download a dhcp server
sudo apt update; sudo apt install isc-dhcp-server
Bind the isc-dhcp-server to the br-lan by modifying /etc/default/isc-dhcp-server and adding to the "INTERFACESv4" entry.
INTERFACESv4="br-lan"
Using the bridge as our binding interface gives us an added benifit of a constant interface name. If we were to try and rely on our tap in this case, then if zipgateway changes the tap name we run into problems of our dhcp server failing to bind to the correct interface.
If you're feeling adventurous, you can leave this as "", but be advised, if any interface gets an address in a range you specify in dhcpd.conf (later) you will begin serving dhcp requests on that interface. Probably not what you want.
In order to host dhcp on an interface, that interface needs a static IP address. Let's modify /etc/network/interfaces.d/br-lan to use a static address; Pick your favorite local subnet, here - I've used 192.168.123.X/24; Note that we change the top line to 'static' rather than 'dhcp'
auto br-lan
#iface br-lan inet dhcp # <- the old line we're replacing
iface br-lan inet static
bridge_stp on
# bridge_ports enp0s3
bridge_ports none
bridge_fd 2
#modifications for static ip4 mode:
address 192.168.123.1
broadcast 192.168.123.255
netmask 255.255.255.0
gateway 192.168.123.1
Now that our dhcp server has a static address, let's configure a range for our zip devices...
add the following to /etc/dhcp/dhcpd.conf; Be sure your range matches a subnet that your static address is in
Note that 200-1 = 199 ipv4 addresses; Not enough ipv4 addresses if you were to have the maximum 2^8=255 nodes; If you need ipv4 addresses for every possible node ID, you will want to change your netmask above to 255.255.254.0 and be aware that your static address should also widen its netmask
Next, enable the dhcp server on reboots
sudo systemctl enable isc-dhcp-server
At this point, you should reboot and confirm everything is working. You should now be able to control zip nodes with ipv4 addresses.
The Silicon Labs EFR32 family of IoT microcontrollers are very flexible and can do a ton of cool stuff. However, along with all that flexibility comes a lot of complexity. With that complexity are default settings that work fine for many applications but in some cases you want to dig into the details to come up with an optimal solution. In this post I’ll show how to speed up the wake up time for the Z-Wave ZGM130S chip from a GPIO.
But first – a caveat: This post applies to Z-Wave SDK 7.13.x. Future releases of the SDK may have different methods for sleep/wake and thus may require a different solution.
The Problem
Frequently Listening Routing Slaves (FLiRS) devices like door locks and many thermostats spend most of their time in Energy Mode 2 (EM2) to conserve battery power. Once per second they wake up briefly and listen for a Beam from an always-on device. If there is a beam, the FLiRS device will wakeup and receive the Z-Wave command. This allows battery powered devices to use very little power but still be able to respond to a Z-Wave command within one second. FLiRS devices use more battery power than fully sleeping devices like most sensors which use Hibernate Sleep mode (EM4). To wake every second the ZGM130 has to wake quickly and go right back to sleep to minimize power. The problem with EM4 is that it takes a few tens of milliseconds to wake up as the entire CPU and RAM have to be initialized as they were powered down to save power. For a FLiRS device, it’s more efficient to keep RAM powered but in a low-power state and resume quickly to go right back to sleep if there is no beam. Typically the ZGM130 can wake up in about 500 microseconds from EM2. But in many cases this is still too long of a time to stay awake if there are other interrupts such as UARTs or other sensors.
The scope shot above shows the processing that takes place by default on the ZGM130S. In this case I am using a WSTK to drive the SPI pins of another WSTK running the DoorLockKeyPad sample application. The chip is in EM2 at the start of the trace. When SPISEL signal goes low, the chip wakes up. But it is running on the HFRCO oscillator which is not accurate enough to run the radio but it is stable and usable in just a few microseconds. Thus, the SPI clock and data is captured in the USART using this clock. However, by default the Interrupt Service Routine is blocked waiting for the HFXO to stabilize. The 39MHz HFXO crystal oscillator has the accuracy required for the radio.
The question is what’s going on during this 500usec? The answer is the CPU is just waiting for the HFXO to stabilize. Can we use this time to do some other work? Fortunately, the answer is YES! The challenge is that it takes some understanding and some code which I’ll describe below.
The Solution
There are three functions that do the majority of the sleep processing. These are provided in source code so you can read the code but you should not change it. Instead you’ll provide a callback function to do your processing while the chip is waking up.
Simplified Sleep Processing Code:
SLEEP_Sleep in sleep.c: The main function called to enter sleep
CORE_ENTER_CRITICAL – PRIMASK=1 mask interrupts
DO-WHILE loop
Call enterEMx() – this is where the chip sleeps
Call restoreCallback (return 0 to wake, 1 to sleep)
Call EMU_Restore – waits for HFXO to be ready ~500us
CORE_EXIT_CRITICAL – ISRs will now run
enterEMx() in sleep.c:
sleepCallback called
Call EMU_EnterEM[1-4]
wakeupCallback after returning from EMU_EnterEMx
EMU_EnterEM2 in em_emu.c:
Scales voltage down
Call EMU_EM23PresleepHook()
__WFI – Wait-For-Interrupt instruction – ZGM130 sleeps here
Call EMU_EM23PostsleepHook() ~ 17usec after wakeup
Voltage Scale restored which takes ~20us
The code is in sleep.c in the SDK which has a lot more detail but at a high level this is what you need to know. The important part to understand here is where the “hooks” are and how to use them.
Use Sleep_initEx() to assign:
sleepCallback – called just before sleeping
restoreCallback – Return 0 to wake, 1 to sleep
wakeupCallback – called after waking
Sleep_initEx() input is a pointer to a structure with the three callbacks or NULL if not used
Define the function:
EMU_EM23PresleepHook()
EMU_EM23PostsleepHook()
These are both WEAK functions with nothing in them so if you define them then the compiler will install them
The two EMU_EM23* weak functions are run immediately before/after the Wait-For-Interrupt (WFI) instruction which is where the CPU sleeps. These are very low level functions and while you can use them I recommend using the callbacks from Sleep_initEx().
The SLEEP_initEx() function is the one we want to use and in particular the restoreCallback. The comments around the restoreCallback function talk about restoring the clocks but if the function returns a 0 the chip will wake up and if it returns a 1 then it will immediately go back to sleep which is what we want! You can use the other two hooks if you want but the restoreCallback is the key one since it will immediately put the chip back to sleep if everything is idle.
The key to using ANY of these function is that you CANNOT call ANY FreeRTOS functions! You cannot send any Z-Wave frames or call any Z-Wave function as they all require the RTOS. At this point in the wakeup processing the RTOS is not running! All you can do in these routines is to capture data and quickly decide if everything is idle and to go back to sleep. If there is more processing needed, then return 0 and wait for the event in the RTOS and process the data there. You also don’t want to spend too much time in these routines as it may interfere with the timing of the RTOS. A hundred microseconds is probably fine but longer you should wait for the HFXO.
In ApplicationInit() you will call Sleep_initEx() like this:
const SLEEP_Init_t sleepinit = {NULL, NULL, CheckSPI};
...
ZW_APPLICATION_STATUS ApplicationInit(EResetReason_t eResetReason) {
...
SLEEP_InitEx(&sleepinit); // call checkSPI() upon wakeup from EM2.
...
}
...
uint32_t CheckSPI(SLEEP_EnergyMode_t emode) {
uint32_t retval=0; // wake up by default
if (GPIO_IntGetEnabled() & 0x0000AAAA) { // Check SPI
GPIO_ODD_IRQHandler(); // service the GPIO interrupt
// wait for all the bytes to come in and compute checksum
NVIC->ICPR[0] = NVIC->ICPR[0]; //clear NVIC pending interrupts
if (!SPIDataError && !IsWakeupCausedByRtccTimeout()) {
retval=1; // go back to sleep!
}
}
return(retval); // 0=wakeup, 1=sleep
}
Recall that every second the FLiRS device has to check for a Z-Wave beam which is triggered by the RTCC timer. Thus the check for IsWakeupCausedByRtccTimer ensures that the beaming still works.
This scope shot shows the wake up processing of the ZGM130S:
SPISEL_N SPI chip select signal goes low triggering a GPIO_ODD interrupt
The chip wakes up, the HFRCO begins oscillating
HFRCO begins oscillating in a few microseconds
Once HFRCO is running, the peripherals are functional
SPI data can begin shifting once the HFRCO is running
The default HFRCO frequency is 19MHz but can be increased
Higher frequencies for HFRCO also may need more wait states for the CPU and will use more power
The WFI instruction that put the CPU to sleep is exited here
EMU_EM23PostSleepHook function is called if defined
After returning from PostSleepHook, the VSCALE is returned to full power which takes about 10usec
It is best to wait for the voltage to be powered up to ensure all logic is running at optimal speeds
EMU_EnterEM2 is exited and restoreCallback is called if initialized
This is the function where the ISR should be called to process data
If the data says things are idle and want to go back to sleep, return 1
If more analysis is needed, then return 0
Carefully clear the interrupt bits
First clear the peripheral Interrupt Flags
Then clear the NVIC Interrupt pending register
NVIC->ICPR[n]=NVIC->ICPR[n] where n is 0-1 depending on your interrupt
Make sure there aren’t other reasons to wake up fully
!IsWakeupCausedByRtccTimeout() is the 1s FLiRS interrupt
There may be other reasons to wake up which is application dependent
In this example the SPI data is being fetched from the USART at each toggle of the GPIO
The final toggle shows that the checksum was computed and the data is idle so go back to sleep
The chip returns back to sleep in a few more microseconds
Total processing time of this interrupt is less than 200usec which is a fraction of the time just waiting for the HFXO to stabilize
Much of that time is receiving and processing the SPI data
It is possible to sleep in under 50usec if the check for idle is quicker
If your peripheral processing will take significantly less than 500usec, then it may be more efficient to process the data using the HFRCO and not wait for the HFXO to power up. But if your application needs more processing, then you are probably better off waiting. Each application must make their own calculations to determine the most efficient path.
What About Sleeping Devices?
Fully sleeping devices (EM4 also known as RSS – Routing Sleeping Slaves) have entirely different wake/sleep processing. For sleeping slaves the processor and RAM have to be re-initialized and the chip essentially boots out of reset. All that initialization takes quite a bit of time – a few tens of milliseconds. If your device needs to do a lot of frequent checking of a sensor, then it might make more sense to force it to stay in EM2 by setting a Power Lock to PM_TYPE_PERIPHERAL. For more details on power locks see INS14259 section 7.6. Deciding which way to go is application specific so you have to make the calculations or measurements to find the right balance for your project.
This is a complex posting but I hope I’ve made it clear enough to enable you to optimize your application firmware. Let me know what you think by leaving a comment below or on my blog at drzwave.blog.
Z-Wave Knowledge Base
Create a standard OTA bootloader for ZGM130S
In general, you can customize a gecko bootloader for Z-Wave 700. We also have example OTA bootloader which is provided with s37 file. However, we don’t have a project to show the default configuration for this example bootloader. This KB will show you how to create a default OTA bootloader for ZGM130S with simplicity studio v5.
1 Create a bootloader project(bootloader-storage-internal-single-512k) for ZGM130S
The bootloader project is created by AppBuilder. The App Builder is included as part of the "Wireless Tools" package. Please make sure you install it following the steps below
Use the Update icon in Simplicity Studio to launch the Package Manager and then on the "Tools" tab make sure the following packages are installed: "Wireless Tools IDE Integration" and "Wireless Tools".
After that, you should be able to find “Silicon Labs AppBuilder Project” in ProjectàNew. If not, try to create new project in “Application Builder” under “Tools” on the main tab
2 Configure plugins
2.1 Enable LZ4 compression
The .isc configuration file will open and under the ‘Plugins’ tab check the GBL Compression (LZ4) option.
2.2 Enable encryption and signing
Click to highlight the option ‘Bootloader Core, provides API: core’ and under Options, select
“Require signed firmware upgrade files” and “Require encrypted firmware upgrade files” from the list.
3 Configure Storage
Click on the Storage tab and configure the Slot 0 as below, this slot is used for storing the GBL file when OTA.
4 Customize your configuration
Feel free to add other configuration what you want, such as enable “Application upgrade version check”, “secure boot” or “GPIO activation”.
Application upgrade version check
You can find this plugin in Plugins tab; this plugin checks the version number and product ID of the application upgrade before applying. Enable this plugin, a valid product ID and higher version number is necessary for OTA.
Secure Boot
The secure boot feature can be found within Bootloader Core under Plugins tab.
If “Secure Boot” is enabled, Gecko Bootloader checks the integrity and authenticity of the application image before executing it. If the integrity check fails, program control remains in the second stage bootloader. Note that, you must sign your application image if you enable Secure Boot, how to sign an Application for Secure Boot can be found in section 6.5.5 of UG162: https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf
GPIO activation
If the “GPIO Activation” plugin is enabled, the host device can keep this pin low/high (depending on configuration) through reset to make the device enter the bootloader. You can find this plugin in Plugins tab.
More features about Gecko bootloader can be found in UG266: https://www.silabs.com/documents/public/user-guides/ug266-gecko-bootloader-user-guide.pdf
5 Generation and Build
Please save your configuration and Generate it before building this project.
After that, you can flash generated bootloader-storage-internal-single-512k-combined.s37. The KB below shows how to do OTA.
https://www.silabs.com/community/wireless/z-wave/knowledge-base.entry.html/2019/04/09/z-wave_700_ota_ofe-i00M
How to OTA a co-processor via Z-Wave
Problem: How to OTA a co-processor via Z-Wave?
You have a second MCU or other data files you want to OTA via Z-Wave. How can you reuse the Bootloader firmware to verify the signature and decrypt the data?
The code to verify and decrypt the file already exists in the bootloader and is known good. Reusing the existing bootloader code is smaller and safer than re-inventing the wheel - or in this case encryption.
The attached project is a modified Z-Wave Door Lock Key Pad sample application that demonstrates how to OTA code/data other than the Z-Wave firmware. OTA of the Z-Wave firmware works in the sample application already - but first the encryption keys MUST be generated. See https://www.silabs.com/community/wireless/z-wave/knowledge-base.entry.html/2019/04/09/z-wave_700_ota_ofe-i00M on how to generate the keys. See the two .BAT files in the comments section which will run all the necessary commands for you. They are also included in this .sls file in the KEYS directory. You MUST create your own project keys to OTA either the Z-Wave Firmware or any other data.
To OTA other types of files you need to start with a binary file. Most microprocessor development environments will output a binary file so use that instead of a HEX file. If you have an Intel hex or Mototola S record file, use a utility like SREC_CAT to convert it to a binary file. SREC_CAT can convert just about any file type into any other file type. If the file is more than 200K bytes, you will need to break the file into 200K or smaller files and OTA each, one at a time. Doing that is beyond the scope of this project. Note there is no need to encrypt the file. We will be using Commander to sign and encrypt it using the keys generated here.
Theory of Operation:
Changes to the SSv4 DoorlockKeyPad sample project are indicated with the comment "AKER" - search for these to find what changed. You can also diff the files with a fresh copy of the DoorLockKeyPad sample app from SSv4. Most of the code to support OTA of an external processor is in this file. A few changes have been made to ota_util.c in ZAF_CommandClasses_FirmwareUpdate but these are expected to be included in a future release of the SDK (currently tested on 7.13).
Commander is used to generate a pair of public and private keys. The private key is then programmed into every device to be OTAed. Commander then encrypts and signs the binary file and wraps it with bootloader tokens. The gbl file is downloaded, the signature checked and the encrypted data is then passed to a callback function 64 bytes at a time. You then have to store the data or pass it to the external MCU. This example simply prints the data out a UART.
Procedure:
Step 1: Generate the keys
There two .BAT files in the KEYS directory for this project. These are windows script files. For other platforms you can easily convert them to the platform specific commands. See the comments in the files for more details. In a windows shell type:
GenGblToken.bat
This will use Commander to generate a project set of keys in the files vendor_*.*. Only execute this command ONCE. The same keys are used for the duration of the project. If you change the keys then you cannot OTA the devices as the keys no longer match.
Step 2: Program the key into a devkit and every DUT
Each device manufactured must have the private key programmed into FLASH. Use the PgmToken.bat to program the key into a target device connected via USB. Note that EVERY unit manufactured must have these keys programmed into it.
Step 3: Generate the .gbl file
Create the .gbl file from the binary file using the following command:
commander gbl create <OTA_FileName>.gbl --metadata <BinaryFile> --sign vendor_sign.key --encrypt vendor_encrypt.key
The --metadata option will wrap the binary data with the necessary tokens for the bootloader to parse the data. Do not use the --compress option. If the data needs to be compressed, use your own algorithm for that. There are 3 sample binary files in the KEYS directory - a small .WAV audio file, a large .M4A audio file and a PNG image file. Use the command above to wrap the file with the necessary tokens for OTA.
Step 4: OTA the .gbl file
Use the PC Controller or other application to send the gbl file over Z-Wave. Once the entire file has been sent and the CRC checked to be good, the FinishFwUpdate function is called to begin processing the image. Note that in the PCC you have to first GET the Current Firmware, then select the Target: 1 to download the metadata. Then click on UPDATE and the OTA will begin. Connect a terminal to the VCOM port of the WSTK to view the data streaming down during the OTA. Once all the data is sent down, the signature is checked and the decrypted data is sent out the UART. This is where you would need to change the code to store the data instead of printing it out the UART.
Step 5: Verify the Signature and pass in the callback function
The bootloader_verifyImage() function is called and the metadataCallback function is passed in. bootloader_verifyImage first returns a zero if the signature matches. If the signature fails an error value is returned giving some details on why it failed. The time to verify the signature can be fairly long depending on the size of the image so the watchdog timer is disabled during the processing.
Step 6: MetadataCallback passes blocks of 64 bytes of the decrypted data
The function passed in to bootloader_verifyImage is called with a pointer to the data and the number of bytes in each block. The size of the block can vary up to 64 bytes. In this example the data is simply printed out the UART. In your application you would replace this function with code to store the data as needed on the other MCU or external NVM.
Step 7: Reboot
It is recommended to reboot after the image data has been stored to ensure the FLASH is cleaned up properly. The current demo however does not reboot.
Note: This is an SSv4 SDK 7.13 sample but the same concepts should work in SSv5. The changes to ota_util.c will be folded into the SDK in a future release but for now those changes are necessary.
Z-Wave 700: EFR32ZG14 CTUNE Calibration
CTUNE is used to adjust the load capacitance of Silicon Labs Wireless Gecko (EFR32™) portfolio devices crystal oscillator (HFXO).
The crystal frequency is 39 MHz for Z-Wave 700 platform, refer to INS14487 Z-Wave 700 Integration Guide for recommended crystal when using EFR32ZG14 SoC.
It is mandatory to calibrate the crystal for Z-Wave 700 product based on EFR32ZG14 device to ensure the frequency of each product is correct. All ZGM130S modules integrate internal 39 MHz crystal, and are calibrated during production.
The CTUNE calibration procedure is described in INS14498 Mandatory crystal adjustment for EFR32ZG14 based products. To be short:
1. Program a RailTest firmware which is built for EFR32ZG14. More info about how to create a RailTest project in Simplicity Studio for Z-Wave 700, please refer to KB - Create a RailTest project for ZGM130S.
2. Adjust CTUEN value by sending RailTest command 'setCtune 0xYYY' via UART interface. Please follow the procedure described in INS14283 Bing-up/test HW development, section 4.5.6 How to Fine-Tune the System Crystal Using RailTest.
3. Measure RF carrier wave (CW) frequency offset.
4. Repeat step 2 and 3 until the CW average frequency error is adjusted to be within +/-1 ppm for each product.
5. The CTUNE value is incorporated into the Z-Wave protocol. Once a valid CTUNE value is found for the specific product, write it into the CTUNE manufacturing token (TOKEN_MFG_CTUNE) in Flash memory, User Data page. This is can be done by using Simplicity Commander ctune set command.
More information using Simplicity Commander, see UG162 Simplicity Commander Reference Guide, section 6.16 CTUNE Commands.
ZGM130S Package Marking
Question
How to identify ZGM130S revision from package marking?
Answer
The top marking of ZGM130S looks like as below:
Controlling multichannel Z-Wave devices
In Z-Wave, some examples of multichannel devices are
In order to communicate with these devices with multiple endpoints, multichannel encapsulation is used.
Note, when adding devices of this type in the PC controller, it is necessary to hit the "Node Info" button to see all the endpoints.
Typically, the root device is mapped to endpoint 1 to allow some functionality with controllers that do not support multichannel encapsulation.
When Z/IP gateway communicates with multichannel devices the source or destination end point fields are non-zero in the COMMAND_ZIP_PACKET command.
In depth information about multichannel communication can be found in: https://www.silabs.com/documents/login/application-notes/APL12955-Z-Wave-Multi-Channel-Basics.pdf
Using MicroRF Link to debug Z-Wave
MicroRF Link can be used to debug background noise or power supply interference problems. It is the 500 series equivalent to RAIL on the 700 series.
Refer to https://www.silabs.com/documents/login/user-guides/INS12880-Micro-RF-Link-User-guide.pdf as a guide.
Once the MicroRF firmware is loaded to a 500 series device, the serial interface can be used to issue commands.
Some example use cases are:
1. Use the rxsweep command to do a spectrum analysis (refer to table 3 in the above document to set the correct frequencies). For example for EU frequencies, set start freq to 86800kHz, stop frequency to 87000kHz, and bandwidth to >1000kHz.
2. Receive/demod frames (like a crude Zniffer)
3. Block a freq using the transmit carrier command
UZB7 not accessible on Windows10
UZB7 not accessible on Windows 10 due to active Energy Saving Mode
Issue: Cases have been reported where new UZB7s are not connecting to the PC Controller when using Windows 10. If energy saving mode is active in Windows 10 then power to the 700 UZB sticks is cut after a short while (when no process is connected to the Serial API). If the UZB stick is accessed again (e.g. through PC Controller) Windows 10 will give it power but for some reason the stick wont boot correctly and is not accessible anymore.
A workaround for this issue is thereby provided until a fix has been released.
How to disable the power save option:
Open the Device Manager -> Ports (COM & LPT) -> Silicon Labs CP210x USB to UART Bridge (COMxx) -> Properties -> Power Management -> Uncheck the box "Allow the computer to turn off ..."
Once the power save option is disabled the UZB sticks will not go to sleep anymore and continue working. However, they still have to be re-plugged once after booting the computer.
Creating Custom Token for ZGM130S
Simplicity Commander supports defining custom token groups for reading and writing. Custom tokens work just like manufacturing tokens, but the definition and location of the tokens is configurable.
Here we provide a step-by-step example to illustrate creating a custom token group in the User Data Page of ZGM130S.
Creating Custom Token Group
To create a custom token group, user can use a custom token file with a special filename, tokens-<group name>-efr32.json. <group name> is the name of the custom token group and can be any string. This file must be placed in a specific location - the tokens folder in Simplicity Commander directory on Windows and Linux.
In Simplicity Commander installation directory, open the token folder, copy the existing example JSON file and rename it as tokens-myapp-efr32.json in the same folder.
Now, you can verify the custom token group name saw by Simplicity Commander using command below:
The new custom token group should appear at the option --tokengroup <tokengroup> like this:
Defining Tokens
The address of User Data Page of ZGM130S is starting 0x0FE0_0000 throug 0x0FE0_007FF, total 2 KB. The first 1KB memory space is reserved for Z-Wave stack, user can use the remaining space from address 0x0FE0_0400 to 0x0FE0_07FF for application if desired.
The JSON file can be opened by common Editor tool, such as Nodepad++, Vim, etc. Referring to the existing example token file, we start to edit the myapp token file, define a token named as "MYAPP_SN_BYTE_USERDATA" in User Data Page with offset address 0x0400, the real address of this new token in Flash memory is 0x0FE0_0400.
Reading Token from a Device
As we have define the location of the custom token in Flash memory, we can dump the current data from a device using Simplicity Commander, and store the data into a text file. In this example, the serial number of J-Link on my test board is 440143907.
Using Custom Token File
Open the generated output file mytokens.txt, modify the value of the 8-byte custom token we defined above to have the desired content, for example, 0x01234567ABCDEF.
Then program the updated token text file into ZGM130S:
Verify the content of the custom token in Flash memory:
More information, see UG162: Simplicity Commander Reference Guide, section 4 EFR32 Custom Tokens.
Below is an example using the custom serial number defined above in Z-Wave Application through the Manufacturer Specific Command Class, Device Specific Report command.
In Simplicity Studio, create SwitchOnOff application, open the SwitchOnOff.c, update the function CC_ManufacturerSpecific_DeviceSpecificGet_handler() to use the custom serial number.
Compiling the update SwitchOnOff application and flash in the ZGM130S. Launch PC Controller, add the device and send the Device Specific Report command, from Zniffer, we can see the value of Device ID Data is the value of the custom token we created above.
Local only Z/IP client, remove the ethernet port from br-lan
In some cases, a solution may be running a zip client locally. In these cases, perhaps you wish to prevent zip traffic from leaving the gateway.
The quickest solution to keeping zip traffic on the gateway, is to take the default lan configuration, and simply delete the ethernet port from the br-lan, leaving all other configuration constant.
Because the zipgateway controls ipv6 address assignment, a local zip client should now be able to use ipv6 addresses to control end nodes.
But what if you need IPv4 control? You will need to run a dhcp4 server on your gateway. In this example, I am using isc-dhcp-server
Bind the isc-dhcp-server to the br-lan by modifying /etc/default/isc-dhcp-server and adding to the "INTERFACESv4" entry.
Using the bridge as our binding interface gives us an added benifit of a constant interface name. If we were to try and rely on our tap in this case, then if zipgateway changes the tap name we run into problems of our dhcp server failing to bind to the correct interface.
If you're feeling adventurous, you can leave this as "", but be advised, if any interface gets an address in a range you specify in dhcpd.conf (later) you will begin serving dhcp requests on that interface. Probably not what you want.
In order to host dhcp on an interface, that interface needs a static IP address. Let's modify /etc/network/interfaces.d/br-lan to use a static address; Pick your favorite local subnet, here - I've used 192.168.123.X/24; Note that we change the top line to 'static' rather than 'dhcp'
Now that our dhcp server has a static address, let's configure a range for our zip devices...
add the following to /etc/dhcp/dhcpd.conf; Be sure your range matches a subnet that your static address is in
Note that 200-1 = 199 ipv4 addresses; Not enough ipv4 addresses if you were to have the maximum 2^8=255 nodes; If you need ipv4 addresses for every possible node ID, you will want to change your netmask above to 255.255.254.0 and be aware that your static address should also widen its netmask
Next, enable the dhcp server on reboots
At this point, you should reboot and confirm everything is working. You should now be able to control zip nodes with ipv4 addresses.
Fast GPIO Wake Up in Z-Wave 700 Series
The Silicon Labs EFR32 family of IoT microcontrollers are very flexible and can do a ton of cool stuff. However, along with all that flexibility comes a lot of complexity. With that complexity are default settings that work fine for many applications but in some cases you want to dig into the details to come up with an optimal solution. In this post I’ll show how to speed up the wake up time for the Z-Wave ZGM130S chip from a GPIO.
But first – a caveat: This post applies to Z-Wave SDK 7.13.x. Future releases of the SDK may have different methods for sleep/wake and thus may require a different solution.
The Problem
Frequently Listening Routing Slaves (FLiRS) devices like door locks and many thermostats spend most of their time in Energy Mode 2 (EM2) to conserve battery power. Once per second they wake up briefly and listen for a Beam from an always-on device. If there is a beam, the FLiRS device will wakeup and receive the Z-Wave command. This allows battery powered devices to use very little power but still be able to respond to a Z-Wave command within one second. FLiRS devices use more battery power than fully sleeping devices like most sensors which use Hibernate Sleep mode (EM4). To wake every second the ZGM130 has to wake quickly and go right back to sleep to minimize power. The problem with EM4 is that it takes a few tens of milliseconds to wake up as the entire CPU and RAM have to be initialized as they were powered down to save power. For a FLiRS device, it’s more efficient to keep RAM powered but in a low-power state and resume quickly to go right back to sleep if there is no beam. Typically the ZGM130 can wake up in about 500 microseconds from EM2. But in many cases this is still too long of a time to stay awake if there are other interrupts such as UARTs or other sensors.
The scope shot above shows the processing that takes place by default on the ZGM130S. In this case I am using a WSTK to drive the SPI pins of another WSTK running the DoorLockKeyPad sample application. The chip is in EM2 at the start of the trace. When SPISEL signal goes low, the chip wakes up. But it is running on the HFRCO oscillator which is not accurate enough to run the radio but it is stable and usable in just a few microseconds. Thus, the SPI clock and data is captured in the USART using this clock. However, by default the Interrupt Service Routine is blocked waiting for the HFXO to stabilize. The 39MHz HFXO crystal oscillator has the accuracy required for the radio.
The question is what’s going on during this 500usec? The answer is the CPU is just waiting for the HFXO to stabilize. Can we use this time to do some other work? Fortunately, the answer is YES! The challenge is that it takes some understanding and some code which I’ll describe below.
The Solution
There are three functions that do the majority of the sleep processing. These are provided in source code so you can read the code but you should not change it. Instead you’ll provide a callback function to do your processing while the chip is waking up.
Simplified Sleep Processing Code:
The code is in sleep.c in the SDK which has a lot more detail but at a high level this is what you need to know. The important part to understand here is where the “hooks” are and how to use them.
The two EMU_EM23* weak functions are run immediately before/after the Wait-For-Interrupt (WFI) instruction which is where the CPU sleeps. These are very low level functions and while you can use them I recommend using the callbacks from Sleep_initEx().
The SLEEP_initEx() function is the one we want to use and in particular the restoreCallback. The comments around the restoreCallback function talk about restoring the clocks but if the function returns a 0 the chip will wake up and if it returns a 1 then it will immediately go back to sleep which is what we want! You can use the other two hooks if you want but the restoreCallback is the key one since it will immediately put the chip back to sleep if everything is idle.
The key to using ANY of these function is that you CANNOT call ANY FreeRTOS functions! You cannot send any Z-Wave frames or call any Z-Wave function as they all require the RTOS. At this point in the wakeup processing the RTOS is not running! All you can do in these routines is to capture data and quickly decide if everything is idle and to go back to sleep. If there is more processing needed, then return 0 and wait for the event in the RTOS and process the data there. You also don’t want to spend too much time in these routines as it may interfere with the timing of the RTOS. A hundred microseconds is probably fine but longer you should wait for the HFXO.
In ApplicationInit() you will call Sleep_initEx() like this:
Recall that every second the FLiRS device has to check for a Z-Wave beam which is triggered by the RTCC timer. Thus the check for IsWakeupCausedByRtccTimer ensures that the beaming still works.
This scope shot shows the wake up processing of the ZGM130S:
If your peripheral processing will take significantly less than 500usec, then it may be more efficient to process the data using the HFRCO and not wait for the HFXO to power up. But if your application needs more processing, then you are probably better off waiting. Each application must make their own calculations to determine the most efficient path.
What About Sleeping Devices?
Fully sleeping devices (EM4 also known as RSS – Routing Sleeping Slaves) have entirely different wake/sleep processing. For sleeping slaves the processor and RAM have to be re-initialized and the chip essentially boots out of reset. All that initialization takes quite a bit of time – a few tens of milliseconds. If your device needs to do a lot of frequent checking of a sensor, then it might make more sense to force it to stay in EM2 by setting a Power Lock to PM_TYPE_PERIPHERAL. For more details on power locks see INS14259 section 7.6. Deciding which way to go is application specific so you have to make the calculations or measurements to find the right balance for your project.
This is a complex posting but I hope I’ve made it clear enough to enable you to optimize your application firmware. Let me know what you think by leaving a comment below or on my blog at drzwave.blog.