This guide will help you convert an existing Niagara AX module to be compatible with Niagara 4. There are a number of changes we’ll need to make including the directory structure, build files and API changes.
Since we’ll need to make some significant changes to both the directory structure of our code as well as the code itself, we’ll need to keep our Niagara AX code separate from our Niagara 4 code.
If you’re using a version control system such as Mercurial, Git or CVS, we recommend creating a branch for your Niagara AX code base and working on your Niagara 4 changes on the main or default branch.
In this guide we’ll assume that you have your Niagara AX code and Niagara 4 code checked out to separate folders on your file system.
To get started we’ll need to divide our module into one or more module parts (each with different runtime profiles). We can do this by hand, creating the new folder structure, converting build.xml files to .gradle files, moving source files and splitting apart module-include.xml, or we can make use of some of the Niagara tools to do a lot of that work for us.
We can create the proper directory structure and gradle files by using the New Module Wizard.
You’ll need to run the New Module Wizard once for each module part that you need to create. For most Niagara AX modules this you’ll run it once for the rt module part and once for the wb module part.
Notes:
Copy the .gradle files from the ‘dev’ folder of the Niagara 4 Developer image zip file. You will need:
These should be placed in the parent folder that you chose in the New Module Wizard.
Edit vendor.gradle
to set the correct group/vendor and moduleVersion.
Since we have multiple module parts, we want to setup a multi-module build environment. The .gradle files from the ‘dev’ folder set this up but we need to make a few changes to the build.gradle files that the New Module Wizard produces (as it produces single moule build files). Rename <moduleName>-rt/build.gradle
to <moduleName>-rt.gradle
and <moduleName>-wb/build.gradle
to <moduleName>-wb.gradle
. In each of these gradle files, remove the line:
apply from: "${System.getenv("niagara_home")}/etc/gradle/niagara.gradle"
Note: we do this because the niagara gradle plugin is already applied by the root build.gradle
file. Now you can continue with the file copy and IDE import!
The ext { }
section can also be removed from these files since it will override the values in vendor.gradle
Now as a starting point we need to copy the files over from the Niagara AX source location to the Niagara 4 source location.
You can do this using Eclipse or IntelliJ IDEA. The following instructions are for importing into IntelliJ IDEA 2016.1.
If you are using Eclipse or older versions of IntelliJ IDEA, you’ll want to execute gradlew eclipse
or gradlew idea
from your project directory to auto-generate project files for your IDE. You can then open the project file in your IDE.
Niagara 4.2 introduces a new gradle task for converting Niagara AX style slot definitions to Niagara 4 annotation style slot definitions. While Niagara AX style slot definitions will continue to work in Niagara 4, we recommend moving to Niagara 4 annotation style slot definitions as IDEs provide syntax highlight and auto-completion for this style as well as being able to auto-generate module-include.xml files.
The slot tool migration serves two purposes in this guide.
Open the Gradle projects window, and execute the task
niagara > niagara (root) > niagara > migrateSlotomatic.
This is equivalent to executing the console command
gradlew slotomatic -Dslotomatic.migrateBeforeRecompile
Then remove module-include.xml from both the rt and wb module parts. These files will be regenerated with the correct type information during the build process.
Finally you need to fix the code to use the new Niagara 4 APIs. You can identify these by running the Gradle task from the Gradle projects window:
niagara > niagara (root) > build > build
Or, from the command line:
gradlew build
Or, you can open the files in your IDE and identify the items highlighted in red.
The Collections API are detailed in the Collections section of Doc Developer. One common change is in BQL Ord resolutions. - Remove the import of the (nonexistent) javax.baja.collection.BICollection - Update BQL Ord resolutions:
// Niagara AX
BICollection result = (BICollection)BOrd.make("bql:select displayName").get(this);
BITable table = result.toTable();
// Niagara 4
BITable<BObject> table = (BITable<BObject>)BOrd.make("bql:select displayName").get(this);
The Alarm and History APIs were updated to be connection oriented APIs in Niagara. Calls to the Alarm and History Databases will need to be updated. These changes are details in the Alarm and History sections of Doc Developer.
Build the module using the gradlew build
task. Again, you can build it from the IDE or the command line.
Remember to migrate your Niagara AX station as well. You can use the n4mig
executable to do this from the Niagara 4 console.
Copyright © 2000-2019 Tridium Inc. All rights reserved.