Quick Start

The following section shows how to quick start a Cryo HMI Application project based on the template project.

Warning

This manual assumes that the user has already knowledge of TE2000

Prerequisites

Installed software:

TwinCAT XAE 3.1.4024.n, where n > 25. The same as IFW.
TwinCAT 3 HMI Engineering | TE2000: 1.12.760.59.
The ESO cryo framework (version 1.0.1, NuGet package)
The ESO cryo PLC library (version 0.0.2.12)
The ESO cryo PLC HMI gateway library (version 0.0.0.1)

The TcHmiTemplate is a Beckhoff TwinCAT TE2000 project. It was developed using TE2000 version 1.12.760.59. It is highly recommended to use this version to open up the project to minimize compability issues. If this particular version is not available for download from Beckhoff’s website, then the local Beckhoff support can provide the correct version.

The ESO Cryo Framework is a NuGet package. Your development environment needs to be able to find it, which it can do through the “TwinCAT HMI Customer” package source, which by default is C:\TwinCAT\Functions\TE2000-HMI-Engineering\References. The ESO cryo framework nuget package (CryoFramework.1.0.1.nupkg) needs to be copied to this folder.

All other NuGet dependencies that the TcHmiTemplate needs are available through the NuGet.org package source. The packages that are used and not pre-installed by default for TE2000 are:

As both packages are public packages available through the NuGet.org package source, they can be automatically installed and no manual installation is necessary.

Guidelines

Updates to TcHmiTemplate

It can be safely assumed that there will be changes done to the TcHmiTemplate over the lifespan of the project. One limitation of the TwinCAT HMI (as of now, this will change in a future version of the TwinCAT HMI), is that it’s not possible to package the user controls (*.usercontrol) as NuGet packages.

This is different with framework controls as these can be packaged (and versioned) using the conventional NuGet package management, which makes upgrades of the controls easier. This means that any new updates of user controls have to be manually managed.

If the parameters of an user control have been changed (either by new parameters being added, or by existing parameters data definition being updated), the user controls would have to be manually copied over to the users HMI project. If a change in the HMI gateway function block is made and the equivalent user control is changed, it’s important to make sure that the mapping is refreshed in the HMI project.

For example, if a data field is added to a gateway HMI function block, it will mean that the ADS definition for that function block will be different than what is currently defined in the project. This will have an impact on the user control, whose parameters will change. As such, if a change of this type is made, it’s necessary to refresh the mappings of all HMI gateway function blocks, which is accessible through TwinCAT HMI → Windows → TwinCAT HMI Configuration → Server Symbols → Mapped Symbols.

Right-click on all the mismatched mappings (visible through a yellow exclamation mark on the symbol) and select Refresh Mapping.

Important

To facilitate upgrades between different versions of the TcHmiTemplate project, ESO will make sure to include release notes between the different releases of the TcHmiTemplate so that it’s clear what changes have been made to it.

Naming conventions

As every instance of every control’s identity is global in the TwinCAT HMI project namespace, it’s important to give unique names to every object created in the TwinCAT HMI. The general naming convention for all objects in the TwinCAT HMI is:

<ContentName>_<TypeOfControl>_<UniqueName>

For example there is one instance of the PumpUserControl called CryogenicController_PumpUserControl_PVP. In other words, there is an instance of the user control PumpUserControl in the content page CryogenicController having the name PVP.

One example of how it could look like using the document outline:

../_images/UniqueNames.png — Example of several user controls in the CryogenicController content page.

Important

Adhering to these rules will guarantee that every object will not have a name collision with another object (in possibly another completely different content), and it will make sure that every object has a clear and descriptive name (rather than the ambigous auto-generated name by the TwinCAT HMI).

Whitelisting

The TcHmiTemplate project has Whitelisting enabled. With whitelisting, PLC symbols can be explicitly hidden or shown for use in the HMI. This avoids that all the PLC-variables are visible for the TwinCAT HMI, and it also makes it clear in the PLC-code which variables will be displayed in the HMI and which variables will be used to execute a command.

For this to work, the variables that should be whitelisted need to be marked with at least one pragma. There are mainly two pragmas in use in the PLC-code:

{attribute 'TcHmiSymbol.Show'}

This will tell the HMI that the symbol should be accessible to the HMI. Additionaly to this, the following pragma is also used:

{attribute 'TcHmiSymbol.ReadOnly'}

This will tell the HMI that this variable can not be written to, and is a ReadOnly variable. This is useful for cases where we want to indicate a value or status for something that we don’t want the HMI to change, such as an analog value (such as a temperature). This pragma is not be used for variables that require write access, such as variables to command the system to do something (such as going to manual or automatic mode for a control).

Project Setup

Open up the TcHmiTemplate project by opening the file CryoHmiTemplate.sln in the project root. If necessary, rename the application as described in the section Using Template Object.

Start the PLC application so that the TcHmiTemplate project has the associated variables available to it. The default PLC-runtime settings (ADS) for the HMI project is to connect to the local AmsNetId (127.0.0.1.1.1).

Next, either run the live-view (TwinCAT HMI → Windows → TwinCAT HMI Live-View) or by installing a TwinCAT HMI server (TF2000) and publishing the HMI project (TwinCAT HMI → Publish to TwinCAT HMI Server…). The latter is recommended as it will give the full functionality, including user management which is important especially for the function of the maintenance mode.

Using template project

The TcHmiTemplate project can be used either as-is or as an inspiration from where the various user controls, JavaScript and examples can be copied from.

If used as-is, it can be renamed by renaming the solution and the TwinCAT HMI project directly in the TcXaeShell. This is however not enough, as there is still one step that needs to be done manually.

For example, let’s assume both the solution and the TwinCAT HMI-project is renamed like this:

../_images/RenameProject.png — Result after project is renamed.

In the root of the project however, there will still be a folder called CryoHmiTemplate. It will be necessary to rename this appropriately, for example MicadoHmi.

Now it will be necessary to open the *.sln-file (in this case, the MicadoHmi.sln). In there a line like this will exist:

Project("{FE7A1B72-C5B7-4D7C-BB7D-76384D4DE8E1}") = "MicadoHmi", "CryoHmiTemplate\MicadoHmi.hmiproj", "{4CD6F035-8A9F-42E8-9D15-1C7F369338F5}"

The CryoHmiTemplate\ will have to be replaced with MicadoHmi\ or whatever the name of the folder is.

If used as inspiration, special care has to be taken to make sure all the data definitions and mappings are also properly created. When linking a variable from the PLC to the HMI, the TwinCAT HMI creates a mapping between the PLC-variable and a local name. Simply copying all objects (such as contents) with their various event listeners will not automatically create these mappings, and they have to be created manually.