Geographic Information System Mapping

The SCADA Additional Components bundle, provided along with the recent Adroit long-term support release is available separately and includes, amongst other things, a Geographic Information System (GIS) Add-on:

In this quick start guide we install the GIS Add-on and build a demo water treatment application monitoring half-a-dozen different reservoirs geographically spread around UK. The reservoirs and geographical co-ordinates in decimal notation are shown in the table below:

Reservoir Latitude Longitude
Ardleigh 51.915278 0.955556
Bosley 53.191389 -2.118056
Derwent 54.866667 -1.9833336
Drift 50.108 -5.591
Llyn Cwellyn 53.072222 -4.151667
Threipmuir 55.861944 -3.319444

Installing the GIS Add-on and creating a GIS data source

Start with the Adroit Config Editor and create a new configuration called GIS Quick Start after ensuring you have allowed multiple configurations. Name, and then create the new configuration by clicking OK and make it the active configuration by clicking the Apply button…

You can now go ahead and install the GIS Add-on by making sure it is selected in the list of additional components, and clicking the Next button (cf. screenshot above)

Once the GIS Add-on has completed installing, start the Adroit Agent Server which will in turn start the Adroit Smart UI Server enabling us to run Adroit Smart UI Designer

Start Smart UI Designer and when it has started up and logged you in, right-click the top server node in the Servers tree as shown, and click Add Datasource. Select the GIS Datasource Plugin, and call it, say, GIS1

At this point you should see a new GIS folder, below the Projects folder at the bottom of the tree with a single GIS datasource called GIS1

Creating agents to implement water treatment application

Next we create and configure a handful of agents to represent our water treatment application

Agent Groups

Firstly, after opening the Configurator in Smart UI Designer create AgentGroups corresponding to each of the six geographically dispersed sites…

Call these ARD, BOS, DER, DRI, LLY, THR, i.e. the first three letters of each site name

We will use these same three letters as prefixes for the agent names at each of the different sites

At each site we are going to monitor for four Analog level alarms High-high, High, Low, and Low-low, as well as a single Digital On intruder alarm

In other words, the agents to be created for each site are…

Site Group (Agent Group) Level Alarms (Analog) Intruder Alarm (Digital)
Llyn Cwellyn LLY LLY_LVL_001 LLY_INTR
Threipmuir THR THR_LVL_001 THR_INTR


Create Analog agents named as XXX_LVL_001 where XXX is one of the three-letter site prefixes described above

Starting with, say, Analog ARD_LVL_001, Ardleigh Reservoir Level, change the Engineering Maximum from its default value of 1000 to 100. At the same time create thresholds of 90, 75, 25, and 10 corresponding to the different Alarms and specify Engineering Units of metres, as shown

Copy Agent ARD_LVL_001 to BOS_LVL_001, changing only the Name and Description as required. Copying like this (as opposed to Creating) avoids having to do the same configuration changes each time for every new level

Repeat this until all six Analog levels have been created

Note: we could easily have done this in an offline Excel worksheet as described in the very first Quick Start guide in this series, but it hardly seems worth the trouble for a mere half-dozen levels

Complete the alarm configuration for the six Analogs by multiply selecting them, using either Shift-End or Ctrl click as required, and then click the Alarm… button centre right in the main configurator window to invoke the Alarming dialog for a batch of agents as shown

Next, move the required four Alarm types from the Available list to the Current list by double-click or left chevron [<<] button

To keep things manageable (no audibles or acknowledgements required), select Route 3 and uncheck the Acknowledgement required checkbox

Finally for the High-high and Low-low alarm types choose Priority 3 High instead of the default Priority 2 Normal


Now create the six Digital agents named XXX_INTR, starting with ARD_INTR, Ardleigh Intruder Alarm, and successively copy them, each time just changing the name and description just as you did for the levels

Complete the alarm configuration for the six Intruder Alarms by multiply selecting them, using either Shift-End or Ctrl click as required, and then click the Alarm… button centre right in the main configurator window to invoke the Alarming dialog for a batch of agents as shown

Next move the required On Alarm type from the Available list to the Current list by double-click or left chevron [<<] button

Once again, to keep things manageable, select Route 3 and uncheck the Acknowledgement required checkbox

Finally choose Priority 4 highest instead of the default Priority 2 normal

Agent Grouping

In order to group the Analogs and Digitals into the correct groups, select them one-by-one and allocate them to their respective groups by clicking the Groups… button centre right in the main configurator window to invoke the Agent Groups dialog as shown

Allocate group membership by moving the required group name from the Available list to the Current list for the selected agent

You need to do this for both the Reservoir Level Analog and the Intruder Alarm Digital at each reservoir site

Thereafter, you should be able to navigate around the configuration by selecting the required Group from the right-hand side Group combo box in the main configurator window, instead of just navigating by Type using the more usual Type combo box centre left in the main configurator window

Note that unlike when navigating by Type, when navigating by Group you can see heterogenous agents e.g. Analogs and Digitals, instead just one type (homogenous agents)

Simulating Application Activity

In order to simulate some activity in the application, we create two Script agents – INTRUDER_SIMULATION and LEVEL_SIMULATION. These are scheduled to run every minute

The JScript scripts for these are shown below…

For the Intruder Simulation script, running every minute…

If the minute relative to start is a multiple of 3, Ardleigh Intruder Alarm is set ON, and all the others are set OFF, but if the minute number is a multiple of 5, Bosley Intruder Alarm is set ON, and all the others are set OFF

And so on, for increasing prime numbers and sites until if the minute number from start is a multiple of 17, Threipmuir Intruder Alarm is set ON, and all the others are set OFF

For the Level Simulation script, every minute we simply set a different random real number between 0.0 and 100.0 into each of the six site’s reservoir levels

Clearly, this is a lot more dynamic/volatile than you’d expect from a real-world water treatment application, but should at least provide regularly varying data so that we can easily visualize what’s happening without having to wait too long


The final bit of agent server configuration is to log the changing tags so that we can see their history on any site trends displayed

To do this, select the first Analog ARD_LVL_001 from the list of Analog type agents in the main configurator window, and click the Log… button bottom right

Change the length and rate as shown to 1 day and 1 second, which will be more than adequate since tags aren’t changing any more frequently than once every minute. Click on the Start radio button at the top to start logging

Next, multiply select the remaining reservoir levels either by Shift- or Ctrl-click whichever you prefer, and then simply click the Log… button again. This will log the remaining levels according to the same logging parameters as the first one (1 day, 1 second, and started)

Do the same for the Intruder Alarm Digitals by multiply selecting them all and just clicking the Log… button

In this way, we have been quickly able to configure a whole bunch of data points for historical logging

Adapting some existing templates

Adroit Smart UI includes an impressive number of in-built artefacts enabling you to build your user interface without having to do too much stuff from first principles

So, we are going to adapt some existing faceplate templates to suit our needs in water treatment

First, in Smart UI Designer, create a new project called GIS Quick Start by right-clicking the Projects tree-node as shown, and then selecting Add a Project from the context menu that appears

Next, navigate into Shapes Wizards and Examples and locate the Analogue Faceplate Template form under the Templates/Analogues sub-folder. Open it and then save it as Reservoir Level Template in the GIS Quick Start project...

As an illustration of how to adapt existing artefacts, we are going to customize this template for a water treatment application

Select the circular gauge in the template, delete it and replace it by a PictureBox in the Windows Forms tree-node and a LinearVerticalGauge in the Gauges tree-node of Designer Toolbox. Delete “Analogue Value” from the Name property of the Analogue Value GroupBox since it just gets in the way

Find a level transducer icon such as the one on this page, copy and paste it as a JPG file to say your Windows desktop, and then browse the file into the Image property of the newly added PictureBox

Click the glyph top-right on LineChart and change series title to Level and the line width from 1 to 3 (Edit Chart link, Advanced View button)

Change the chart Timespan to 10 minutes (Edit Time Details link)

On the newly added LinearVerticalGauge apply a Display Value behaviour by clicking the glyph top-right as shown. Make sure the Input Data Element is: Adroit.Analog.{Analogue Data Element}.value

The text between the curly braces is particularly important as this needs to match other behaviours already on the template and will act as an Alias for substituting real tag values when the template is displayed at run-time

We will now do a similar thing for the existing Digital Faceplate Template also in the Shapes Wizards and Examples project. So locate this template, open it and save it as Intruder Alarm Template in GIS Quick Start project

Then, delete the Stop/Off and Start/On buttons since our Intruder Alarm Digitals are purely inputs not control outputs

Blank out the Name property of the Digital Value GroupBox

Click the glyph top-right on LineChart and change series title from Digital Value to Intruder Alarm the series type from Line to Area and since an Intruder Alarm is a serious, highest priority alarm, the series colour from blue to red

Change the chart Timespan to 10 minutes (Edit Time Details link)

Configuring the GIS Datasource

GIS relates to SCADA HMI because quite often the starting point for user interaction in geographically dispersed applications is a map overview. This is usually a natural and logical reference point to centralize information monitoring and control tasks from

By using the GIS Add-on, you can add intelligence to map overviews by providing icons that represent the actual location of plant items and equipment

The Adroit Smart UI GIS Add-on uses a hierarchy when defining items that adheres to a structure adopted by existing ISA S95 and ISA S88 standards:

So, in our water treatment application, we have the six geographically dispersed sites: Ardleigh in Essex, Bosley in Cheshire, Derwent in Northumberland, Drift in Cornwall, Llyn Cwellyn in Wales, and Threipmuir in Scotland

Each site has a single area: Reservoir

And each reservoir has two equipment items: Level (Transducer) and Intruder Alarm (Detector)

Adding Sites, Areas, and Items

There are two ways of configuring the GIS Datasource

To gain an appreciation of both methods, we will configure the first site interactively, and then bulk-configure the remaining sites via an Excel Workbook

To create the first site, right-click the GIS Datasource GIS1 and select Add Site from the context menu

Enter Ardleigh into the Site Name edit field as shown

Next, right-click the newly created site Ardleigh and select Add Area from the context menu

Enter Reservoir into the Area Name edit field

Right-click the newly created area Reservoir and select Add/Edit GIS Items from the context menu. This pops up the Add/Edit Items form containing a five-column grid as shown below:

Name This column contains the equipment item names, of which we have two, namely: Level and Intruder Alarm
Latitude This column contains degrees latitude in decimal notation for each item of equipment. We offset the Intruder Alarm slightly from the actual reservoir latitude so that it shows up as a distinctly separate icon to Level on any zoomed map views
Longitude This column contains degrees longitude in decimal notation for each item of equipment. We could offset the Intruder Alarm slightly from the actual reservoir longitude for clarity on zoomed map views but for Ardleigh we choose to use the same longitude
Graphic Form This column contains names of the graphic forms to display when clicking on item icons on a map view. Although not fully visible in the screenshot, we specify the full path of our Reservoir Level Template for the Level item and our Intruder Alarm Template for the Intruder Alarm item. These graphic form paths can be accurately obtained by clicking a browse button […] to the right of the cell
Alarm Tag This column contains names of Adroit agents indicating that items are in alarm. For the Ardleigh site, Level Alarms are indicated by ARD_LVL_001 Analog agent, and Intruder Alarms are indicated by ARD_INTR Digital agent. Once again these names can be accurately obtained by clicking a browse button to the right of the cell. Note: make sure the slot name at the end of this string is statusAlarmsActive which is the slot that indicates alarm activity and not the default value slot

Populating template graphic forms with site data

At this stage you may wonder how just displaying the same Level or Alarm template at each site can depict information specific to the site. Well, remember these forms are templates after all, and they need to have their Aliases assigned before they can be meaningfully displayed

To this end, there is a section at the bottom of the Add/Edit Items form, shown below, that allows you to add and edit Additional Attributes for each item of equipment. For each item we create an additional attribute with its name corresponding exactly to the name of a Form Alias on the template. For our Level template recall the alias is Analogue Data Element and for our Intruder Alarm template the alias is Digital Data Element

The values assigned to these attributes are the actual agent names to be used for the equipment items. For the Ardleigh site these are Adroit.Analog.ARD_LVL_001 for Level...

and Adroit.Digital.ARD_INTR for Intruder Alarm…

Note: these attribute values are just Agent names and not full Tag names that include a slot. This is because the template itself will append different slot names to the aliased agent name depending on which property or properties of the agent it has been designed to depict

Bulk-configuring GIS Datasource from Excel

The above screenshot shows an Excel workbook with six separate worksheets, one for each site. The worksheets are named according to the site names we have chosen

There are seven columns in each site worksheet. These correspond to the five grid columns described previously, but with the addition of a column at the beginning defining the Area name and a column at the end listing additional attributes

This last, additional attributes column contains a semi-colon (;) delimited list of attribute name, value pairs. The name and value for each attribute are separated by a colon character (:). Since we have only one additional attribute per item there is no need for a semi-colon separating the attributes. If, however, we were wanting to display a template that had more than a single alias we would need a list of additional attributes

Once you have completed the worksheets, configure the GIS datasource by right-clicking GIS1 in Smart UI Designer, and selecting Import from Excel on the context menu

This will display the Import from Excel form allowing you to browse for the GIS Excel workbook file via Windows Explorer

You can select a worksheet within the workbook, and also which worksheet columns correspond to grid columns

Click Finish at the bottom of the form, and repeat this for all sites until GIS1 datasource is fully populated

As we did when manually configuring the first site, be sure to leave a small geographical offset between the different equipment items in each area so that they are individually distinguishable on a zoomed map view

Using Adroit Smart UI Mapping Control

Now that we have a properly populated GIS datasource along with some template forms that can be displayed, it’s time to make use of the other Smart UI GIS component, the MappingControl

In Smart UI Designer, create a graphic form called Overview in the GIS Quick Start project. Locate the MappingControl under the GIS tree-node of Smart UI Designer Toolbox, and drop an instance of the MappingControl onto the form

Set the Dock property of the mappingControl instance to Fill so that it fills the whole form

Under Advanced properties:
  • Set GISDataSourceName to GIS1
  • Set StartLatitude to 54, StartLongitude to -6, and StartupZoomLevel to 6.5
These settings should have the effect of filling the form almost entirely with a map of just UK
Run the Overview form and you should see a UK map with different coloured push-pins showing the locations of various equipment items at the six geographically dispersed reservoirs

Recall from earlier when simulating application activity, we noted that alarms have been set up to happen quite a rapid frequency

So, the red push-pins show sites where at least one equipment item is in alarm, and the green push-pins show sites where there are currently no active alarms

On a highly populated GIS, you probably don’t want pushpins for sites that are not in alarm to clutter up the map. The way to achieve this is to modify the StatusColors property under Advanced mappingControl properties
To hide the green push-pins we define the default state colour to be Transparent instead of green. This is first colour at the top of the list of Web colours as shown

Other Controls that can be associated with Mapping Control

Navigation can be enhanced by associating TreeView and/or AlarmViewer controls on the same form, with a Mapping Control

Starting with an alarm viewer, locate the AlarmViewer control under the Adroit tree-node of Smart UI Designer Toolbox, and drop an instance onto the Overview form

Next, locate the TreeView control under the Windows Forms tree-node of Smart UI Designer Toolbox, and drop an instance onto the Overview form If you now Run the form, it should look something like the screenshot below:

The tree view on the left, when opened up fully, shows all Sites, Areas, and Equipment Items as well as list of currently active Alarms

The alarm view at the bottom, also lists currently active alarms in more detail

Double-clicking any item or alarm in the TreeView on the left should cause the MappingControl to display a zoomed view centred on the geographical co-ordinates of the item clicked

Similarly double-clicking an alarm in the AlarmViewer at the bottom should also cause the MappingControl to display a zoomed view centred on the item clicked...

Putting it all together in a project Navigation Template

Best practice in Adroit Smart UI dictates the use of some kind of standard project template to navigate around the graphic forms in an application. So once again, we will modify one of the existing templates to suit our purpose

Locate and open the Project_Navigation_Template form under the Navigation Template Buttons Left and Top project in Smart UI Designer. Save this form with the same name but in the GIS Quick Start project

Firstly, delete the AlarmViewer control at the bottom of the navigation template since we already have an alarm viewer on our Overview form

Next, delete the Raw Materials, Processing and Finished Products buttons from the navigation panel on the left of the form, since these buttons are not relevant to our water treatment application

You may have noticed when running our Overview form in Designer that there is no obvious easy way to get back to the startup zoom level once you are zoomed in at any site. The following workaround overcomes this limitation

Create a new form called Blank in the GIS Quick Start project

Click Advanced on the View tab in Smart UI Designer and re-open the Blank form

Click on Spider Configuration tab at the bottom. Right-click in the dotted Spider Workspace and select Create New Spider->Application->Application

Right-click the spider and show its Detail View. Configure it to Open graphic form Overview and set it to Replace, i.e. when the spider triggers it will replace form Blank with form Overview

Finally, set Form Load as the Event Trigger meaning that as soon as it loads it will replace itself with the Overview form

Next, re-open the modified Project_Navigation_Template form and by clicking the glyph top-right of the Home button, change the Execute Command behaviour to load form Blank instead of the previous project landing page that it was set to

Similarly, by clicking the glyph top-right of the Main_TGO TemplateGO, change its Default Graphic Form to load to form Blank instead of the previous project landing page it was set to

At this point we should be ready to run the complete application in Smart UI Operator, so modify the Default profile Operator Settings as shown in the screenshot below...

Run Smart UI Operator and you should see something like…

Double-click a reservoir Level Alarm somewhere, then click the alarm push-pin to bring up the Reservoir Level Template aliased according to the site you are looking at…

Double-click an Intruder Alarm somewhere, then click the alarm push-pin to bring up the Intruder Alarm Template aliased according to the site you are looking at…

From any zoomed map view, click the Home button top-left on the navigation template, and this will display the Overview form at its startup zoom level

Download Adroit Download GIS Add-on