HMI Editor
Reference manual

What is HMI Editor.

The HMI Editor app is the developer component of the HMI Pad system for creating Human Machine Interfaces for real time monitoring of industrial PLC based systems and processes. The other two components are the HMI app and the HMI Pad Service.

Main features.

• Very fast native app, launches and connects immediately regardless of project size, not a web based app.

• All data types supported including Boolean, Integer and Floating Point values.

• Advanced Expressions Engine supporting a number of data types including Strings, Arrays and Dictionaries.

• Projects can be fully edited on-screen as you run and monitor your process. Or can be exported and edited as a text file.

• Configurable User Accounts allow for project storage in the cloud and easy deployment to end users.

• The app connects to PLCs directly using native communication protocols. Connections are performed without any intermediate servers or boxes.

• TCP/IP based security.

The concept behind the HMI Pad apps.

The HMI Editor and HMI apps are built on top of two main modules: the Communications Module and the Expressions Engine. These modules interact with each other and to the user interface to provide most of the underlying capabilities and many advanced features.

The HMI Editor lets Integrators build fully customizable HMI interfaces by adding visual items or other objects to pages. Objects have properties that can be connected between them or with PLC tags through expressions. Virtually all properties can be linked through expressions. This architecture provides an extremely powerful environment for Integrators to create advanced HMI interfaces.

HMIs can be fully created and deployed from the app by dragging and connecting items together. Integrators can also chose to edit project files on a text editor. The app also fully supports copy/paste/duplicate of items, tags, connections etc, and has unlimited undo/redo capabilities.

The app comes with a free service on the cloud, the HMI Pad Service, for convenient storage of projects and associated assets and further deployment to End Users.

The complementary HMI app let automation integrators to safely and securely deploy projects to end users devices with no physical access to them. Projects on the HMI app are installed as encrypted, non-editable instances of your projects, thus helping you to safely keep your work and know how.

1 The HMI Pad System Components

The HMI Pad System is made up of 3 components:

HMI Editor.

This the app Integrators use to create and deploy HMI projects.

HMI Pad Service.

The HMI Pad app is designed to work with a service in the cloud named the HMI Pad Service.

The app seamlessly integrates this service to provide storage options in the cloud and convenient distribution and deployment of your HMI projects to your End Users or customers. The HMI Pad Service uses Apple's CloudKit infrastructure as the physical media to store data in the cloud.

Refer to the "HMI Pad Deployment Guide" for more information on what options you have available to work with the HMI Pad Service as you develop HMI projects.

HMI Pad View.

This is the app where end users run HMI projects developed by integrators. Projects on the HMI app are installed through the HMI Pad Service and are stored as encrypted instances that can not be edited or moved to other devices.

2 The HMI Editor app main user Interface

The HMI Editor app interface consists of two main draggable panels, the Application Panel and the Project Viewer.

The Application Panel is shown on the left and there you will find options and settings related with the app.

The Project Viewer is on the right and lets you edit, review and run your project. The Project Viewer can be made full screen by closing the Application Panel.

2.1 The Application Panel

The Application Panel lets you create and manage the following aspects of the app

• User Accounts and Settings.

• Projects and Assets stored locally.

• Projects and Assets stored on the HMI Pad Service

• Remote Deployment.

2.1.1 Settings

The Settings panel is reached from the GENERAL section of the Application Panel sidebar. It groups app-wide preferences, maintenance actions, and links to documentation. Changes take effect immediately and are persisted across launches.

Alarms and Background Task

• Disable Auto-Lock. When enabled, prevents iOS from putting the device to sleep while HMI is in the foreground — useful for kiosk or always-on installations. Disabled (greyed out) on Mac Catalyst, where the system idle timer is not affected by the app.

• Haptic Feedback / Pulse Feedback. Provides physical feedback when interacting with controls (Button, Switch, Custom Switch, Slider, Knob, Segmented Control, Array Picker, Dictionary Picker, Tap Recognizer). On devices with a Taptic Engine the row is labelled Haptic Feedback and uses the standard iOS impact / selection generators. On older iPhone, iPad and Mac Catalyst hardware the row is labelled Pulse Feedback and uses a short system click sound as a fallback. Enabled by default.

• Alarm on Disconnection. When enabled, raises an alarm event if a PLC, REST, or MQTT connector loses its connection.

• Keep Connected. When enabled, HMI Editor keeps PLC, REST and MQTT connections alive while you switch to another app. When disabled, connections are torn down when HMI goes to the background and re-established on return.

Maintenance

• Clear Image Cache. Empties the on-device image cache. Use it if an image is not updating after being renamed or replaced.

• Delete Pending Receipts. Clears any pending in-app-purchase receipts that were not consumed.

Embedded Web Server

• Port. TCP port used by the embedded Web Server (default 8080). Change it if another app on the device is using the same port.

Give Feedback / Help

Quick links to the App Store review page, this Reference Manual, the Deployment Guide, and Technical Support.

2.2 The Project Viewer

The Project Viewer is where you create, configure, edit and run projects. From the Project Viewer you get access to Pages, Connections, Alarms and the internal aspects of your project. You can also set some editing properties and edit objects on screen using common gestures.

Several sub-panels provide means to navigate through your project to obtain detailed information. You may find the following panels that will appear at appropriate times or upon particular actions as you edit your project:

• Page Viewer, shows the current page. The Page Navigator appears from the left and displays the list of pages.

• Inspector Panel, appears from the right and contains the Connections Panel, the Tag Viewer and the Alarms Viewer.

• Model Browser, appears as a floating window you can drag around the screen.

• Object Configurator, appears as a floating window when you tap on 'configure' for an object.

• Expressions Keyboard, appears on the bottom of the screen, when editing Object Properties.

• PLCs and TAGs Configuration Panels, appear as floating windows, accessible from the Model Browser

• Model Seeker, appears as a floating window, accessible from the Object Configurators or the Expressions Keyboard

2.2.1 The Model Seeker

The Model Seeker is the picker that opens when you tap the search (magnifying glass) icon next to a property field in the Object Configurator, or the corresponding key on the Expressions Keyboard. It lets you fill the field by selecting a value from a list rather than typing one.

The Seeker shows different content depending on the property’s data type:

• For most expression properties it lists the project objects, connectors, tags, and system values that can supply a value to that property.

• For image-path properties (such as a Shape’s fillImage, an Image item’s imagePath, or a Button’s image), the Seeker presents an SF Symbols tab containing the full Apple SF Symbols catalogue, grouped into categories such as Arrows, Indicators, Communication and so on. A search bar at the top filters the grid by symbol name.

Tapping a symbol fills the property with the symbol’s identifier (for example arrow.up or bolt.fill). SF Symbols are rendered using the system tint and respect the current color settings of the item — they scale cleanly at any size and adapt automatically to light / dark appearance.

3 Creating and opening Projects

To create a new project go to "Local Storage -> Projects" on the "Application Panel" and tap on "+", then chose "New Empty Project". A new project with a default name will appear on the list. Alternatively, you can tap on "New From Template" and the app will show you a list of already made simple projects you can use to start from.

You can open the project you just created by "sliding" to the right the row in the list containing its name.

It is recommended to rename your projects with suitable names that clearly identifies them to you. To do so set the list to edit mode by tapping on "Edit", then select the project you want to rename, and choose the appropriate option from the "Actions" menu on the bottom of the panel.

3.1 The Current Project Panel

When a project is open it appears under LOCAL STORAGE in the Application Panel sidebar. Selecting it shows a Current Project panel with the project thumbnail, identifying metadata (Project ID, Date, Size), and a set of per-project options.

Start Page

The Start Page selector — labelled Set the page to open when the project starts — controls which page is shown when the project is next opened. Tap the selector to choose one of:

• Last Used — open the page that was active when the project was last closed. This is the historical default.

• Any page identifier in the project — open that page every time the project starts, regardless of which page was active at close.

The selection is stored per-project (keyed by the project UUID) and survives reopening the app.

Project actions

• Activate. Stores this Project in the Cloud, or activates it for end users.

• Duplicate. Creates a new local project based on this one, preserving items, expressions, connectors and assets.

• Close. Closes the project.

• Test Project using its Attached Assets. When on, the project is exercised against the assets bundled with it rather than the ones on local storage.

The Current Project panel also lists Required Local Assets — files referenced by the project that should be present on the device before deployment.

4 Editing Projects in the Project Viewer

With the HMI Editor app you can fully edit your HMI projects on the "Project Viewer". When the project viewer is fully visible tap on the"Edit" button on the top-right of the panel to start editing your project.

It is not a purpose of this manual to fully describe all and every editing option available, but just to provide a guide on what is at your disposal to complete your editing and where to look at for a specific editing need. For the most part the app interface follows commonly recognized patterns and provide built-in help that should be enough for the common cases.

The Project Viewer features a toolbar on the top with the following options from left to right:

Pages toolbar icon.

The pages tab bar icon toggles the Page Viewer. From the Page Viewer you can navigate to a particular page in order to open it. The Page Viewer can also be shown/dismissed with a drag gesture over it or from the left edge of the Project Viewer.

User toolbar icon.

The User toolbar icon presents a project user login screen. For more information on project users look at the $UsersManager and Users sections in this manual.

Tools toolbar icon (edit mode only).

Several tools are available for helping on positioning items on pages and editing frames. You will find options to enable or disable auto align rulers, to lock frame editing and to enable multiple selection. You can also enable/disable visual reporting of error conditions while in edit mode or make hidden items visible while in edit mode.

A number of editing tools are available:

Allow Multiple Selection. When enabled, multiple item selection will be active, allowing for multiple selection of items for example for grouping. Default is Off.

Enable Auto Align Rulers. Determines whether auto-alignment rulers and alignment magnets are enabled. Switch it to off to allow free layout of items. Default is On.

Allow Frame Editing. By setting this to off any layout changes of items will be globally disabled. You still will be able to set item properties. You can disable frame editing on particular items by locking them individually. Default is On.

Enable Fine Frame Positioning. Determines whether a joy-stick tool will appear for selected items allowing for fine positioning and resizing of items. When arranging items using this tool, auto-alignment rulers will still display on screen for a second but no alignment magnets will be in effect. Default is Off.

Error Frames When Editing. Determines whether error frames are displayed around objects with undefined values also on edit mode. Disabling this eliminates page clutter while editing in case you do not have a life PLC connection or your object properties contain broken links. Default is On.

Display Hidden Items. Items with their hidden property set to Off are still partially visible on edit mode. However you can override this behavior by setting this to Off. Default is On

Interface Idiom. Represents the Interface Idiom you are working on. Chose iPad for building screens for the iPad native resolution or iPhone for working on interfaces designed for iPhone or iPod touch.

Undo/Redo toolbar icons (edit mode only).

The app has unlimited undo-redo capabilities that are supported on virtually all changes performed on projects.

New Item toolbar icon (edit mode only).

From this toolbar icon you create new pages or new visual items that you can place on pages or use on your HMI projects. Items are arranged in categories such as Controls, Indicators, Images and so on. New items are created with default properties and placed on the center of the page, you can then move them to the desired position and configure their properties. The application also features intelligent copy/paste/duplicate of Objects, Pages, Connectors, Tags , including among different projects.

Model Browser toolbar icon (edit mode only).

The model browser icon toggles the Model Browser.

Inspector toolbar icon

The Inspector toolbar icon toggles the Inspector Panel The Inspector Panel can also be shown/dismissed with a drag gesture over it or from the right edge of the screen. In view mode the toolbar button is replaced by a clickable area that shows the number of active/number PLC connectors, and the number of active/total alarms

Edit/Done toolbar icon

The Edit/Done toolbar icon toggles the project from Edit to View mode. As a visual effect the entire toolbar becomes blue while in edit mode.

4.1 Editing Projects in a Text Editor

Project Files in HMI Editor are plain text files that can be manually edited on a text editor. Project Files can be exported and imported to HMI Editor through the Mail application. They have a .hmipad extension and HMI Editor recognizes any Mail attachment with this extension as a HMI Editor Project File.

If you open an HMI Project file (extension .hmipad) on a text editor you will be able to identify all the Objects and Properties of your project as they were configured in the application. Indeed, a Project File is a text representation of everything in a project and a direct description of what you see on the Model Browser. This of course includes all Visual Items on Pages, Background Items, Alarms, Connectors and PLC Tags.

For example, a knob control on a page may look like this in the .hmipad file

knob_1 = SWKnobItem.new;

knob_1.framePortrait = SM.rect(29, 27, 175, 189);

knob_1.frameLandscape = SM.rect(99, 243, 171, 175);

knob_1.backgroundColor = "ClearColor";

knob_1.hidden = 0;

knob_1.continuousValue = 738.846130371094;

knob_1.enabled = 1;

knob_1.verificationText = "";

knob_1.style = 0;

knob_1.thumbStyle = 0;

knob_1.value = source.max_setpoint;

knob_1.minValue = 0;

knob_1.maxValue = 1000;

knob_1.majorTickInterval = 100;

knob_1.minorTicksPerInterval = 4;

knob_1.format = "%g";

knob_1.label = "";

knob_1.tintColor = "gray";

knob_1.thumbColor = "black";

knob_1.borderColor = "red";

a PLC Tag may look like this in the .hmipad file

source_tags19 = SWSourceNode.new;

source_tags19.name = "max_setpoint";

source_tags19.tag = SWObject.new(source_tags19_tag);

source_tags19.write_expression = max_setpoint.value,knob_1.value;

source_tags19_tag = SWPlcTag.new;

source_tags19_tag.address = "DM10";

source_tags19_tag.type = "REAL";

source_tags19_tag.scale_rmin = 0;

source_tags19_tag.scale_rmax = 0;

source_tags19_tag.scale_emin = 0;

source_tags19_tag.scale_emax = 0;

The ability to manually editing your projects using a Text Editor is an advanced feature that you can use to create and store project templates, quickly add/replace tags in bulk, find objects and properties for debugging purposes, configure pages or groups of objects with repetitive patterns, and more.

IMPORTANT NOTE: This is a very advanced feature that brings a lot of power, but it also carries the risk of accidentally breaking Project functionality or introducing syntax errors on Project Files that would prevent them from being opened by HMI Editor.

HMI Editor will attempt to report syntax or other errors on imported files in an accurate way but still you may fail at attempting to fix a particular issue after incorrect manual editing of a file. Therefore, it is strongly recommended to always keep a working copy of your projects in safe place, so you can recover from them in case something goes really wrong.

4.2 Moving Items Between Pages

Selected items on a page can be moved to another page in a single step, rather than being copied + deleted manually. The operation is atomic — both the removal from the source page and the insertion on the destination page happen inside the same undo group, so one undo reverses the entire move.

To move items between pages:

1. In edit mode, select one or more items on the source page.

2. Long-press (or right-click on Mac) any selected item to open the context menu. Tap MoveToPage.

3. The Model Browser opens at the Pages list. Tap the destination page to open it.

4. Tap the action (upload) button at the bottom of the Model Browser. A Move option now appears in the action sheet — choose it to drop the items onto the destination page.

If you change your mind before completing step 4, simply close the Model Browser; the source page is left unchanged.

The same context menu also exposes Copy, Duplicate, Delete, SendBack, BringFront and Lock for selected items.

5 Objects, Properties and the Project Object Model

As you build your HMI project you create Pages, Visual Items, PLC connections, PLC Tags, Alarms and so on. Everything you place on pages and the remaining objects you use to build a project are stored in the Object Model. The Object Model also contains object configurations and all the expressions you used to link objects.

The HMIDraw app is entirely based on Objects, everything is achieved through connecting objects, and every aspects of your HMI project development is based on managing objects of different kinds.

In HMI Editor there is not a separate concept for generating displays and constructing control logic. There are not either separate procedures for each kind of task. Instead, you concentrate all your development on one single easy concept. It is very likely that you already understand the concept because it is not new to you. You already know how to link cells on an Excel spreadsheet using formulas to produce results that depend on other cell values, so this is it.

Objects in the HMI Editor app have Properties. Going back to the spreadsheet analogy, object properties are the equivalent to spreadsheet cells.

To create an HMI project with HMI Editor you simply create objects and link their properties together using expressions, just as you would do to link cells on a spreadsheet program. This concept extends to the whole app and includes the way objects are linked to PLC tags. Effectively, tags are just properties of a special kind of object called Connector.

The Object Model is internally architected as a tree-like graph of objects connected through expressions. When something changes at some point of the model, for example due to an user action or a PLC tag change, a change event is propagated only to the affected object properties. The application is even-driven to its core, which means that this also applies to display updating, alarming and control logic, and it makes the app very efficient.

The Object Model is fully visible and accessible through the Model Browser.

5.1 The Model Browser and Main Object Types

From the Model Browser you access the Object Model of your project. This is equivalent to say that all the objects of your projects are accessible from the Model Browser.

Furthermore, the Model Browser presents a hierarchical view of your project. In the section named 'Objects Reference' a description of each object type and its properties is provided in more detail.

The available main object types are listed next:

System Objects.

Represent objects that provide real time iPad sensor information or access to project related properties.

Pages.

The pages that your project contains. In pages you place visual items that can be of a variety of types.

Background.

They are objects that do not have a visual component but you can use on your project.

Alarms.

You set alarm or any arbitrary event conditions that will be displayed on the Inspector Panel when triggered.

Users.

You can create users on a project basis.

Data Loggers.

Data Loggers allow you to log historical values on database files.

REST Connectors.

REST Connectors represent connections to web services that may adopt the REST architecture.

PLC Connectors.

PLC Connectors represent connections to PLCs. A connector includes PLC communication settings and PLC tags.

5.2 Object Properties

Objects in the HMI Editor app have Properties.

Particular properties may represent object states or visual conditions.

Properties are identified in expressions by object name followed by a dot and the property name.

objectName.property

You connect object properties together to add dynamic functionality to your HMI projects. Properties are connected through expressions.

Example:

Let's suppose we have on a page a switch control and a lamp indicator which are named as such. We want to turn the lamp on/off with the switch control. To do so we need to enter the switch value on the value property of the lamp.

By entering the switch.value into the value property of the lamp we achieve the desired effect because when the switch changes a change event will propagate a change to the value property of the lamp

Notice that we entered this in the value property of the lamp, not the switch. This may seem odd before you are used to it or if you come from traditional HMI systems, but you just need to think on terms of a spreadsheet to see why this works. On a spreadsheet let's assume you want cell 'A1' to follow the value of cell 'A0'. You would enter '=A0' in cell 'A1'. This is exactly how the HMI Editor app works, we enter 'switch.value' in 'lamp.value' because we want the lamp to follow the switch.

Object Properties are accessible through the Object Configurator which is available from the "Configure" menu item upon selecting an object on screen or by tapping the "gear" icon for an object on the Model Browser.

5.2.1 Property Kinds

Object Properties can be read/write but some of them are read only,(particularly on system items) or constants. You identify the kind of properties by how they are presented or what is allowed for them on the Object Configurator.

Read Only.

Read only properties are mostly used on system objects. They usually provide real time information that can not be set by users or in general any data value that can not be edited.

An example of a Read Only property is '$System pulse1s'

Read / Write.

Most properties on regular objects are Read/Write. On the Object Configurator they provide a field where you can enter an expression. In particular, Read/Write properties are identified because they present an entry field with light yellow background.

An example of a Read/Write property is '$Project currentPageIdentifier'

Constants.

Constant properties are similar to Read/Write properties except that any expression or value entered on them can not be changed at runtime. Constant properties are identified by the presence of an entry field with white background.

An example of a Read/Write property is '$Project title'

5.2.1 Property Data Types

Object Properties can be of a variety of data types, such as Integer, Double, String and so on.

It is important not to confuse Property Data Types with Expression Result Types as they may not always be related. Particularly, Property Data Type represents the type that semantically best describes the Property, while Expression Result Types do carry a semantically agnostic meaning.

For example, a string representing a color name can be assigned to a Property of type Color, but it will still remain a String and will be simply treated as such by the Expressions Engine.

The concept of Property Data Types abstracts expression result types from their intended actions on properties, thus adding a flexibility layer on the use of data types in expressions. For example a Color can be physically represented by a String or by a Number in expressions, and yet be assigned to the same property of type Color.

Property Data Types are shown just below Property Names on the Object Configurator. Some of the most used are Integer, Bool, Color, Double, Range, Url, FontName, FormatString, Orientation, TextAlignment, and more.

Property Data Types are enumerated and explained in more detail for particular objects on the Object Reference section when relevant.

6 Expressions

Expressions can be entered on read/write properties and provide an advanced way to customize various aspects of the interface and behavior of HMI Pad projects.

You can combine Object Properties with operators and methods to produce custom results and assign them to other Properties. Object Properties are referred in expressions by using a dot notation as described in the Object Properties section

Event Driven Architecture.

Expressions in HMI Pad System are stored in a compiled form and are executed by an event-driven engine. The execution engine keeps expression reference information in a way that value changes trigger expression evaluation. The engine is not endlessly executing 'for' loops but only change events.

References to dependent expressions create a tree like network where all expressions may have links to other expressions. When a PLC tag changes, or an user interacts on a control, a change event is originated. This event, that occurs at some point in the expressions network, is propagated through the relevant links to reach only the expressions that need to know about it, generally only a few.

The result is that expressions execution time is basically independent of project sizes or the total number of expressions defined in projects. The Event Driven Architecture is specially suitable for running HMI projects in the constrained environment of a mobile device and still be able to support very big projects with no noticeable performance penalties.

Another responsibility of the Expressions Engine is to determine the minimum set of data that is required at a given time to keep a consistent interface. This is translated to the minimum set of tags to poll and is notified to the Communications Module so no tags are polled unnecessary at any given time. The Communications Engine then automatically groups and optimizes command requests to PLCs for minimum communication overhead. All these processes, including communications, happen on a secondary execution thread so users never feel or notice them.

The ultimate result is highly responsible HMI projects with controls that respond and react quickly to user actions and fast updates of interface elements.

Analogy with an Excel Spreadsheet

To help to understand the whole concept of the app it may be helpful to think on it as a Excel spreadsheet and compare what Excel and HMI Editor do. Indeed the behavior of the expressions engine on Excel and HMI Editor are very similar in concept.

In the case of Excel you have Cells where you enter formulas. Excel Cells connect to other cells through expressions. For example, in cell A2 you can write =B1+B4. In the context of Excel, when the value of B1 or B2 changes the value of A2 is automatically updated.

So this is exactly what HMiPad does. Instead of Cells we have Objects with Properties. On the HMI Editor app an Object Property is the equivalent of an Excel Cell. You connect Object Properties as you would Excel Cells.  On Excel you refer to Cells by Column-Row (example B1) On HMI Editor you refer to Object Properties by their names using a dot notation (example numberField.value).

Unless Excel Cells HMI Editor Object Properties have a meaning and perform a particular action, thus when you make them to change there is an effect, possibly a visual one such as changing a Color.

Basically, understanding the concept unlocks the full power of the app. Expressions can be very simple or extremely complex, and as we evolve the app more Objects with more Properties will be added.

Using Expressions.

HMI Editor expression syntax is based on the open source Ruby scripting language syntax. For basic operations this syntax is similar to that of the ‘C’ programming language and virtually identical to all modern scripting languages.

The Ruby language was chosen because it features a clean, easy to learn, object-oriented syntax with a particular focus on expressions allowing for practical ways to represent and dealt with several data types and formats with great flexibility. HMI Editor supports most operators including all common Logical, Arithmetic and Comparison operators, as well as commonly used Ruby functions and methods.

Support of Ruby expressions in HMI Editor is a subset of the Ruby language. Expressions are not, and do not pretend to be a complete implementation of Ruby. In some cases we provided a single way to accomplish something that on Ruby can be done in several ways, and in other cases we integrated several functionalities in single methods instead of implementing all of them. So it is important to refer to this manual if you are also using a Ruby tutorial to determine what it is actually supported on HMI Editor and which behavior differences may apply.

For those who already used Ruby, one of the most obvious differences between ‘real’ Ruby and HMI Editor is the treatment of boolean values. Ruby treats everything as object pointers, including numbers, while HMI Editor keeps the traditional ‘C’ like behavior. For example, in Ruby any number used in a boolean expression is a true value even if it holds a zero, just because it exists as a pointer. HMI Editor, on the other hand, will still take 0 (zero) as false and non-zero as true, in the traditional sense of earlier programming languages, and hopefully in accordance to what PLC programmers would expect or feel more comfortable with.

You should always use values expressed in engineering units when using expressions in HMI Editor. The HMI Pad expressions engine does not have a notion of PLC raw values, as this is handled by the communications component of the app.

When using expressions in your project you must be aware of the following:

• Object and Property names in expressions are case sensitive. This means that an object property named textField.value will not be the same than another one named textfield.value.

• Logical or Comparison operators assume non-zero values to be true and zero values to be false. The result of a Logical or Comparison operator, however, is always a value of 0 or 1.

• Comparison operators are non-associative. This means that expressions such as a<b<c are not valid. You must use a<b && b<c instead.

• Assignments in expressions are not supported. Therefore expressions such as condition && (intProperty = 3 ) will cause a syntax error on the assignment operator. Do not confuse the assignment operator = with the the equality operator == which is fully supported.

• An expression is executed only when at least one of the referred object properties change. The process is totally transparent and integrators might not need to know about how it works underneath. However, keeping the event driven nature of HMI Pad in mind can help integrators to understand why and when dependent object properties including PLC tags will be written or alarms will trigger as a consequence of an user interaction or a PLC Tag change that originated a cascade of change events.

• Expressions containing Logical operators are no exception to the event driven design. They will be fully executed even if a change occurs on the right side of the Logical operator. For example the expression condition1 && condition2 would be always false if condition1 is false, however it will execute anyway as a consequence of a change on condition2. Although the expression result will not change (it will remain false), the engine will still send a change event to any depending expressions, which could potentially cause other effects such as a PLC tag rewrite if the expression was linked to a PLC tag.

• Expressions can not create circular or recursive references. This means that a result of an expression can not be refitted to another expression that ultimately would send a change event to the originating expression. This is not allowed at any level on the expressions execution chain. For example the following expression textField.value+1 on the value property of an object named textField is not valid because textField.value creates a circular reference around the value property. Note that HMI Editor essentially behaves as a SpreadSheet program and this restriction also applies on SpreadSheet programs..

6.1 Data Types in Expressions

Expressions in HMI Editor support the following primitive data types: Number, String, Array, Dictionary, AbsoluteTime, and Range. other native types include Point, Size, and Rect,

Appropriate operators and methods allow for conversion among types and to perform custom operations with great flexibility. See the following sections for a discussion on methods and operators.

Mixing different data types such as Numbers, Strings or Arrays is only possible through the use of the appropriate operators and methods that result in compatible types. A direct consequence is, for instance, that you can not concatenate a number to a string unless you convert the number to a string first. Also, some operators have particular semantics depending on type. This is just like most modern scripting languages including Ruby. On the following sections we discuss further on this and on other subjects.

Numeric values.

Numeric values in expressions are internally stored as Double Float values (64 bits) All Arithmetic, Logical and Comparison operations are performed as Double Float operations. You may never expect to obtain truncated values from arithmetic calculations.

The above statement may change in the future to give support for true integer arithmetic. Currently, an implicit conversion to an integer type is only performed for bit or bitwise operations on numbers, and indexed access to string or array elements. In other cases you can use the to_i method to explicitly get the integral part of a numeric value according to your needs.

Constant numbers can be represented with optional decimal point and a base 10 exponent. Additionally, hexadecimal and binary notations are supported by using the 0x or 0b prefixes. The special forms true, false +inf and -inf are supported as well.

Examples:

-1.42 (decimal representation)

1.1666e+2 (decimal representation with exponent)

0xe0af (hexadecimal representation)

0b011011101 (binary representation)

true (same as 1)

false (same as 0)

-inf (very big negative number)

+inf (very big positive number)

Strings.

Strings are arbitrary sequences of characters that are manipulated as a whole,. Several operations can be performed on strings such as concatenate, split or substring extraction by using the appropriate operators or methods. String literals are represented enclosed in double quotes. Strings are internally encoded in a compatible type (usually UTF8)

Examples :

"This is a literal string"

"Дискретные датчики"

"ピーエルシーのアラーム表示"

Arrays.

Arrays are-indexed collections of data values. Each element in an array is associated with and referred to by an index.

Array indexing starts at 0. A negative index is assumed relative to the end of the array, that is, an index of -1 indicates the last element of the array, -2 is the next to last element in the array, and so on.

Arrays can hold values of any data type such as Numbers, Strings, Dictionaries, Arrays and so on. Arrays can be created in expressions by using its implicit form consisting on separating their elements by commas and enclosing them in square brackets.

Example:

["element at index 0", 123.4, [ 33, obj.value]]

The above expression represents an array of three elements.

At index 0 we have a literal string: "element at index 0".

At index 1 we have a numeric value: 123,4.

At index 2 we have an array of 2 elements with the number 33 and the variable ‘temperature’ as their components

Elements of the referred array can be accessed by index as shown next:

["element at index 0", 123.4, [ 33, obj.value]][1] would return 123.4

["element at index 0", 123.4, [ 33, obj.value]][-3] would return "element at index 0"

["element at index 0", 123.4, [ 33, obj.value]][-1][0] would return 33

["element at index 0", 123.4, [ 33, obj.value]][2][1] would return the actual value of obj.value

or assuming that the array is stored on an Object Property named exp.value the above is equivalent to:

exp.value[1] would return 123.4

exp.value[-3] would return "element at index 0"

exp.value[-1][0] would return 33

exp.value[2][1] would return the actual value of obj.value

Dictionaries.

Dictionaries are collections of unique keys and their values. They have some similarity to Arrays but where an array uses an integer as in index, a Dictionary allows you to use any data type as a key to retrieve a value.

Keys on a dictionary can be any data type but Strings, Numbers and Absolute Times are the most obvious choices.

Values on a dictionary can be of any data type such as Numbers, Strings, Dictionaries, Arrays and so on. Dictionaries can be created in expressions by using its implicit form consisting on separating their key:value elements by commas and enclosing them in curly brackets.

Example 1:

{"red":"rojo", "blue":"azul"}

The above expression represents a dictionary of two elements.

For key "red" we have the string "rojo"

For key "blue" we have the string "azul"

Elements of the referred dictionary can be accessed by key as shown next:

{"red":"rojo", "blue":"azul"}["red"] would return "rojo"

{"red":"rojo", "blue":"azul"}["blue"] would return "azul"

or assuming that the dictionary is stored on an Object Property named exp.value the above is equivalent to:

exp.value["red"] would return "rojo"

exp.value["blue"] would return "azul"

Example 2:

{"red":["rojo", "rouge"], "blue":["azul", "bleu"]}

The above expression represents a dictionary of two elements.

For key "red" we have the array ["rojo", "rouge"]

For key "blue" we have the array ["azul", "bleu"]

Assuming that the dictionary is stored on an Object Property named exp.value elements can be accessed by key as shown below:

exp.value["red"] would return ["rojo", "rouge"]

exp.value["blue"] would return ["azul", "bleu"]

exp.value["red"][0] would return "rojo"

exp.value["red"][1] would return "rouge"

Example 3

{"red":{"sp":"rojo", "fr":"rouge"}, "blue":{"sp":"azul", "fr","bleu"}}

The above expression represents a dictionary of two elements.

For key "red" we have the dictionary {"sp":"rojo", "fr":"rouge"}

For key "blue" we have the dictionary {"sp":"azul", "fr","bleu"}

Assuming that the dictionary is stored on an Object Property named exp.value elements can be accessed by key as shown below:

exp.value["red"] would return {"sp":"rojo", "fr":"rouge"}

exp.value["red"]["sp"] would return "rojo"

exp.value["red"]["fr"] would return "rouge"

Absolute Time values.

Absolute Times are similar to Numeric values with a special meaning.

An Absolute time is measured in seconds relative to the absolute reference date of January 1 1970 00:00:00 GMT. A positive value represents a date after the reference date, a negative value represents a date before it. For example, the Absolute Time 1,000,000,000 seconds translates into the calendar time 9 September 2001 01:46:40 GMT

A Specific variable, $System.absoluteTime is provided to obtain the current time. Specific methods are also provided to extract interesting calendar fields from an Absolute Time value, as well as to get custom string representations of calendar dates.

Examples

$System.absoluteTime may return 1355481788 (seconds count since the reference date)

$System.absoluteTime.year may return 2013

$System.absoluteTime.timeformatter("yyyy-MM-dd HH:mm:ss") may return the string "2013-01-20 10:15:34"

Ranges.

A Range represents an interval of numeric values with a beginning and an end. A range can be created with its implicit form consisting on the lower and upper values separated by two points

Examples

0..100 represents the interval from 0 to 100 inclusive

-10..30 represents the interval from -10 to 30 inclusive

6.2 Supported Operators and Operator precedence

The following table shows the available operators and its precedence. The table lists all operators from highest precedence to lowest.

6.3 Functions, Methods and more about Operators

Methods can be applied to intermediate expressions or object properties to perform type conversions or to achieve particular requirements. They are like computer language functions that perform particular tasks. Not all methods are applicable to all types and their meaning can vary depending on type. Methods are invoked by appending a dot (method selector operator) followed by its name to the variable or subexpression they apply to.

Operators can also have a different meaning depending on the data type they are applied to.

In the following tables we describe the function of the applicable operators and methods depending on data type.

6.3.1 Numeric Operators and Methods

6.3.2 String Operators and Methods

6.3.3 Array Operators and Methods

6.3.4 Dictionary Operators and Methods

6.3.5 Absolute Time Operators and Methods

The following illustration demonstrates the use of a time expression on a label item.

6.3.6 Range Operators and Methods

6.3.7 Rect, Point and Size Methods

6.3.8 MATH Methods

The following illustration uses a MATH expression to display a value on a label item.

6.3.9 Built-in Functions

6.3.10 System Methods

6.4 Format specifiers for ‘format’ and ‘to_s’

The built-in function format returns a string formatted according to a format string following the usual printf conventions of the C language. In addition, format accepts %b for binary. The to_s method also support formatting when applied to numbers or strings.

HMI Editor. format specifiers adopt the following form:

%<flags><width><.precision>specifier

Where specifier is the most significant one and defines the type and the interpretation of the value of the corresponding argument (’<’ and ’>’ denote optional fields).

For types supporting the to_s method format specifiers are also applicable

The following format conversion specifiers are available:

For the meaning and possible contents of the optional flags, width, and precision fields refer to the sprintf specification:

http://www.cplusplus.com/reference/cstdio/printf/

Since there is no need for the length field it is not available neither in Ruby or HMI Editor.

6.5 The ternary conditional operator

The ternary conditional operator provide conditional execution of expressions. Its syntax is the following:

expr ? expr1 : expr2

The expression above returns expr1 if expr is not zero (true) or expr2 otherwise.

The ternary conditional operator executes when any of expr, expr1, expr2 generate a change event. The result is always updated and will be consistent with the values of expr, expr1 and expr2 at all times. The execution will in turn trigger relevant change events up the expressions tree just as any expression would do.

Consider the following case

switchColorSelection.value ? color1.value : color2.value ;

The resulting color will be always updated according to switchColorSelection upon any change on switchColorSelection, color1 or color2 values

6.6 The ‘if-then-else’ clause

The if-then-else clause provide conditional choice of expressions. It is used as follows:

if expr [then] expr1 [else expr2] [end]

Executes expr1 if expr is not zero (true). If expr is zero (false) expr2 is executed instead. Items between brackets are optional.

The if-then-else clause only attends to expr change events. Any changes in expr1 or expr2 will not have an effect until expr executes. Furthermore, if expr is false and expr2 was not specified, the execution tree is trimmed at this stage and no further execution up the expresion tree will happen.

You should only use the if-then-else clause when the above is required, otherwise use the ternary conditional operator.

The if-then-else clause is useful in cases where you want to achieve a differential effect, for example to trigger an event when a condition goes from false to true but not the opposite. This is not possible with the ternary conditional operator because it will always execute both ways.

Consider the following expression entered on the value property of a lamp object:

if startButton.value then 1 else (if stopButton.value then 0)

The previous lines asume the existence of a start button startButton and a stop button stopButton. When the start button is touched 1 will be written to lamp.value. When the stop button is touched 0 will be written to lamp.value. Because we are using the if-then-else clause, no change event will be sent to lamp.value upon release of the buttons.

Another use of the if then else clause is the implementation of a counter.

Consider a background item named counter and the following expression entered on its value property

if resetButton.value then 0 else (if incrementButton.value then counter.value+1)

The resetButton and incrementButton buttons provide in this case the interface for incrementing the counter value.

NOTE: We recommend to restrict the use of the 'if-then-else' clause to cases where it is strictly necessary as described above and only where the ternary conditional operator would not work.

Ab-using or mis-understanding the purpose and consequences of using it of may create uninitialized values or properties specially on first project launch or update. It is important to always foresee such circumstance and provide an initializer to values that otherwise would never be valid.

For example on the counter example provided above, we incorporated a reset button to allow users to initialize the counter to a valid initial known state.

6.7 The Expression List Operator

The Expression List Operator is an advanced feature that enables you to selectively execute one of several expressions based on the actual flow of change events in the Expression Engine.

Its purpose is similar to the if-then-else clause but in this case the result does not depend on a explicit condition but on the last expression on the list that received a change.

Consider the following expression list.

exp1, exp2, exp3

We have a list of three expressions separated by commas. The result of the above will be either exp1, exp2 or exp3 depending on the one that last changed. For instance if exp1 just received a change, then the result of the list will be exp1 If now exp3 changes then the result will be exp3

Note that the result is always the first expression in the list that changed, For example the following expression list exp1+1, exp1+2 will always return exp1+1 upon a change of exp1 because it s the first in the list to change .

One particularly interesting use case of the Expression List Operator is when you need to write a value to a PLC tag based on more than one item on screen. For example you want to write a set-point value on a PLC Tag based on user action on a slider or on entering a value on a number field on the interface.

You can enter the following on the write_expression field of the PLC tag

slider.value, numberField.value

In this case, a change on slider.value or the numberField.value will result on the writing or the resulting value to your PLC Tag

6.8 Putting it all together. Advanced Expressions

Examples

You can use expressions in your HMI Editor project in many advanced ways. Expressions provide a lot of power and flexibility and most of the features of HMI Editor are unveiled through the advanced use of expressions.

We present next some examples of advanced expressions involving several operators, methods and data types to obtain particular results. This is of course not exhaustive as you can use expressions for tasks that we could not even imagine.

Converting an arbitrary number of seconds to hh:mm:ss format

The following expression shows how to get a string in the form ‘hh:mm:ss’ from a numeric value containing seconds.In this example x contains the total number of seconds to be converted to the desired format.

[(x/3600).to_s("%02d"), ((x%3600)/60).to_s("%02d"), (x%60).to_s("%02d")].join(":")

The operators % and / are used to calculate hours, minutes, seconds as numeric values. These are then truncated to integer with the to_i method and successively converted to formatted strings with to_s. The resulting individual strings are embedded into an array and then joined by means of the the join method using ‘:’ as separator.

Instead of using the join method we could have used the format function as a more convenient way. Consider the following:

format("%02d:%02d:%02d”, x/3600, (x%3600)/60, x%60)

in this case the format specifiers in the format string are just replaced with the relevant time values.

Calculating seconds from a string having the hh:mm:ss format.

Just to illustrate what expressions allow to do let’s try now to get the original seconds value from a string already in the hh:mm:ss format. To do so we can use the following expression:

3600*t.split(":").fetch(-3,0).to_i + 60*t.split(":").fetch(-2,0).to_i + t.split(":").fetch(-1,0).to_i

In this case we extract separately the hours, minutes and seconds as numeric values from the string, we multiply them by 3600, 60 and 1 respectively and then add them to get the total number of seconds. The extraction of each value from the original string is performed by the split method using ‘:’ as delimiter. The relevant element from the split array is obtained with the fetch method. We use 0 as the default value for fetching.

Note that we could have used simple array indexing such as t.split(":")[-3] to get each part of the original string but this would lead to potential out of bound errors in case the original string had some missing part. Particularly, if the original string did only contain minutes and seconds, such as "50:30" ( 50 minutes, 30 seconds) the referred indexed expression would give an out of bounds error as it would attempt to access a non existing element (the one before the first one).

Note also that in all cases we use negative indexing because we interpret that the last part is always meant to be the seconds, the previous to the last one the minutes and so on.

The proposed expression can be optionally optimized by storing the split string in a temporary variable (background expression) so that the splitting is only performed once. If we apply this optimization.the final solution would look as follows:

t.split(":") <- we store this on the value property of tspt

3600*tspt.value.fetch(-3,0).to_i + 60*tspt.value.fetch(-2,0).to_i + tspt.value.fetch(-1,0).to_i

Creating a label that alternates between displaying the current time and an arbitrary value

In this example we will create a label that shows a living digital clock showing the current time. Every 5 seconds the time is alternated with a temperature value given in an item named temperature. In order to achieve this we enter the following expression in the value property of a label item.

$System.pulse10s ? "Time: "+$System.date.split(" ")[1] : "Temp: "+temperature.value.to_s("%3.1f")+" ºC"

We use the ternary operator to switch between the time and the temperature depending on the $System.pulse10 pulsating property. For the clock we take $System.date and discard the date portion by splitting it out. The temperature is presented formatted with a custom prefix and suffix appended to the actual value.

We can alternatively use the format function to simplify a bit some portions of the expression

$System.pulse10s ? format("Time: %s", $System.date.split(" ")[1]) : format("Temp: %3.1f ºC", temperature.value)

7 Object Properties Reference

Refer to this section for reference of all Object Property descriptions.For classes of objects that share similar properties they are presented hierarchically. The same hierarchy is shown in most cases in form of table sections in the Object Configuration panel.

7.1 System Objects

They are special objects that provide device sensor data, and other system or project related information.

7.1.1 $Project

The $Project Object contains properties that may affect the entire project.

7.1.2 $System

The $System object provides the interface for using system or project related info on your project:

7.1.3 $Location

The $Location object provide the gateway for the delivery of location and heading related events to your project.

7.1.4 $Motion

The $Motion Object is the gateway to the motion services provided by iOS. These services provide accelerometer data, rotation-rate data, magnetometer data, and other device-motion data such as attitude.

7.1.5 $Player

The $Player Object provides the interface for playing audio in your project.

7.1.6 $Scanner

The $Scanner Object provides the interface for bar code scanning.

The following bar code types are supported:

UPC-A
UPC-E
Code 39
Code 39 mod 43
Code 93
Code 128
EAN-8
EAN-13
Aztec
PDF417
QR

7.1.7 $UsersManager

The $UsersManager object provides the interface for presenting a Log In screen for project users. It also provides a set of properties to determine the currently logged in user and her/his associated access level.

Project Users are created from the Model Browser on the 'Users' section. The $UsersManager is the central controller to manage a Log In screen and to retrieve information on the current user.

Transferring project users to the HMI Pad Service.

Project users are transferred along with your project when you upload it to the HMI Pad Service. However no login information is kept on the HMI Pad Service.

An user with username "admin" is implicitly available as long as you created at least one user. When you log into an user while in view mode, the Application Panel is not available, particularly on HMI. This allows you to create a closed application that will run only your project.

By convention, every time a project is downloaded from the server the app will start with the implicit admin user logged in. The same applies when projects are redeemed or updated on the HMI app.

Only the admin user is allowed to redeem or update projects on HMI. However, once a project user is logged in, the app prevents further access to the Application panel and thus no integrator server related options are available.

To gain access to the Application panel and full app features in HMI you must log into the admin user. Therefore, it is important that the password associated with the admin user is only known for those who are responsible of project updates or the management of projects in HMI.

For more information about users and user accounts refer to the HMI Pad Deployment Guide

7.2 Page Object

You can place visual items on a pages. Pages themselves have their own properties.

7.3 Interface Objects

In this section we cover Items with a visual component that can be placed on pages

Visual Items placed on Pages have the following properties:

7.3.2 Controls

Control items are visual objects you place on pages that can be operated by users. They all have the following properties.

7.3.2.1 Input Fields

The following properties are common on several visual Items that present text or are related with text.

7.3.2.1.1 Text Field

A control item providing the interface for entering a text on a field.

7.3.2.1.2 Numeric Field

A control item providing the interface for entering a number on a text field..

7.3.2.2 Button

A control providing the interface of a button.

7.3.2.3 Switch

Properties common to switch controls

7.3.2.3.1 Styled Switch

A control providing the interface of a regular switch.

7.3.2.3.2 Custom Switch

A control providing the interface of a Switch made of custom images.

7.3.2.4 Segmented Control

An object providing the interface for a segmented control.

7.3.2.5 Slider

An object providing the interface of a slider control.

7.3.2.6 Knob Control

A control providing the interface of a rotary knob.

7.3.2.7 Array Picker

A control providing the interface for selecting an array element.

7.3.2.8 Dictionary Picker

A control providing the interface for selecting an entry in a dictionary.

7.3.2.9 Tap Gesture Recognizer

An control providing the interface for a tap gesture recognizer

7.3.3 Indicators

Indicators are visual objects on pages designed to present information in specific ways.

7.3.3.1 Label

An indicator item providing the interface for displaying a text label.

7.3.3.2 Bar Level

An Indicator presenting a numeric value as a dynamic bar.

7.3.3.3 Range Indicator

An advanced Indicator presenting a numeric value such as a set point in the context of several ranges. Also called a High Performance Indicator.

7.3.3.4 Data Presenter

A Data Presenter allows you to present historical data from a SQLite database. Databases on HMI Pad are created with the Data Logger object ( see section Historical data and Data Logger objects and the Data Logger object for more information).

Data can be presented as it is being generated on a real time basis, or can be picked from any time in the past.

The following properties are available to objects acting as data presenters.

7.3.3.4.1 Trend

An Indicator providing the interface for a time based trend for presenting real time data.

Performance Considerations when using trends

PLC communications. Because trends follow value changes at all times, any PLC tags that ultimately are directly or indirectly involved in trends are continuously polled in order to keep consistence. Also, HMI Editor may continue polling tags while running in the background. Thus, special care should be taken when deciding what tags will be involved in trending. Particularly, it is recommended to setup tags involved in trends as contiguous as possible. Observing this recommendation will lead to shorter communication patterns and less network overhead, ultimately improving the end user experience.

Graphic rendering on screen. Setting the updatingStyle property to continuous may also lead to some performance degradation due to increased graphic rendering pressure, specially on devices with lower GPU or CPU specs such as iPods or earlier generation iPads. It is recommended to check your project on the real field before setting trend updating to continuous. Even if performance looks fine, the extra required rendering cycles will decrease battery life compared with the discrete setting. So this is also something that bust be balanced.

7.3.3.5 Chart

An Indicator providing the interface for presenting an array of values on a chart .

7.3.3.6 Scale

An Indicator providing the interface for presenting a drawing of a lineal scale.

7.3.3.7 Gauge

An indicator providing the interface of a rotary gauge

7.3.3.8 Lamp

An indicator for presenting the interface of a led like lamp.

7.3.3.9 Horizontal Pipe

An indicator for presenting the interface of a horizontal line with custom color.

7.3.3.10 Vertical Pipe

An indicator for presenting the interface of a vertical line with custom color.

7.3.3.11 Group

Items can be grouped together by enabling multiple selection and choosing 'Group' on the popover menu. A new interface item will be created that acts as a container of the selected elements.A group of objects is in itself an interface item so it has the basic properties described in Item Properties. For example an useful property for groups is the hidden property.

7.3.4 Image Objects

Image Objects are Visual Items that are related or cover aspects related with presenting custom images on the interface.

7.3.4.1 Image

An object providing the interface for presenting custom images.

7.3.4.2 Frame Shape

An object providing the interface for presenting custom advanced frames for incorporating into your page designs..

7.3.5 Web Objects

Web Objects are Visual Items for presenting web content or web related information.

7.3.5.1 Web Browser

An object providing the interface for displaying a web browser.

On the web browser component you can display any content You can present any web related content such as web sites, web based cameras, or even run a web based SCADA in it.

In addition you can display any content stored on the Assets section such as pdf files, doc documents, text files and more.

7.4 Background Objects

Objects that are not visually presented on pages but intervene on the flow execution of your project are named Background Objects.

7.4.1 Expression Object

An Expression Object allows you to store intermediate results or to centralize operations in a single place. It also provides an opportunity to optimize or normalize your project by reducing the need to repeat some subexpressions that otherwise would be present in several places.

An Expression Object has a single property

7.4.2 Recipe Sheet Object

A Recipe Sheet Object provides the interface for retrieving data from a csv file. In the csv file data is organized in rows representing recipes, and columns representing ingredients.

On the first column we place recipe names (or numeric keys).

On the first row we enter ingredient names (or keys).

The cell on the first row and column contains an identifier for the entire recipe sheet.

An example of such a csv file is represented below:

Recipe Keys can be strings or numbers. Ingredient keys can be strings or numbers. Recipe ingredient data can be a string or a number.

The Recipe Sheet object can read the above file in csv format and make it available through its properties. The following properties are available.

7.4.3 Data Snap Object

A Data Snap object allows you to capture snap shots of data in an efficient way. Particularly, this object can be used to capture data from a PLC based on a custom trigger -such as the press of a button- instead of the usual connector based polling interval.

For example you may want to efficiently represent a big array of data from a PLC on a chart graph, but not on a chart that is continuously refreshing, but based on user action. In such case you can link your PLC data to the inputValue of a dataSnap object, link a push button to the snap property, and then use the snapValue as the input to a chart object. Provided that the referred PLC data is only used in the context of this dataSnap object, the system will perform a single PLC read each time an user taps the button. This is in contrast to having your PLC data directly connected to a chart object where updates will be made realtime as data changes in the PLC.

7.4.4 On Timer (TON)

An On Timer (TON — Timer On-Delay) object allows you to implement delays on actions or to program delayed operations. It is similar to a timer.

The On Timer object can be used to allow one operation to complete before another begins, or to require a condition to exist for a period of time before an alarm is activated.

The default identifier for newly created On Timer objects is delayOn.

7.4.5 Off Timer (TOF)

An Off Timer (TOF — Timer Off-Delay) object keeps an output active for a configurable period after its input drops. It is the complementary behaviour of the On Timer: where TON delays a rising transition, TOF delays a falling transition.

A typical use is to keep a motor or fan running for a few seconds after the command signal is removed, or to extend a momentary trigger into a longer pulse.

The default identifier for newly created Off Timer objects is delayOff.

7.4.6 Pulse Timer (TP)

A Pulse Timer (TP) object generates a fixed-duration pulse on its output whenever the input transitions from false to true. Once the pulse starts, further changes on the input are ignored until the pulse completes — making this object useful for debouncing, for guaranteeing a minimum output duration regardless of how brief the input event is, or for converting an edge into a measurable signal.

The default identifier for newly created Pulse Timer objects is pulse.

7.4.7 Retentive Timer (TONR)

A Retentive Timer (TONR — Retentive Timer On-Delay) is similar to the On Timer but it accumulates elapsed time across multiple true-intervals of its input. The internal timer pauses (without resetting) when value goes false, and resumes counting from where it left off when value goes true again. The accumulated total is cleared only by setting the reset property to true.

This makes TONR useful for total-runtime measurements, maintenance interval triggers, and any situation where an operation may be suspended and resumed without losing progress.

The default identifier for newly created Retentive Timer objects is retentive.

7.4.8 JavaScript

A JavaScript object lets you embed a snippet of JavaScript code that is evaluated inside the HMI’s built-in JavaScriptCore sandbox. The result of the last expression in the script is written to the object’s value property, which other expressions throughout the project can read like any other value.

Inside the script, all document objects are accessible by their identifier using dot notation. For example, if you have a REST API source with identifier rest you can reference its response as rest.response; an MQTT client with identifier mqtt exposes properties such as mqtt.data. PLC tags and any other named object in the project are reachable the same way. The editor offers autocomplete based on the set of visible identifiers in the current project.

The script can be driven by two mechanisms, used independently or together: a change in the trigger expression re-runs the script, and a positive pollingInterval (in seconds) re-runs it on a timer.

Example.

Suppose you have a REST API source named rest whose response property holds a parsed JSON dictionary returned by the server, and you want to expose the dictionary’s status field as a single, easily-bound value elsewhere in the project. Create a JavaScript object with:

• script: rest.response.status

• trigger: rest.response (so the script re-runs whenever a new response arrives)

• pollingInterval: 0

Other items in the project can then bind to the JavaScript object’s value property (for example script.value if the object’s identifier is script) to display the latest status without each consumer having to drill into the REST response themselves.

For periodic computation that doesn’t depend on a triggering value (e.g. computing a moving average every 5 seconds), leave trigger at its default and set pollingInterval to 5.

7.5 Alarm Objects

Alarm objects are designed to present eventual information on the Alarms Viewer.

When an alarm condition is triggered, alarm information such as their group and comment properties are displayed in an ordered list on the Alarms Viewer. Alarms will remain on the list as long as they are active or otherwise if they have not been acknowledged. Their current state is shown by small icons next to the alarm text:

• Bright Red Alarm Clock icon means active and not acknowledged

• Dark Red Icon means active and acknowledged

• Gray Clock Icon means inactive and not acknowledged

Performance Considerations

PLCCommunications. Because alarms do track eventual events at all times, any PLC tags that are ultimately involved in alarms are continuously polled. Also, HMI Editor may continue polling tags while running in the background. Thus, special care should be taken when deciding what tags will be reserved for alarms. Particularly, it is recommended to chose tags involved in alarms to be as contiguous as possible. It is also more efficient to have alarms depending on boolean tags than on scalar values. For protocols supporting arrays of BOOL, they will be the best choice. Observing this recommendation will lead to shorter communication patterns and less network overhead, ultimately improving the end user experience.

7.5.1 Alarm

An alarm object keeps eventual information and appears on the Alarms Viewer when it is first activated.

7.6 Users

You can create user accounts on a project basis.

By creating user accounts you can provide restricted or personalized access to selected features on your project. To do so you must assign a differentiated accessLevel to users. On your project, you use the $UsersManager.currentUserLevel property to determine the accessLevel of the currently logged in user and enable or disable specific features based on expressions.

7.6.1 User

An User object stores Log In information of a project user account and assigns an accessLevel to it.

7.7 Historical data and Data Logger objects

HMI Pad uses the open source SQLite database format to store historical data. SQLite is convenient and extensively used for storing large data sets. It comes with built in searching capability and filtering. Databases are stored locally by HMI Editor/View and can be exported to a desktop computer for further analysis. You will find database files on the Databases section of the HMI Editor/View application panel.

Several software tools are readily available for opening and extracting data from SQLite files. You can apply filters and convert data to alternative file formats such as csv files if needed.

On HMI Pad you use data logger objects for data storage, and data presenters for data retrieval.

Data loggers on HMI Pad are linked to physical SQLite database files by specifying a database name and a time range for the database. See Data Logger object below. Based on databaseName and databaseTimeRange a suitable file name for the database file will be composed. If a database file for a given time period is not present at the time a data logger attempts to store historical data, a new one will be created.

7.7.1 Data Logger

Data Logger objects provide an interface to store historical data on SQLite databases. Data provided on the values property is stored in table rows in the SQLite database.

7.8 Connector Objects

Connectors represent PLCs. For each PLC you want to communicate with you must create a connector.

Connectors have a list of PLC Tags. For each PLC tag you create on a connector an implicit property with the same name is added to the connector.

For example if you want to communicate with a particular PLC with 3 tags you create a Connector Object configured as appropriated for the PLC, then add to it your 3 tags. If you named your connector myPlc and you named your tags var0, var1, var2 you will be able to refer these tag values anywhere in the app by using myPlc.var0, myPlc.var1, myPlc.var2.

When you create a Connector you must specify its particular type.and set appropriate parameters.

Each tag you create must be configured appropriately by setting its PLC address and data type.

A connector object is created starting from the model browser.

7.8.1 Supported PLC Connector Types

Upon creation of a connector you must indicate its type. The following connectors for Industrial PLC communications are supported.

7.8.2 PLC Connector Parameters

PLC Connectors have the following parameters.

Additional Parameters for Modbus connectors.

The Modbus specification does not exactly define how the data should be stored in registers or in which order the bytes or words are sent. The following global attributes help to deal with it. Swapped words/bytes options for modbus are global.

Additional Parameters for Allen Bradley connectors.

Allen Bradley ControlLogix controllers can be plugged in any slot on the backplane. Ethernet/IP messages can be sent ”connected” or ”unconnected”. The following attributes can be used to determine these characteristics. These are global attributes.

Additional Parameters for Siemens S7 connectors.

For Siemens S7 controllers you can set ’Controller Slot’ and give an appropriate ’rack’ and ’slot’ number

Additional Parameters for Siemens/Symbolic (Web API) connectors.

For Siemens/Symbolic connectors you must provide credentials for the PLC’s Web API. These map to a user created in TIA Portal under PLC properties → Web server → User management.

PLC requirements for Siemens/Symbolic:

• Firmware: S7-1500 V1.8 or later, S7-1200 V4.5 or later. Earlier firmwares do not include the Web API and will reject every request with HTTP 400. Use the Siemens/ISO_TCP driver instead on older PLCs.

• Web Server enabled in TIA Portal under PLC properties → Web server → Activate web server on this module.

• HTTPS only (Permit access only with HTTPS). The driver accepts the PLC’s self-signed certificate automatically.

• User permissions: the configured Web API User must have at least Read variables via API — add Write variables via API if you’ll write tags. Don’t forget to download the configuration to the PLC after changing users.

Connection endpoint: the driver opens https://<host>:<port>/api/jsonrpc. Default port is 443. Both Local and Remote fields can be filled in — the driver tries the previously-successful one first and falls back to the other on connection failure.

7.8.3 Network Settings for local access.

HMI Pad uses wireless TCP/IP technology to connect and to communicate with PLCs. Direct access from a Local Network requires that both devices be in the same subnet. The PLC acts as the communications server and the iOS device is the client.

The following picture shows a typical setup using the recommended industrial wireless hardware, but basically any WiFi router will do it.

7.8.3.1 PLC Settings for local access.

1. In case of Omron’s Fins/TCP protocol use CX-Programmer tool to set a fixed local IP and Port for the PLC on the ethernet configuration panel.

2. For EIP/Native protocol and Allen Bradley controllers use RS-Logix 5000 tool to set a fixed local IP for the PLC on the ethernet module properties panel.

3. For EIP/PCCC protocol use Allen Bradley's RS-Logix 500 tool and set a fixed local IP for the PLC on the Channel Configuration panel

4. For other PLCs or devices based on the Modbus/TCP protocol, Siemens/ISO_TCP or Mitsubishi's Melssec/TCP consult the relevant vendor documentation to know how to set ports and addresses.

5. The relevant PLC Connector parameters for local connections are local and local port.

7.8.4 Network Settings for remote access.

HMI Editor is designed to communicate with PLCs without using dedicated servers or any specific software installed on a PC. Communications with PLCs are made by using industrial protocol commands.

To establish a remote connection, a GPRS or DSL router is needed at the PLC site, which will act as a bridge between the LAN (Local Network) where the PLC is physically wired and the WWAN or WAN (Internet) to which a remote iPhone or iPod Touch will have access to. This figure shows a standard setup.

First determine the LOCAL IP address of the GPRS or ADSL router. PLCs need to know the router address as it is the gateway to the internet.

1. In case of Omron Fins/TCP copy the router address in the ‘IP Route Table’ field of the ethernet configuration panel for the PLC in CX-Programmer.

6. For EIP/Native protocol and Allen Bradley controllers use RS-Logix tool to set the fixed local router IP (gateway) on the ethernet module properties panel.

7. For EIP/PCCC protocol use Allen Bradley's RS-Logix 500 tool and set the gateway IP on the Channel Configuration panel

8. For Modbus/TCP based devices Siemens S7 or Mitsubishi controllers refer to the vendor’s documentation.

9. Now log into the GPRS or DSL Router and configure NAT options to set up a bridge between the WAN and your PLC local address and port. Note that the default port number is 44818 for Ethetnet/IP, 502 for Modbus/TCP, and 9600 for Omron PLCs. Protocol on the router must be set to TCP/IP. Look at your router documentation for details.

10. If you have a fixed IP address enter it as such in the remote parameter of your PLC Connector in HMI Editor. .

11. If your router access the WAN through a dynamic IP then you must create an account with a dynamic DNS services provider such as www.dyndns.org, and configure your router to notify of IP changes. In this case, enter in the remote parameter the name you chose for your dynamic DNS. The remote port number must still be the one configured in the NAT section of your router.

7.8.5 Network Security.

HMI Editor networking security is based on TCP/IP technology and depends in part on the security features available in the router installed at the PLC location.

For local connections through WiFi security is given by the wireless network security protocol in use. WPA and WPA2 with a strong password is the recommended security protocol.

For remote connections, an iPhone or iPad is able to make use of secure data tunnels by enabling VPN. If your router supports L2TP/IPSEC or PPTP then you will be able to create this kind of connection. Most medium to high-end DSL or Cable routers support at least PPTP. VPNs client connections are configured on the iOS device with the General Settings App.

For most protocols, HMI Editor provides an independent way to protect users from undesired access of persons using uncontrolled HMI Editor or ScadaMobile copies. This is done by setting a Validation Code both in the PLCs and HMI Editor which will prevent the app to access PLCs unless both codes match. Next section describes validation codes and how you can set them.up.

Finally, physical access can compromise security. It is relatively easy for an unauthorized user to gather physical access to a device and run a remote monitoring application. To fight this possibility, HMI Editor user accounts provide password based security. You can set the 'automatic login' switch off in the HMI Editor or HMI settings tab, and a password key will be asked each time the app is launched, thus preventing unauthorized people from using the app. Additionally Apple provides a service for blocking lost or stolen devices so that no one is able to access to data or execute apps in them until the real owner reactivates them.

7.8.6 The Default Validation Tag .

For most protocols HMI Editor requires a validation code being held by the PLC, which is queried on each connection. This password must be stored in your PLC as a 16 bit hexadecimal value (0 to FFFF) and must match the value specified in ‘Validation Code’ for connections to a PLC to succeed. In most cases this security measure alone is enough for simple applications.

Validation Codes are stored in PLCs in the following Memory Address or Tag depending on protocol.

Validation codes are entered in the relevant field of your HMI Editor’ connector. Note that HMI Editor will always perform this security check. There is no way to disable or prevent it, however you can set a custom Validation Tag:

7.8.7 [Setting a Custom Validation

Tag](http://www.macsurfer.com/)

If the default validation tag interferes with your project you can set a custom one with the Validation Tag parameter.

When using a custom Validation Tag you must be aware of the following rules:

• It is explicitly forbidden to use 0 (zero) for the Validation Code when you set a custom Validation Tag. If you do so validation check will always fail.

• If you explicitly set the Validation Tag property to the same as the default one, you will still have to explicitly set a non zero value for the validation code, as using 0 will always fail the validation check.

• To return to the Default Validation Tag, and thus remove the restriction on a value of 0 for the Validation Code, simply leave the Validation Tag field empty.

7.8.8 International Languages Support and String

Encodings

The HMI Editor app fully supports International Characters and Strings in any language. Integrators can therefore chose to present their project interface in any language.

To represent strings the concept of String Encodings is used. String Encodings are international conventions that determine how characters representing particular languages are stored into files and device memory.

By default HMI Editor assumes project files and Strings to conform to the UTF-8 Encoding. This is specially adequate for English and relatively compact for most Western European languages such as German, French, Spanish, Portuguese, and many others. UTF-8 is still designed to work for virtually any international language including Asian languages (Chinese, Japanese, Korean) and the rest of languages that are not based on Latin derived characters. It does not require any particular setting.

The UTF-8 encoding is backward compatible with old plain ASCII, meaning that ASCII characters share the same codes when represented in UTF-8 encoding.

International languages can be represented with encodings other than UTF-8 which are generally more efficient for a particular language. This is presented on the next section.

The default string encoding for String storage in PLCs is WindowsLatin1. Like UTF-8 the WindowsLatin1 encoding is backward compatible with ASCII, but contrary to UTF-8, it uses one single byte per character for representing most Western European languages like German, French, Spanish, or Portuguese.

7.8.8.1 String Encoding for International

Languages.

The following explicit string encodings are supported on HMI Editor:

7.8.8.2 Use of International Characters in PLC

Strings

You can store international Strings in PLCs with HMI Editor just as easily as you do ASCII strings. HMI Editor will use the string encoding specified for the Connector to decode/encode strings onto raw bytes in the PLC.

When storing international Strings into PLCs you must expect the number of bytes used, and thus the PLC string length, to be larger than the number of characters the string actually contains. This is particularly notorious when storing Chinese or Japanese strings in PLCs.

The UTF-8 encoding, for instance, can use up to 6 bytes per character in a PLC. However, this does not affect how strings are allocated in HMI Editor or the behavior of String methods and operators in expressions, since these always refer to actual characters and actual character lengths regardless of encoding.

Of couse, if you only use English or ASCII characters with an encoding that is backward compatible with ASCII, or you use the default WindowsLatin1 encoding, only one byte per character will be allocated in your PLC to store strings.

7.9 PLC Tags

PLC Tags are associated with PLC Connectors through Properties that are dynamically created upon addition of PLC Tags. This makes possible to access them as any regular Object Property. PLC Tags are accessible as Properties of PLC Connectors

The syntax for accessing a tag named tagName of a PLC Connector named source is the following:

source.tagName

PLC Tags have in turn their own configuration panel. The following parameters are available:

7.9.1 Specification of Variable Types (‘Type’

Parameter)

Type determine the native data type of variables in PLCs. A Type may refer to a simple scalar value such as an INT or FLOAT or to an array of values.To indicate that you access a PLC Variable as an array you append [n] to its data type. In the table below, ‘n’ indicates the total number of elements that the array must hold.

The following types are supported.

7.9.1.1 Representation of Character Strings in PLCs

Strings in PLCs are stored in several ways depending on PLC brand or family. HMI Editor uses a homogeneous way to indicate PLC tag Types that in some cases differ slightly from the PLC manufacturer way.

In general, you do not need to worry about which particular representation a particular PLC uses. HMI Pad handles it all automatically for you.

Not all PLCs share the same fields for representing a string. For example Allen Bradley controller strings are fixed capacity and can hold up to 82 character bytes. Siemens S7 controllers, on the other hand, require a size specification for strings.

For Allen Bradley Controllers you can simply use STRING to indicate a single string, or STRING[n] to indicate an array of n strings. The actual representation of a single string on the PLC consists on a UINT or UDINT field followed by a 82 bytes long buffer.

AB MICROLOGIX STRING REPRESENTATION (STRING):

AB LOGIX STRING REPRESENTATION (STRING):

The same criteria apply for Opto22 PAC controllers as they represent STRINGs with a variable length structure starting with a field containing a value for both size and length followed by the same number of raw characters after the length field.

OPTO22 STRING REPRESENTATION (STRING):

For Siemens S7 Controllers you must use STRING(size) where size is the total number of byte characters that the string can hold, or STRING(size)[n] to indicate an array of n strings of size character capacity. The actual representation of a STRING(size) in the PLC consists on the following pattern.

SIEMENS SIMATIC S7 STRING REPRESENTATION (STRING(size)):

Although the above representations are the default ones for the mentioned controller brands, HMI Editor will still attempt to chose one of the above for use on controllers with no explicit STRING specification. The choice will depend on whether you used a size specifier.

On controllers with no explicit STRING representation you will want to use the raw char string representation CHAR(n)

RAW CHAR STRING REPRESENTATION (CHAR(size)):

For raw char string reads, HMI Editor will understand a NULL character or the total buffer size as the termination of the string. For writes, HMI Editor will pad all unused bytes with NULL characters. This is the usual convention for raw character string representations.

Important note about Strings with Siemens Simatic S7 controllers.

The size field for STRINGS in S7 must be generally specified. This is usually done in Siemens software by appending the size in square brackets just after 'STRING'. For example STRING[20].However, HMI Editor already uses square brackets to identify arrays so this notation conflicts with S7 notation.

To work around this we chose to use normal parentheses to indicate size.

Thus, STRING sizes must be indicated in the Type parameter using round parentheses. The square notation is still reserved for arrays, so when you use them you will be referring to ARRAYs. Consider the following cases:

STRING(20) This refers to a STRING with a capacity of 20 characters and should not be confused by STRING[20]

STRING(20)[3] This is an ARRAY of 3 elements, each element is a string with a capacity of 20 characters

STRING[20] This is an ARRAY of 20 STRINGs. This is not a string of 20 characters!. Since the default string size for S7 is 254 (256 bytes including the size and length fields) you will end having an array of 20 STRINGs with a capacity of 254 characters each. Actually you will end reading (or writing) a range of 20*256 = 5120 bytes on your PLC for this tag and your PLC will most probably reply with an out of range error.

7.9.2 Specification of Variable Addresses

(‘Address’ Parameter)

A Variable Address represents a memory location, a register or a Tag in a PLC to which a Variable refers. Addresses are specified in different ways depending on the particular communications protocol.

For protocols based on registers or memory areas, Addresses are specified by a prefix referring to the memory area followed by a numeric value indicating the position in that area. For Allen Bradley's Logix controllers and Opto 22 PAC controllers Addresses are based on symbolic names.

The following memory areas and prefixes are supported.

Accessing data types longer than one register.

For data types requiring more than one register or memory location, the lower address in their range must be specified. For example, a variable of type DINT addressed by HR100 will use HR100 and HR101 because 2 Modbus registers (16 bits) are required to accommodate the complete variable (32 bits). Integrators must be aware of it to avoid overlapping tag values. This applies to all protocols except EIP/Native and Opto22/Native.

Accessing a Register as a BOOL.

Generally, it is possible to specify a BOOL type for a register or memory location even if it is not meant to hold a BOOL. You can for example specify that HR1 is a BOOL. In such case, HMI Editor will apply the usual convention of true non zero values

EIP/Native does not allow a non BOOL PLC Tag to be treated as BOOL due to the strict type checking that this protocol encourages.

Siemens/ISO_TCP enforces size identification along with memory area, thus some restrictions apply for use of BOOL type on larger sizes.

The Opto22/Native protocol does not add type information to tags so you can use BOOL as Type to display values as per the general rule.

Accessing individual bits in a Register.

Individual bits on registers can be accessed by using the BOOL type and by specifying a bit address using the dot (.) or slash (/) notation depending on protocol (see table above). When writing, HMI Editor will use the appropriate protocol command to avoid overwriting undesired bits on the register.

On EIP/Native you can still use the dot notation to access individual bits on variables, but due to strict type checking you must set the correct variable Type.

With the Opto22/Native protocol the general rule still works for reads and therefore you can use the dot and bit number notation to obtain the corresponding bit value, for example ‘myIntTag.3’ will return the value of bit 3.

Note on EIP/Native communications protocol (AB Logix controllers).

EIP/Native communications do not rely on particular memory locations or positions, but on symbolic names. With this protocol the user is relieved from the responsibility to assign memory addresses or registers and from the need to take tag sizes into account for storage. Additionally, EIP/Native tags carry data information such as type and size, which HMI Editor uses to check against type mismatches on PLC returned values. As a result, it is not possible to store values that differ in type or size from the values that are uniquely defined in the PLC. Any attempt to so so will result in a ‘type mismatch’ error on the offending tag.

For EIP/Native any valid reference to an existing scalar or array type tag including structure members or array elements is supported. For example “myStructData[2,3].intMember” may refer to an integer value referenced by the intMember member of element (2,3) of an array of structures.

As a general rule, any Tag name path referring to an existing scalar value (BOOL, SINT, INT, DINT, REAL, STRING) or array of such elements in a Logix Controller can be accessed.

To access arrays as a whole you need to set the array size on Type, as discussed on the previous and following sections.

You can also access program tags by using the following syntax

Program:<program_name>.<tag_name>

Note that ‘Program’ is literal. <program_name> and <tag_name> identify just what they suggest.

Note also that HMI Editor performs a Validation Code security check before any other attempt to access other tags is made, therefore, it is mandatory to have a tag named “SMValidationCode” of type INT in your PLC for communications to work. (see The Default Validation Tag)

Note on Opto22/Native communications protocol (Opto22 PAC).

The Opto22/Native is a symbolic communications protocol that uses PAC control symbolic tag names to access variables in Opto22 PAC controllers. Integer, Float and String data types and Tables are fully supported for read and write. Additionally, HMI Editor provides ways to perform particular operations on timers and chars and to access fields of digital and analog I/O points. The way you use HMI Editor for accessing to these features is described in continuation.

DataTypes: Supported types for Opto22 are DINT, REAL and STRING (Type Parameter). Other data types in HMI Editor can be used as well but they may trim results depending on the actual values in the controller.

Tables: Tables are fully supported. Tables can be of DINTs, REALs or STRINGs. To access tables you define the number of elements to read or write from a table as an array subscript on Type. For example REAL[8] will refer to 8 elements of a table of floats. Similarly, on Address you specify the starting element, for example myRealTable[3]. These two entries combined will cause reads or writes of 8 values from the table myRealTable starting at element 3 and continuing through element 10 inclusive.

DIgital and Analog I/O Points: I/O points in Opto22 are represented by data structures which HMI Editor can read and provide access to some of its members. In order to access I/O point structure members a dot notation using particular names is used. The following member access names are available:

digital_IO_point.state read access to a BOOL value corresponding to the actual state of any Digital I/O point

digital_I_point.on_latch read access to a BOOL with the On Latch attribute of a Digital Input point

digital_I_point.off_latch read access to a BOOL with the Off Latch attribute of a Digital Input point

digital_I_point.counter read access to a DINT value with the Counter value of a Digital Input point

analog_IO_point.value read access to a REAL with the actual value of any Analog I/O point

analog_I_point.min read access to a REAL with the min value of an Analog Input point

analog_I_point.max read access to a REAL with the min value of an Analog Input point

IO_Point.enabled read access to an an 8 bit value register associated with an I/O point to check if its I/O Unit and I/O Point Communication flags are enabled.

Note that these member access names are not available on the expressions engine but only as an extension for point variable definitions as entered in Address. In other words, a point variable data structure cannot be read as a single object but only through its members.

Timers:. Timer values are accessed as any regular float variable. Additionally, some actions can be performed on timers when operated in write mode. In such case particular commands are sent to the PAC controller as opposed to a data value. To cause commands for appropriate actions to be sent you must set the write_expression parameter on the PLC Tag. Actions are specified using the dot notation with particular names as follows:

timer Actual value, a REAL with the value of the Timer variable timer.

timer.start_timer when written to sends the command StartTimer to the Timer timer

timer.stop_timer when written to sends the command StopTimer to the Timer timer

timer.pause_timer when written to sends the command PauseTimer to the Timer timer

timer.continue_timer when written to sends the command ContinueTimer to the Timer timer

Charts:. It is possible to read Chart Status and to perform Start and Stop operations. This is provided by means of structure member access names. The Start and Stop commands work with writable tags. The same recommendations given for Timer commands apply for Chart commands.

chart.chart_status provides read access to the 32 bit BitStat value of Chart chart as a UDINT value

chart.start_chart when written to sends a Start command to the Chart chart

chart.stop_chart when written to sends a Stop command to the Chart chart

7.9.3 PLC Memory Arrays and Access Patterns

It is possible to read or write consecutive memory locations in the PLC as memory arrays and use them as single property values. In order to do so you define the array size for the PLC Tag Type. HMI Editor will read the specified number of values and will make them available as an Array through the Property associated to the PLC Tag.

To deal with PLC arrays HMI Editor uses several access patterns depending on the specified Type and actual size of data in the PLC. We will use examples based on the modbus protocol to discuss each possible case. The same patters will work on all protocols for similar types and data sizes. For the examples we assume PLC Tags belong to a Connector named source.

The following access patterns are possible:

1 - Accessing 1 bit data size memory areas as single values (modbus coils).

• BOOL, SINT, INT, DINT, in Type

• Cx in Address

The tag property gets the value of Cx (0 or 1) regardless of Type

Example: get value at C1 as INT

testTag INT C1

source.testTag will contain 0 or 1 depending on the value in C1.

2 - Accessing 1 bit data size memory areas as an array (modbus coils)

• BOOL[n], SINT[n], INT[n], DINT[n] in Type

• Cx in Address

The tag property will be an array containing n elements of the specified type. Bits in each element will be taken from the PLC memory from the less significative to the most significative.

Example: get array of 2 INTs starting at C1

testTag INT[2] C1

Array element 0 (source. testTag[0]) will contain bits from C1 to C16.

Array element 1 (source. testTag[1]) will contain bits from C17 to C32.

Example: array of 10 BOOLs starting at C1

testTag BOOL[10] C1

Array element 0 (source.testTag[0]) will contain C1

Array element 1 (source.testTag[1]) will contain C2

...

Array element 9 (source.testTag[9]) will contain C10

3 - Accessing regular PLC memory as single values (valid on all protocols).

• BOOL, SINT, INT, DINT, REAL, STRING, CHAR[n] in Type

• HRx in Address

The tag property gets the value of HRx taking either the full register or the necessary following registers to hold the complete value. For types that are shorter than the actual register size the value in the PLC register is taken as a whole rather than trimmed to a shorter type.

Example: get DINT at HR1

testTag DINT HR1

source.testTag will contain the DINT value contained in HR1,HR2. (this is because DINT is 32 bits long and HRs hold 16 bits each)

Example: get HR1 as a BOOL

testTag BOOL HR1

source.testTag will contain 1 (true) if HR1 is not zero, or 0 (false) otherwise. HR1 raw value is therefore interpreted as boolean.

4 - Accessing regular PLC memory as an array of values (valid on all protocols).

• SINT[n], INT[n], DINT[n], REAL[n], STRING[n] in Type

• HRx in Address

The tag property will be an array containing n elements of the specified type. The array gets its values starting from HRx taking the necessary following registers to complete all its data according to data type size. Data is packed as it is found in PLC memory for types that are shorter than the actual PLC register size and taking into account the native endianness of the protocol.

Example 1: get array of 2 REALs starting at HR1

testTag REAL[2] HR1

Array element 0 (source.testTag[0]) will contain the REAL value at HR1,HR2.

Array element 1 (source.testTag[1]) will contain the REAL value at HR3,HR4.

Example 2: get array of 4 SINTs starting at HR1

testSTag SINT[4] HR1

Array element 0 (source.testSTag[0]) will contain the first byte of HR1.

Array element 1 (source.testSTag[1]) will contain the second byte or HR1

Array element 2 (source.testSTag[2]) will contain the first byte of HR2

Array element 3 (source.testSTag[3]) will contain the second byte of HR2

5 - Accessing individual bits of regular PLC memory (valid on all protocols).

• BOOL, SINT, INT, DINT, REAL in Type

• HRx.y in Address

The tag property gets the value of bit y (0 or 1) of HRx regardless of its type

For writes, using this pattern guarantees that writes of individual bits on registers will not affect or overlap other bits in the same or other registers.

Example: get HR1.0 as DINT

testTag DINT HR1.0

source.testTag will contain 0 or 1 depending on the value in HR1.0

6 - Accessing individual bits of PLC memory as an array of boolean values (valid on all protocols).

• BOOL[n], in Type

• HRx in Address

The tag property will be an array containing n elements of type BOOL. The array gets its values starting from Bit zero of HRx taking the necessary following registers to complete all its data.

Note that writing BOOL arrays with a size that is not a multiple of the raw register size on PLC memory will cause the exceeding bits to be set to zero.

Example: array of 32 BOOL starting at HR1

testTag BOOL[32] HR1

Array element 0 (source.testTag[0]) will contain bit 0 of HR1

Array element 1 (source.testTag[1]) will contain bit 1 of HR1.

...

Array element 16 (source.testTag[16]) will contain bit 0 of HR2

...

Array element 31 (source.testTag[31]) will contain bit 15 of HR2

Note on EIP/Native communication protocol (AB Logix controllers).

Since EIP/Native communications rely on symbolic names and type checking is performed on returned data, type matching must be observed. Basically, most of the above patters are applicable in the general way as far as the data type specified in column B matches the actual type on the PLC tag. This includes strings and arrays of any type.

From your perspective as integrator you do not need to treat Logix BOOL arrays in a special way as HMI Editor handles them automatically for you, in essence you can access individual elements by just entering BOOL on Type and the particular array element on Address (pattern 3), or you can get the complete (or part of the) array by specifying BOOL[n] on Type (pattern 6)

Note on Opto22/Native communication protocol (Opto22 PAC controllers).

The Opto22/Native protocol is symbolic but it does not always carry type information. Therefore, all the above accessing patters (except 1 and 2) are applicable and will work as described in most cases, specially for Integer and Float data values. The availability of access patters allows for advanced ways to get partial information from Opto22 strategy variables

Pattern 4 is especially relevant to be considered when used with Integer or Float Tables as it will prioritize the specified element size (for example 2 bytes for INT[n]) as opposed to the actual table element size (always 4 for Opto) and will still produce the effects described for that pattern (so when reading integer elements from OPTO into INT arrays, each OPTO table element will consume 2 HMI Editor array-elements).

Of course, if you always use DINT[n] or REAL[n] for accessing tables (strongly recommended), each table element will correctly fit in one element both in the Opto22 PAC controller and HMI Editor.

7.9.4 Writing to PLC Variables

('write_expression' Parameter)

You can configure writes to PLC Variables by entering an expression into the write_expression. The write_expression property is designed to perform writes on the PLC as the expression changes (receives a change event).

Example 1

For example if you enter button1.value on the write_expression property of a BOOL Tag, HMI Editor will send the button action (1 or 0) to the PLC when an user taps on the button.

Example 2

Consider that we have a switch on screen we want to link both ways with a PLC Tag named source.myTag. We want the switch to track changes of source.myTag and we want source.myTag to update when the switch changes.

Therefore we need to connect both sides of the required actions through expressions as schematized below:

1:- On the value property of the switch we enter: source.myTag. (This will update the switch when source.myTag changes)

2:- On the write_expression of the myTag we enter: switch.value (This will update source.myTag when the switch changes )

It is worth observing that you can enter whatever expression on each side of the link. This allows for achieving complex things such as updating interface elements that depend on several PLC values (or other interface elements) and perform writes to PLC tags that depend (or are linked) to disparate elements on the interface.

Use of the Expression List Operator (comma operator) to differentiate writes

The Expression List Operator ',' (comma operator) can be used to easily configure writes that should trigger on separate conditions without affecting each other.

For example we may have a numberField and a knob control on the interface and we want to update a PLC Tag for changes on any of the two. In this case you can enter the following on the write_expression property of said PLC Tag :

numberField.value, knob.value

this will write a value to the PLC Tag when either numberField.value changes or knob.value changes. Of course to keep both controls updated on the opposite direction you need to enter source.tag in the value fields of both controls..

7.10 REST API Connectors

REST API Connectors let a project exchange data with HTTP/HTTPS web services that follow the REST style. A connector represents a single configurable request whose response, status code, and trigger behaviour are exposed as properties to the rest of the project.

REST connectors are project-level objects. They are created from the Model Browser under REST connectors and monitored from the Inspector panel’s REST API tab.

7.10.1 Creating a REST API Connector

1. Open the Project Viewer.
2. Open the Model Browser with the loupe button.
3. Select REST connectors.
4. Tap + to add a new connector.
5. Select the new connector and configure its properties in the Object Configurator.

7.10.2 Connector Properties

7.10.3 Monitoring REST API Connectors

Open the Inspector panel and select REST API. On compact tab bars it may appear under More.

Each connector shows:

• A title row with the connector identifier and a status dot.
• An Enabled switch (green = enabled, gray = disabled).
• A live information row showing the base URL, path, method, polling interval, HTTP status, and total request count.
• A Last response row that opens a JSON-syntax-highlighted response viewer.

Turning Enabled off stops all requests, including the polling timer; turning it back on resumes both polling and trigger-based requests. The enabled state is saved with the project.

7.10.4 Example

Assuming a connector identifier of weather, you can read its response anywhere in the project:

weather.response["main"]["temp"]

weather.statusCode == 200 ? "OK" : "Error"

weather.gotResponse ? "new data!" : ""

To fire the connector on demand from a button, bind a control’s value to its trigger property. To poll automatically every 30 seconds, leave trigger at its default and set pollingInterval to 30.

7.11 MQTT Clients

The MQTT Client lets a project connect directly to an MQTT broker, subscribe to a topic, publish messages, and expose the latest MQTT state to expressions. Use it when an HMI page needs to exchange data with devices, gateways, or services that speak MQTT instead of a PLC protocol.

MQTT Clients are project-level objects. They are created from the Model Browser and monitored from the Inspector panel.

7.11.1 Creating an MQTT Client

1. Open the Project Viewer.
2. Open the Model Browser with the loupe button.
3. Select MQTT connectors.
4. Tap + to add a new MQTT Client.
5. Select the new connector and configure its properties in the Object Configurator.

The connector also appears in search results under MQTT CONNECTORS.

7.11.2 Connection Properties

The client reconnects automatically when connection properties change. It also uses MQTT auto-reconnect with a 5-second interval after a connection drop.

Note: The current TLS implementation enables SSL and allows untrusted CA certificates. Use this accordingly on trusted networks or with VPN protection where certificate validation policy matters.

7.11.3 Subscribe Properties

When a message arrives the connector updates its live read-only values:

Example use, assuming the connector identifier is mqtt:

mqtt.connected

mqtt.gotMessage

mqtt.lastTopic

mqtt.lastMessage["state"]

mqtt.messageCount

Use lastMessage["name"] style access for JSON object payloads. For plain-text payloads, use lastMessage as a string.

7.11.4 Publish Properties

The Inspector shows the latest published topic and payload after the first publish in the current session. This publish history is transient and resets when the project is reloaded.

7.11.5 Monitoring MQTT Clients

Open the Inspector panel and select MQTT. On compact tab bars it may appear under More.

Each connector has:

• A title row with the connector identifier and a status dot.
• An Enabled switch.
• A live information row showing the broker, subscription, received message count, publish topic, and publish count.
• A Last message row that opens the received and published payload viewer.

Status dot meanings:

• Green: enabled and connected.
• Yellow: enabled but disconnected or still connecting.
• Gray: disabled.

Turning Enabled off disconnects the MQTT client. Turning it back on reconnects using the configured properties. The enabled state is saved with the project.

7.11.6 JSON Payloads

Received JSON payloads are parsed automatically when they are valid JSON objects or arrays. This lets expressions read fields directly from lastMessage.

Published payloads can also be built as structured values. If publishPayload evaluates to a dictionary or array, HMI publishes it as JSON. If it evaluates to a string, HMI publishes the string unchanged.

The Last message view in the MQTT Inspector pretty-prints JSON for both received and published payloads.

7.11.7 Practical Notes

• Use one MQTT Client per broker/topic role when it keeps expressions simpler.
• Leave subscribeTopic empty for publish-only clients.
• Leave publishTopic empty for subscribe-only clients.
• Use QoS 0 unless the broker/device workflow requires 1 or 2.
• Set an explicit clientID when the broker requires stable client identities or persistent sessions.
• Password values are project configuration data; handle project files with the same care as other credentials.
• MQTT runs independently from PLC connectors. It does not require a PLC connection.

Document Revision History

Refer to this section to look at changes on this document over different versions.

Version 3.5

• New Settings section (§2.1.1) covering Disable Auto-Lock, Haptic / Pulse Feedback, Alarm on Disconnection, Keep Connected, Maintenance actions, Embedded Web Server port and Help links.

• New Model Seeker section (§2.2.1) describing the value picker and the SF Symbols tab for image-path properties.

• New Current Project Panel section (§3.1) describing the Start Page selector (Last Used / per-page) and per-project actions.

• New Moving Items Between Pages section (§4.2) describing the MoveToPage context-menu action and destination-page picker.

• Many new Ruby-style methods documented:

  • Numeric (§6.3.1): between, clamp, zero, positive, negative, even, odd, class.

  • String (§6.3.2): empty, upcase, downcase, capitalize, strip, reverse, start_with, end_with, include, count, sub, gsub, class.

  • Array (§6.3.3): empty, count, index, include, first / last / shift / pop, push / unshift, take / drop, sort / sort_by, reverse, rotate, uniq, compact, flatten, sample, sum / sum_of, product, average / mean, min_max / min_by / max_by, all / any / none, map / filter_map / flat_map, select / reject, dig, zip, tally, class.

  • Dictionary (§6.3.4): empty, has_key, include, has_value, invert, to_a, class.

• New stepValue property on the Knob control (§7.3.2.6).

• New enabled, verificationText, linkToPage and linkToProject properties on the Tap Gesture Recognizer (§7.3.2.9).

• New barColorStartPoint property on the Bar Level indicator (§7.3.3.2).

• New colorFillStartPoints key on the options dictionary of the Trend (§7.3.3.4.1) and Chart (§7.3.3.5) indicators.

• New timeRemaining property on all timer background objects, and three new timer types added alongside the existing On Timer:

  • Off Timer (TOF) (§7.4.5)

  • Pulse Timer (TP) (§7.4.6)

  • Retentive Timer (TONR) (§7.4.7) with new reset property

• JavaScript background object renumbered to §7.4.8.

• New REST API Connectors chapter (§7.10) with full property reference, Inspector tab description and example.

• New MQTT Clients chapter (§7.11) with connection, subscribe, publish and Inspector sections, plus practical notes.