pyads 3.1.1

Python wrapper for TwinCAT ADS library

pyads - Python package

This is a python wrapper for TwinCATs ADS library. It provides python functions for communicating with TwinCAT devices. pyads uses the C API provided by TcAdsDll.dll on Windows adslib.so on Linux. The documentation for the ADS API is available on infosys.beckhoff.com.

Documentation: http://pyads.readthedocs.io/en/latest/index.html

Installation

From PyPi:

$ pip install pyads

From Github:

$ git clone https://github.com/MrLeeh/pyads.git --recursive
$ cd pyads
$ python setup.py install

Quickstart

Creating routes

ADS uses its own address system named AmsNetId to identify devices. The assignment of a devices to an AmsNetId happens via routing. Routing is handled differently on Windows and Linux.

Creating routes on Linux

Open a port and create a AmsAddr object for the remote machine.

>>> import pyads
>>> pyads.open_port()
32828

Add a route to the remote machine (Linux only - Windows routes must be added in the TwinCat Router UI).

>>> remote_ip = '192.168.0.100'
>>> adr = pyads.AmsAddr('127.0.0.1.1.1', pyads.PORT_SPS1)
>>> pyads.add_route(adr, remote_ip)

Get the AMS address of the local machine. This may need to be added to the routing table of the remote machine. NOTE: On Linux machines at least one route must be added before the call to get_local_address() will function properly.

Adding routes to a PLC on Linux

Beckhoff PLCs require that a route be added to the routing table of the PLC. Normally this is handled in the TwinCAT router on Windows, but on Linux there is no such option. This only needs to be done once when initially setting up a connection to a remote PLC.

Adding a route to a remote PLC to allow connections to a PC with the Hostname "MyPC"

>>> import pyads
>>> SENDER_AMS = '1.2.3.4.1.1'
>>> PLC_IP = '192.168.0.100'
>>> USERNAME = 'user'
>>> PASSWORD = 'password'
>>> ROUTE_NAME = 'RouteToMyPC'
>>> HOSTNAME = 'MyPC'
>>> PLC_AMS_ID = '11.22.33.44.1.1'
>>> pyads.add_route_to_plc(SENDER_AMS, HOSTNAME, PLC_IP, USERNAME, PASSWORD, route_name=ROUTE_NAME)

Creating routes on Windows

On Windows you don't need to manually add the routes with pyads but instead you use the TwinCAT Router UI (TcSystemManager) which comes with the TwinCAT installation. Have a look at the TwinCAT documentation infosys.beckhoff.com TcSystemManager for further details.

Testserver

For first tests you can use the simple testserver that is provided with the pyads package. To start it up simply run the following command from a separate console window.

$ python -m pyads.testserver

This will create a new device on 127.0.0.1 port 48898. In the next step the route to the testserver needs to be added from another python console.

>>> import pyads
>>> pyads.open_port()
>>> adr = pyads.AmsAddr('127.0.0.1.1.1', pyads.PORT_SPS1)
>>> pyads.add_route(adr, '127.0.0.1')

Usage

Connect to a remote device

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', pyads.PORT_SPS1)
>>> plc.open()
>>> plc.close()

Read and write values by name

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', pyads.PORT_SPS1)
>>> plc.open()
>>> plc.read_by_name('global.bool_value', pyads.PLCTYPE_BOOL)
True
>>> plc.write_by_name('global.bool_value', False, pyads.PLCTYPE_BOOL)
>>> plc.read_by_name('global.bool_value', pyads.PLCTYPE_BOOL)
False
>>> plc.close()

If the name could not be found an Exception containing the error message and ADS Error number is raised.

>>> plc.read_by_name('global.wrong_name', pyads.PLCTYPE_BOOL)
ADSError: ADSError: symbol not found (1808)

For reading strings the maximum buffer length is 1024.

>>> plc.read_by_name('global.sample_string', pyads.PLCTYPE_STRING)
'Hello World'
>>> plc.write_by_name('global.sample_string', 'abc', pyads.PLCTYPE_STRING)
>>> plc.read_by_name(adr, 'global.sample_string', pyads.PLCTYPE_STRING)
'abc'

You can also read/write arrays. For this you simply need to multiply the datatype by the number of array elements you want to read/write.

>>> plc.write_by_name('global.sample_array', [1, 2, 3], pyads.PLCTYPE_INT * 3)
>>> plc.read_by_name('global.sample_array', pyads.PLCTYPE_INT * 3)
(1, 2, 3)

Read and write values by address

Read and write UDINT variables by address.

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', pyads.PORT_SPS1)
>>> plc.open()
>>> # write 65536 to memory byte MDW0
>>> plc.write(pyads.INDEXGROUP_MEMORYBYTE, 0, 65536, pyads.PLCTYPE_UDINT)
>>> # write memory byte MDW0
>>> plc.read(pyads.INDEXGROUP_MEMORYBYTE, 0, pyads.PLCTYPE_UDINT)
65536
>>> plc.close()

Toggle bitsize variables by address.

>>> # read memory bit MX100.0
>>> data = plc.read(pyads.INDEXGROUP_MEMORYBIT, 100*8 + 0, pyads.PLCTYPE_BOOL)
>>> # write inverted value to memory bit MX100.0
>>> plc.write(pyads.INDEXGROUP_MEMORYBIT, 100*8 + 0, not data)

Simple handling of notification callbacks

To make the handling of notifications more Pythonic a notification decorator has been introduced in version 2.2.4. This decorator takes care of converting the ctype values transfered via ADS to python datatypes.

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', 48898)
>>> plc.open()
>>>
>>> @plc.notification(pyads.PLCTYPE_INT)
>>> def callback(handle, name, timestamp, value):
>>>     print(
>>>         '{1}: received new notitifiction for variable "{0}", value: {2}'
>>>         .format(name, timestamp, value)
>>>     )
>>>
>>> handles = plc.add_device_notification('GVL.intvar',
                                          pyads.NotificationAttrib(2), callback)
>>> # Write to the variable to trigger a notification
>>> plc.write_by_name('GVL.intvar', 123, pyads.PLCTYPE_INT)

2017-10-01 10:41:23.640000: received new notitifiction for variable "GVL.intvar", value: abc

>>> # remove notification
>>> plc.del_device_notification(handles)

The notification callback works for all basic plc datatypes but not for arrays or structures.