Upgrading 700 series project from 7.12.2 to 7.13.3
03/90/2020 | 08:21 PM
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.
Knowledge Base Articles
Z-Wave
SDK 7.13.3.1.0 was released today which provides the workaround for creating the GBL file in the release notes. See SRN14629 page 8 or search for SWPROT-4021. The code was not fixed, just the release notes explaining the workaround.
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.