Template Project

TcHmiTemplate allows for rapid development, it already provides to the user:

1. HMI Base Application: An HMI solutions already implemented.

2. Reusable Elements: The project comes bundled with a set of UserControls that can be used, copied and/or extended.

HMI Base Application

TcHmiTemplate consists of the usual elements that every TE2000 project has (Server settings, references, themes etc) and additionaly custom content.

The custom content included is:

• HMI Layout default.

• Navigation Header that can be extended.

• Views for different screen resolutions.

• Maintenance Mode configuration.

• Reusable Elements as UserControls.

HMI Layout

The standard layout for the HMI application, it is divided into three main parts:

• Navigation Bar: Provides the element for navigating the different contents of the system, and additionally a possibility to logout the current user. It’s described in more detail at the Navigation Bar Section

• Main Content: Main display area with the most screen estate, in where the content will change depending on which navigation button is pressed.

• Status Bar: Presents the current date/time, the currently logged-in user and the latest created event.

Main layout concept for the HMI Base Application.

Navigation

The main navigation content is the Pages/Header.content. It consists of several UserControls/NavigationButton.usercontrol. To create a new page for content, first create the page (content) itself. Next add a NavigationButton to the Header. The NavigationButton has three parameters:

1. Identity. This uniquely identifies a specific page that should be displayed when that navigation element is selected. It is defined as a data types under Project/PageIdentity (available under TwinCAT HMI Configuration → Data types). This data type is used in an internal symbol named SelectedPageIdentity in the project.

2. Label. This is the text label for the button. Add a text to the localization and use that here.

3. Icon. This is the graphical symbol in the navigation element. This is a themed resource (avaiable under TwinCAT HMI Configuration → Themes Resources), using two different icons, one black and one white, so that it works for both the light and dark theme.

Once the navigation element has been added, it’s necessary to add the logic for switching the page when the navigation button has been pressed. This is done in the ControlCabinet.view and ControlRoom.view. In each one of them, there is a event-listener on SelectedPageIdentity that switches the content of the main region to the correct content. Add your page to this event listener and make sure to do this for both views.

Views

It’s assumed that the HMI will be running on primarily two different types of operator panels.

1. In the control cabinet

2. In a control room

The first one is assumed to be a small low-resolution display (around 15 inches, 1024x768 resolution) mounted in or close to the electrical cabinet hosting the PLC. The second one would be something in a control room where there is more space, and therefore the display will most likely be larger and thus also the resolution. To have the flexibility to develop for both, the TcHmiTemplate provides two views for this purpose.

1. ControlCabinet.view

2. ControlRoom.view

The ControlCabinet view has been optimized for a resolution of 1024x768, while the ControlRoom view can be used for anything higher than that. Even though the ControlCabinet view is optimized for a resolution of 1024x768, it can be used for higher resolutions as well. In this case, the HMI will simply be scaled to fit the screen. The disadvantage of this is that it’s not an optimal way to use the screen estate on a high resolution display.

Using the ControlRoom view gives the option to maximize the usage of the available screen estate which can be shown in this example.

ControlCabinet View, showing the system events

ControlRoom View, showing the system events

As can be seen, the ControlRoom view has much more space for the navigation elements (at the top), the main content (in this case the events) and more space for the status bar (at the bottom).

The different views can be accessed from the client browser through adding ?View=<ViewName> to the URL, in other words like this:

• https://127.0.0.1:1020/?View=ControlCabinet

• https://127.0.0.1:1020/?View=ControlRoom

The advantage of this is that for the commisioned system it’s possible to make a shortcut to the web browser that will autostart during boot of that system and include the correct view for that system. So for example, assuming we would use Chrome (or better yet, the ungoogled chromium browser) and we wanted to create a shortcut that autostarted when TwinCAT boots at full screen we could achieve this by creating this shortcut:

chrome.exe --kiosk https://localhost:1020?View=ControlCabinet --incognito --disable-pinch --overscroll-historynavigation=0

This would fire up Chromium in so-called kiosk-mode (full-screen, not possible to minimize or close) and using the ControlCabinet view. If we wanted to create another shortcut for other system (i.e. for the control room of the telescope) we would simply replace the ControlCabinet with ControlRoom.

Maintenance mode

If an operator at the instrument logs in into the system, we want to be sure that no-one else can remotely control the instrument at the same time. As the TwinCAT HMI is based on web technology, it is technically possible to have both a local operator and remote operator logged in into and controlling the system at the same time. To solve this problem, the concept of a maintenance user was created. The maintenance user should only be used at the instrument platform.

The idea is simple; when a maintenance user logs in, everyone else that is not a maintenance user will get a popup that fills the whole screen:

When in Maintenance Mode any other user gets this popup.

This will cover the whole screen and it’s not possible to click or interact with any other elements in the HMI. The only thing that any other user can do is to click/press on the Logout button or wait for the Maintenance user to logout (which if it happens, would make the popup go away automatically).

This functionality is implemented in the following way:

1. An user with name “Maintenance” was added to the Users in the TwinCAT HMI configuration.

2. A boolean variable was added in the PLC program MAIN.bMaintenanceUserLoggedIn.

3. A global event in the TwinCAT HMI was added that fires of when the HMI is initialized. This consists of a small JavaScript that sets the PLC-variable to TRUE if the user that has logged in is the Maintenance user.

4. A piece of JavaScript is added on the .onPressed-event of the Logout button that sets the PLC-variable to FALSE if the user that logs out is the Maintenance user.

5. An user control InMaintenanceModePopupUserControl.usercontrol was created which is the popup that shows up on every user that is not maintenance (if maintenance user is logged in).

6. An instance of this user control is created in both the ControlCabinet and ControlRoom views, and an event listener is added on them to show the popup if the PLC-variable is set to true (but only if the user is not the maintenance user).

Reusable Elements

TcHmiTemplate provides a set of content made to be used as TcHmi UserControls. They are developed with direct compatibility with the PLC devices. The user controls consist of two categories.

1. Controls

2. Faceplates

Controls

The controls are wrappers around some of the controls of the CryoHmiFramework (NuGet package). They’re implemented as user controls (.usercontrol) in the HMI Project. They provide access to the functionality of the framework controls by directly linking them to a PLC variable using the HMI gateway function blocks, which are part of the cryohmi library. When the user control is linked to a PLC-variable, it gets all the information it needs to display correctly.

For example, if an instance of the PumpUserControl is created in the HMI, with the unique identity CryogenicController_PumpUserControl_PVP, it’s necessary to link it a PLC-variable on the PLC. In the example below, an instance of the FB_HMI_CRYO_PUMP (available in the cryohmi library) named hmi_pump_pvp has been created in the path MAIN.pds_cryo_ctrl.

Representation of PumpUserControl instance CryogenicController_PumpUserControl_PVP binding with the PLC device of type FB_HMI_CRYO_PUMP.

The parameter PumpHmiObject of the PumpUserControl is to be linked to the PLC-variable (through the usual mapping in TwinCAT HMI).

On top of requiring an PLC-variable to be set as parameter, every user control has a few other parameters that can be changed which are related to how the user control should be shown. This could for example be direction and stroke thickness of the symbol.

To use a control, simply drag and drop one of the user controls (for example PumpUserControl or ValveUserControl) into a content and set the parameters for it.

PumpUserControl

Pump user control with all interfaces needed to be connected to an instance of the FB_HMI_CRYO_PUMP function block in the HMI gateway library.

PumpUserControl Interface Table

Parameter	Description
PumpHmiObject	To be linked to an instance of the FB_HMI_CRYO_PUMP function block in the PLC project.
SymbolType	See table “Pump interface Table” in document “Cryo HMI Framework Controls”.
Direction	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
SymbolMarginSize	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
StrokeThickness	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.

StirlingCoolerUserControl

Stirling cooler user control with all interfaces needed to be connected to an instance of the FB_HMI_CRYO_COOLER function block in the HMI gateway library.

StirlingCoolerUserControl Interface Table

Parameter	Description
StirlingCoolerHmiObject	To be linked to an instance of the FB_HMI_CRYO_COOLER function block in the PLC project.
Direction	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
SymbolMarginSize	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
StrokeThickness	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.

ValveUserControl

Valve user control with all interfaces needed to be connected to an instance of the FB_HMI_CRYO_VALVE function block in the HMI gateway library.

ValveUserControl Interface Table

Parameter	Description
ValveHmiObject	To be linked to an instance of the FB_HMI_CRYO_VALVE function block in the PLC project.
SymbolType	See table “Valve interface Table” in document “Cryo HMI Framework Controls”.
Direction	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
SymbolMarginSize	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
StrokeThickness	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
ShowFeedback	See table “Valve interface Table” in document “Cryo HMI Framework Controls”

AnalogSensorUserControl

This is a wrapper for the Analog Sensor framework control.

AnalogSensorUserControl Interface Table

Parameter	Description
Value	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
DataValid	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
Simulated	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
Notation	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
Decimals	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
Signed	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
Unit	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.
UnitTextboxWidth	See table “Analog Sensor Control Interface Table” in document “Cryo HMI Framework Controls”.

HeaterUserControl

This is a wrapper for the Heater framework control.

HeaterUserControl Interface Table

Parameter	Description
Value	See table “Heater interface Table” in document “Cryo HMI Framework Controls”.
Direction	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
SymbolMarginSize	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
StrokeThickness	See table “Common Controls Interface Table” in document “Cryo HMI Framework Controls”.
TextFontSize	See table “Heater interface Table” in document “Cryo HMI Framework Controls”.

Faceplates

Faceplates are user controls to show certain information related to a function. There are two kinds of faceplates:

1. Control faceplates

2. Sequence faceplates

Control faceplates

The control faceplates are small popups that are shown when the user presses a control (such as a pump or a valve). They provide additional information about a certain control and additionaly provide some control functionality (such as ON/OFF, Engineering Mode ON/OFF). They’re implemented as user controls (.usercontrol) in the TwinCAT HMI.

The basic layout of a faceplate looks as follows:

Faceplate example of a device named PVP. Currently on Tab Operate

Every faceplate has three tabs:

1. Operate

2. Messages

3. Service

The Operate Tab is used to see the overall status of the device and a possibility to operate it. From here it’s possible to control the device manually and see the current actuation status. It’s also possible to switch the mode between automatic and manual for the device. The small square in the upper left corner of the On and Off indicate what the setpoint for the automatic control is. In the screenshot above, the automatic mode wants the pump to be off as the small square inside the Off button is green. The Confirm button is used to confirm all alarms and warnings. Note that this will only confirm the associated events in the event logger, and not clear them. Clearing can only be done automatically (given that the conditions for clearing them are met).

Faceplate example of a device named PVP. Currently on Tab Messages

The Messages Tab is used to control what events for the device associated with the faceplate should be displayed in the event tab. By clicking on the Active Alarms button, the event page will be shown and only all events associated to that device that are not cleared (and thus active) will be displayed. Clicking the All Messages button will show all messages related to this device, including the ones that are cleared. Clicking the Reset button will show all events in the event logger, in other words it will display all events and not just the ones related to this device.

Faceplate example of a device named PVP. Currently on Tab Service

The Service Tab is used to enter and exit engineering mode. Note that it’s only possible to enter engineering mode if the device is in manual mode. Upon entering engineering mode, an orange frame will indicate that the device is in engineering mode.

Faceplate example of a device named PVP. The orange colored border signals that Engineering Mode is activated

Note that this orange frame is not only visible in this tab but across the whole faceplate.

Faceplate example of a device named PVP. The orange colored border signals that Engineering Mode is activated

In the very same way as for the controls, a faceplate requires an equivalent function block in the HMI to be linked to. For every user control that can be interacted with (such as pump, valve, cooler, …) there is an equivalent faceplate user control.

To use a faceplate user control, it needs a context in where the contents of the user control should be shown. This is achieved by displaying it in a popup, which is realized using the JB.TcHmiDynamicPopup. The dynamic popup is instantiated when the user clicks on the user control, more precisely the .onPressed()-event. Here it’s necessary to create an instance of the DynamicPopup by drag-and-dropping the function CreatePopup() from the DynamicPopup category amongst the JavaScript functions.

Pop-Up configuration of onPressed()-event.

What fields/parameters that are necessary to enter to create a popup is documented in the official documentation for the TcHmiDynamicPopup, however we will clarify some things for the targetFile-parameter. When clicking on the three dots ... for the targetFile, it’s necessary to fill in the faceplate that you want to be displayed and some additional parameters.

targetFiles-parameter editing.

The PumpObject parameter is an instance of the HMI gateway function block (in this case, an instance of the FB_HMI_CRYO_PUMP). The EventGrid parameter refers to the (only) instance of the EventGrid control in your application. In the template, this is simply called Events_TcHmiEventGrid. The drop-down menu should only show one of them and this is the one that needs to be selected. The reason this is necessary to provide is because the faceplates provide a filtering possibility for events, and thus need a handle to the event grid. The EventPageIdentity parameter is the value of the PageIdentity internal symbol representing the page for events. This is necessary to have as using the event filters in the face plate will automatically open up the page of the events.

CoolerFacePlate

This is a faceplate for the stirling cooler user control.

CoolerFacePlate Interface Table

Parameter	Description
CoolerObject	Linked to an instance of the HMI gateway function block FB_HMI_CRYO_COOLER.
EventGrid	The reference to the instance of the EventGrid control in the application
EventPageIdentity	The value of the PageIdentity internal symbol representing the page for events

PumpFacePlate

This is a faceplate for the pump user control.

PumpFacePlate Interface Table

Parameter	Description
PumpObject	Linked to an instance of the HMI gateway function block FB_HMI_CRYO_PUMP.
EventGrid	The reference to the instance of the EventGrid control in the application.
EventPageIdentity	The value of the PageIdentity internal symbol representing the page for events

ValveFacePlate

This is a faceplate for the valve user control.

ValveFacePlate Interface Table

Parameter	Description
ValveObject	Linked to an instance of the HMI gateway function block FB_HMI_CRYO_VALVE
EventGrid	The reference to the instance of the EventGrid control in the application.
EventPageIdentity	The value of the PageIdentity internal symbol representing the page for events

Sequence faceplates

The sequence faceplate is used to give basic control of a sequence. It’s implemented as an user control and can be dragged and dropped into any content.

The SequenceFaceplate.usercontrol

When pressing the start or stop-button, the following is overlayed.

Example: Confirm start of evacuation sequence

Only after pressing OK is the start/stop command executed. Pressing CANCEL will mean the start/stop command is not executed, and the faceplate is presented again. The purpose of this overlay is so that the operator doesn’t accidentally stop/start a sequence but has to confirm the action first.

The user control consists of the following elements:

1. The title. The title of the faceplate. Should describe what the sequence does.

2. The status. Shows the current status of the sequence. This is a longer textual description of what the sequence is currently doing.

3. Start & Stop buttons. Allows the operator to start or stop the sequence.

4. Permit Start & Stop indicators. Shows whether it’s possible to start or stop a sequence.

5. Detailed sequence information. Pressing this button will show a flowchart of the sequence.

When creating an instance of the sequence faceplate, the following parameters are available:

SequenceFaceplate Interface Table

Parameter	Description
Title	The title in the faceplate. Represents (1) in the figure above.
SequenceStateText	The string that represents (2) in the figure above. Linked to a string variable.
StartStopSequence	The boolean variable to toggle the start/enable (true) or stop/disable (false) of the sequence.
SequencePageIdentity	The value of the PageIdentity internal symbol representing the page for the sequence.
ShowSequenceButton	Set to true if sequence button should be visible, otherwise set to false. Useful for example if you want to be able to show the sequence faceplate on the actual sequence page (like for example the EvacuateSequence.content) for controlling the sequence (stop/start) but don’t want that the sequence button to be visible.

For the button (5) to work in the figure above, it’s necessary to:

1. Create a separate content-page where the detailed sequence will be shown.

2. Add that page as a value in the PageIdentity data type (available under TwinCAT HMI Configuration → Data types).

3. Set the parameter SequencePageIdentity of the instance of the SequenceFaceplate.usercontrol to the new value created in the previous step.

4. Open up the ControlCabinet.view, locate the TcHmiRegion with identity ControlCabinet_TcHmiRegion_Main, go to the custom event listener SelectedPageIdentity and add the new content to the switch-case. If the ControlRoom.view is used, do the same for it.

By doing these steps, the button (5) will display the new content-page when it’s pressed.

Sequence

The details of how sequences work are described in the chapter Sequences of the Cryo HMI framework documentation. This chapter will focus on the usage of the sequences in the actual HMI application.

When using the sequence faceplate, for the button (5) to work in the figure above it’s necessary to create a separate content page where the detailed sequence will be displayed in. The EvacuateSequence.content is the example for this in the TcHmiTemplate project. This is a standard TwinCAT HMI content page. To get a fully working sequence, it’s necessary to add the following to the content:

1. An instance of TcHmi.Controls.CryoFramework.SequenceContainer from the Cryo HMI Framework. The SequenceContainer needs to be linked to the sequence in the PLC through an instance of the T_CRYO_HMI_SEQUENCE_STAT struct, in terms instantiated through creating an instance of the FB_CRYO_HMI_SEQUENCE function block.

2. A combination of TcHmi.Controls.CryoFramework.Process, TcHmi.Controls.CryoFramework.Decision and TcHmi.Controls.CryoFramework.Terminator to define the sequence. These have to be put inside the SequenceContainer, and assigned an unique BlockId (parameter State → BlockId) representing their location in the array arSequence located in T_CRYO_HMI_SEQUENCE_STAT. Make sure all elements are located in the SequenceContainer by using the document outline (TwinCAT HMI → Windows → TwinCAT HMI Document Outline) and checking that all elements are sub-nodes under the SequenceContainer.

TwinCAT HMI document outline: Sequence Container

The SequenceContainer example in the TcHmiExample project is linked to an instance of T_CRYO_HMI_SEQUENCE_STAT with the symbolic name PLC1.MAIN.pds_cryo_ctrl.evac.hmi_sequence.stat:

TwinCAT HMI document outline: Sequence Container linking

Every Process, Decision and Terminator has to have an unique BlockId number, equivalent to the number that is used to define that particular step in the sequence in the PLC-code.

Sequence Container Node: BlockId linking