Switch Management Objects#

EtherNet/IP switch management: Device Level Ring (DLR), QoS, Base Switch, SNMP, Power Management, RSTP (Bridge/Port), and Parallel Redundancy Protocol (PRP).

[ODVA CIP Vol 2] Wrappers for EtherNet/IP switch management objects: Device Level Ring (class 0x47, §5-6), QoS (class 0x48, §5-7), Base Switch (class 0x51, §5-8), Simple Network Management (SNMP) (class 0x52, §5-9), Power Management (class 0x53, §5-10), RSTP Bridge (class 0x54, §5-11), RSTP Port (class 0x55, §5-12), Parallel Redundancy Protocol (PRP) (class 0x56, §5-13), and PRP Nodes Table (class 0x57, §5-14).

class icspacket.proto.cip.objects.switch.BaseSwitchObject(connection: CIP_Connection, instance: int = 1)[source]#

Basic status information for a managed Ethernet switch device (See CIP Vol 2, §5-8).

Devices implement no more than one instance. Attributes 6-8 are bitmaps packed across port_mask_size DWORDs (one bit per port) and attribute 14 is a nested, variably-sized structure whose inner port-mask array is itself sized by port_mask_size; all four are exposed as raw bytes rather than a fixed schema.

device_up_time: CIPAttribute[int]#: Seconds since the device was powered up (attribute 1).

total_port_count: CIPAttribute[int]#: Number of physical ports available (attribute 2).

system_firmware_version: CIPAttribute[str]#: Human-readable System Firmware Version, empty if not configured (attribute 3).

power_source: CIPAttribute[int]#: Bitmap of power source/supply status, 2 bits per source (attribute 4, See Table 5-8.4).

port_mask_size: CIPAttribute[int]#: Number of DWORDs in each port-mask bitmap attribute, minimum 4 (attribute 5).

existing_ports: CIPAttribute[bytes]#: Bitmap (one bit per port) of ports physically present in the switch housing; size in DWORDs given by port_mask_size (attribute 6, optional).

global_port_admin_state: CIPAttribute[bytes]#: Bitmap of each port’s Admin state; size in DWORDs given by port_mask_size (attribute 7, optional).

global_port_link_status: CIPAttribute[bytes]#: Bitmap of each port’s link status; size in DWORDs given by port_mask_size (attribute 8).

system_boot_loader_version: CIPAttribute[str]#: Human-readable System Boot Loader Version, empty if not configured (attribute 9, optional).

contact_status: CIPAttribute[int]#: Bitmap of switch contact closure status, 2 bits per contact (attribute 10, optional, See Table 5-8.8).

aging_time: CIPAttribute[int]#: Timeout in seconds for aging out dynamically-learned forwarding information, 0 = learning off, default 300 (attribute 11, optional).

temperature_c: CIPAttribute[int]#: Switch temperature in degrees Celsius (attribute 12, optional).

temperature_f: CIPAttribute[int]#: Switch temperature in degrees Fahrenheit (attribute 13, optional).

resiliency_protocol_list: CIPAttribute[bytes]#: List of resiliency protocol entities used by the switch: a UINT count followed by, for each entry, a Resiliency Protocol Select value, a port-mask bitmap sized by port_mask_size, and a path to the protocol’s own object (attribute 14, optional, See §5-8.3.3.7).

get_class_attribute(attribute: int) → bytes[source]#: Read a Base Switch class attribute from instance 0 (See §5-8.3.1, Table 5-8.2).

class icspacket.proto.cip.objects.switch.BridgeIdentifier(priority: int, mac: str)[source]#: Combined 2-byte priority + 6-byte MAC bridge identifier (RSTP Bridge Object attribute 12; RSTP Port Object attributes 3, 15, and 17, See IEEE 802.1D-2004 §17.18.6).

class icspacket.proto.cip.objects.switch.DLRObject(connection: CIP_Connection, instance: int = 1)[source]#

Configures and monitors a Device Level Ring (DLR) network node (See CIP Vol 2, §5-6).

network_topology: CIPAttribute[int]#: 0 = Linear, 1 = Ring (attribute 1).

network_status: CIPAttribute[int]#: Current DLR network status (attribute 2, See Table 5-6.3).

ring_supervisor_status: CIPAttribute[int]#: Current Ring Supervisor status; valid only while ring_supervisor_config.enable is set (attribute 3).

ring_supervisor_config: CIPAttribute[RingSupervisorConfig]#: Ring Supervisor configuration (attribute 4).

ring_faults_count: CIPAttribute[int]#: Number of times the ring has transitioned from Normal to Ring Fault state (attribute 5).

last_active_node_on_port_1: CIPAttribute[NodeAddress]#: IP/MAC address of the last node this device detected on Port 1 (attribute 6).

last_active_node_on_port_2: CIPAttribute[NodeAddress]#: IP/MAC address of the last node this device detected on Port 2 (attribute 7).

ring_protocol_participants_count: CIPAttribute[int]#: Number of nodes that responded to the last Discover_Topology sequence (attribute 8).

active_supervisor_address: CIPAttribute[NodeAddress]#: IP/MAC address of the active Ring Supervisor (attribute 10).

active_supervisor_precedence: CIPAttribute[int]#: Precedence value of the active Ring Supervisor (attribute 11).

capability_flags: CIPAttribute[int]#: Bitmap of DLR capabilities supported by this device (attribute 12, See Table 5-6.10).

redundant_gateway_config: CIPAttribute[RedundantGatewayConfig]#: Redundant Gateway configuration (attribute 13).

redundant_gateway_status: CIPAttribute[int]#: Current Redundant Gateway status (attribute 14, See Table 5-6.11).

active_gateway_address: CIPAttribute[NodeAddress]#: IP/MAC address of the active gateway (attribute 15).

active_gateway_precedence: CIPAttribute[int]#: Precedence value of the active gateway (attribute 16).

get_class_attribute(attribute: int) → bytes[source]#: Read a DLR class attribute from instance 0 (See §5-6.2, Table 5-6.1).

verify_fault_location() → bytes[source]#: Invoke Verify_Fault_Location (service 0x4B), requesting a beacon- based ring fault check.

clear_rapid_faults() → bytes[source]#: Invoke Clear_Rapid_Faults (service 0x4C), re-arming rapid fault/ restart counters.

restart_sign_on() → bytes[source]#: Invoke Restart_Sign_On (service 0x4D), restarting the Sign_On sequence used to build the ring node list.

clear_gateway_partial_fault() → bytes[source]#: Invoke Clear_Gateway_Partial_Fault (service 0x4E), clearing a Redundant Gateway partial fault condition.

class icspacket.proto.cip.objects.switch.NetworkManagerIdentifier(identifier_format: int, identifier: str)[source]#

Network manager address (SNMP Object attributes 3 and 4, See §5-9.3.2.3).

identifier_format: int#: 0 = unconfigured, 1 = IPv4 dotted-decimal, 2 = domain name.

identifier: str#: Address value; empty when identifier_format is 0.

class icspacket.proto.cip.objects.switch.NodeAddress(ip: IPv4Address, mac: str)[source]#: IP/MAC address pair identifying a node on the ring (DLR Object attributes 6, 7, 10, and 15, See §5-6.3.2.1).

class icspacket.proto.cip.objects.switch.PRPNodesTableObject(connection: CIP_Connection, instance: int = 1)[source]#

Records PRP-capable nodes detected on the network (See CIP Vol 2, §5-14).

Devices may implement one or more instances.

prp_nodes_table_count: CIPAttribute[int]#: Number of nodes in the PRP Nodes Table (attribute 1).

prp_nodes_table: CIPAttribute[Collection[PrpNodeEntry]]#: PRP node entries, one per prp_nodes_table_count (attribute 2).

get_class_attribute(attribute: int) → bytes[source]#: Read a PRP Nodes Table class attribute from instance 0 (See §5-14.3.1, Table 5-14.1).

class icspacket.proto.cip.objects.switch.PRPObject(connection: CIP_Connection, instance: int = 1)[source]#

Configuration and diagnostic interface for Parallel Redundancy Protocol (PRP) dual-LAN operation (See CIP Vol 2, §5-13, IEC 62439-3 clause 4).

prp_enable: CIPAttribute[int]#: 1 = PRP enabled, 0 = disabled (default) (attribute 1).

node_type: CIPAttribute[int]#: 0 = deprecated PRP Mode 0, 1 = PRP Mode 1 (default) (attribute 2).

node_name: CIPAttribute[str]#: Human-readable name of the PRP Link Redundancy Entity, empty if unconfigured (attribute 3).

version_name: CIPAttribute[str]#: Human-readable version name of the PRP Link Redundancy Entity (attribute 4).

prp_mac_address: CIPAttribute[str]#: MAC address used by PRP (attribute 5).

duplicate_discard: CIPAttribute[int]#: 0 = doNotDiscard, 1 = discard (default) (attribute 6).

transparent_reception: CIPAttribute[int]#: 0 = removeRCT (default), 1 = passRCT (attribute 7).

prp_interface_counters: CIPAttribute[PrpInterfaceCounters]#: Frame counters for Ports A/B and the interlink/DANP interface (attribute 8).

prp_duplicate_detection_counters: CIPAttribute[PrpDuplicateDetectionCounters]#: Duplicate-detection entry counters for Ports A/B (attribute 9).

prp_proxy_nodes_count: CIPAttribute[int]#: Number of nodes in the Proxy Nodes Table (attribute 10).

proxy_nodes_table: CIPAttribute[Collection[str]]#: MAC addresses of nodes this device proxies for, one per prp_proxy_nodes_count (attribute 11); the Get_Member service (0x18) is required by the spec for indexed access but is not implemented here.

prp_nodes_table_path: CIPAttribute[EPATH]#: Path to this device’s PRP Nodes Table object instance (attribute 12, optional).

get_class_attribute(attribute: int) → bytes[source]#: Read a PRP class attribute from instance 0 (See §5-13.3.1, Table 5-13.2).

class icspacket.proto.cip.objects.switch.PowerManagementObject(connection: CIP_Connection, instance: int = 1)[source]#

Marker wrapper for the Power Management Object (See CIP Vol 2, §5-10).

Volume 2 defines no attributes or services of its own beyond the base object described in Volume 1: only the behavioral requirement that a device whose Sleeping state support is enabled (base object attribute 6) must accept Wake-on-LAN “Magic Packets” to exit that state. This class exists so object_for() can resolve class 0x53; the base Volume 1 attributes/services are out of scope here.

class icspacket.proto.cip.objects.switch.PrpDuplicateDetectionCounters(entries_unique_count_a: int, entries_unique_count_b: int, entries_duplicate_count_a: int, entries_duplicate_count_b: int, entries_multiple_count_a: int, entries_multiple_count_b: int)[source]#: PRP Object attribute 9 payload (See §5-13.3.3.3, IEC 62439-3).

class icspacket.proto.cip.objects.switch.PrpInterfaceCounters(transmit_count_a: int, transmit_count_b: int, transmit_count_c: int, receive_count_a: int, receive_count_b: int, receive_count_c: int, wrong_lan_a_count: int, wrong_lan_b_count: int)[source]#: PRP Object attribute 8 payload (See §5-13.3.3.2, IEC 62439-3).

class icspacket.proto.cip.objects.switch.PrpNodeEntry(mac: str, time_last_seen_a: int, time_last_seen_b: int)[source]#

One entry in the PRP Nodes Table (PRP Nodes Table Object attribute 2, See §5-14.3.2, Table 5-14.2).

mac: str#: MAC address of the source node, as advertised by its PRP Supervision frames.

time_last_seen_a: int#: TimeTicks (1/100s) since the last frame from this node was received over LAN A, 0 upon registration.

time_last_seen_b: int#: TimeTicks (1/100s) since the last frame from this node was received over LAN B, 0 upon registration.

class icspacket.proto.cip.objects.switch.QoSObject(connection: CIP_Connection, instance: int = 1)[source]#

Configures 802.1Q tagging and DSCP values for EtherNet/IP traffic (See CIP Vol 2, §5-7).

dot1q_tag_enable: CIPAttribute[int]#: 1 = send 802.1Q tagged frames for CIP and IEEE 1588 messages, default 0 (attribute 1, conditional).

dscp_ptp_event: CIPAttribute[int]#: DSCP value for PTP (IEEE 1588) event messages, default 59 (attribute 2, conditional).

dscp_ptp_general: CIPAttribute[int]#: DSCP value for PTP (IEEE 1588) general messages, default 47 (attribute 3, conditional).

dscp_urgent: CIPAttribute[int]#: DSCP value for CIP transport class 0/1 Urgent priority messages, default 55 (attribute 4).

dscp_scheduled: CIPAttribute[int]#: DSCP value for CIP transport class 0/1 Scheduled priority messages, default 47 (attribute 5).

dscp_high: CIPAttribute[int]#: DSCP value for CIP transport class 0/1 High priority messages, default 43 (attribute 6).

dscp_low: CIPAttribute[int]#: DSCP value for CIP transport class 0/1 Low priority messages, default 31 (attribute 7).

dscp_explicit: CIPAttribute[int]#: DSCP value for CIP UCMM, transport class 2/3, and all other EtherNet/IP encapsulation messages, default 27 (attribute 8).

get_class_attribute(attribute: int) → bytes[source]#: Read a QoS class attribute from instance 0 (See §5-7.3, Table 5-7.2).

class icspacket.proto.cip.objects.switch.RSTPBridgeObject(connection: CIP_Connection, instance: int = 1)[source]#

Configuration and diagnostic interface for RSTP at the bridge level (See CIP Vol 2, §5-11, IEEE 802.1D-2004 clause 17).

Devices may implement multiple instances (e.g. one per VLAN). list_of_rstp_ports decodes greedily from its own Get_Attribute_Single response; its true length equals number_of_rstp_ports.

bridge_object_identification: CIPAttribute[str]#: Vendor-defined identification for this Bridge Object instance, empty if unused (attribute 1).

bridge_identifier_priority: CIPAttribute[int]#: Manageable component of the Bridge Identifier, range 0-61440 in steps of 4096, default 32768 (attribute 2).

transmit_hold_count: CIPAttribute[int]#: Limits the Port Transmit state machine’s transmission rate, range 1-10, default 6 (attribute 3).

number_of_rstp_ports: CIPAttribute[int]#: Number of RSTP ports associated with this bridge, default 2 (attribute 4).

list_of_rstp_ports: CIPAttribute[Collection[int]]#: RSTP Port Object instance numbers associated with this bridge, one per number_of_rstp_ports (attribute 5).

force_protocol_version: CIPAttribute[int]#: 0 = STP compatibility mode, 2 = normal operation (default) (attribute 6, optional).

bridge_max_age: CIPAttribute[int]#: Maximum age (in 1/256s units) of information transmitted by this bridge while Root, range 6.0-40.0s, default 20.0s (attribute 7, optional).

bridge_hello_time: CIPAttribute[int]#: Interval (in 1/256s units) between Configuration Message transmissions by Designated Ports, range 1.0-2.0s, default 2.0s (attribute 8, optional).

bridge_forward_delay: CIPAttribute[int]#: Delay (in 1/256s units) used to transition Root/Designated Ports to Forwarding, range 4.0-30.0s, default 15.0s (attribute 9, optional).

time_since_topology_change: CIPAttribute[int]#: Time (in 1/256s units) since the last topology change (attribute 10, optional).

topology_change_count: CIPAttribute[int]#: Total number of topology changes detected since last reset (attribute 11, optional).

designated_root: CIPAttribute[BridgeIdentifier]#: Bridge Identifier of the root of the spanning tree (attribute 12, optional).

root_cost: CIPAttribute[int]#: Cost of the path to the root as seen from this bridge, default 200,000 for 100Mbps (attribute 13, optional).

root_port: CIPAttribute[int]#: Port identifier of the port offering the lowest-cost path to the root, 0 = undefined (attribute 14, optional).

max_age: CIPAttribute[int]#: Actual Max Age value currently in use by this bridge (in 1/256s units), range 6.0-40.0s, default 20.0s (attribute 15, optional).

hello_time: CIPAttribute[int]#: Actual Hello Time value currently in use by this bridge (in 1/256s units), range 1.0-2.0s, default 2.0s (attribute 16, optional).

forward_delay: CIPAttribute[int]#: Actual Forward Delay value currently in use by this bridge (in 1/256s units), range 4.0-30.0s, default 15.0s (attribute 17, optional).

get_class_attribute(attribute: int) → bytes[source]#: Read an RSTP Bridge class attribute from instance 0 (See §5-11.3.1, Table 5-11.2).

class icspacket.proto.cip.objects.switch.RSTPPortObject(connection: CIP_Connection, instance: int = 1)[source]#

Configuration and diagnostic interface for RSTP at the port level (See CIP Vol 2, §5-12, IEEE 802.1D-2004 clause 17).

At least 2 instances are required wherever RSTPBridgeObject is implemented.

bridge_object_instance: CIPAttribute[int]#: RSTP Bridge Object instance associated with this port, default 1 (attribute 1).

ethernet_link_instance: CIPAttribute[int]#: Ethernet Link Object instance associated with this port, default 0 (attribute 2).

reference_bridge_identifier: CIPAttribute[BridgeIdentifier]#: Bridge Identifier of the bridge this port is associated with (attribute 3).

port_mac_address: CIPAttribute[str]#: MAC address unique to this port instance (attribute 4).

rstp_port_enable: CIPAttribute[int]#: 0 = RSTP disabled (default), 1 = RSTP enabled (attribute 5).

port_identifier_priority: CIPAttribute[int]#: Manageable component of the Port Identifier, range 0-240 in steps of 16, default 128 (attribute 6).

oper_edge_port: CIPAttribute[int]#: Current operEdgePort value as determined by the Bridge Detection state machine, default 1/True (attribute 7).

port_state: CIPAttribute[int]#: 1=Disabled (default), 2=Blocking, 3=Listening, 4=Learning, 5=Forwarding, 6=Broken (attribute 8).

mcheck: CIPAttribute[int]#: Set by management to force the Port Protocol Migration state machine to transmit RST BPDUs, default 0/False (attribute 9, optional).

port_path_cost: CIPAttribute[int]#: Contribution of this port to the path cost of paths toward the spanning tree root, 0 = use automatically calculated default (attribute 10, optional).

port_admin_edge_port: CIPAttribute[int]#: Administrative value of the Edge Port parameter, default 0/False (attribute 11, optional).

admin_point_to_point_mac: CIPAttribute[int]#: 0=forceTrue, 1=forceFalse, 2=auto (default) (attribute 12, optional).

oper_point_to_point_mac: CIPAttribute[int]#: Operational point-to-point status of the attached LAN segment, default 0/False (attribute 13, optional).

port_role: CIPAttribute[int]#: 0=Unknown (default), 1=Alternate/Backup, 2=Root, 3=Designated (attribute 14, optional).

designated_root: CIPAttribute[BridgeIdentifier]#: Bridge Identifier recorded as Root in Configuration BPDUs for this port’s segment (attribute 15, optional).

designated_root_path_cost: CIPAttribute[int]#: Path cost of the Designated Port of this port’s segment, default 200,000 (attribute 16, optional).

designated_bridge_identifier: CIPAttribute[BridgeIdentifier]#: Bridge Identifier this port considers the Designated Bridge for its segment (attribute 17, optional).

designated_port: CIPAttribute[int]#: Port Identifier of the port on the Designated Bridge for this port’s segment, default 0 (attribute 18, optional).

forward_transitions_count: CIPAttribute[int]#: Number of times this port transitioned from Learning to Forwarding (attribute 19, optional).

get_class_attribute(attribute: int) → bytes[source]#: Read an RSTP Port class attribute from instance 0 (See §5-12.3.1, Table 5-12.2).

class icspacket.proto.cip.objects.switch.RedundantGatewayConfig(enable: int, gateway_precedence: int, advertise_interval: int, advertise_timeout: int, learning_update_enable: int)[source]#

DLR Object attribute 13 payload (See §5-6.3.2.1, Table 5-6.9).

enable: int#: 1 = Redundant Gateway capability enabled for this device.

gateway_precedence: int#: Priority used to select the active gateway; 0 = highest.

advertise_interval: int#: Advertise frame transmission interval, in microseconds.

advertise_timeout: int#: Time without receiving an Advertise frame before declaring a fault, in microseconds.

learning_update_enable: int#: 1 = send a Link_Status/Neighbor_Check frame to speed up address-table updates on failover.

class icspacket.proto.cip.objects.switch.RingSupervisorConfig(enable: int, precedence: int, beacon_interval: int, beacon_timeout: int, vlan_id: int)[source]#

DLR Object attribute 4 payload (See §5-6.3.2.1, Table 5-6.4).

enable: int#: 1 = Ring Supervisor capability enabled for this device.

precedence: int#: Priority used to select the active Ring Supervisor; 0 = highest.

beacon_interval: int#: Beacon frame transmission interval, in microseconds.

beacon_timeout: int#: Time without receiving a Beacon frame before declaring a ring fault, in microseconds.

vlan_id: int#: VLAN ID used for DLR protocol frames.

class icspacket.proto.cip.objects.switch.SNMPObject(connection: CIP_Connection, instance: int = 1)[source]#

Configures the SNMP Agent embedded in a device (See CIP Vol 2, §5-9).

A device implementing this object provides exactly one instance.

snmp_agent: CIPAttribute[int]#: 1 = SNMP Agent enabled (default), 0 = disabled (attribute 1).

snmp_agent_version: CIPAttribute[int]#: 1 = SNMPv1, 3 = SNMPv3, 31 = bilingual SNMPv1+v3 (attribute 2).

primary_network_manager: CIPAttribute[NetworkManagerIdentifier]#: Primary Network Manager address that TrapPdus are sent to (attribute 3).

secondary_network_manager: CIPAttribute[NetworkManagerIdentifier]#: Secondary Network Manager address that TrapPdus are sent to (attribute 4).

notifications: CIPAttribute[int]#: 1 = sending of SNMP TrapPdus enabled (default), 0 = disabled (attribute 5).

trap_type: CIPAttribute[int]#: 1 = TrapV1Pdu, 2 = TrapV2Pdu (requires snmp_agent_version 3 or 31) (attribute 6, optional).

get_class_attribute(attribute: int) → bytes[source]#: Read an SNMP class attribute from instance 0 (See §5-9.3.1, Table 5-9.2).