Setup a test system with Ignition Primary Host

Information and guides
Sparkplug™ information | Preview how-to | Setup a test system with Ignition Primary Host | Add SparkplugB to an existing CODESYS project

This page
Introduction | Installation

Introduction

This is a recipe to setup a free test system for use with Sparkplug for CODESYS with an Ignition Primary Host.
If you follow this recipe closely it "should" take you between 1 or 2 hours, depending on your experience.
Need any help? -> Drop us a question below, we are happy to assist you.

On choosing your Ignition SCADA Flavor

It's up to you to decide which flavor of Ignition you wish to run as they are identical but differ in use-case scenario.
The provided information is not intended as advertisement but merely to provide you with enough information for you to make a choice on what installation is best suited for you.

Maker Edition

Ignition Maker Edition has powerful industrial-grade features of Ignition Enterprise by Inductive Automation️® to any number of your personal or educational projects
at no cost. All you need is a permanent internet connection for it to work (so called 'always connected'). This seems for most purposes the optimal choice.

https://inductiveautomation.com/ignition/maker-edition for more information

Enterprise Edition

This is the full fledged version of Ignition Enterprise SCADA. Without proper licensing it runs in a DEMO trial period for 2 hours.
The trialperiod can be extended an unlimited amount of times by a single push of a button.

https://inductiveautomation.com/ignition/ for more information

Required Software Components

Host software

• Windows 10 https://www.microsoft.com/en-gb/software-download/windows10
  • WinSCP https://winscp.net/eng/download.php for copying files over from your local Windows 10 Machine (Host) to your Virtual Box Debian client
  • CODESYS Development System V3 https://store.codesys.com/codesys.html
    • CODESYS Control Win 64
    • CODESYS Gateway 64
    • CODESYS IIoT Libraries SL https://store.codesys.com/iiot-libraries-sl.html
    • IEC SparkplugB library https://forge.codesys.com/prj/mqttsparkplugb/home/Home/#download
    • IEC SparkplugB example project https://forge.codesys.com/prj/mqttsparkplugb/home/Home/#download
  • MQTT.fx (optional) https://mqttfx.jensd.de/
  • Oracle VM VirtualBox https://www.virtualbox.org/wiki/Downloads

Client Software

• Debian 10 https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/
  • Mosquitto server (apt install mosquitto)
  • Ignition https://inductiveautomation.com/downloads/ignition
  • MQTT Engine https://inductiveautomation.com/downloads/third-party-modules/8.0.16

Installation

This guide assumes you have Windows 10 and WinSCP already installed on a PC. Feel free to deviate in any way from this guide.
* Download the latest version of all the components listed above:

* With the CODESYS Development System V3 installer, CODESYS Control Win 64 and CODESYS Gateway 64 are also installed.

* Once CODESYS Development System is installed, double click the IIoT Libraries SL package to install it. This has a 30 minute demo, which is reset when you restart the PLC.
* Install mqtt.fx. This is an MQTT client, which also has a SparkplugB decoder. Handy for debugging.

• Install VirtualBox.

Installing Debian

• Install Debian:
  • Open Virtual Box
  • Press File > Host Network Manager > Create. Then tick the DHCP Server Enable box. Then Apply > Close
    
  • Press New, give it a name, and operating system Linux / Debian (64-bit). Press Next.
    
  • Use recommended memory size, but more the merrier.
    
  • Select “Create a virtual hard disk now”, Press “Create”, select the default hard disk file type, dynamically allocated. As it is dynamically allocated, make it as big as you want, say 50GB.
    
  • You should now be back to the main VirtualBox window. Click Settings for the newly created VM.
    
  • Under storage, select the empty CD drive, then the tiny blue CD next to Attributes > Optical Drive. Choose the option “Choose a disk File”.
    
  • Choose the debian iso.
    
  • Under Network, leave Adapter 1 as NAT. Add Adapter 2 as host only network adapter.
    
  • Press OK to accept the settings.
  • Press start to start your VM.
    
  • If asked, hit “Start” on the start-up disk selection dialog
    
  • The Debian installer opens. Select “Graphical install”… choose appropriate languages… choose the first network in the list
  • Choose a useful hostname, maybe debian10-ignition-mosquitto
  • Skip the domain name by leaving it blank
  • Choose a top secret root password, that you can remember. Failing to remember means repeating all these steps again.
  • Choose a useful full name, and then username. Don’t forget the username.
  • Partitioning method: Guided – use entire disk … All files in one partition … Answer Yes to “Write the changes to disks?”
  • Go get a coffee, or other 15minute task, while it installs…
  • Choose the default package manager options.
  • Choose whether to opt in to statistic gathering.
  • Untick the desktop environment, unless you like that stuff.
  • Untick print server.
  • Tick SSH and standard system utilities.
    
  • You could probably squeeze in another coffee at this point.
  • Yes install to master boot record.
  • Install to VBOX_HARDDISK
    
  • Boom! You now have a Debian installation in a VM! Type the username and password you remembered from earlier to get to the terminal
    

Update debian, install mosquitto and get the ip address

• If you are not logged in yet to your linux VM, login.
• su
• type your root password
• apt update
• apt full-upgrade
• apt install mosquitto //note that mosquit[t]o is misspelled, because they wanted to have two ‘t’s like MQTT does.
• nano /etc/network/interfaces
• now copy the lines for enp0s3 and duplicate for enp0s8, and change allow-hotplug to auto
  
• Press Ctrl+X to exit and Y to save. Press Enter to accept original file location.
• systemctl restart networking
• ip addr show enp0s8
• take a note of the ip address, you will need this!

Install Ignition

• Use scp from a windows command prompt to copy the installer to your linux box

  • WindowsKey+R, type “cmd”, enter
  • Use an scp command similar to:
  • scp C:\Ian\install\ignition-8.0.16-linux-x64-installer.run user@192.168.56.103:ignition-install.run
  • scp C:\Ian\install\MQTT-Engine-signed.modl user@192.168.56.103:MQTT-Engine-signed.modl
    
  • Login to linux.
  • su
  • chmod +x ignition-install.run
  • /sbin/useradd ignition
  • ./ignition-install.run
  • Give the user you added above (ignition)
  • Default install location
  • Press 2 for custom install
  • Press y for modifying included modules
  • Press n for every one of the default modules, except maybe OPC-UA and Vision.
  • Press y for modify additional modules, then press y for install additional modules. The path is:
  • /home/user/MQTT-Engine-signed.modl
  • Type n for “Would you like to install additional modules?”
  • Type y for “Are you finished modifying the modules?”
  • Type y for “do you want to continue?”
  • Type y for “Start Ignition now”
  • Type y for “Install Service”
  • Back in Windows, open a browser and navigate to http://ip-address:8088
  • Pick any flavour you like (Maker Edition has no time-out)
    
  • Agree the terms
  • Set up a memorable username and password
  • Start Gateway:
    
  • Once it starts, go to Config > System > Modules > Quarantined Modules > MQTT Engine > Install
    
  • You now have an Ignition server with MQTT Engine installed.

• You did it!

Running an application

• Start MQTT.fx to monitor the topics:
  • If not already started, start your Debian10-ignition-mosquitto. No Need to login to linux.
  • Launch MQTT.fx from Start menu or C:\Program Files\mqttfx\mqttfx.exe
  • Press the gear to add your MQTT Server
    
  • Press the + down the bottom to add a new Server
    
  • Give it a profile name, the IP address of your mqtt server, generate a client ID, then press OK
    
  • Press Connect
    
  • Go to the subscribe tab, and subscribe to the following topics:
    • spBv1.0/SparkplugBDevice/NBIRTH/+
    • spBv1.0/SparkplugBDevice/NDEATH/+
    • spBv1.0/SparkplugBDevice/NDATA/+
    • spBv1.0/SparkplugBDevice/NCMD/+
    • STATE/+
      
  • Switch the payload decoded by to Sparkplug Decoder
    
• Start Ignition, to wait for connections:
  • If not already started, start your Debian10-ignition-mosquitto. No Need to login to linux.
  • By default, Ignition MQTT Engine will automatically connect to the local MQTT Server, so this does not need setup. If you need to set it up, use http://ip-address:8088 > Login > Config > MQTT Engine > Servers > Create new or edit.
  • The easiest way to browse tags is through designer. Login to http://ip-address:8088 then press the Get Designer button to download the installer.
    
  • Once installed launch designer. If your Gateway isn’t there, Add Gateway > Manually Add Gateway and type in http://ip-address:8088 before pressing “Add Gateway”.
  • You should now see the Gateway, click Launch to launch designer. Login.
    
  • Create a new project
    
  • Use the defaults, but give it a name and title.
    
  • Looking at the tag browser, you should currently see no sparkplug nodes.
    
• Install the sparkplug library:
  • Now go back to the folder where you downloaded everything. Double click the sparkplug library to open it.
    
  • Press the filing cabinet icon “Save Project and Install into Library Repository”
    
• Configure the example project for your CODESYS runtime:
  • Back to the folder where you downloaded everything. Double click the sparkplug example project to open it.
    
  • These steps are CODESYS 101. You should do this for every example project you open:
    • Cancel the initial dialog asking about updating compiler etc.
      
    • Right click Device in the Devices view, And select “Update Device”
      
    • Select the actual version of your PLC runtime and hit “Update Device”, wait for it do its thing, then hit “Close”
      
    • Project > Project Environment > Set All to Newest > OK > OK
    • If your PLC is not running, start it now from the system tray. If you haven’t purchased a license, the PLC will stop after 2 hours, and the CODESYS MQTT Client SL will stop working after 30 minutes. If this happens you will have to stop it and start it again.
      
    • Double Click the Device in Devices Tree, and go to the communication Settings Screen. Scan your local Gateway, and double click your local PLC. (ProTip: If you want this much nicer view, Tools > Options > Device editor > Communication page > Classic mode)
      
  • Open PRG_FB_EoN_Node, and change the server URL to the ip address of your MQTT server.
  • As this is a private Mosquitto, we will change test scenario to 2 as well.
    
  • Go Online with this icon:
    
  • Yes:
    
  • Hit F5 or press the play icon to run the application:
    
  • After a few seconds you should see it ONLINE:
    
  • Now let’s look at the log.
    • Double click the Device in the device tree and go to the Log tab.
    • If you do not have a license for the runtime or you do not have a license for the CODESYS IIoT Libraries SL, sou should see these messages:
      
    • To access the sparkplug specific logs, press these buttons and select SparkplugB:
      
    • You can change the verbosity of the logs with the verbosity param. Go Offline and open library manager, and browse through Sparkplug B MQTT > SparkplugB > GlobalVariables > GVL_Param_sparkplugB.
      
• Is everything working?
  • Check in MQTT.fx, you should have some payloads:
    
  • Check in Ignition Designer, you should have some new tags in tag browser, changing every 5 seconds (configurable):
    
• For more information on using CODESYS, go to help.codesys.com and forge.codesys.com/forge/talk/
• For more information on using Ignition, go to inductiveuniversity.com and forum.inductiveautomation.com

Need help? -> Drop us a question, we are happy to assist you.