ctrlX HMI - Basic Template

1. Introduction

The free HMI template for ctrlX Automation supports HMI users in creating innovative and user-friendly user interfaces for controlling and monitoring machines and systems.
The ready-made HMI interface is based on WebIQ from Smart HMI and offers the user complete freedom for individual customization and design.
The template, consisting of an HMI interface and a corresponding PLC program, is ready for immediate use and enables quick and efficient HMI development.

The following documentation describes how to use the HMI-Template. It helps to setup the template on your ctrlX CORE or ctrlX CORE^virtual. Furthermore, it explains how the template is created and gives tips how to modify or create your own HMI Solution. Start at this point if you want to install the template for the first time.

Download ctrlX HMI - Basic Template 

General hints

• This template is created with ctrlX OS version 2.6.2 and WebIQ Designer version 2.15.7. There is no guarantee that the code will compile successfully in newer ctrlX CORE versions without adaptation.
• To understand this documentation, you must be familiar with the basics of ctrlX AUTOMATION and WebIQ.
• There are two possobilities to intall and use the HMI Template:
  
  • by restoring ctrlX^virtual image "ctrlX_CORE_virtual_Backup_2_6_2.zip" (ready to use HMI&PLC Template /ctrlX OS version 2.6.2). To access HMI Template refer chapter 4.5 onwards. Hint: Due to an error during backup creation, the symbol settings must be updated (refer chapter 4.2)
  • by installing all required apps and licenses and following instruction form chapter 3 onward (for operational use on ctrlX CORE)

Additional information

• Collection of how to videos, blogs and examples for ctrlX AUTOMATION 
• See PLC Engineering manual
• See WebIQ manual
• For further queries and feedbacks about HMI Template please use ctrlX HMI Forum.

2. Main objectives of the HMI Template

WebIQ project template with

• Screen template in ctrlX layout
• Navigation concept
• Basis communication mechanisms (in collaboration with communication interface)

WebIQ Standard (HMI) template, which is a pre-designed layout or framework used in the development of graphical user interfaces for various systems, machines, or applications. The primary goals of an WebIQ HMI template are:

• Consistency: HMI templates ensure a consistent look and feel across the user interface. By using a standardized template, designers can maintain a cohesive design throughout the application, making it easier for users to navigate and interact with the system.
• User Experience (UX): The ultimate goal of any HMI template is to enhance the overall user experience. By employing a well-designed template, the interface becomes intuitive and user-friendly, reducing the learning curve for new users and minimizing errors.
• Time and Cost Efficiency: HMI templates save development time and costs. Designers and developers don't need to create the entire interface from scratch each time; they can use the template as a starting point and customize it to fit the specific requirements of the application.
• Flexibility and Customization: While templates provide a foundation, they should also allow for flexibility and customization to suit the specific needs of the application or system. Designers should be able to modify the template to accommodate unique features or functionalities.
• Scalability: HMI templates should be scalable to support different screen sizes and resolutions. As technology evolves and new devices with varying display dimensions emerge, the template should adapt accordingly.
• Responsiveness: With the increasing prevalence of mobile devices and tablets, an HMI template should be responsive and adaptable to different screen orientations and form factors.
• Aesthetics and Branding: HMI templates often incorporate a visually appealing design and can be customized to reflect the branding and identity of the organization or product.
• Usability Guidelines: Templates can follow established usability guidelines and best practices, ensuring that the interface adheres to industry standards and optimizes user interactions.
• Feedback and Iteration: HMI templates can be continuously improved based on customers feedback and iterative design processes, allowing for ongoing enhancements and optimizations.

3. Prerequisites

3.1 Prerequisite for HMI and PLC development

3.2 Prerequisite for using OPC UA, PLC and HMI Apps

The following apps are necessary to run all features of the provided example. You need the licenses for each app.

Note: The 10-day trial license for ctrlX OS Apps can also be used for test purposes ( ctrlX OS License - Trial all ctrlX OS Apps (10 Days)).

4. First Startup

4.1 Preparation of the ctrlX CORE

• Install apps and licenses (refer 3.2) and reboot the ctrlX CORE. 
• To keep template simple, it uses the default user and password boschrexroth.
• In a real project, for security reasons, you should create a user only with OPC UA rights for OPC UA communication.
• The same applies for the user used for the REST API communication.

The Basic HMI Template uses Recipe manager developed by Rexroth Team (refer 6.1). Therefore, this step is required to load predefined .rcp file.

To install the example recipe files, do the following steps.

• Switch system state to “Setup” (1)
• Click “Manage App Data” (2)
• Click “…” -> “Upload” (3) and select AppData_for_HMI_Template_2_6_2.zip. The archive contains default recipe file. 

Required setting for process communication in the data layer of ctrlX Works V2.6 onwards. 

4.2 Update symbol-settings

• Go to Settings → Datalayer (1)
• In “plc” node, open "symbol-settings" under "admin/runtime-settings" (2)
• Change "enumRepresentaion" to "BASETYPE" insted of "FLATBUFFER" and "arrayDisplayName" to "OFF" insted of "ON" (3) 

4.3 Preparation of ctrlX PLC 

When you are not familiar with PLC Engineering, see chapter 9 "PLC Implementation for HMI Template".

• Unzip PLC project from "PLC_Template_2_6_2.zip" and then extract "PLC_Template_2_6_2.projectarchive" with ctrlX PLC Engineering.
• Open project: File> Open Project…
• Check if project device matches your device (ctrlX CORE^virtual or ctrlX CORE)
  • Right click ctrlX CORE… in the project tree
  • Select Update device
  • Select device you are using
  • Click on button Update device
  • Click on button Close
• Check IP settings:
  • Right click ctrlX CORE… in the project tree
  • Select Communication settings…
  • Enter IP or select it from selection box
  • Click on button Apply to verify connection
• Login to ctrlX CORE or ctrlX CORE^virtual 
  • Online> Login (Provide user & password)
  • Default user and password: boschrexroth
• Start PLC program
  • Debug> Start

4.4 Preparation of OPC UA communication between project and ctrlX CORE / ctrlX CORE^virtual

To change the OPC UA settings, you need the WebIQ Designer and the ctrlX CORE user interface. 

First Step: Project adaptation in WebIQ Designer

• Start WebIQ Designer (license required refer chapter 3.1 and chapter 7)
  
• Import HMI project "HMI_Template_2_6_2.zip" in WebIQ designer. 
• Open IO Manager and check for connectivity to ctrlX CORE or ctrlX CORE^virtual. If not connected update the endpoint URL ( CORE IP-address), click apply. It will send an OPC UA connection request to the OPC UA server on ctrlX CORE/ctrlX CORE^virtual. (refer also: WebIQ - Create your first HMI project.)
  
  Best practice: use IP address of the ctrlX device instead of hostname because you can run the project on multiple devices of same IP address without adapting WebIQ project.

Second step: Trust OPC UA certificate in ctrlX CORE user interface

To establish the OPC UA communication the OPC UA client certificate of SmartHMI must be trusted in ctrlX CORE. This must be done only during the first startup.

• To trust the certificate, open ctrlX CORE Web page, go into Settings > Certificates & Keys > OPC UA Server. Click on “…” of the Smart HMI certificate and select “Trust”.

Final steps in WebIQ Designer after OPC UA establishment:

•  Publish HMI Project in WebIQ Designer.
• After publishing go to the Project list in WebIQ Designer, click on "..." and export project to any Location of your choice. It will export a zip file of the project, which will be used to load WebIQ project to ctrlX CORE or ctrlX CORE^virtual. 

4.5 Start WebIQ Project

Login to ctrlX CORE / ctrlX CORE^virtual web page and click on “WebIQ Runtime Manager”.
The first time after installation of WebIQ on ctrlX CORE / ctrlX CORE^virtual you must define a user and password for login (e.g. User: admin password: boschrexroth1). This user is valid for “Runtime Manager” and “Designer”.

Hint:    When you forget the password, you must delete and reinstall the WebIQ app. This means all WebIQ projects on ctrlX CORE are deleted.

To start the WebIQ Server with the HMI template refer to following steps:  

• In menu item Hmi Projects (1) press Upload (2) button and select the WebIQ project (e.g. HMI_Template_2_6_2.zip) you have exported in previous step.
• Press … and select Start (3) to run the project
• Press … and select Open (4) to display the project in browser

HINTS

• When the OPC UA communication is not working please "Trust OPC UA certificate in ctrlX CORE user interface" again (see above)
• When you are using a newer WebIQ server version than 2.15.10, the WebIQ project must be updated first (Please refer to the WebIQ manual)
  

Start the machine and test the different functionalities of the template. For example, start the movement, switch to automatic mode and press the Start button or follow the Product (User) Document given below.

5. Product (User) Documentation

Features of the HMI Basic Template:

• Responsive design (Min. requested resolution tablet).
• Navigation concept (Shrunken/Extended navigation and Left/right Navigation).
• Communication check: HMI is locked if not connected to PLC
  (reasons: 1. security 2. some features are only working when PLC is running).
• PLC example code with Agitator tank application, see FB_Machine_Customer.mAutoPlc().
• GAT Compact state machine and Operation mode implementation, See FB_Machine_Base().
• Last active recipe is automatically loaded at ctrlX CORE startup. 
• Table for editing Recipe parameters (Recipe).
• Recipe handling in PLC with Open, Save, SaveAs and Delete in mode Manual & Setup (Recipe) (PLC recipe structure stRecipe).
• Alarm handling: Active, history based on WebIQ Widget and ctrlX CORE diagnostics (Diagnostics).
• Debug table: Used for debugging and simulation (Debug).
• Predefined HMI languages: German, English (Settings > General Settings).
• Side navigation positioning: Left or Right (Settings > General Settings).
• Screen cleaning Mode: Disable screen for cleaning (Settings > General Settings).
• System Login: Sign into ctrlX CORE (Settings > General Settings).
• Machine Name: Edit machine name (Settings > General Settings).
• Toggle Full Screen: Toggle between Kiosk and Framed browser (Settings > General Settings).
• HMI User Manager which allows to add, edit, delete… users (Settings > User Management).
• About: Version information of HMI and HMI project (About).

5.1 System information Header

• Machine name / Screen name
  • Displays the Machine Name (User defined from system settings). Also displays respective screen names of the selected screen.
• Alarms / Status banner (based on PLC diagnostic)
  
  • Alarm notifications banner alert the user to specific events (Errors, Warnings, Notifications etc.) or conditions that need attention.
  • The 'Reset All Alarms' feature allows users to clear all active alarms from the system.
• System Date and Time
  • System Date and Time is displayed in the Header 1 section.
  • Time format is HH:MM:SS 
  • Date format is YYYY-MM-DD
• Logout and User info 
  • In the Header 1 section, you will find a user icon, which displays the user name of the currently logged-in user.
  • In order to change or manage the user, click on the user icon in the Header 1 section. 
    • In the dropdown menu that appears, locate and click on the "Logout" option to change the User. 
    • Or select "Users" option to enter "User Management".
      
• Language selection
  • Customer can select the language of the HMI. Language change is done interactively in the HMI and can be applied without restart.
• Rexroth logo / Reload screen
  • Company logo is displayed on the upper right-hand corner, clicking on that reloads the page.

5.2 Machine status Header

Operation Modes (OpMode):
OpMode functionality helps to switch between different operating modes (Auto, Manual, Setup). Auto mode has functionality of Start, Pause and Stop machine. These buttons appear only in Auto mode and hides in other modes.

• Automatic OpMode: In the Automatic mode, the system primarily follows pre-set sequences or parameters, allowing operations to continue seamlessly without continuous user intervention.
  • Start: Activates the automatic sequence.
    • On activation, the HMI initiates its programmed operations.
    • Following this, the 'Pause' option surfaces, facilitating users to momentarily pause the operations.
    • While in this active state, the interface hides the 'Manual' and 'Setup' options to minimize disruptions.
  • Pause: Provides an interim hold to the ongoing automatic process.
    • This is beneficial for instances when users foresee an intervention or adjustment necessity.
    • Post pausing, the 'Start' option becomes available again, letting users recommence operations from the paused point.
  • Stop: Conclusively ends the automatic operations.
    • Once invoked, the process cannot continue from the last point; it necessitates a new start.
    • Subsequent to the 'Stop' command, the 'Manual' and 'Setup' options become accessible, facilitating mode transitions.
• Manual OpMode:
  • The Manual mode is structured to grant users direct command over the system. It's an ideal mode for specialized tasks, troubleshooting, and instances demanding detailed operational control.
  • User can operate machine manually using manual operation buttons . In this example application user can toggle each valve, Motor and Heater individually.
• Setup OpMode:
  • ctrlX CORE or ctrlX CORE^virtual Dashboard is displayed in Setup Mode using Iframe.

     

Recipe:

• Shows name of the Loaded recipe 
• In case of Setup- and Manual- OpMode with the dropdown menu recipe manager functionalities will be available as follows:
  • Open: Opens dialog box contains list of pre-programed Recipes, User can select one of them and loads into system.
  • Save: Save the changes made in the Recipe using Receipe Parameners table (see below).
  • Save as: Save existing recipe with different name.
  • Delete: Delete existing Recipes.

Operation Mode Status:

• Shows active Operation Mode 

Heartbeat indicator:

• Heartbeat detection is a mechanism used to monitor the connection status between a HMI and a PLC bidirectionally. The primary purpose of heartbeat detection is to ensure the continuous and reliable communication between the two.
• The connected icon will appear in Green color and with a connection-on style, indicating a successful and active connection to the PLC.
• This visual representation serves as a quick reference to ensure that the system is actively communicating with the PLC and functioning as intended.
• Upon detecting a loss of heartbeat, the HMI and/or PLC can trigger appropriate actions, such as displaying an error message, or attempting to reestablish the connection. 

6. Side Navigation 

• Shrunken/Extended Side Navigation
  • Provide more space to user Application view
• Left/ Right Side Navigation
  • facilitate user likability in case such as if user is Left handed or right handed ( change side navigation position in Settings ).

6.1 Recipe Parameters

WebIQ provides a recipe manger, which can be used to store recipe data. But in this template we implemented and example, which has the following advantages compared to webIQ recipe manager:

• Store data on files in PLC
• Content of recipe is completely defined in PLC (Variable, Data type, min, max values, text lists)
• Formatted display of data in table rows
• Number of data edited in recipe can easily expanded without expanding the communication variables

The recipe parameter table (Rexroth custom widget) is used to display and edit the Recipe parameters.
The features are:

• Display/edit recipe parameters such as Duration, flow rate and level .
• Filter/Sort/Clear table columns.
• Copy/Paste table rows.
• Navigate up, & down through rows.

In Auto mode, Recipe parameters table is displayed without table editor functionality. In Manual & Setup Mode user can see Recipe parameters table along with editor buttons.

6.2 Diagnostics

In Diagnostics there are three Tabs Alarms & Messages,  Alarms & Messages History and ctrlX Diagnostics.

• Alarms & Messages ( user specific PLC error handling)
  Alarm notifications alert the user to specific events (Errors, Warnings, Notifications etc.) or conditions that need attention.

  • Real-time Alerts: As soon as an issue arises, the system sends an instant notification
  • Prioritization: Alarms are ranked by severity to help users address the most critical issues first.
  • Pending diagnostics: 'Pending Diagnostics' lists all the system events and diagnostics that are in process. 
    
    
• Alarms & Messages History (user specific PLC error handling)
  Error history provides a record of all alarms and errors that have occurred over time.
  
  
  • Timestamps: Each error is recorded with the exact time and date of occurrence.
  • Severity Indicator: Easily identify the severity of each error.
  • Filter Options: Filter errors by date, severity, or type.

• ctrlX Diagnostics:
  Shows all ctrlX alarms and messages embedded via Iframe. 

6.3 Commissioning

• Commissioning screen includes two blank tabs for user. It can be use to show Input/ output information and System Information.  

6.4 Debug

• Debug screen is used for debugging and simulation. Alarm, warning and information can be simulated with Debug table.
• With pretty less effort you can display and edit any PLC variable.

6.5 Settings

•  General Settings 
  • Language Selection: Select HMI Language. Currently there are two languages available for user DE (Deutsch) and EN (English).
  • Sidebar Position: Toggle Side Navigation left/right
  • Screen Cleaning Mode: In this mode, screen is locked for cleaning for a certain duration.
  • System Login: Communication user Login (Rest API)
  • Machine Name: User can define Machine name here, which is then displayed in System information Header.
  • Toggle Full screen: If HMI is not started in Kiosk mode then you can toggle between full screen and browser frame(temporary Kiosk mode).
• User Management
  • Once in the User Management section, you'll be presented with a user-friendly table that provides an overview of all registered users and their associated details (see WebIQ user management widget).

6.6 About

• Version information
  Shows version info of PLC App, WebIQ HMI Designer and HMI Template version.

7. HMI Template customization for user Application

The WebIQ Designer is the PC based Engineering tool from Smart HMI. In order to edit and test HMI Template (located on the ctrlX CORE) in WebIQ Designer, you would need to establish a connection between ctrlX CORE and WebIQ Designer. 

Note: The WebIQ Designer is subject to license. If you have activated a WebIQ Server license on the ctrlX CORE (e.g. ctrlX CORE License - Smart HMI - WebIQ Server 500 Tags), you do not need a separate Designer license. When connecting to the ctrlX CORE, the onboard Designer license of the ctrlX CORE is automatically used.

7.1 Connect the WebIQ Designer to the ctrlX CORE 

To connect the WebIQ Designer to the ctrlX CORE, you must add some parameters. Create a new shortcut (on Windows Desktop) for the WebIQ Designer application and click on Properties. In this example the used IP address is “10.52.244.3“. At download page of WebIQ Designer in ctrlX Store, there is a documentation which describes this in detail. There is even a script, doing the work for you.
Target settings: “<WebIQ_Installation_path>\Designer\webiq-designer.exe" --ws-host=10.52.244.3 --ws-port=10123 --user-data=webiq-designerCtrlx" to the target input field and apply the changes.

 Start WebIQ Designer (via shortcut) and login.

• The first time after installation of WebIQ on ctrlX CORE you must define a user and password for login. The user for "Runtime Manager" and "Designer" is the same
• Import Project "HMI_Template_2_6_2.zip" 
• Load Project 
• Install packages (containing additional features) via WebIQ Package Manager.
• Publish Project
• Start program

7.2 Rexroth Custom Widget

The HMI Template uses Custom widgets that are not included in the WebIQ scope of delivery. You will find the widgets in the “WebIQ Designer widgets list” after the custom widget packages have been installed.

7.2.1 HMI Custom widget Package cxVisual

Custom widget Package for HMI Basic Template which include visual widgets for ctrlX (eg. button, table, input....). For documentation see 'ctrlX Forum' section 'How-to' article 'WebIQ packages cxVisual'. If user do not install this package, he/she may be able to use the already configured implementation but not able to change the configuration and reuse it somewhere else. In the absence of package user will see the package not found warning instead of configurations.

In our Template we have used "button-widget" for OpModeControls and "cx-table" widget to show Recipe Parameters and Debug variables in the form of table.

 7.2.2 Custom Library Package cxTools
This custom library package includes implementation of custom Keypads, message Box and tools to extend webIQ features. 

7.2.3 Custom Library Package Axios
This custom library package consists of Axios implementation. Axios is a promise-based HTTP client for node.js and the browser. With the help of this custom library package we enable use JavaScript in WebIQ to connect to ctrlX Core REST API. We have used REST-API in our template to get data information about Recipe script, system login and license information etc.

8. Interface between PLC and HMI (Data Layer)

When you load PLC application in ctrlX CORE/ ctrlX CORE^virtual you would get the following node points in your Data Layer under PLC Node by default. In HMI project also you will find these variable in Process Data manager. 

9. PLC Implementation for HMI Template

This chapter consists of PLC implementation of Base Template. The GAT compact status machine from the MLC (IndraWorks) is used in this template. Since the original graphical implementation could not separate basis from user code, implementation has been changed to Structured Text. This results in the following advantages:

• Separation of base and user code. => Easy version update
• Entry and exit methods can be active for several PLC cycles instead of only 1 cycle before.

Below you see the structure of PLC application for HMI Template.

Base folder under GAT_CORE consists of implementations of all base functionalities for template such as state machine, operation modes, heartbeat connection and alarm management. Theses functionalities are commonly used in many industrial application.

Customer folder under GAT_CORE is majorly dedicated for customer applications. The function block FB_Machine_Customer extends the basic function block FB_Machine_Base. Tank Agitator system application is used in this template and recipes can be used for setting and monitoring values for a specific set of variables in example Application.

These following 2 libraries are included in the project archive of this Template:

• App_CommonData
• App_Tools

They provide powerful functions, but they are not part of the ctrlX PLC Engineering installation by default.

Hint on ctrlX CORE Task Configuration: 

• Dependent on your program requirements, you might have to adapt Task Configuration.
• ctrlX CORE^virtual has no real time operating system, therefore the cycle time and watchdog must be big, or disabled to avoid PLC stops caused by a watchdog.

So far, no performance tests and analyses have been carried out. Therefore, no experience about shorter and longer cycle times is available.

9.1 Machine Base

9.1.1 PLC state machine

State Machine of the Template is referenced from GAT Compact. As shown below the state machine Logic diagram HMI Template consists of multiple Operation modes:

• Error: Error is checked cyclically. In case of active error, active OP mode change to "Error" and active state to "Stop". when error gets clear machine goes default Operation Mode, in our case it's INIT.
• Init: Init is the default active OP mode in state machine
• Auto: After reboot complete, auto mode gets active. Operation states during auto mode are run, pause and stop. 
• Manual: Manual mode can be selected from HMI and could be used for user defined manual operations.  
• Setup: Setup mode can be selected from HMI and could be used for user defined setup operations.

Although the inheritance of object orientation is used here, the required knowledge to use it, is very basic. All necessary information's are included as a comment in the source code. All entry, active and exit methods have the same structure.

9.1.2 Heartbeat Connection
Heart beat connection checks the communication between HMI and PLC. With uiHeartBeatPLC incremented value is sent to HMI cyclically and fbHMIConnected() is used to check if HMI is connected. 

9.1.3 Alarm/Warning/Info Management

We have implemented a multiplexing channel for alarm/warning/info handling with the following features:

• The number of different alarms/warnings/info’s is unlimited (e.g., 1000, 4000, or more)
• Up to 30 alarms can be displayed simultaneously (method mAlarmSet())
• Up to 10 warnings can be displayed simultaneously (method mWarnSet())
• Up to 10 information’s can be displayed simultaneously (method mInfoSet())
• With increasing number of alarms/warnings/info’s, there is no need to add further communication variables
• If the translation not defined in WebIQ, only the error code is displayed

When you do not like this behavior, you can use the default implementation of WebIQ where a single variable for every message item is used.
Alarm IDs starts at 1000. This ensures a correct numeric sort in the alphabetically sorted Localization Manager list of WebIQ. This section shows the steps how to create a new error.

• PLC: In EN_APP_ALARM add a new error enumeration item
  e.g. APE_APP_NO_RECIPE_LOADED := 1019
• PLC: To raise the error call method Tools.mAlarmSet().
  Beside the error enum you can provide 3 optional strings, which are displayed in HMI.

          IF (stRecipeMgr.strName = '')  THEN
                   mAlarmSet(enAppError:=APE_APP_NO_RECIPE_LOADED, '','','')
         END_IF

• WebIQ: In Localization Manager create variable alm1019 if not exists and enter the alarm text for all languages.

9.2  Customer Base

9.2.1 Recipe Parameter table configuration

The package cxVisuals, contains the widget cx-table, which is used to display and edit the Recipe parameters. This table is completely controlled by FB_RecipeParameters which extends FB_TableMgr. The features are:

• Display/edit any PLC structure array variables
• Filter/Sort/Clear table columns
• Copy/Paste table rows
• Format table cells via JS functions defined in WebIQ (e.g. 1 => 001)
• Text lists for display and edit of numeric variables

The FB provides a manager for arbitrary PLC array of structures. To use the FB for a specific structure, the following must be observed:

• Methods in folder Adapt must be implemented to fit used array of structure
• See description & source code of the methods for usage and examples
• mDefineVars() Define table columns to display with title, alignment, editable,…

• mClearAllRows() Overwrite all struct array elements with default values defined here

9.2.2 Debug> Debug Funcs

On this page some debug information’s are displayed. Especially the table feature is used to display and edit any PLC variable. All base variable types are supported.

• To add a new variable, enter it in FB_DebugVarsMgr.mDefineVars()
• Text lists are defined in FB_DebugVarsMgr.mDefineTextList()
• That is all, nothing to do in WebIQ.

9.2.3  Example Application

Example application of Agitator tank is integrated in the Template.  mAutoPlc() method consists of sequence of the Agitator application, which is called when Auto mode is active.