Introduction

ciplink is a fork of pycomm3 by Ian Ottoway, a Python library for communicating with Allen-Bradley PLCs using Ethernet/IP. It keeps the pycomm3 API (import ciplink instead of pycomm3) and adds:

• tag requests addressed by symbol instance ID, including UDT members and program-scoped tags

• tag-table change detection with the controller’s edit counter, so online edits trigger a reload instead of reading a reused instance ID

• fast reloads, batched tag-list uploads and a restart cache (tag_cache_file)

• Add-On Instruction access probing: whole AOI reads return their readable parameters, and AOI locals are refused without a request

Without the work of the pycomm3 developers, and of the original pycomm developers before them, ciplink would not exist. The pycomm3 documentation applies to ciplink apart from the import name.

Drivers

ciplink includes 3 drivers:

• CIPDriver

  This driver is the base driver for the library, it handles common CIP services used by the other drivers. Things like opening/closing a connection, register/unregister sessions, forward open/close services, device discovery, and generic messaging. It can be used to connect to any Ethernet/IP device, like: drives, switches, meters, and other non-PLC devices. ciplink is a client for explicit messaging only (unconnected/UCMM and class 3 connected over TCP 44818); implicit class 0/1 I/O (UDP 2222), produced/consumed tags and acting as a CIP server/adapter are not supported.

• LogixDriver

  This driver supports services specific to ControlLogix, CompactLogix, and Micro800 PLCs. Services like reading/writing tags, uploading the tag list, and getting/setting the PLC time.

• SLCDriver

  This driver supports basic reading/writing data files in a SLC500 or MicroLogix PLCs. It is a port of the SlcDriver from pycomm with minimal changes to make the API similar to the other drivers. Currently this driver is considered legacy and it’s development will be on a limited basis. PLC-5 processors are not supported by any driver.

Disclaimer

PLCs can be used to control heavy or dangerous equipment, this library is provided “as is” and makes no guarantees on its reliability in a production environment. This library makes no promises in the completeness or correctness of the protocol implementations and should not be solely relied upon for critical systems. The development for this library is aimed at providing quick and convenient access for reading/writing data inside Allen-Bradley PLCs.

Setup

The package can be installed from PyPI using pip: pip install ciplink or python -m pip install ciplink.

Optionally, you may configure logging using the Python standard logging library. A convenience method is provided to help configure basic logging, see the Logging Section in the docs for more information.

Python and OS Support

ciplink is a Python 3-only library and is supported on Python 3.9 and newer. There should be no OS-specific requirements and should be able to run on any OS that Python is supported on. Development and testing is done primarily on Windows 10. If you encounter an OS-related problem, please open an issue in the GitHub repository and it will be investigated.

Documentation

This README covers a basic overview of the library, full documentation can be found on Read the Docs or by visiting https://pycomm3.dev.

Contributions

If you’d like to contribute or are having an issue, please read the Contributing guidelines.

Highlighted Features

• generic_message for extra functionality not directly implemented

  • working similar to the MSG instruction in Logix, arguments similar to the MESSAGE properties

  • See the examples section for things like getting/setting drive parameters, IP configuration, or uploading an EDS file

  • used internally to implement some of the other methods (get/set_plc_time, forward open/close, etc)

• simplified data types

  • allows use of standard Python types by abstracting CIP implementation details away from the user

  • strings use normal Python str objects, does not require handling of the LEN and DATA attributes separately

  • custom string types are also identified automatically and not limited to just the builtin one

  • BOOL arrays use normal Python bool objects, does not require complicated bit shifting of the DWORD value

  • powerful type system to allow types to represent any CIP object and handle encoding/decoding the object

LogixDriver Overview

Creating a driver is simple, only a path argument is required. The path can be the IP address, IP and slot, or a full CIP route, refer to the documentation for more details. The example below shows how to create a simple driver and print some of the information collected about the device.

from ciplink import LogixDriver

with LogixDriver('10.20.30.100/1') as plc:
    print(plc)
    # OUTPUT:
    # Program Name: PLCA, Device: 1756-L83E/B, Revision: 28.13

    print(plc.info)
    # OUTPUT:
    # {'vendor': 'Rockwell Automation/Allen-Bradley', 'product_type': 'Programmable Logic Controller',
    #  'product_code': 166, 'revision': {'major': 28, 'minor': 13}, 'status': b'`0', 'serial': 'ffffffff',
    #  'product_name': '1756-L83E/B', 'keyswitch': 'REMOTE RUN', 'name': 'PLCA'}

class Tag(NamedTuple):
    tag: str  # the name of the tag, does not include ``{<# elements>}`` from request
    value: Any  # value read or written, may be ``None`` if an error occurred
    type: Optional[str] = None  # data type of tag, including ``[<# elements>]`` from request
    error: Optional[str] = None  # ``None`` if successful, else the CIP error or exception thrown

with LogixDriver('10.20.30.100') as plc:
    plc.read('tag1', 'tag2', 'tag3')  # read multiple tags
    plc.read('array{10}') # read 10 elements starting at 0 from an array
    plc.read('array[5]{20}') # read 20 elements starting at elements 5 from an array
    plc.read('string_tag')  # read a string tag and get a string
    plc.read('a_udt_tag') # the response .value will be a dict like: {'attr1`: 1, 'attr2': 'a string', ...}

    # writes require a sequence of tuples of [(tag name, value), ... ]
    plc.write('tag1', 0)  # single writes do not need to be passed as a tuple
    plc.write(('tag1', 0), ('tag2', 1), ('tag3', 2))  # write multiple tags
    plc.write(('array{5}', [1, 2, 3, 4, 5]))  # write 5 elements to an array starting at the 0 element
    plc.write('array[10]{5}', [1, 2, 3, 4, 5])  # write 5 elements to an array starting at element 10
    plc.write('string_tag', 'Hello World!')  # write to a string tag with a string
    plc.write('string_array[2]{5}', 'Write an array of strings'.split())  # write an array of 5 strings starting at element 2
    plc.write('a_udt_tag', {'attr1': 1, 'attr2': 'a string', ...})  # can also use a dict to write a struct

    # Check the results
    results = plc.read('tag1', 'tag2', 'tag3')
    if all(results):
        print('They all worked!')
    else:
        for result in results:
            if not result:
                print(f'Reading tag {result.tag} failed with error: {result.error}')

Unit Testing

pytest is used for unit testing. The tests directory contains an L5X export of the testing program that contains all tags necessary for testing. The only requirement for testing (besides a running PLC with the testing program) is the environment variable PLCPATH for the PLC defined.

set PLCPATH=192.168.1.100
pytest --ignore tests/online/test_demo_plc.py

License

ciplink is distributed under the MIT License