File Explorer and Virtual Directory

So what is an Virtual Directory in the HMI?

A virtual directory is a directory name that you specify in the HMI config page that will map to a physical directory on the local server's hard drive or a directory on another server.

With the ability to create a path to the system we have the possibility to access files and interact with them in the HMI Client. This is good because then we do not need to add files that are for example getting frequently updated to the project itself and then we can have our HMI project cleaner.

This also opens up a lot of other possibilities in the HMI. We can for example have data that the PLC writes in a file that we can directly access and show in the HMI, e.g., presenting the data inside a data grid or a line chart.

In TwinCAT HMI version 1.12.754.4 the control File Explorer got added to the toolbox. This control exists in the Control package so no extra nuget package is needed to use this.

With the File Explorer control, we now have an easy way to work with our Virtual Directories. The control has functions such as Create Folder, Upload, Download, Copy, Paste, Cut, Rename and Delete.

This makes it possible for the client to remotely upload and download files to the file system. So for e.g. a client can open the HMI and download the data that the machine has generated to his own device or even uploading data to the machine that the PLC need to run a specific product.

Creating a sample project

Before I go through how I created and configured the sample project let’s have a look at the finished project demo below.

In the video I'm accessing a folder on my desktop that has an Image and Data folder. When I click in the File Explorer, I have a JavaScript function that is running in the background checking the file type, if it's an image I will show it in the image control and if it’s a .json file I will show it in the line chart control.

Let’s start with the folder that we are going to use and then configure this path in the virtual directory.

Here I have my folder on the desktop with a Data and Image folder containing my test files. I will copy the full path to the folder and then go to the HMI project.

1. Double click the TcHmiSrv
2. Make sure you use the correct "Publish Configuration". Remote = Published HMI (remote HMI server) and Default = Live Engineering server. For this demo purpose I will use the default config but in a real application you would want to use the remote one.
3. Click Add Virtual Directory

The Name can be anything you want but it needs to start with an forward slash /

After your Virtual Directory is configured, it is now time to add the File Explorer control to your HMI.

Under Common in the properties window for the File Explorer control you need to define the path that is going to be used.

You can configure it with a start Path and keep the ability to access the Root (first picture) or you can directly write the /MyFiles to the Root property. This will make it so the user cannot access anything above this Root path.

You can now test this in the Live View to see if it works!

To add some more advanced logic to the File Explorer I will make use of the built-in event .onSelectionChanged and also read out the path and selected items from the control.

In my sample I will add the TcHmiImage and TcHmiLineChart control to the HMI.

For the Image control you can add any images you like to the Image folder. For the data folder I'm using a generated json array. Here is a code snippet for the array that you can copy and then save to your data folder. (You can make the array any length you want so feel free to copy the data multiple times and save different version of the file to the folder)

{
	"array": [
		1.323,
		54.554,
		7.435,
		29.322,
		5.891,
		8.332,
		11.339,
		95.608,
		6.953,
		63.35	
	]
}        

Next step is to add your JavaScript (function) to the project and then we will configure the parameters to the function like this;

Open the function and add this code snippet inside it;

//Return if empty
if (SelectedItems == undefined || SelectedItems.length === 0 || FullPath === "") return;
if (ImageControl == "" && ChartControl == "") return;


//Use regular expression to check if selected item have a file extension of type image
if (SelectedItems[0].match(/.(jpg|jpeg|bmp|png|gif)$/i)) {


? ? //Get the Image Control
? ? const imageControl = TcHmi.Controls.get(ImageControl);


? ? //Set BackgroundImage with path and image name
? ? imageControl.setBackgroundImage(FullPath + "/" + SelectedItems[0]);


} else if (SelectedItems[0].match(/.(json)$/i)) {


? ? //Get the Chart Control
? ? const chartControl = TcHmi.Controls.get(ChartControl);


? ? //Read the JSON-data and set the array to the chart
? ? let jsonPath = FullPath + "/" + SelectedItems[0];


? ? //Get data
? ? $.getJSON(jsonPath, function (data) {


? ? ? ? let arr = [];
? ? ? ? let subArr = [];
? ? ? ? arr.push(subArr);
? ? ? ? for (var i = 0; i < data.array.length; i++) {
? ? ? ? ? ? let chartObject = {};
? ? ? ? ? ? chartObject["x"] = i;
? ? ? ? ? ? chartObject["y"] = data.array[i];
? ? ? ? ? ? subArr.push(chartObject);
? ? ? ? }


? ? ? ? chartControl.setLineGraphData(arr);
? ? });


}        

The code above uses regular expression to check the file extension of the selected item. If the file is of the type of image we will show it in the Image control by using the "setBackgroundImage" function.

If the selected item is of type .json we will then read in the array-data and add it to the line chart control.

To be able to show the json array inside the Line chart I need to make sure the data matches the structure that the line chart needs. The array needs to be two dimensional so this is the reason I use "subArr" in the code above.

https://infosys.beckhoff.com/content/1033/te2000_tc3_hmi_engineering/3922250891.html?id=422991186212029478

Make sure you have configured your Line chart control. A good option is to use the auto scaling for the axis and in my data-sample I will only have one Y-axis so this is what I have configured here;

Ok so now we should have the following: Virtual Directory configured, File Explorer control, Image control and Line Chart control added and the JavaScript function.

Next step is to add the JavaScript function to the event in the File Explorer here;

Open up the .onSelectedChanged event and then add the JavaScript function (Found under Functions > Other)

Here we need to add the FullPath, SelectedItems and the Id for our controls. This JavaScript will then run everytime the selected item change in the File Explorer control.

You can now test this in the Live view and it should hopefully work :)

A few last words and thoughts

Now we have completed the simple sample project with some more advanced functionality with the help of JavaScript. This was just a sample to give you some ideas on what is possible or what you could do in your TwinCAT HMI application.

In this sample I configured the Virtual Directory in the "default" configuration and not in the "remote" one. The "remote" configuration is used for the published HMI so when you want this function in your real HMI-server then remember to configure the path there as well and also to check this checkbox during the publish;

(You can also manually configure this inside the server config-page)

The Virtual Directory we configured is an URL so it’s possible to access the data in the browser like below if you know the exact path and filename

I hope you enjoyed this article and found it helpful!

Best Regards, Jack Borelius