LogixDriver API#

class pycomm3.LogixDriver(path, *args, init_tags=True, init_program_tags=True, **kwargs)[source]#

An Ethernet/IP Client driver for reading and writing tags in ControlLogix and CompactLogix PLCs.

__init__(path, *args, init_tags=True, init_program_tags=True, **kwargs)[source]#
Parameters:

  • path (str) –

    CIP path to intended target

    The path may contain 3 forms:

    • IP Address Only (10.20.30.100) - Use for a ControlLogix PLC is in slot 0 or if connecting to a CompactLogix or Micro800 PLC.

    • IP Address/Slot (10.20.30.100/1) - (ControlLogix) if PLC is not in slot 0

    • CIP Routing Path (1.2.3.4/backplane/2/enet/6.7.8.9/backplane/0) - Use for more complex routing.

    Note

    Both the IP Address and IP Address/Slot options are shortcuts, they will be replaced with the CIP path automatically. The enet / backplane (or bp) segments are symbols for the CIP routing port numbers and will be replaced with the correct value.

  • init_tags (bool) – if True (default), uploads all controller-scoped tag definitions on connect

  • init_program_tags (bool) – if False, bypasses uploading program-scoped tags. set to False if there are a lot of program tags and you aren’t using any of them to decrease tag upload times.

Tip

Initialization of tags is required for the read() and write() to work. This is because they require information about the data type and structure of the tags inside the controller. If opening multiple connections to the same controller, you may disable tag initialization in all but the first connection and set plc2._tags = plc1.tags to prevent needing to upload the tag definitions multiple times.

open()[source]#

Creates a new Ethernet/IP socket connection to target device and registers a CIP session.

Returns:

True if successful, False otherwise

property revision_major: int#

Returns the major revision for the PLC or 0 if not available

Return type:

int

property tags: dict#

Read-only property to access all the tag definitions uploaded from the controller.

Return type:

dict

property tags_json#

Read-only property to access all the tag definitions uploaded from the controller. Filters out any non-JSON serializable objects.

property data_types: dict#

Read-only property for access to all data type definitions uploaded from the controller.

Return type:

dict

property connected: bool#

Read-Only Property to check whether or not a connection is open.

Return type:

bool

Returns:

True if a connection is open, False otherwise

property info: dict#

Property containing a dict of all the information collected about the connected PLC.

Fields:

  • vendor - name of hardware vendor, e.g. 'Rockwell Automation/Allen-Bradley'

  • product_type - typically 'Programmable Logic Controller'

  • product_code - code identifying the product type

  • revision - dict of {‘major’: <major rev (int)>, ‘minor’: <minor rev (int)>}

  • serial - hex string of PLC serial number, e.g. 'FFFFFFFF'

  • product_name - string value for PLC device type, e.g. '1756-L83E/B'

  • keyswitch - string value representing the current keyswitch position, e.g. 'REMOTE RUN'

  • name - string value of the current PLC program name, e.g. 'PLCA'

The following fields are added from calling get_tag_list()

  • programs - dict of all Programs in the PLC and their routines, {program: {'routines': [routine, ...}...}

  • tasks - dict of all Tasks in the PLC, {task: {'instance_id': ...}...}

  • modules - dict of I/O modules in the PLC, {module: {'slots': {1: {'types': ['O,' 'I', 'C']}, ...}, 'types':[...]}...}

Return type:

dict

property name: Optional[str]#
Return type:

Optional[str]

Returns:

name of PLC program

get_plc_name()[source]#

Requests the name of the program running in the PLC. Uses KB 23341 for implementation.

Return type:

str

Returns:

the controller program name

get_plc_info()[source]#

Reads basic information from the controller, returns it and stores it in the info property.

Return type:

dict

get_plc_time(fmt='%A, %B %d, %Y %I:%M:%S%p')[source]#

Gets the current time of the PLC system clock. The value attribute will be a dict containing the time in 3 different forms, datetime is a Python datetime.datetime object, microseconds is the integer value epoch time, and string is the datetime formatted using strftime and the fmt parameter.

Parameters:

fmt (str) – format string for converting the time to a string

Return type:

Tag

Returns:

a Tag object with the current time

set_plc_time(microseconds=None)[source]#

Set the time of the PLC system clock.

Parameters:

microseconds (Optional[int]) – None to use client PC clock, else timestamp in microseconds to set the PLC clock to

Return type:

Tag

Returns:

Tag with status of request

get_tag_list(program=None, cache=True)[source]#

Reads the tag list from the controller and the definition for each tag. Definitions include tag name, tag type (atomic vs struct), data type (including nested definitions for structs), external access, dimensions defined (0-3) for arrays and their length, etc.

Note

For program scoped tags the tag[‘tag_name’] will be 'Program:{program}.{tag_name}'. This is so the tag list can be fed directly into the read function.

Parameters:

  • program (Optional[str]) – scope to retrieve tag list, None for controller-only tags, '*' for all tags, else name of program

  • cache (bool) – store the retrieved list in the tags property. Disable if you wish to get tags retrieved to not overwrite the currently cached definition. For instance if you’re checking tags in a single program but currently reading controller-scoped tags.

Return type:

List[dict]

Returns:

a list containing dicts for each tag definition collected

read(*tags)[source]#

Read the value of tag(s). Automatically will split tags into multiple requests by tracking the request and response size. Will use the multi-service request to group many tags into a single packet and also will automatically use fragmented read requests if the response size will not fit in a single packet. Supports arrays (specify element count in using curly braces (array{10}). Also supports full structure reading (when possible), return value will be a dict of {attribute name: value}.

Parameters:

tags (str) – one or many tags to read

Return type:

Union[Tag, List[Tag]]

Returns:

a single or list of Tag objects

write(*tags_values)[source]#

Write to tag(s). Automatically will split tags into multiple requests by tracking the request and response size. Will use the multi-service request to group many tags into a single packet and also will automatically use fragmented read requests if the response size will not fit in a single packet. Supports arrays (specify element count in using curly braces (array{10}). Also supports full structure writing (when possible), value must be a sequence of values or a dict of {attribute: value} matching the exact structure of the destination tag.

Parameters:

tags_values (Union[str, int, float, bool, List[Union[int, float, bool, str]], Dict[str, Union[int, float, bool, str, List[Union[int, float, bool, str]], Dict[str, ForwardRef]]], Tuple[str, Union[int, float, bool, str, List[Union[int, float, bool, str]], Dict[str, Union[int, float, bool, str, List[Union[int, float, bool, str]], Dict[str, ForwardRef]]]]]]) – (tag, value) tuple or sequence of tag and value tuples [(tag, value), …]

Return type:

Union[Tag, List[Tag]]

Returns:

a single or list of Tag objects.

get_tag_info(tag_name)[source]#

Returns the tag information for a tag collected during the tag list upload. Can be a base tag or an attribute.

Parameters:

tag_name (str) – name of tag to get info for

Return type:

Optional[dict]

Returns:

a dict of the tag’s definition