Tame4

JS library for the access to a TwinCAT PLC.

View project on GitHub

Current version: V4.3.1 final

Introduction

TAME is JavaScript library created for an easy and comfortable access to the TwinCAT ADS WebService. The name is an acronym for „TwinCAT ADS Made Easy“ and stands also for „taming“ the complexity of ADS and AJAX requests. Originally a „wast product“ from the programming of a browser based visualization for my home, it has become a (in my opinion) useful little piece of software and I hope it will help others who want to develop their own visualizations.

The reason for V4 is that synchronous XMLHttpRequests in the main thread are depricated and browsers will stop supporting them one day. See here for more details. In V3.x synchronous requests were internally used for fetching the symbol and data type information from the PLC while instancing the client. Switching to asynchronous requests makes things a little bit more complicated. You have to start your scripts with the new “onReady” function.

Usage

The library allows to exchange data with a TwinCAT PLC without any knowledge of ADS or AJAX. The browser connects to the webserver running on the PLC device and the ADS commands are wrapped in AJAX/SOAP requests.

Link the library in your project like any other JavaScript file and create the client like this:

var Plc =  TAME.WebServiceClient.createClient({
    serviceUrl: 'http://192.168.1.2/TcAdsWebService/TcAdsWebService.dll',
    amsNetId: '192.168.1.2.1.1',
    onReady: function() {
        //Place your code here, i.e. start cyclic polling
    }
});

See the documentation for more options (i.e. AMS port or alignment).

To write a boolean variable to the PLC you just have to write one line of code:

Plc.writeBool({name:"MAIN.MyBoolVar", val: true});

Reading a PLC variable and storing the value in a (global) JavaScript variable is also quite easy:

Plc.readBool({name:"MAIN.MyBoolVar", jvar:"myVar"});

A more complex example of reading multiple variables with a function executed after the request has successfully finished:

Plc.sumReadReq({
    items: [
        {
            name: 'MAIN.Ramp1',
            jvar: 'counter1.data'
        },{
            name: 'MAIN.Ramp2',
            jvar: 'counter2.data'
        },{
            name: 'MAIN.RunningLight1',
            jvar: 'runLight[0]'
        },{
            name: 'MAIN.RunningLight2',
            jvar: 'runLight[1]'
        },{
            name: 'MAIN.RunningLight3',
            jvar: 'runLight[2]'
        },{
            name: 'MAIN.RunningLight4',
           jvar: 'runLight[3]'
        },{
            name: 'MAIN.RunningLight5',
            jvar: 'runLight[4]'
        },{
            name: '.In_SINT1',
            jvar: 'field5.data'
        },{
            name: '.In_INT1',
            jvar: 'field6.data'
        }
    ],
    oc: function() {
        //Set the background-color after reading data
        for (var i = 0; i < 5; i++) {
            if (runLight[i] === true) {
                pageElem[i].style.backgroundColor = 'green';
            } else {
                pageElem[i].style.backgroundColor = 'red';
            }
        }
    }
});

Have a look at the manual for more information. TAME comes with various working examples including the PLC program, the best is to just try them out.

Features

  • Methods for read and write access to single variables, variable blocks, arrays and structures exists.

  • Supported data types: BOOL, BYTE, WORD, DWORD, USINT, SINT, UINT, INT, UDINT, DINT, TIME, TOD, DT, DATE, REAL, LREAL and STRING. Bounds checking is implemented but can be switched off.

  • Sum commands are supported (read and write).

  • Handles are supported. Access to single elements of structures and arrays and also internal variables and parameters of FB’s is possible.

  • The TPY-file generated by TwinCAT can be used. The file contains information about the PLC, the symbols and the data types. With these informations one no longer have to set NetId, port or alignment. Reading structures from the PLC the JavaScript objects can be built automatically without the need of structure definitions. Access to single elements of structures and arrays and also internal variables and parameters of FB’s is possible even without using handles.

  • Special „type“ named INT1DP: It’s an INT variable in the PLC, but in JavaScript the variable is of type float with 1 decimal place (i.e. a value of 568 in the PLC is 56.8 in JavaScript).

  • Built-in conversion of date and time values to formatted strings.

  • REAL values can be rounded to a desired number of decimal places.

  • Add prefix and suffix to values for a user defined output.

  • Automatic structure padding for exchanging data with TwinCAT 2 and ARM-based devices (i.e. CX90xx) or with TwinCAT 3.

  • Export/import functions for symbols and data types to/from files. Intented for the use with Tasker (Android).

  • Force synchronous XMLHttpRequests for easier scripting in Tasker.

Requirements

Required is a running ADS WebService, look at the [Beckhoff Infosys] (http://infosys.beckhoff.com) for more information about the installation. And a TwinCAT PLC of course. ;-)

License

TAME is dual licensed under the MIT and the GPLv3 license.

Beckhoff® and TwinCAT® are registered trademarks of Beckhoff Automation GmbH.