Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC®and XTS® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The EtherCAT Technology is covered, including but not limited to the following patent applications and patents:
EP1590927, EP1789857, DE102004044764, DE102007017835
with corresponding applications or registrations in various other countries.

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Introduction

A PC equipped with Microsoft Windows XP Media Center Edition combines the abbilities of Windows with the functionality of a modern entertainment station. Because it is based on Windows XP Professional, Windows XP Media Center Edition can use the entiry hard- and software available on the market. The extensibility of its user interface enhances the possibilities even more.

This example discribes how the user interface of the Windows XP Media Center can be extended by own dialogs and how these dialogs can communicate with TwinCAT. With this it is possible to control automation solutions on the TV by remote control.

Prerequisites

Server:

  • .NET-Framework V2.0
  • Microsoft Internet Information Services (IIS)
  • TwinCAT PLC V2.10
  • Microsoft Visual Studio 2005
  • HTML-Editor

Knowledge:

  • Programming .NET (especially WebServices)
  • Creating HTML-pages (including CSS and Javascript)
  • Fundamentals in Windows XP Media Center SDK
  • PLC-Programming with TwinCAT V2.10

Sample files

All sample files can be found in the archive TcMCE_Sample.zip. They are needed for the following operations so please copy them onto the server.

Content

  • Step 1: Creating the PLC project
  • Step 2: Creating the Media Center compatible user interface
  • Step 3: Creating the WebService
  • Step 4: Implementing the WebService behaviour
  • Step 5: Setting up the visualization


Step 1: Creating the PLC project

The PLC program of the sample is wittingly simple. 3 global variables have to be created:

Global varables

VAR_GLOBAL
   bLight1  : BOOL;
   bLight2  : BOOL;
   nCounter : INT;
END_VAR

bLight1 & bLight2 are simple boolean variables used as an indication of the states of two lights.
nCounter is a counter, which be be read out as well.

"MAIN"-program

Just one line is added to the "MAIN"-program:

nCounter := nCounter + 1;

This line increases nCounter each cycle by 1.

Please continue with step 2.


Step 2: Creating the Media Center compatible user interface

Windows XP Media Center can display user interfaces with the help of purpose-built HTML-pages. These pages can also be viewed with the Internet Explorer. This enables the possibility to have access to the visualization without Windows XP Media Center.

In general the creation of the Media Center pages follow the same rules as normal HTML-pages. Therefore only the special settings needed to make the page Media Center compatible are mentioned here.

Necessary implementations

  • The files "BasicFunctions.js", "Hilite.htc", "Hilite.js" and "MoveFocus.js" have to be copied to the same directory as the HTML-page(s). These files can be found in the sample or the HTML templates of the Media Center SDK.
    To include these files into the HTML-page add the following lines to the head:
    • <script src="BasicFunctions.js" type="text/javascript"></script>
<script src="MoveFocus.js" type="text/javascript"></script>
  • You need a special CSS file (see below) (the sample already contains the file "mediacenter.css").
    This stylesheet determines the look and behaviour of the page and her elements.
    Include this file in the head as followed:
    <link href="mediacenter.css" type="text/css" rel="stylesheet" />
  • Add a javascript-section to the head, which contains the onLoad-method
    function Loader()
{
   setBGColor("#0B5EBB");
   checkSVP();
   setArray();
   startFocus();
}

    The name of this function can be choosen freely. The 4 function-calles can be extended by own commands. The use and meaning of these functions are described in the HTML templates of the Media Center SDK.

  • Furthermore the script-section must contain a "doSelect"-function for the eventhandling.
    function doSelect()
{
   switch(oCurFocus.id)
   {
      ...
   }
}
    This function is called by left-clicking or pressing the "OK"-button on the remote control. If an element shoud react on this, you have to enter the ID of the element as a case. The method-calls have to be placed inside the case.

    Example:

    function doSelect()
{
   switch(oCurFocus.id)
   {
      case "btnLight1Toggle":
         ToggleLight_Request(1);
         break;

      case "btnLight2Toggle":
         ToggleLight_Request(2);
         break;

      case "btnCounterReset":
         ResetCounter_Request();
         break;
   }
}

  • The "body"-tag needs some additional attributes:
    • onload="" : Insert the name of your onLoad-method here.
    • MCFocusStart="" : Insert the ID of the element which should be focused/highlighted when opening the page.
    • onkeydown="onRemoteEvent(window.event.keyCode) : This attribute is necessary for the remote control.
  • Focusable or important elements should be declared as a SPAN-element. Additionaly they need the following attributes:
    • id="" : Insert a unique name for the element here.
    • class="" : Determines which style and behaviour (from the CSS-file) the element should have.
    • MCFocusable="" : Enter "true" if the element should be focusable, otherwise "false".
  • If the page shall contain the functionality of a "shared view port" the following line has to be added to the body: (Important: Don't change this line in any way, or the functionality gets lost)
    <table><tr><td><span id="SVP" MCFocusable="true" /></td></tr></table>
    The "shared view port" is a small window-element at the bottom-left side of the screen, which allows the user to have access to a running media while doing something elese in the Media Center.

The HTML-page

<html>
<head>
<title>Connecting TwinCAT with Windows XP Media Center Edition</title>

<link href="mediacenter.css" type="text/css" rel="stylesheet" />
<script src="BasicFunctions.js" type="text/javascript"></script>
<script src="MoveFocus.js" type="text/javascript"></script>

<script type="text/javascript">
function Loader()
{
   setBGColor("#0B5EBB");
   checkSVP();
   setArray();
   startFocus();
}

function doSelect()
{
   switch(oCurFocus.id)
   {
      case "btnLight1Toggle":
         break;

      case "btnLight2Toggle":
         break;

      case "btnCounterReset":
         break;
   }
}
</script>
</head>

<body id="body" class="body" MCFocusStart="btnLight1Toggle" onload="Loader()" onkeydown="onRemoteEvent(window.event.keyCode)">
<span id="headback" class="headback">BECKHOFF</span>
<span id="headfront" class="headfront">Connecting TwinCAT with Windows XP Media Center Edition</span>
<table><tr><td><span id="SVP" MCFocusable="true" /></td></tr></table>

<span id="leftmenu" class="leftmenu">
   <table>
      <tr>
         <td>
            <img src="../images/logo_beckhoff.gif" width="250" height="72"/>
         </td>
      </tr>
   </table>
</span>

<span id="navmenu" class="navmenu">
   <table align="center">
      <tr>
         <td>
            <span id="lblLight1Text" class="navlabel" MCFocusable="false">Light 1 :</span>
            <span id="lblLight1Value" class="navlabel" MCFocusable="false">???</span>
            <span id="btnLight1Toggle" class="navbutton" MCFocusable="true">toggle</span>
         </td>
      </tr>
      <tr>
         <td>
            <span id="lblLight2Text" class="navlabel" MCFocusable="false">Light 2 :</span>
            <span id="lblLight2Value" class="navlabel" MCFocusable="false">???</span>
            <span id="btnLight2Toggle" class="navbutton" MCFocusable="true">toggle</span>
         </td>
      </tr>
      <tr>
         <td>
            <span id="lblCounterText" class="navlabel" MCFocusable="false">Counter :</span>
            <span id="lblCounterValue" class="navlabel" MCFocusable="false">???</span>
            <span id="btnCounterReset" class="navbutton" MCFocusable="true">reset</span>
         </td>
      </tr>
   </table>
</span>

</body>
</html>

The CSS-file (here: "mediacenter.css")

More detailed information about the creation of these CSS-files can be found in the HTML templates of the Media Center SDK.

body
{
   background-color: "#0B5eBB";
   background-image: url(../images/background.jpg);
   background-repeat: no-repeat;
}

td
{
   position: relative;
}

.headback
{
   filter: alpha(opacity=10);
   position: absolute;
   left: -5px;
   top: 30px;
   color: White;
   font-family: Arial;
   font-size: 150px;
   text-align: left;
   font-weight: bold;
}

.headfront
{
   position: absolute;
   top: 125px;
   left: 105px;
   color: White;
   font-family: Arial;
   font-size: 25px;
   text-align: left;
   font-weight: bolder;
}

.leftmenu
{
   position: absolute;
   top: 200;
   left: 20;
   color: White;
   font-family: Arial;
   font-size: 20pt;
   font-weight: bold;
   font-size: 20pt;
   text-align: center;
   padding-top: 10px;
}

.navmenu
{
   position: absolute;
   top: 200;
   left: 280;
   height: 63%;
   width: 72%;
   overflow: hidden;
}

.navlabel
{
   color: White;
   width: 150px;
   height: 50px;
   font-family: Arial;
   font-size: 20pt;
   font-weight: bold;
   text-align: center;
   padding-top: 10px;
}

.navbutton
{
   behavior:url(Hilite.htc);
   color: White;
   background-image: url(../images/navbutton.gif);
   background-repeat: no-repeat;
   width: 250px;
   height: 50px;
   font-family: Arial;
   font-size: 20pt;
   font-weight: bold;
   text-align: center;
   padding-top: 10px;
   cursor: hand;
}

.navbutton_hilite
{
   behavior: url(Hilite.htc);
   color: White;
   background-image: url(../images/navbutton_hilite.gif);
   background-repeat: no-repeat;
   width: 250px;
   height: 50px;
   font-family: Arial;
   font-size: 20pt;
   font-weight: bold;
   text-align: center;
   padding-top: 10px;
   cursor: hand;
}

Continue with step 3.


Step 3: Creating the WebService

WebServices are used to call methods on the server by HTTP requests. The methods provide the complete range of funtions the .NET-Framework can offer.

General information: Its is highly recommended to use the Microsoft Visual Studio for creating the WebService.

The ASMX-page

By creating a new Web Site project with the Visual Studio the ASMX-page is generated automaticly, but it is possible to change this file.
The prameters of this file have the following meanings:
Language : Stands for the programming language used in the sourcecode-file
CodeBehind : Indicates the path of the sourcecode-file
Class : Enter the name of the class in the sourcecode-file, which inherits from System.Web.Services.WebService

Example:

<%@ WebService Language="C#" CodeBehind="~/App_Code/TcMCE_Sample.cs" Class="TcMCE_Sample" %>

The sourcecode-file

This file contains the source code. To declare a class as a WebService, it has to inherit from System.Web.Services.WebService.
In addition this class has to be public an must have the prefix "[WebService()]".

To have access to the functions of this class, these methods likewise have to be public and must have the "[WebMethod]" prefix .
These methods are able to have several input parameters.
If you want to return more data then the returning value allows you to, you have to use referenced parameters.

Example:

public int ToggleLight(int nNumber, ref bool bValue)

The communication with the PLC can be realized via the Ads.NET-components, the Ads-DLL or the Ads-OCX. The implementation and use of these libraries can be found in the corresponding documentations of the Beckhoff Information System.

Example (using C#) :

using System;
using System.Web.Services;
using TwinCAT.Ads;

[WebService()]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class TcMCE_Sample : WebService
{
   TcAdsClient adsClient;
   int hLight1;
   int hLight2;
   int hCounter;

   public TcMCE_Sample()
   {
      adsClient = new TcAdsClient();
      adsClient.Connect(801);

      hLight1 = adsClient.CreateVariableHandle(".bLight1");
      hLight2 = adsClient.CreateVariableHandle(".bLight2");
      hCounter = adsClient.CreateVariableHandle(".nCounter");
   }

   ~TcMCE_Sample()
   {
      adsClient.DeleteVariableHandle(hLight1);
      adsClient.DeleteVariableHandle(hLight2);
      adsClient.DeleteVariableHandle(hCounter);
      adsClient.Dispose();
   }

   [WebMethod]
   public bool GetValues(ref bool[] arrLightValues, ref int nCounterValue)
   {
      try
      {
         arrLightValues = new bool[2];
         arrLightValues[0] = Convert.ToBoolean(adsClient.ReadAny(hLight1, typeof(bool)));
         arrLightValues[1] = Convert.ToBoolean(adsClient.ReadAny(hLight2, typeof(bool)));
         nCounterValue = Convert.ToInt32(adsClient.ReadAny(hCounter, typeof(int)));
         return true;
      }
      catch(Exception)
      {
         return false;
      }
   }

   [WebMethod]
   public int ToggleLight(int nNumber, ref bool bValue)
   {
      try
      {
         AdsStream adsStream = new AdsStream(1);
         AdsBinaryWriter adsWriter = new AdsBinaryWriter(adsStream);

         switch(nNumber)
         {
            case 1:
               bValue = !(Convert.ToBoolean(adsClient.ReadAny(hLight1, typeof(bool))));
               adsWriter.Write(bValue);
               adsClient.Write(hLight1, adsStream);
               return 1;
            case 2:
               bValue = !(Convert.ToBoolean(adsClient.ReadAny(hLight2, typeof(bool))));
               adsWriter.Write(bValue);
               adsClient.Write(hLight2, adsStream);
               return 2;
            default:
               return 0;
         }
      }
      catch(Exception)
      {
         return 0;
      }
   }

   [WebMethod]
   public bool ResetCounter()
   {
      try
      {
         AdsStream adsStream = new AdsStream(2);
         AdsBinaryWriter adsWriter = new AdsBinaryWriter(adsStream);
         adsWriter.Write((Int16)0);
         adsClient.Write(hCounter, adsStream);
         return true;
      }
      catch(Exception)
      {
         return false;
      }
   }
}

Now the WebService has to be called by the HTML-page via javascript ("WebService behaviour"). This is explained in step 4.


Step 4: Implementing the WebService behaviour

This step discribes how the Media-Center-HTML-page can execute the methods of the WebService (created in step 3) via javascript ("WebService behaviour").

For this the file "webservice.htc" from the sample or the Microsoft MSDN is needed. Please copy this file to the same directory as the HTML-page from step 2.

Necessary implementations

  • Add the following line to the "body" in the CSS-file:
    behavior:url(webservice.htc);

  • Add the following lines to the onLoad-method of the HTML page:
    body.onserviceavailable = enableServiceCall();
body.useService("...","...");
    The first parameter of the "useService"-function call must contain the URL of the WebService-WSDL-format.
    The second parameter stands for the name the WebService behaviour will have in this script.

    Example:

    body.useService("../TcMCE_Sample.asmx?wsdl","WebServiceSample");

  • Add the following line to the script-section of the HTML page:
    function enableServiceCall(){}

Asynchronous call of the WebServices

A WebService can be called with the following script ("WebServiceSample" must be replaced by the the name that was entered as the second parameter in the "useService" -function call):
iCallID = body.WebServiceSample.callService(... , "...", "...");
The first parameter contains the name of the function, that catches the response of the WebService.
The second parameter must contain the name of the WebService-method to call.
If the WebServiceMethod needs input parameters, these can be entered as additional parameters.

Example:

iCallID = body.WebServiceSample.callService(ToggleLight_Result, "ToggleLight", nNumber);

Catching the WebService responses

The response catching method must have the input parameter "res".
With the call "res.value["WebServiceMethodNameResult"]" the returning value of the method can be obtained.
Additional ouput parameters can be obtained with the call "res.value["ParameterName"]".
Example:

function GetValues_Result(res)
{
   if(res.value["GetValuesResult"] == true)
   {
      lblLight1Value.innerText = res.value["arrLightValues"][0];
      lblLight2Value.innerText = res.value["arrLightValues"][1];
      lblCounterValue.innerText = res.value["nCounterValue"];
   }
}
As you can see in the example it is even possible to read out arrays.

To make sure that the values are read out constantly, a loop has to be implemented which continuously checks for new values. Take care that the timeout is not too small, because this may cause a stressing of the server(epecially when many users are accessing the server).

For these loops the "window.setTimeout()"-method is very helpfull."

To get more information about the WebService behaviour please read the corresponding articles in the MSDN.

A concrete example of this implementation can be found in the sample.

Now you should have the knowledge to realize communication with TwinCAT via Media Center on your own.

For setting up the visualization please refer to step 5.


Step 5: Setting up the visualization

  • Run the PLC project on the machine and runtime that fits your needs. If necessary change the AMS-Net-Id and the port in the WebService-sourcecode.
  • Create a new virtual directory in the IIS of the server containing the WebService, the HTML-page and its script-files and grant sufficient rights for accessing and executing.

  • The visualization can now be embedded within Media Center with the help of an "MCL"-file and/or a special installation.
    For more information please read the Media Center SDK.

    Example for an MCL-file:

    <application
   url="http://VisuServer/TcMCE_Sample/HTML/TcMCE_Sample.html"
   name="Connecting TwinCAT with Media Center"
   ThumbnailImage = "http://VisuServer/TcMCE_Sample/images/thumbnail.jpg"
/>