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.
This guide uses the DoorlockKeyPad built under 7.12.2 but the same basic concepts apply to any sample app and your project. A generic KBA on upgrading SDKs for Bluetooth projects provides general insights but this document is specific to this Z-Wave release.
Update Simplicity Studio (SS)
From the Launcher perspective, click on the download icon and then click on Update All
Close Simplicity and restart (just to be safe) - SS may ask to do this as well
Click on the download button again, click on Package Manager, click on SDK tab, click on each Update button (keep scrolling down). I recommend restarting SS between each update.
Set the Preferred SDK to the latest release
Plug in a WSTK devkit or select the ZGM130S in the MyProduct window
From the Launcher perspective, click here:
Select the Gecko SDK Suite 7.13.3.0
Now when you want to create a new project it will start with the 7.13.3 release
At this point there are 3 options for upgrading:
Open a new 7.13.3 project and then copy your changes into it
Import/Export parts of your project into a new 7.13.3 project
Manually edit the .cproject and .project files
Far and away the best option is the first one - option A
The advantage of this is that you get all the latest and newest files of the Z-Wave Application Framework (ZAF), emlib, linker scripts, and lots of other stuff
The challenge is that you have to plug all of your changes back into the sample application
If you’ve made most of the changes in files other than the sample application, then the changes are probably easy to install
However, if you’ve made a lot of changes to the sample application source code file it will take more time
Option B or C might be the way to go but at some point it might still be better to go back to option A. Option A is fairly straightforward as the sample apps in the 7.13.3 release already work so just copy in your changes a few at a time and keep recompiling to make sure you haven’t broken something.
If taking option A you’re done! No need to read any further! Create the new sample app and start plugging in your changes
If you’re not taking option A, pick one of the 2 options below. The choice of B or C is up to you and primarily how confident you are in fixing XML files. If you think you can fix an XML file, then use option C otherwise use B.
Option B - Import/Export parts of your project into a new 7.13.3 project:
This option avoids manually editing the XML file but requires importing/exporting several files and using the GUI to fix paths. The advantage however is that you shouldn’t break the XML file which is easily done with manual editing.
Export the project created with Z-Wave 12.2 SDK using [File] > [Export...].
Window->Preferences->SimplicityStudio->SDKs
Remove the 7.1x.xx SDKs from the Simplicity Studio SDK preferences
This does not delete or uninstall the actual SDK, just removes it from the current workspace settings so it will not be used during the project import step
Import the .sls file created with the export. ([File] > [Import...]) above
Right click the project from the IDE perspective
Project Properties [C/C++ Build] > [Board / Part / SDK] and select the Gecko SDK Suite: 7.13.3.0, Flex 2.7.3 from the dropdown list
When it asks to Rebuild Now - click on YES!
The build will fail because the Linker script location has changed from:
Try to Build again but now there are all sorts of problems with basic things like SizeOf.h cannot be found. This is caused by the change in the directory structure for the 7.13 SDK.
In the 7.13.3 project - right click on the project->properties->C/C++ General->Paths and Symbols and click on EXPORT Settings
Export them all to a temporary file - IE:Seven13Paths.xml
Return to the same screen in your project, <CTL-A> to select all the paths then Delete - be sure to delete ALL of them
Then click on Import Settings and select the Seven13Paths.xml file
Build again and you should get a “conflicting types for __Vectors” error
This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
Build again and you get an error “No rule to make target libZWaveSlave.a”.
Right click properties->C/C++Build/Settings->GNU ARM C Linker->Other objects
If other errors turn up, try doing a Clean Project and exit SS and start it up again
Click Build
OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
Click Build
The error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2. Basically, delete (or #if 0/#endif) several lines of code.
Click Build
The error is: Undefined Reference to CC_FirmwareUpdate_InvalidateImage
The confusing part of this error is that you can click on this function and it will open the correct file. The problem is that it is not included in the project.
The problem is there are 2 new Linked files - btl_reset_cause_util.[c,h].
Copy via a link into the ZAF_CommandClasses_FirmwareUpdate
The project builds correctly! You may have additional files/directories that need to be cleaned up or corrected. Usually compare what is in the 7.13.3 project with yours to find what’s changed.
Program your project in your device and verify it still works
It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
Connect the debugger using an Attach To
Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
ASSERT(NULL != pData);
Looking back in the sample app we notice there is a new Init routine for this command class:
CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
Which also needs a new definition:
SCCZWavePlusInfo CCZWavePlusInfo = { …
Adding these to the source code, recompiling and downloading and testing it now works
There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.
Option C - Manually edit the .cproject and .project XML files:
This option uses a text editor to edit the two XML files SS uses to build your project. XML files are very picky and if you mess up the structure of the document it simply won’t work. So be very careful or go back to option A.
Open a new sample project in the 7.13.3 release using the same sample app you started with originally
Compile it and make sure it builds without error - change APP_FREQ to REGION_US (or your region) if needed
Close Simplicity Studio
The .cproject and .project are XML files which you can edit in a text editor. If you mess up the hierarchy of the file, it can make the files unusable. Editing the files is tricky so be very careful and keep backups of your work.
Rename the .cproject and .project files in your application directory - add .orig or .old to the filename
Copy the .cproject and .project files from the top level of the 7.13.3 sample app into your application directory
Open the two .cproject files in a text editor and diff the two files
Carefully copy the few things you need from your original .cproject file into the 7.13.3 one - typically this is just a few filenames you have added to the project and other customizations
You’ll see that many files are now in different directories
many files now have /protocol/z-wave added or /util removed - all of these changes are necessary now that Z-Wave has been integrated with the other wireless protocols
Open the two .project files in a text editor and diff the two files
Follow the same procedure as with the .cproject file
The project name is the 3rd line of the file - this will certainly need to change
Open SS and select the project
Click on Clean Project
Click on Build
There are likely several errors usually caused by include paths not being correct
Click on the Problems tab and highlight the error
Go to the corresponding line in the 7.13.3 project and find the correct include path
Copy that into your project properties
In my trial SS was not able to find ZAF_common_helper.h
Adding "${StudioSdkPath}/protocol/z-wave/ZAF/ApplicationUtilities/_commonIF" to the C include paths got it past this error
Click Build
Next problem is that UReceiveCmdPayload did not have a corresponding member
In this case the structure has added an extra level of hierarchy so the reference changes from:
Next problem is that __Vectors has conflicting types
This is caused by a new Device/startup_zgm13[.S,.c] - copy these files from the 7.13.3 project into your project
Click Build again
Now the error is: Undefined reference to `FileSystemVerifySet' in DoorLockKeyPad.c
The problem here is that the ZAF has changed how it is checking the state of the file system and using a much easier process of checking a few Tokens in NVM3. Compare the 7.13.3 sample app code and use that process instead of the one from 7.12.2.
Click Build
OtaInit() function has changed to CC_FirmwareUpdate_Init() which needs a 4th argument which is “true”.
Click Build
The project should now build correctly
There are other potential problems with missing include directories, #defines or function names that have changed. The solution is to search the new 7.13.3 project for the same area of code and identify the new directory or function name.
Program your project in your device and verify it still works
It is possible that other changes to the code may be required for SmartStart, Inclusion, handling of NVM3, interrupts, peripherals and other features. Expect that it may take a day or so to resolve these problems.
For example, in the DoorLockKeyPad sample application, when a Z-WavePlusInfo_GET is sent, an ASSERT is executed and the CPU takes a hardfault and essentially crashes.
Connect the debugger using an Attach To
Click on Pause and the Debug pane shows the call stack which says we hit an assert within the SDK from handleCommandClassZWavePlusInfo()
Set a breakpoint at the start of this command and restart the debug session and resend the ZWavePlusInfo_GET which should stop the CPU at the start of the handler
Single step thru the code until you find the CPU in the defaultHandler again (you’ll have to click Pause)
The problem is that the Static structure pData is NULL and as a result the ASSERT is triggered:
ASSERT(NULL != pData);
Looking back in the sample app we notice there is a new Init routine for this command class:
CC_ZWavePlusInfo_Init(&CCZWavePlusInfo);
Which also needs a new definition:
SCCZWavePlusInfo CCZWavePlusInfo = { …
Adding these to the source code, recompiling and downloading and testing it now works
There may be several other things that need to be updated or initialized with each release so more testing and debug may be required.
Another minor issue with the 7.13.3 release is that it is not properly creating the .GBL files for OTA. The fix is simple:
Modify line 46 in \SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.7\protocol\z-wave\ZAF\ApplicationUtilities\application_properties.c
from:
.type = 1<<6UL,
to:
.type = 1<<7UL,
My recommendation is to click on this file in the Project Explorer->ZAF_ApplicationUtilites and make the change. When you change the code, this popup comes up:
And you should click on Make A Copy.
When the next minor release comes out this will be fixed and you will then want to delete the copy and go back to the Linked version of the file. I do NOT recommend changing the files in the SDK.
The Z-Ware C API allows for OTA updates of devices. This article provides an example of how to use it.
zwif_fw_info_get() should first be called to find information about the device and then zwif_fw_updt_req() should be called to perform the update. Each of those functions has callbacks that must be implemented.
The example provided is based on the existing bin_switch demo. It finds the first binary switch node and then allows that node to be updated by adding an additional menu option to do so.
Two places in the code were modified from the plain bin_switch demo. Inside the bin_sw_intf_get() function an additional option to find the firmware update interface was added. The callbacks were added and the main function was modified to add menu option 3 to perform the update.
To run the demo make sure you have a firmware image (.gbl or .otz file) for the binary switch end device example in the same directory as the executable.
Z-Wave Knowledge Base
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.
Upgrading 700 series project from 7.12.2 to 7.13.3
This guide uses the DoorlockKeyPad built under 7.12.2 but the same basic concepts apply to any sample app and your project. A generic KBA on upgrading SDKs for Bluetooth projects provides general insights but this document is specific to this Z-Wave release.
Another minor issue with the 7.13.3 release is that it is not properly creating the .GBL files for OTA. The fix is simple:
Modify line 46 in \SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.7\protocol\z-wave\ZAF\ApplicationUtilities\application_properties.c
from:
.type = 1<<6UL,
to:
.type = 1<<7UL,
My recommendation is to click on this file in the Project Explorer->ZAF_ApplicationUtilites and make the change. When you change the code, this popup comes up:
And you should click on Make A Copy.
When the next minor release comes out this will be fixed and you will then want to delete the copy and go back to the Linked version of the file. I do NOT recommend changing the files in the SDK.
Z-Ware OTA Firmware Update with the C API
The Z-Ware C API allows for OTA updates of devices. This article provides an example of how to use it.
zwif_fw_info_get() should first be called to find information about the device and then zwif_fw_updt_req() should be called to perform the update. Each of those functions has callbacks that must be implemented.
The example provided is based on the existing bin_switch demo. It finds the first binary switch node and then allows that node to be updated by adding an additional menu option to do so.
Two places in the code were modified from the plain bin_switch demo. Inside the bin_sw_intf_get() function an additional option to find the firmware update interface was added. The callbacks were added and the main function was modified to add menu option 3 to perform the update.
To run the demo make sure you have a firmware image (.gbl or .otz file) for the binary switch end device example in the same directory as the executable.
Z-Wave 700: TX Power calibration/adjustment in RAILTest and Application FW.
The relation between the TX-Power in dB and the raw value used in RAILTest is given by this:
To make the conversion easy the INS14664: Introduction to MaxPowerCalc has been added in Simplicity Studio.
#define 0dBmMeasured // dBm Value measured by raw power setting 24,
// remember to counteract for cables in the setup.
#define wantedOutputPower // The dBm PA output power wanted for the customers application
#define scaledPower (wantedOutputPower - 0dBmMeasured) // intermediate variable for use below
#define rawPASetting (0.000133848*(scaledPower)^5 + 0.001042021*(scaledPower)^4 \
– 0.005109317*(scaledPower)^3 + 0.11773548*(scaledPower)^2 \
+ 3.007063918*(scaledPower) + 24.35849668)
The raw values are used in RAILTest (please make sure to use lower case letters "raw" in RAILTest )
and the settings in the Z-Wave SDK application code are set in "config_rf.h" in dBm:
// The maximum allowed Tx power in deci dBm
#define APP_MAX_TX_POWER 0 // set to 0 dBm by default in the Z-Wave SDK
// The deci dBm output measured at a PA setting of 0dBm (raw value 24)
#define APP_MEASURED_0DBM_TX_POWER 0 //Set to 0 to measure the 0 dBm
// This is set to 33 by default to support the development boards in the Z-Wave SDK
The maximum raw value in RAILTest is limited to 155 and the TX power max is 13dBm on the RFpin
More information can be found in
INS14283-6 Bring-up/test HW development, 4.5.1 How to Adjust the PA Output Power Using RailTest
INS14259-9 Z-Wave Plus V2 Application Framework SDK7, 6.3 Setting Up config_rf.h