Getting Started With Ignition Module Development

You’ve got a great idea for a new Ignition module and want to start writing code for it yesterday. Let’s get you and your development environment up and running as quickly as possible so you can start writing code! I advise reading this guide completely through before running the commands one by one, as there are some “gotchas.”

In making this guide, I am using Windows 10 64-bit and Ignition 7.9.1. There may be significant differences if using different platforms.

In developing modules for Ignition, you will be using Maven to “manage a project’s build, reporting and documentation.” To install Maven, open a Windows command prompt as Administrator and simply run the following:

@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

choco install maven

Chocolatey (AKA choco) is a package manager for Windows that makes installing Maven very simple.

An perk of using Maven is that Inductive Automation has Maven Archetypes that you can use to bring in the basic scaffolding of any module, allowing you to more quickly get to writing the code that is specific to your module. Here is an example of creating a new project (your module project) using Maven archetypes. Change to the directory where you would like your module directory stored in and run the following:

mvn archetype:generate -DarchetypeGroupId=com.inductiveautomation.ignitionsdk -DarchetypeArtifactId=client-designer-gateway-archetype -DarchetypeVersion=1.0.3

If running this command using Windows PowerShell the -Doptions need to be quoted, like:

mvn archetype:generate "-DgroupId=com.mycompany.app" ...

There are several archetypes to choose from, depending on what kind of module you are developing.  Above, we used client-designer-gateway-archetype but you may choose from:

  • client-designer-gateway-archetype
  • opc-ua-driver-archetype
  • vision-component-archetype

After running the above mvn command, you will be prompted for several options as follows. Customize the options specific to your module.

Define value for property 'groupId': : com.perfectabstractions.myapp
Define value for property 'artifactId': : testModule
Define value for property 'version':  1.0-SNAPSHOT: : 1.0.3
Define value for property 'package':  com.perfectabstractions: :

Using the default version of 1.0-SNAPSHOT will result in an error when trying to import your module later on. It appears that Ignition requires your module to have a three digit version number such as 0.0.1 or 1.0.3. Version numbers such as 1.0 will result in an error.

Next you will want to install the Eclipse Neon IDE  and Java SE Development Kit 8 if you haven’t already. Within Eclipse, import the Maven project using File -> Import -> Maven -> Existing Maven Projects. Select the root directory of the Maven project you created above, select all the projects, and click Finish.

Your Eclipse window should now look something like this:

You can probably guess that you can extend functionality in the client, designer, and gateway. Let’s make a Hello World in the Designer. Expand yourModule-designer and its subfolders until you find DesignerHook.java. You may notice some red underlining on import statements. Hovering over the red underlined text will show messages like “The import org.slf4j cannot be resolved.” To resolve these issues, while hovering over the text, select the “Fix Project Setup” Quick Fix and click “OK” to add the archive to your project.

Now you can see the very handy Eclipse auto-complete in action. As you start typing your code, you will see the methods that are available to the class you are using:

In our case, in DesignerHook.java, within the startup method of the DesignerHook class, let’s add the following line of code after the super.startup line:

logger.info("Hello World!");

Now we’re ready to build our project! Right click on the root project (i.e. testModule, not testModule-Designer) in Eclipse, and select Run As -> Maven Build. The first time you select this option, you will have to enter “package” in the Goals field. Every other time it will remember this configuration choice.

Then click “Run” and you should see output in your Eclipse Console that ends with:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.450 s
[INFO] Finished at: 2017-03-07T11:13:31-08:00
[INFO] Final Memory: 12M/245M
[INFO] ------------------------------------------------------------------------

Congratulations! You have built your first Ignition module. Let’s load the module into our Ignition Gateway. First, since we are not worrying about signing our module at this time, we have to allow unsigned modules. In ignition.conf (default location C:\Program Files\Inductive Automation\Ignition\data\ignition.conf), in the #Java Additional Parameters section, add the following line:

wrapper.java.additional.7=-Dignition.allowunsignedmodules=true

Then restart Ignition using the Gateway Control Utility and you can now load unsigned modules. In the Configure section of the Gateway website, go to the configure -> Modules page. At the bottom, click “Install or Upgrade a Module…” Click Choose File, and select your .modl file. The default directory for this file is yourModuleRootDirectory\testModule-build\target. Follow the simple instructions to install your module. Back on the Modules page, you should see something like this if your module installed correctly:

Now, launch the Ignition Designer, open a project, and you should see something like the following in your Console:

INFO  [main-Designer-Startup] Starting module: testModule Ignition Module [+3890]
INFO  [DesignerHook-Designer-Startup] Hello World!

That’s it! You now have a working Ignition module. In later posts, we will explore how to do some basic functionality like creating new windows, adding new items to the menu bars, and interacting with the Project Explorer tree.

Indispensable resources for any Ignition module developer include:

2 thoughts on “Getting Started With Ignition Module Development

Leave a Reply

Your email address will not be published. Required fields are marked *