Symbols

Symbol creation

Reading from or writing to an ADS variable (= an ADS symbol) can be done even more pythonic through an AdsSymbol instance:

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', pyads.PORT_TC3PLC1)
>>> plc.open()
>>> symbol = plc.get_symbol('global.bool_value')

The address and type of the symbol will be automatically determined using a READ_WRITE request to the ADS server, based on the variable name. This lookup is skipped when all the information has already been provided:

>>> import pyads
>>> plc = pyads.Connection('127.0.0.1.1.1', pyads.PORT_TC3PLC1)
>>> plc.open()
# Remaining info will be looked up:
>>> symbol = plc.get_symbol('global.bool_value')
# Alternatively, specify all information and no lookup will be done:
>>> symbol = plc.get_symbol('global.bool_value', index_group=123,
                            index_offset=12345, symbol_type=pyads.PLCTYPE_BOOL)

Here the indices are same as used in Connection.read() and Connection.write(). The symbol type can also be the same as with the read and write method, e.g. pyads.PLCTYPE_INT or pyads.PLCTYPE_BOOL. Alternatively, the class will also accept a string of the variable type in PLC-style, e.g. ‘LREAL’, ‘INT’, ‘UDINT’, etc.

Symbols also work with structures and arrays of structures. Use the parameter structure_def to define the structure and array_size to define the size of the array.

 >>> structure_def = (
         ("i", pyads.PLCTYPE_INT, 1),
         ("s", pyads.PLCTYPE_STRING, 1)
     )
 >>> symbol = plc.get_symbol("MyStructure", structure_def=structure_def, array_size=2)
 >>> symbol.write([{"i": 1, " "s": "foo"}, {"i": 2, "s": "bar"}])
 >>> symbol.read()
[{"i": 1, " "s": "foo"}, {"i": 2, "s": "bar"}]

Read and write operations

Reading from and writing to symbols is straightforward:

>>> symbol.read()
True
>>> symbol.write(False)
>>> symbol.read()
False
>>> plc.close()

The symbol objects have the value property, which is the buffered symbol value:

>>> if symbol.read() > 0.5:
>>>     print(symbol.value)

The example above will perform a single READ request. value is updated on every read and write of the symbol. If None is passed to AdsSymbol.write() (the default parameter), the buffer will be written to the target:

>>> symbol.write(3.14)

>>> # Is identical to:
>>> symbol.value = 3.14
>>> symbol.write()

The symbol can be set to auto-update the AdsSymbol.value property through a device notification. See the subsection below.

Device notifications

Notifications (function callbacks) can be attached directly to a symbol:

>>> symbol.add_device_notification(my_func)

The symbol will track the handles of the notifications attached to it and free them up when the object runs out of scope.

You can delete specific notifications or clear all of them:

>>> handles = symbol.add_device_notification(my_func)
>>> symbol.del_device_notification(handles)

>>> # Or clear all:
>>> symbol.clear_device_notifications()

AdsSymbol.add_device_notification() will automatically create a notification attribute object with the right variable length. You can also specify an optional notification attribute and/or user handle:

>>> attr = NotificationAttrib(length=sizeof(pyads.PLCTYPE_BOOL), max_delay=1.0, cycle_time=1.0)
>>> user_handle = 123
>>> symbol.add_device_notification(my_func, attr=attr, user_handle=user_handle)

Auto-update

A built-in notification is available to automatically update the symbol buffer based on the remote value. This is disabled by default, enable it with:

>>> symbol.auto_update = True

This will create a new notification callback to update AdsSymbol.value. This can be efficient if the remote variable changes less frequently then your code runs. The number of notification callbacks will then be less than what the number of read operations would have been.

It can be disabled again with:

>>> symbol.auto_update = False

Using auto_update will also write the value immediately to the plc when AdsSymbol.value` is changed.

Warning

Take care that AdsSymbol.clear_device_notifications() will also remove the auto-update notification. Like all symbol notifications, the auto-update will be cleared automatically in the object destructor.

Get all symbols

In order to get a list of the device’s declared variables, use the get_all_symbols method.

>>> symbols = plc.get_all_symbols()
>>> print('\n'.join("%s: %s" % item for item in vars(symbols[0]).items()))
index_group: 16448
index_offset: 384800
name: Constants.bFPUSupport
symtype: BOOL
comment: Does the target support multiple cores?