A Python Ethernet/IP library for communicating with Allen-Bradley PLCs.
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 and Micro800 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.
Setup
The package can be installed from PyPI using pip: pip install pycomm3 or python -m pip install pycomm3.
Optionally, you may configure logging using the Python standard logging library.
Documentation
This README covers a basic overview of the library, full documentation can be found on Read the Docs.
Highlighted Features
simple API, only 1 read method and 1 write method for tags.
does not require using different methods for different data types
requires the tag name only, no other information required from the user
automatically manages request/response size to pack as many requests into a single packet
automatically handles fragmented requests for large tags that can’t fit in a single packet
read support the reading of an entire structure
does not require reading of each attribute separately
returns a value dict {attribute: value}
New - write supports full structure writing
Experimental support added in v0.7.0
value should be a list/tuple of values for each attribute, nested for arrays and other structures
not recommended for built-in types (TIMER, CONTROL, COUNTER, etc)
all or nothing, does not update only parts of a struct
simplified data types
strings use normal Python str objects, does not require reading/writing of the LEN and DATA attributes
BOOL arrays use normal Python bool objects, does not require complicated bit shifting of the DWORD value
uploads the tag list and data type definitions from the PLC
no requirement for user to determine tags available (like from an L5X export)
controller-scoped tags by default, program-scoped tags are optional
definitions are required for read/write methods
automatically enables/disables different features based on the target PLC
Extended Forward Open (EN2T or newer and v20+)
Symbol Instance Addressing (Logix v21+)
detection of Micro800 and disables unsupported features (CIP Path, Ex. Forward Open, Instance Addressing, etc)
additional methods for:
getting/setting the PLC WallClockTime
separate generic read/write methods that work similar to the MSG instruction in Logix
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 for more complex routing
first 2 examples will be replaced with the full path automatically, they’re there for convenience.
enet/backplane (or bp) are for port selection, easy to remember symbols for standard CIP routing pairs
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. 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 retrieved and cached.
Tag Definitions and Data Types
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}.
Definitions for structures are accessible from the data_types attribute. These include things like User-Defined Data Types (UDT), Add-On Instructions (AOI), strings, and pre-defined types (TIMER, COUNTER, etc). For structure tags (tag['tag_type'] == 'struct'), the data type definition will be stored in the data_type attribute. ('atomic' tags will only have a string with their data type name: 'DINT', 'REAL', ...).
For details on the information contained and the structure of the definitions, refer the to the Documentation.
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.
TODO
(wip) - improve documentation and include more real-world example scripts
(not started) - make API case insensitive
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.