A PLC communication library for Python
Project description
pycomm3 is a Python 3 fork of pycomm, which is a native python library for communicating with PLCs using Ethernet/IP. The initial Python 3 translation was done in this fork, this library seeks to continue and expand upon the great work done by the original pycomm developers. This library supports Ethernet/IP communications with Allen-Bradley Control & Compact Logix PLCs. pycomm has support for SLC and MicroLogix PLCs, but they have not been ported yet. The module still exists in the package, but is broken and will raise a NotImplementedError on import. pylogix is another library with similar features (including Python 2 support), thank you to them for their hard work as well. Referencing pylogix code was a big help in implementing some features missing from pycomm. This library is only supported on Python 3.6 and up.
Disclaimer
PLCs can be used to control heavy or dangerous equipment, this library is provided ‘As Is’ and makes no guarantees on it’s 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 Control/Compact Logix PLCs.
Implementation
The Logix5000 Controller Data Access Manual, available here Rockwell Developer How-to Guides, was used to implement the Ethernet/IP features in this library. Features like reading tags/arrays, writing tags/arrays, getting the tag list are all implemented based on the Data Access Manual. The Rockwell KB Article CIP Messages References 748424 lists many useful KB Articles for using the MSG instruction to perform various Ethernet/IP services. The Rockwell Knowledge Base Article 23341 was used to implement feature for getting the program name of the controller. Article 28917 was used for collecting other controller information.
Setup
The package can be installed from
PIP:
pip install pycomm3
Basic Usage
Connect to a PLC and get some basic information about it. The path argument is the only one required, and it has 3 forms:
IP Address Only (10.20.30.100) - Use if PLC is in slot 0 or if connecting to CompactLogix
IP Address/Slot (10.20.30.100/1) - Use if PLC is not in slot 0
- CIP Routing Path (10.20.30.100/backplane/3/enet/10.20.40.100/backplane/0) - Use if needing to route thru a backplane
first 2 examples will replaced with the full path automatically, they’re there for convenience.
enet/backplane (or bp) are for port selection, standard CIP routing but without having to remember which port is what value.
from pycomm3 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, 'version_major': 28, 'version_minor': 13, 'revision': '28.13', 'serial': 'FFFFFFFF', # 'device_type': '1756-L83E/B', 'keyswitch': 'REMOTE RUN', 'name': 'PLCA'}
By default, when creating the LogixDriver object, it will open a connection to the plc, read the program name, get the controller info, and get all the controller scoped tags. Using the init_tags kwarg will enable/disable automatically getting the controller tag list, and init_info will enable/disable program name and controller info loading. By reading the tag list first, this allows us to cache all the tag type/structure information, including the instance ids for all the tags. This information allows the read/write methods to require only the tag name. If your project will require program-scoped tags, be sure to set the init_program_tags kwarg. By default, only the controller-scoped tags will be read and cached. Calling plc.get_tag_list(program='*') will also have the same effect.
Symbol Instance Addressing is only available on v21+, if the PLC is on a firmware lower than that, getting the controller info will automatically disable that feature. If you disable init_info and are using a controller on a version lower than 21, set the plc.use_instance_ids attribute to false or your reads/writes will fail.
Tag Definitions
Tag definitions are uploaded from the controller automatically when connecting. This allows the read/writing methods to work. These definitions contain information like instance ids and structure size and composition. This information allows for many optimizations and features that other similar libraries do not offer. The old pycomm API does not depend on these, but the new read/write methods do. The tag definitions are accessible from the tags attribute. The tags property is a dict of {tag name: definition}.
Tag Information Collected:
{ 'tag1': { 'tag_name': 'tag1', # same as key 'dim': 0, # number of dimensions of array (0-3) 'instance_id': # used for reads/writes on v21+ controllers 'alias': True/False, # if the tag is an alias to another (this is not documented, but an educated guess found thru trial and error 'external_access': 'Read/Write', # string value of external access setting 'dimensions': [0, 0, 0] # array dimensions 'tag_type': 'atomic', 'data_type' : 'DINT' # string value of an atomic type } 'tag2' : { ... 'tag_type': 'struct', 'data_type': { 'name': 'TYPE', # name of structure, udt, or aoi 'internal_tags': { 'attribute': { # is an atomic type 'offset': 0 # byte offset for members within the struct, used mostly for reading an entire structure 'tag_type': 'atomic', 'data_type: 'Type', # name of data type 'bit': 0 # optional, exists if element is mapped to a bit of a dint or element of a bool array 'array': 0, # optional, length of error if the attribute is an array } 'attribute2': { # is a struct ..., 'tag_type': 'struct', 'data_type': { 'name': 'TYPE', # name of data type, 'internal_tags' : { # definition of all tags internal/hidden and public attributes ... # offset/array/bit/tag_type/data_type }, 'attributes' : [...], # list of public attributes (shown in Logix) 'template' : {...}, # used internally } } ... } } } ... }
COM Usage
For Windows clients, a COM server is also available. This way pycomm3 can be used from VBA in Excel like RSLinx.
To register, run the following command: python -m pycomm3 --register
VBA Example:
Sub Test() Dim plc As Object: Set plc = CreateObject("Pycomm3.COMServer") plc.ip_address = "10.20.30.100" plc.slot = 1 plc.Open Debug.Print plc.read_tag("Tag1") Debug.Print plc.get_plc_name # also stores the name in plc.name Debug.Print plc.name plc.Close End Sub
Unit Testing
pytest is used for unit testing. The tests directory contains an L5X export of the Pycomm3_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.
License
pycomm3 is distributed under the MIT License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.