NetLogic is C# code that is linked to Optix. Optix can call methods with parameters, set private C# variables, and has numerous C# Libraries integrated by default to assist with passing data between Optix and your C# code. Optix also allows you to link the monitoring of C# code to an Optix runtime instance.

Linking Variables

When creating NetLogic, you can define variables that interface with the C# code, and can be both written to and read from said C# code. You can also define variable categories to assist with organization.

• First, Variables are added onto the NetLogic object in Optix.

An example of variables attached to a NetLogic object

These variables can be referenced in the C# logic by utilizing the “GetVariable” method on our LogicObject.

• For any variables at the top-most level, simply call: LogicObject.GetVariable(“YourVariable”).
• For nested variables (such as variables under “Table” in the example above), define a new IUAVariable for the nested name (Tables in this case), and then reference the individual elements of that new variable.

private void ParametersSetup()

{
	DB_SERVER_IP = LogicObject.GetVariable("Server IP").Value;
	DB_SERVER_PORT = uint.Parse(LogicObject.GetVariable("Server port").Value);
	SERVICE_NAME = LogicObject.GetVariable("Service name").Value;
	DB_USERNAME = LogicObject.GetVariable("Username").Value;
	DB_PASSWORD = LogicObject.GetVariable("Password").Value;
	DB_QUERIES_FEEDBACK = LogicObject.GetVariable("Queries feedback");
	TABLES = LogicObject.GetVariable("Tables");

	TABLE_DESTINATION = TABLES.GetVariable("Destination").Value;
	TABLE_DISTANCE = TABLES.GetVariable("Distance").Value;
	TABLE_LOCATIONCHANGE = TABLES.GetVariable("LocationChange").Value;
	TABLE_EQUIPMENTSTATUS = TABLES.GetVariable("EquipmentStatus").Value;
	NUMBER_OF_DEVICES = LogicObject.GetVariable("Number of devices").Value;
	NUMBER_OF_EQUIPMENT_AREAS = LogicObject.GetVariable("Number of equipment areas").Value;
	CONNECTIONSTRING = $"Data Source=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST={DB_SERVER_IP})(PORT={(int)DB_SERVER_PORT})))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME={SERVICE_NAME})));User Id={DB_USERNAME};Password={DB_PASSWORD};";
}

private void ParametersSetup()

{
	DB_SERVER_IP = LogicObject.GetVariable("Server IP").Value;
	DB_SERVER_PORT = uint.Parse(LogicObject.GetVariable("Server port").Value);
	SERVICE_NAME = LogicObject.GetVariable("Service name").Value;
	DB_USERNAME = LogicObject.GetVariable("Username").Value;
	DB_PASSWORD = LogicObject.GetVariable("Password").Value;
	DB_QUERIES_FEEDBACK = LogicObject.GetVariable("Queries feedback");
	TABLES = LogicObject.GetVariable("Tables");

	TABLE_DESTINATION = TABLES.GetVariable("Destination").Value;
	TABLE_DISTANCE = TABLES.GetVariable("Distance").Value;
	TABLE_LOCATIONCHANGE = TABLES.GetVariable("LocationChange").Value;
	TABLE_EQUIPMENTSTATUS = TABLES.GetVariable("EquipmentStatus").Value;
	NUMBER_OF_DEVICES = LogicObject.GetVariable("Number of devices").Value;
	NUMBER_OF_EQUIPMENT_AREAS = LogicObject.GetVariable("Number of equipment areas").Value;
	CONNECTIONSTRING = $"Data Source=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST={DB_SERVER_IP})(PORT={(int)DB_SERVER_PORT})))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME={SERVICE_NAME})));User Id={DB_USERNAME};Password={DB_PASSWORD};";
}

private IUAVariable DB_QUERIES_FEEDBACK;
private string DB_SERVER_IP;
private uint DB_SERVER_PORT;
private string SERVICE_NAME;
private string DB_USERNAME;
private string DB_PASSWORD;
public IUAVariable TABLES;
private string TABLE_DESTINATION;
private string TABLE_DISTANCE;
private string TABLE_LOCATIONCHANGE;
private string TABLE_EQUIPMENTSTATUS;
private Int32 NUMBER_OF_DEVICES;
private Int32 NUMBER_OF_EQUIPMENT_AREAS;

private IUAVariable DB_QUERIES_FEEDBACK;
private string DB_SERVER_IP;
private uint DB_SERVER_PORT;
private string SERVICE_NAME;
private string DB_USERNAME;
private string DB_PASSWORD;
public IUAVariable TABLES;
private string TABLE_DESTINATION;
private string TABLE_DISTANCE;
private string TABLE_LOCATIONCHANGE;
private string TABLE_EQUIPMENTSTATUS;
private Int32 NUMBER_OF_DEVICES;
private Int32 NUMBER_OF_EQUIPMENT_AREAS;

Calling Methods

C# Methods can be called directly from Optix when the [ExportMethod] Line is added above said method. Any parameters associated with the Method will also be exposed, allowing you to set them dynamically from Optix, using a MethodInvocation or by linking them to events.

An example method invocation that shows all the [ExportMethod] methods from the Netlogic C# code

[ExportMethod]

public void SelectAllDevicesDestination()

{

…

[ExportMethod]

public void SelectAllDevicesDestination()

{

…

Monitoring Code

When NetLogic is created, Optix automatically configures the codespace (if utilizing VSCode) to attach to the Optix runtime instance, allowing you to monitor your C# card while the Optix application is running.

Visual Code is attached to the Optix Runtime when monitoring

Logging and Error Handling

Optix has a C# library for logging code that should be utilized, as it will output to the console in FT Optix Studio, as well as to the log file for the Optix application.

catch (System.Exception ex)
{
	Log.Error(MethodBase.GetCurrentMethod().Name, ex.Message);
}

catch (System.Exception ex)
{
	Log.Error(MethodBase.GetCurrentMethod().Name, ex.Message);
}

The location of Optix log files for an emulated project

Read the Other Articles in this Series

• FactoryTalk Optix Series 1 – Getting Started with FactoryTalk Optix
• FactoryTalk Optix Series 2 – Variables, Attributes, Dynamic Links, and Converters

The post FactoryTalk Optix Series 3 – NetLogic Overview and Examples appeared first on DMC, Inc..

This blog series covers the essentials to creating your own HMI and SCADA applications using Optix as well as some helpful examples for common applications.

Installation

FactoryTalk Optix Studio is installed via FactoryTalk Hub, and it is the IDE used to program Optix projects. You can either download the IDE application or utilize a web-based IDE if your license supports it.

The Optix Runtime tools are also installed via FactoryTalk Hub, and they are required on any machine that is going to run an Optix application.

FactoryTalk Hub: which hosts a number of FT applications (including FactoryTalk Design Studio for Optix)

Licensing and Pricing

Optix licensing is done on a token-based system, with more features requiring more tokens, and, therefore, a larger license. Generally speaking, the largest contributors to token usage are multiple concurrent web clients, OPC-UA connections, or database connections.

Examples of features that affect the sizing of your application include the following:

• Controller connections
• Multiple web clients
• Alarming
• Recipes
• PDF reports
• Data logging
• Database connectivity
• OPC UA connectivity

For more information on tokens and licensing, please see Rockwell’s documentation.

Presentation Engines

Presentation engines are responsible for rendering and displaying UI elements during runtime. There are two available presentation engines that can be used simultaneously – the native presentation engine and the web presentation engine.

The native presentation engine launches the project in its own window as an application.

The web presentation engine hosts the application on a web server, accessible via the defined web page. Multiple concurrent web clients can access the application (if multiple connections are defined in the web presentation engine), but more concurrent clients require more tokens.

Optix can make use of session-specific tools to allow concurrent clients to have different screens/panels open, have different users logged in, and display different information, provided that the Optix project was designed with multiple clients in mind.

An example configured Web Presentation Engine

Style Sheets

Style sheets allow the definition of default colors, shapes, sizes, and other UI element configurations. A project’s style sheet can be swapped during runtime. Some properties can be defined both in the style sheet and in an individual UI element. In the case that a property is explicitly defined for an individual element, it will override the style sheet.

An example Style Sheet

Screens and Panels

FT Optix uses screens, panels, and popups as the main methods for displaying UI elements. Screens and popups can both contain multiple panel loaders, which can be used to dynamically change displayed content when a defined action is performed, such as hitting a button.

To see panel loaders being implemented to create a dynamic device sidebar that changes what device it controls (and the associated UI elements) at the push of a button, stay tuned for our upcoming FactoryTalk Optix – Dynamic Device Faceplate blog post.

A panel loader that is a part of the main overlay of an application. It has the ability to load either a Motor or a GroundRack panel into the panel loader.

A runtime instance with the “Motor” panel loaded into the panel loader

A runtime instance with the “Ground Rack” panel loaded into the panel loader

Converters

Converters allow you to modify variables dynamically based on other variables. For instance, a key-value converter could change the text displayed in a string variable when a different integer variable’s value changes, and an engineering unit converter can be used to scale variable values differently.

There are more converter types and use cases that were not mentioned above. For more information on converters, stay tuned for our upcoming FactoryTalk Optix – Variables, Attributes, Dynamic Links, and Converters blog post.

A Key-Value converter that parses an integer out into valve status strings

Dynamic Links

Dynamic links are used to define relationships between two or more variables or attributes within the FT Optix project. Complex dynamic links allow the use of built-in converters, allowing further customization of UI elements.

For further information on Property Bindings, stay tuned for our upcoming FactoryTalk Optix – Variables, Attributes, Dynamic Links, and Converters blog post.

For an example of leveraging complex dynamic links, stay tuned for our upcoming FactoryTalk Optix – Dynamic Device Faceplate blog post.

A dynamic link that performs mathematical operations on several variables to return an adjusted distance

Events

Events call methods when a specific trigger happens, such as a button being pressed or a variable’s value changing. Events can be added onto most UI elements, and they can trigger multiple methods.

Methods

Methods are called by events. FT Optix has a number of built-in methods, but custom methods can be defined through NetLogic as well.

You can also create pre-defined method invocations, which allow the calling of methods with pre-defined parameters.

A list of common methods available in FT Optix

A custom method invocation for renaming a MySQL Database table

NetLogic

NetLogic allows C# code to be integrated and run in an FT Optix project. FT Optix can call parameterized methods, and they can send and receive variables with the C# project.

For further information on NetLogic, stay tuned for our upcoming FactoryTalk Optix – NetLogic Overview and Examples blog post.

An example NetLogic snippet that returns a localized time

Data Stores

Data stores are databases used to store values from different loggers and NetLogic (if you so choose). You can either use an embedded database, which is a simple SQLite database created with minimal overhead, or you can choose to create a connection to a database (SQL Server or MySQL). Other database types may be supported through ODBC connections, but they have not been tested or confirmed yet.

Loggers can be linked directly to a data store and will automatically configure tables for themselves on said database.

An example data store with an “Alarm Logger” linked to it, auto generating the necessary tables

Communication Drivers

Communication Drivers allow defining communication paths to PLCs and other devices, as well as the importing of tags and other information to be used in the Optix project. A list of the currently available communication drivers is available below.

All available communication drivers in Optix

The tag importer display from an example Rockwell Ethernet Driver linked to a PLC

Template Library

Optix’s Template Library

The template library stores templates created by Rockwell and allows you to create/import your own libraries as well. Some examples of useful templates that are included with Optix are:

• Alarm Grid
• Alam History
• Alarm Banner
• User Login Popup
• Confirmation Dialog
• Date and Time Display
• File Selector
• File System Browser
• Alarm Importer and Exporter
• Alarm Logger

Read the Other Articles in this Series

• FactoryTalk Optix Series 2 – Variables, Attributes, Dynamic Links, and Converters
• FactoryTalk Optix Series 3 – NetLogic Overview and Examples

The post FactoryTalk Optix Series 1 – Getting Started with FactoryTalk Optix appeared first on DMC, Inc..

• Getting started with C++ on a Beckhoff PLC – Part One: Setup

The second part of this series on how to run C++ real-time on a Beckhoff PLC will cover creating the interface that will host the C++ code, creating methods and data types within that interface, and how to access that interface from the structured text code.

The C++ Interface is the same concept as interfaces in structured text programming on Beckhoff PLCs, however the interface is implemented through the C++ TMC file (TwinCAT Module Class Editor) instead of a POU.

The interface will specify method declarations, return types, and the parameters needed, while the C++ file will provide the method definitions.

Table of Contents

1. Creating the C++ Interface
2. Static Link to C++ Module
   • Creating the C++ TcCOM Module
   • Connect the C++ Interface to Structured Text
3. Dynamic Link to C++ Module
4. Tips and Tricks

Creating the C++ Interface

Back to Table of Contents

1. To create the interface, open the .tmc file in the C++ project.

2. In the TMC editor, click Data Types and click “Adds a new interface ()”

3. The interface will contain all the methods that will be made accessible. To add new methods, click the drop-down icon to the left of the interface and select “Methods”. The buttons in the ribbon can create, remove, reorganize, or copy and paste methods.

4. Once a method has been created, double click it to edit its parameters and return type.

Note about custom data types:

a. While the TMC editor allows you to create structs in the module and set the interface method’s return data type to a struct, TwinCAT does not allow structs as a return data type in the structured text / C++ interface. Doing so will cause a Structured return value not allowed in external function calls error.

b. Additionally, structs cannot be used as parameters in method calls either. This will cause a Structured value types not allowed in external function calls error.

c. Because of this limitation, to return multiple values from a method, it is recommended to use pointers or references to your desired return value as parameters of the method. TwinCAT will pass these values by reference.

5. When editing Method Parameters, TwinCAT allows you to specify parameters as pointers, pointer to pointers, or a reference.

6. Add all methods with return types and parameters to the interface.

7. Once all methods are added, add the new interface to the TMC’s Implemented Interfaces section. This specifies that we are implementing the code for the interface within the C++ module. The interface created should appear in the list next to “(local)”.

8. Click the “Run TMC Code Generator” button and TwinCAT will automatically create function definitions and declarations in the .cpp file. The “Fun TMC Code Generator” can be run by clicking the button.

a. The TMC Code Generator must be run any time you make changes to the TMC file (editing method parameters, return types, and adding new methods, etc.).

b. If a previously generated method’s parameters or return type were edited, TwinCAT will move the program to the bottom of the .cpp file under an <AutoGeneratedContent id=”Obsolete_ImplementationOf_IInterface1″> tag, and provide an empty function implementation. You can copy the previous code and make any edits as necessary.

9. Add the C++ code into the function definitions.

10. Once all functions are added, compile the C++ code into a TMX file by right clicking the C++ Project and selecting “Publish Modules”. The Build Output of Visual Studio will show if the C++ project compiled successfully.

After creating the C++ interface, it must be linked to the structured text by creating a proxy function block. The structured text function block will host an interface pointer to the C++ memory which will expose the methods defined in the TMC file and allow the function block to call the C++ functions.

This can be done by creating a TcCOM object that is linked to a structured text FB (Section B) or can be dynamically created from within the structured text. (Section C).

Static Link to C++ Module

Back to Table of Contents

The static link will create individual proxy function blocks for each instance of the C++ module. This is done by creating TcCOM modules for each instance desired. All instances must be created before runtime and cannot be created/deleted during runtime. 

Creating the C++ TcCOM Module

1. After compiling the code, a C++ Module instance must be created. This can be added in the C++ project, or under System/TcCOM Objects.
   • In the C++ Project, right click the C++ project and click “Add new Item”. In the Insert TcCom Object popup, it will search the local project for the module’s TMC file. Select the module created and click OK.
   • If adding under System/TcCOM, TwinCAT will search your development PC (not the target PC) for the TMC file. Search for the module and verify that the file path is correct, then click OK.

2. Double-click the Module Instance and select “Interfaces”. You should see your created interface in the list. This verifies that you have created your C++ interface and instance correctly.

3. The TcCOM allows a system task to be assigned to the module in the “Context” tab; however, that is only necessary if you have cyclic code. If you are only providing interface methods, it is not required.

Connect the C++ Interface to Structured Text

Once a TcCOM module has been created for the C++ code, it must be linked to a structured text function block through an interface pointer. The function FW_ObjMgr_GetObjectInstance can be used to create an interface pointer to an object instance upon function block initialization: FB_Init().

Upon function block deletion, FB_Exit() is called which runs FW_SafeRelease which releases the interface pointer memory. Note: this does not delete the C++ memory and any internal variables will be stored.

1. Create a PLC Project if one does not exist.
2. Add a new POU for the C++ Interface.

3. A popup should appear allowing you to input a name for the POU.

4. Add the following vars and methods to the function block in the main FB:

VAR
{attribute 'TcInitSymbol'}
oidInstance : OTCID;
//ipInterface is the name of the interface pointer. You can provide any name.
ipInterface : IInterface1;
hrInit : HRESULT;
END_VAR
}

A. FB_Init() – This code connects the object specified at oidInstance with the interface specified at iid (in step 10) and provides the pointer to the interface in pipUnk.

METHOD FB_init : BOOL
VAR_INPUT
	bInitRetains : BOOL; // if TRUE, the retain variables are initialized (warm start / cold start)
	bInCopyCode : BOOL;  // if TRUE, the instance afterwards gets moved into the copy code (online change)
END_VAR
//Implementation
IF NOT bInCopyCode THEN 
		IF ipInterface1 = 0 THEN
			hrInit := FW_ObjMgr_GetObjectInstance ( oid:=oidInstance,
													iid:=TC_GLOBAL_IID_LIST.IID_IInterface1,
													pipUnk:=ADR(ipInterface1) );
		END_IF
END_IF
}

METHOD FB_init : BOOL
VAR_INPUT
	bInitRetains : BOOL; // if TRUE, the retain variables are initialized (warm start / cold start)
	bInCopyCode : BOOL;  // if TRUE, the instance afterwards gets moved into the copy code (online change)
END_VAR
//Implementation
IF NOT bInCopyCode THEN 
		IF ipInterface1 = 0 THEN
			hrInit := FW_ObjMgr_GetObjectInstance ( oid:=oidInstance,
													iid:=TC_GLOBAL_IID_LIST.IID_IInterface1,
													pipUnk:=ADR(ipInterface1) );
		END_IF
END_IF
}

[endif]-

B. FB_Exit() – This code deletes the interface pointer.

METHOD FB_exit : BOOL
VAR_INPUT
	bInCopyCode : BOOL; // if TRUE, the exit method is called for exiting an instance that is copied afterwards (online change).
END_VAR
//Implementation
IF NOT bInCopyCode THEN
	FW_SafeRelease(ADR(ipInterface1));
END_IF
}

METHOD FB_exit : BOOL
VAR_INPUT
	bInCopyCode : BOOL; // if TRUE, the exit method is called for exiting an instance that is copied afterwards (online change).
END_VAR
//Implementation
IF NOT bInCopyCode THEN
	FW_SafeRelease(ADR(ipInterface1));
END_IF
}

5. The C++ Methods can now be called the interface pointer’s methods. These method calls can be made in the FB’s main implementation or any FB method or action.

IF ipInterface <> 0 THEN
    // ipInterface is the interface pointer.
    getPrivInt := ipInterface.SetPrivInt(5);
END_IF

IF ipInterface <> 0 THEN
    // ipInterface is the interface pointer.
    getPrivInt := ipInterface.SetPrivInt(5);
END_IF

6. Add an instance of the FB to MAIN or any other POUs. Once all methods are added, click "Build" and see if the project compiles successfully. Once built, click the PLC instance and there will be a tab called "Symbol Initialization". Select the oildInstance for the C++ object instance in the drop-down list.

7. Click “Apply to config” to download the structure text and C++ code to the PLC.

Dynamic Link to C++ Module 

Back to Table of Contents

Instead of creating a TcCOM object that is an instance of the C++ code, the structured text function block can also dynamically create the TcCOM module during initialization: FB_Init(), or any method. This can be done using Twincat’s function FW_ObjMgr_CreateAndInitInstance.

Upon function block deletion, FB_Exit() is called which will run FW_ObjMgr_DeleteInstance. 

1. Click the “TcCOM Objects” and select “Class Factories”. This list displays all C++ drivers on the computer. Ensure that the C++ driver you wish to implement has “Load” checked.

2. Create a structured text function block. This function block is what will create the C++ interface instance.

3. Add the Tc2_Utilities library to your project references. This library is needed for the “STRING_TO_GUID” function used in FB_Init().

 a. Under References, right click and select “Add library”.

b. Search “Utilities” at the top and add Tc2_Utilities.

4. Next, get the GUID and Library ID of the interface. This can be done by creating a TcCOM object and copying the GUID and Class ID. (instructions on how to create a TcCOM object can be found in part B).

5. Add the following functions and code to your function block:In FB’s implementation.

a. In FB’s implementation. The <GUID> is the GUID specified in the previous step, and <Library ID> is the text in the parentheses in Class Factory.

FUNCTION_BLOCK FB_CppDynamicLink VAR_OUTPUT   // this does not have to be an array     
ipInterface  : ARRAY [1..5] OF CppInterface;     
numInterfaces : INT := 1; 
END_VAR 
VAR     
  objName : STRING;     
  classId : CLSID := STRING_TO_GUID('<GUID>');     
  sLibraryId  : STRING := '<Class ID>';     
  classIdVersioned : CLSID;     
  iid : IID := TC_GLOBAL_IID_LIST.IID_<InterfaceName>;     
  hrInit  : HRESULT; 
END_VAR

FUNCTION_BLOCK FB_CppDynamicLink VAR_OUTPUT   // this does not have to be an array     
ipInterface  : ARRAY [1..5] OF CppInterface;     
numInterfaces : INT := 1; 
END_VAR 
VAR     
  objName : STRING;     
  classId : CLSID := STRING_TO_GUID('<GUID>');     
  sLibraryId  : STRING := '<Class ID>';     
  classIdVersioned : CLSID;     
  iid : IID := TC_GLOBAL_IID_LIST.IID_<InterfaceName>;     
  hrInit  : HRESULT; 
END_VAR

b. FB_Init() – This code will create C++ instance upon function block’s initialization. This code can also be adapted to create additional instances during runtime.

[Declaration] 
METHOD FB_init : BOOL VAR_INPUT bInitRetains : BOOL; // if TRUE, the retain variables are initialized (warm start / cold start) 
bInCopyCode : BOOL; // if TRUE, the instance afterwards gets moved into the copy code (online change) 
sObjName : STRING; 
eObjState : TCOM_STATE; 
END_VAR [Implementation] 
IF NOT bInCopyCode THEN objName := sObjName; 
  F_GetClassIdVersioned(sLibraryId := sLibraryId, clsId := classId, clsIdVersioned:=classIdVersioned); 
  hrInit := FW_ObjMgr_CreateAndInitInstance( clsId := classIdVersioned, iid := iid, pipUnk := ADR(ipInterface) + SIZEOF(ipInterface[1])*(numInterfaces-1), objId := OTCID_CreateNewId, parentId:= TwinCAT_SystemInfoVarList._AppInfo.ObjId, name := sObjName, state := eObjState, pInitData:= 0); 
END_IF

[Declaration] 
METHOD FB_init : BOOL VAR_INPUT bInitRetains : BOOL; // if TRUE, the retain variables are initialized (warm start / cold start) 
bInCopyCode : BOOL; // if TRUE, the instance afterwards gets moved into the copy code (online change) 
sObjName : STRING; 
eObjState : TCOM_STATE; 
END_VAR [Implementation] 
IF NOT bInCopyCode THEN objName := sObjName; 
  F_GetClassIdVersioned(sLibraryId := sLibraryId, clsId := classId, clsIdVersioned:=classIdVersioned); 
  hrInit := FW_ObjMgr_CreateAndInitInstance( clsId := classIdVersioned, iid := iid, pipUnk := ADR(ipInterface) + SIZEOF(ipInterface[1])*(numInterfaces-1), objId := OTCID_CreateNewId, parentId:= TwinCAT_SystemInfoVarList._AppInfo.ObjId, name := sObjName, state := eObjState, pInitData:= 0); 
END_IF

c. FB_Exit()

[Declaration]
METHOD FB_exit : BOOL
VAR_INPUT
    bInCopyCode : BOOL; // if TRUE, the exit method is called for exiting an instance that is copied afterwards (online change).
END_VAR
VAR
    i : INT;
END_VAR
[Implementation]
IF NOT bInCopyCode THEN
    FOR i := 1 TO 5 DO
        IF ipInterface[i] <> 0 THEN
            FW_ObjMgr_DeleteInstance(ADR(ipInterface) + SIZEOF(ipInterface[1])*(numInterfaces-1));
        END_IF
    END_FOR
END_IF

[Declaration]
METHOD FB_exit : BOOL
VAR_INPUT
    bInCopyCode : BOOL; // if TRUE, the exit method is called for exiting an instance that is copied afterwards (online change).
END_VAR
VAR
    i : INT;
END_VAR
[Implementation]
IF NOT bInCopyCode THEN
    FOR i := 1 TO 5 DO
        IF ipInterface[i] <> 0 THEN
            FW_ObjMgr_DeleteInstance(ADR(ipInterface) + SIZEOF(ipInterface[1])*(numInterfaces-1));
        END_IF
    END_FOR
END_IF

6. Add all function block methods to call the C++ methods as desired. The example at the bottom of the article shows how an internal C++ variable can be modified and accessed from the structured text.

7. Once the proxy function block is made, create an instance of the FB in MAIN or any other program. Any of the proxy function block’s methods can be called from that program. 

Tips and Tricks

Back to Table of Contents

1. While doable in C++ real time code, it may be easier to do any file IO (Reading/Writing from CSV) within the structured text and passing the read data to the C++ through a method call. 
2. TwinCAT had difficulty passing in 2D array pointers from Structured Text to C++. Because of this, I found the best way was to split the 2D array within the structured text into multiple 1D arrays that are passed in, and a Boolean to flag when it is the last row in the 2D array.
3. To debug the C++, Follow these steps:

a. Build the C++ project in Debug instead of Release.

b. In the C++ Node settings, select the Enable C++ Debugger checkbox.

c. Right click your C++ project, go to Debug and click “Start New Instance”.

d. The C++ Debugger should start if you are running the C++ code. Keep in mind that the step controls for the C++ debugger are different from the Structured Text step controls and PLC controls. These are the specific controls for debugging the C++ :

4. Running multiple instances of the C++ Module are allowed and will have separate memory from one another. This can be done by:

a. Creating multiple TcCOM objects and FB instances as described in Section B. Once all new FB instances are made, select the correct OID for each instances in the Symbol Initialization page. (Step 7 of Part B) Note: Both TcCOM objects are C++ project Instances are allowed.

Figure 1: Object 1 and 2 are TcCOM objects, while Untitled3_Obj1 is a C++ Project instance.

b. Creating multiple instances of the dynamic function block as described in Section C. Because the function block dynamically creates the C++ instances, the oidInstances do not need to be set. The sObjName can be modified however, it is not required. Both instances will be unique.

c. A mix of dynamic and static instances.

Learn more about our Beckhoff and TwinCAT 3 programming expertise and contact us for your next project.

The post Getting started with C++ on a Beckhoff PLC – Part 2: Creating the ST/C++ Interface appeared first on DMC, Inc..

This guide will cover how to create the external interface and how to make C++ function calls and algorithms within your PLC program.

Steps

1. Setting up the TwinCAT C++ IDE
2. Creating your C++ and PLC programs.
3. Adding a Test Signature Certificate.

Step 1: Setting up TwinCAT C++ IDE

Back to Steps List

While structured text development on TwinCAT can be done within the TwinCAT XAE Shell, TwinCAT C++ development must be done within Visual Studio 2019 with the TwinCAT extensions installed. If a TwinCAT solution with a C++ project is opened in XAE shell, you will be unable to view or edit the C++ code. TwinCAT integration will support Visual Studio 2022 in build 4026.

If XAE Shell was installed before Visual Studio 2019, XAE shell must be uninstalled before installing Visual Studio, then XAE Shell can be reinstalled with the integration added.

You can follow TwinCAT’s guide on integrating with Visual Studio.

Step 2: Creating the C++ and PLC programs

Back to Steps List

The C++ integration can be added to a new or existing PLC program. Here’s a series of DMC guides on how to set up and connect to a TwinCAT PLC.

To add or create the C++ project: 

1. Under the C++ node of the solution, right click and select “Add New Item…”

2. A popup will appear displaying the different types of TwinCAT C++ Projects.
   1. Select “Versioned C++ Project” to create an interface accessible by structured text.
   2. “Driver projects” are no longer recommended by TwinCAT and have fewer features compared to “Versioned C++ Projects”.
   3. “Static Library Projects” create static libraries that create functions and classes that can be accessed from other C++ projects; however, they cannot create an interface accessible from structured text code.
3. For this external interface, I will select “Versioned C++ Project”.
4. A popup will appear asking what type of Module Class to add a preset configuration.
   1. To create a project that provides functions to call from structured text, select “TwinCAT Module Class for RT Context”. 
   2. The Cyclic Caller, Cyclic IO, and Data Pointer options all create a CyclicUpdate() function that can be attached to a task and have C++ run cyclically. This will run C++ code every scan.

4. Enter a name and click OK.

Step 3: Adding a TwinCAT Test Certificate

Back to Steps List

To run C++ programs on the PLC, a certificate must be added to ensure all C++ code is verified. TwinCAT allows for officially signed certificates, but a test certificate is sufficient for developing and testing code. TwinCAT recommends that all new projects use Versioned C++ projects, which requires the new TwinCAT Certificate. If developing software that uses the older “Driver Project”, then an Operating System certificate is needed instead.

For more information about Driver signing, reference the Beckhoff Information System.

To add a new test certificate for a C++ Versioned Project:

1. In Visual Studio 2019, go to Extensions/TwinCAT/Software Protection. In XAE Shell, go to TwinCAT/Software Protection.

2. In the wizard, click “Create New…” and fill out the OEM name, Unique Name, and select the checkbox for “Sign TwinCAT C++ Executables (.tmx). Click "Yes" on the popup that appears.

4. Click “Start” and save the file in the default location (C:/TwinCAT/3.1/CustomConfig/Certificates/). 
5. Enter a password. 
   1. It is recommended to use the TcSignTool to create the test signature password as TwinCAT will store the password in plaintext in the project file which can be easily shared.
6. Once the certificate has been created, it needs to be added to the C++ project. Right click the C++ Project and click "Properties." Under the “Tc Sign” tab, select "Yes" for TwinCAT signing, and enter the certificate name and password.

8. Because these test certificates are not countersigned by Beckhoff, the target PLC must be put into test mode to run the C++ code. Once the certificates have been countersigned by Beckhoff, your target PLC will not need to be in test mode.
   1. On your Target PLC, open Command Prompt with Administrator privileges.
   2. Run “bcdedit /set testsigning yes” in Command Prompt (Admin).
   3. Restart your computer/PLC.
   4. The Target PLC will now allow test certificate-signed C++ code to run on the PLC.
9. Right click the C++ Project and click “Publish Modules”. It should create an error that says the certificate is not valid or ADS has failed.
10. Open (C:/TwinCAT/3.1/Target/OemCertificates) on the target PLC and locate the file with the same name as the certificate’s “Unique Name”.
11. Double click the file to add the certificate to Window’s certificate registry. The "Publish Modules" button should now work, and the C++ project can build and run on your machine. 

Now that the IDE and test certificate have been configured, the C++ project can be configured with the desired functions and interfaces and linked to a structured text function block, which will be covered in part two of this blog series.

Learn more about our Beckhoff and TwinCAT 3 Programming expertise and contact us for your next project.

The post Getting started with C++ on a Beckhoff PLC – Part One: Setup appeared first on DMC, Inc..

Creating a high-quality user interface that can run on embedded systems is a challenging task, and that’s doubly (or perhaps triply) true if it’s intended for an international user base.

As with any difficult job, however, it becomes much more manageable with the right tools. Read on to learn the basics of one such tool, LVGL, and its associated utilities.

Getting Started with LVGL

In order to develop with LVGL, it will need to be ported to your platform of choice.

First, pull the latest release of LVGL into a project configured for your target and create “lv_conf.h” from the included template. This file contains a variety of parameters for tweaking the library’s behavior, but they can be left at their default values for now. Add a call to lv_init to your program, ensuring it’s in a location where it will occur before any other LVGL functions are called.

Next, you will need to define drivers for the display showing your UI and any input devices used to interact with it. The specifics of these drivers will vary greatly from project to project, and LVGL already has excellent documentation on porting, so only the general structure will be covered here.

In simple cases, you will only need to allocate some memory to act as a draw buffer, define the resolution of the display, and implement a function to send the information LVGL places into the draw buffer to your screen. The example below shows a basic setup, but additional configuration options exist to implement things like double-buffering or screen rotation.

static lv_color_t draw_buffer[SCREEN_HOR_RES * SCREEN_VER_RES / 10];
static lv_disp_drv_t disp_drv;
static lv_disp_draw_buf_t disp_buf;

void flush_buffer_callback(lv_disp_drv_t* disp_drv, const lv_area_t* area, lv_color_t* color_p);

lv_disp_t* lvgl_display_port_init()
{
    //configure any platform specific peripherals here

    //set up draw buffer
    lv_disp_draw_buf_init(&disp_buf, draw_buffer, NULL, SCREEN_HOR_RES * SCREEN_VER_RES / 10);

    //initialize display driver
    lv_disp_drv_init(&disp_drv);

    //configure display driver
    disp_drv.draw_buf = &disp_buf;
    disp_drv.hor_res = SCREEN_HOR_RES;
    disp_drv.ver_res = SCREEN_VER_RES;
    disp_drv.flush_cb = flush_buffer_callback;

    //set optional fields to customize display driver here
   
    //finalize driver setup
    return lv_disp_drv_register(&disp_drv);
}

void flush_buffer_callback(lv_disp_drv_t* disp_drv, const lv_area_t* area, lv_color_t* color_p)
{
    /* copy pixels from 'color_p' to the area of the screen described by 'area' */
}

static lv_color_t draw_buffer[SCREEN_HOR_RES * SCREEN_VER_RES / 10];
static lv_disp_drv_t disp_drv;
static lv_disp_draw_buf_t disp_buf;

void flush_buffer_callback(lv_disp_drv_t* disp_drv, const lv_area_t* area, lv_color_t* color_p);

lv_disp_t* lvgl_display_port_init()
{
    //configure any platform specific peripherals here

    //set up draw buffer
    lv_disp_draw_buf_init(&disp_buf, draw_buffer, NULL, SCREEN_HOR_RES * SCREEN_VER_RES / 10);

    //initialize display driver
    lv_disp_drv_init(&disp_drv);

    //configure display driver
    disp_drv.draw_buf = &disp_buf;
    disp_drv.hor_res = SCREEN_HOR_RES;
    disp_drv.ver_res = SCREEN_VER_RES;
    disp_drv.flush_cb = flush_buffer_callback;

    //set optional fields to customize display driver here
   
    //finalize driver setup
    return lv_disp_drv_register(&disp_drv);
}

void flush_buffer_callback(lv_disp_drv_t* disp_drv, const lv_area_t* area, lv_color_t* color_p)
{
    /* copy pixels from 'color_p' to the area of the screen described by 'area' */
}

Configuring an input device follows a similar process. Use lv_indev_drv_init to set up the driver, define its type, attach a function for reading its value, and register it using lv_indev_drv_register. 

static lv_indev_drv_t indev_drv;
void input_read(lv_indev_drv_t *indev_drv, lv_indev_data_t *data);

void lvgl_indev_port_init(void);
{
    //configure any necessary platform specific peripherals here

    //set up input device driver
    lv_indev_drv_init(&indev_drv);

    //configure input device driver
    indev_drv.type = LV_INDEV_TYPE_POINTER;
    indev_drv.read_cb = input_read;
    
    //finalize driver setup
    lv_indev_t* touch_indev = lv_indev_drv_register(&indev_drv);
}

void input_read(lv_indev_drv_t *indev_drv, lv_indev_data_t *data)
{
    /* Read location from input device (i.e. last touch location on a touchscreen) */

    /* Read state from input device (i.e. is a touchscreen currently being touched) */

    /* Store current location (x, y) and state (pressed, released) in 'data' */
}

static lv_indev_drv_t indev_drv;
void input_read(lv_indev_drv_t *indev_drv, lv_indev_data_t *data);

void lvgl_indev_port_init(void);
{
    //configure any necessary platform specific peripherals here

    //set up input device driver
    lv_indev_drv_init(&indev_drv);

    //configure input device driver
    indev_drv.type = LV_INDEV_TYPE_POINTER;
    indev_drv.read_cb = input_read;
    
    //finalize driver setup
    lv_indev_t* touch_indev = lv_indev_drv_register(&indev_drv);
}

void input_read(lv_indev_drv_t *indev_drv, lv_indev_data_t *data)
{
    /* Read location from input device (i.e. last touch location on a touchscreen) */

    /* Read state from input device (i.e. is a touchscreen currently being touched) */

    /* Store current location (x, y) and state (pressed, released) in 'data' */
}

With the display and input device drivers implemented, the final step is to create an environment for LVGL to run in. In simple applications, this might be an infinite loop at the end of main function, while more complex applications may utilize an RTOS (real-time operating system) and give LVGL its own thread. Many approaches will work as long as lv_tick_inc and lv_timer_handler are called periodically, with lv_tick_inc occurring at least as frequently as lv_timer_handler.

Note that LVGL functions are not inherently thread-safe or interrupt-safe; if using interrupts or an RTOS, utilize synchronization tools like mutexes or take care to limit calls to LVGL such that they cannot overlap.

With all of the above in place, LVGL should be ready to use.

Internationalization Tools

In addition to the base library, LVGL has several supplementary tools to aid in development. When creating a UI for an international user base, two such tools stand out as essential: LVGL’s internationalization library, which provides simple tools for text substitution, and LVGL's font converter, which allows a developer to parse glyphs from several fonts into a single file for use with LVGL.

For both of these tools, you will need node.js (at least version 14) and the package manager it comes bundled with (called npm). You can download them here. Sticking with the default installation options will work for the tools covered here.

After installing, ensure that both node.js and npm are added to your system PATH. Open command prompt, and install the font converter with npm i lv_font_conv -g and the internationalization library with npm i lv_i18n -g Both tools should now be usable in your project.

lv_i18n

The process described below was adapted from the setup instructions provided with lv_i18n with notes from personal experience. For the original instructions, see the lv_i18n github.

Start off with a simple example, and wrap any text which will be translated in _( ). For strings containing plurals, _p( ) can be used instead to support languages with different pluralization rules from your base language. Include “lv_i18n.h” (this file doesn’t exist yet as it will be generated by the tool later) and, after initializing LVGL, call lv_i18n_init and lv_i18n_set_locale. The locale can be set to any language that you plan to support, and it can be changed any time that it’s safe to call an LVGL API function.

Next, create a folder to store translations, add a .yml file for each language you plan to support (including the language you are developing in), and title the files with language codes. Write the language code, followed by a colon, into the first line of each file (ex: Portuguese would have a file called “pt.yml”, and it’s first line would be “pt:”). Once your example is done, from a command prompt in your project, run the following (without angle brackets):

lv_i18n extract -s ‘<path to your source files>/*.+(c|cpp|h|hpp)’ -t ‘<path to your yml translations>/*.yml’

This will populate the translation files with a list of every string from your project wrapped in _( ). Next to each, add its translation in the language corresponding to the yml file it’s in. To implement these translations, run the following:

lv_i18n compile -t ‘<path to your yml translations>/*.yml’ -o ‘<path where you want lv_i18n.h to go>’

The output location of this command will receive lv_i18n.h and lv_i18n.c, which will contain all of your translations in a form that the tool can reference. It will need to be accessible by any file that calls _( ), so set up its location accordingly.

Now, your example should be ready to run. Any time that code containing a string wrapped in _( ) executes, the current locale will be checked and the string will be substituted for its translation in that locale. This is a simple, literal substitution, so anything referencing the string will be affected, not just LVGL functions. Additionally, if new text is added, you will need to run lv_i18n extract and lv_i18n compile again.

lv_font_conv

If one of your languages uses a script other than the Latin alphabet, you may notice missing characters when its translation is displayed. This is where the font converter comes in. Most fonts don’t describe a glyph for every Unicode character, so you will need to either find one that has all the characters you need or create one by splicing together a few fonts.

First, prepare a list of characters needed, or ranges of characters. Even if you have a font which contains all the characters needed, it’s likely that it also contains many that you don’t, and fonts take up a lot of space (especially physically larger ones; by default, LVGL stores them as byte arrays, and more pixels means more bytes).

Next, parse this list into a font converter call. Broadly, calls to the font converter are structured as a sequential list of font files, which characters to take from them, and then a few parameters to customize the output. Supply a path to the font file with --font, specify which characters to include from it with --range or --symbols, and repeat for each font to be included.

When adding characters, --symbols accepts a list of characters. Duplicates are ignored, so you can freely copy and paste everything from one language’s translation into this argument, but be careful to remove any spaces as they may be treated as the end of the argument. --range accepts a single Unicode value or a contiguous range of Unicode values. See Unicode ranges for reference. You can add as many --range and --symbols arguments as needed. Next, add the font size to generate with --size, the format with --format, the level of detail with --bpp, and a file path to output to with -o. The font converter github page has more details on each of these parameters.

 Altogether, a call might look like the following:

 lv_font_conv --font ARIALUNI.TTF

  --range 0x0000-0x017F

  --range 0x0400-0x04FF

  --symbols КАСБОЙ

 --font NotoSansArabic-Regulat.ttf

  --range 0x0600-0x06FF

  --range 0xFE70-0xFEFF

 --size 10 --format lvgl --bpp 3 -o examplefont.c

 lv_font_conv --font ARIALUNI.TTF

  --range 0x0000-0x017F

  --range 0x0400-0x04FF

  --symbols КАСБОЙ

 --font NotoSansArabic-Regulat.ttf

  --range 0x0600-0x06FF

  --range 0xFE70-0xFEFF

 --size 10 --format lvgl --bpp 3 -o examplefont.c

Note that newlines and indentation are included for clarity, the only separator should be spaces since this is invoked from a command line. To that end, it’s helpful to store arguments in a text file, then parse them into calls in a script with something like bash’s mapfile command.

Once a font has been generated, it can be included in the project, declared with LV_FONT_DECLARE, and used the same as LVGL’s default fonts.

Common Challenges

What follows is a collection of some common challenges one might encounter when creating internationalized UIs, and some tips as to how they can be handled with the tools discussed here.

Base Direction

Languages vary in their base directions; English, for example, is a left-to-right (LTR) language, while languages using the Arabic script are right-to-left languages (RTL). LVGL has some built-in handling for different base directions, namely the base_dir style property.

When creating an object, it can be given a base direction with lv_obj_set_style_base_dir, or attaching a style with the property already set (by lv_style_set_base_dir). This will work in most cases, but, with strings containing both LTR and RTL languages, you may need to specify text direction manually. For this, one can use Unicode directional indicators. Including the following in your project will allow you to change direction within a string.

#define LRI "\xE2\x81\xA6"

#define RLI "\xE2\x81\xA7"

#define PDI "\xE2\x81\xA9"

LRI indicates left-to-right, RLI the opposite, and PDI (pop directional indicator) undoes the most recent indicator. Wrapping chunks of text in LRI/RLI … PDI can be thought of as splitting the overall string into substrings, with the base direction of the overall string governing the order these substrings will appear. As an example, if the following string were to be placed in a label with RTL base direction:

“<LRI>123<PDI> <RLI>456<PDI> <LRI>789<PDI>”

(note: angle brackets included for clarity), it would appear on screen as

“789 654 123”.

Note also that LVGL may output warnings for missing glyph descriptions when rendering strings containing these characters. They are zero-width characters and function correctly regardless of whether they are included in the font, so these warnings can be safely ignored or suppressed in lv_conf.h (though missing glyph warnings are very helpful when working with custom fonts).

Information Density

Languages vary in information density; three Chinese characters might convey the same information as twenty Latin ones in English or thirty in Spanish. As such, it’s helpful to leave extra space in screen layouts for languages less dense than the one being used for development.

When this isn't possible, however, one can also use LVGL’s long text handling. Calling lv_label_set_long_mode will allow the developer to specify whether a label with text that does not fit in its width scrolls, wraps, or is cut off (optionally ending the displayed text with “…”) . Make sure to set the width of the label after calling this function.

In cases where built-in long modes are not desirable, another option is to decrease font size. Using lv_txt_get_size to check whether a string will fit in a space with a given font, it’s possible to implement automatic font scaling (though the exact process will vary greatly from UI to UI depending on the desired behavior).

Inserting Variables into Translated Text

One common use of text in a UI is to provide context for numerical information, which is complicated by the fact that translations need to be compiled beforehand. Thankfully, there’s a simple solution. As mentioned before, lv_i18n’s translation function _( ) is a simple, direct replacement. This means that the translated string can be used with basic C text functions, namely snprintf. Including “%s” (or other format codes) in both the initial string and its translations will allow values to be inserted into the string by code after translation. When using this method, take care to allocate enough space in the buffer passed to snprintf for your longest translation.

When a string contains multiple variable values, they can appear in different orders from language to language. This can be solved with either clever translation to keep fields in the same order, or by tracking which language is active and supplying arguments to sprintf in the corresponding order.

Duplicate words

Languages often have words that mean several different things. As an example, an English UI might include the string “set” in multiple places, some using the word as a verb, others as a noun. These words don’t necessarily line up between languages, so the string “set” would likely need two translations in other languages. lv_i18n can only attach one translation to each original string per language, so this may initially seem like a significant issue, but the tool is perfectly capable of handling these situations.

lv_i18n creates a lookup table for each language, mapping strings to other strings. The initial, untranslated strings scraped from your file are really just IDs to search translations by, and you can supply corresponding “translations” for them in your base locale (development language) just like any other language.

Returning to the previous example with the word “set”, you can change the strings in your code to “set (v)” and “set (n)” and re-run lv_i18n extract. In the yml files belonging to other languages, fill in the translation for "set" as a noun next to “set (n)” and "set" as a verb next to “set (v)”. In “en.yml”, just place the word “set” next to both.

Re-run lv_i18n compile. Running the program in English, you should still see “set” everywhere, but changing the language will now show different translations for different uses of “set”.

Learn More about DMC's Embedded User Interface Design services and contact us today for your next project.

The post LVGL for International GUI Design appeared first on DMC, Inc..