GOOSE Client#

icspacket.proto.iec61850.goose.GOOSE_ETHER_TYPE = 35000#

Ethernet frames carrying GOOSE (Generic Object Oriented Substation Event) traffic use this EtherType, letting the sniffer/filter below recognize them on the wire.

class icspacket.proto.iec61850.goose.PDU(app_id: int = 0, length: int = 0, reserved1: int = 0, reserved2: int = 0, raw_apdu: bytes = b'')[source]#

Binary layout this library reads from and writes to the Ethernet (ISO/IEC 8802-3) payload for both GOOSE and GSE management traffic.

Every instance corresponds to one on-the-wire frame: a short fixed header (application identifier plus two reserved words) followed by the Application Protocol Data Unit (APDU) that actually carries the GOOSE or GSE management data.

app_id: int = 0#

AppID header word identifying which application instance this frame is intended for.

length: int = 0#

Total on-the-wire byte count for this PDU, covering the 8-byte header made up of app_id, length, reserved1, and reserved2.

raw_apdu: bytes = b''#

Raw bytes of the APDU payload. Depending on how the PDU was produced or decoded, this may already be ASN.1 BER-encoded, or still be a plain bytes object awaiting encoding.

build() → bytes[source]#

Construct a serialized representation of the PDU.

If the raw_apdu field has a ber_encode() method, the APDU is encoded before serialization. The length field is automatically recalculated to include the header.

Returns:

A serialized PDU ready for transmission over Ethernet.

Return type:

bytes

Raises:

TypeError – If raw_apdu is not a byte sequence after encoding.

apdu(asn1_cls: type[_T]) → _T[source]#

Decode the APDU portion of the PDU.

Parameters:

asn1_cls (type) – ASN.1 class type implementing a ber_decode() method.

Returns:

Decoded APDU instance.

Return type:

_T

static from_octets(pctets: bytes) → PDU[source]#

Parse a serialized byte sequence into a PDU.

Parameters:

pctets (bytes) – Raw PDU bytes extracted from an Ethernet frame.

Returns:

A PDU instance parsed from the octets.

Return type:

PDU

class icspacket.proto.iec61850.goose.GOOSE_Client(iface: list[str] | str | None = None, callback: Callable[[Ether, PDU], None] | None = None, ether_type: int = 35000, inputs: list[str] | None = None, app_id: int | None = None, vlan_id: int | None = None)[source]#

Observer and Publisher for IEC 61850 GOOSE (Generic Object Oriented Substation Event) messages.

This class provides a dual role:

  1. Observer - It captures and filters incoming GOOSE PDUs using Scapy’s asynchronous sniffer. Incoming PDUs can be accessed through a queue or by registering a callback.

  2. Publisher - It constructs and transmits GOOSE PDUs over Ethernet, supporting both raw PDUs and higher-level APDUs. VLAN tagging is supported where required by the application environment.

Clients can be used as context managers to ensure proper startup and teardown of the sniffer. For example:

with GOOSE_Client(iface="eth0") as client:
    # Capture one incoming PDU
    incoming_pdu = client.recv_next()

    # Publish a new PDU (simple echo)
    client.publish_pdu("01:0c:cd:01:00:01", incoming_pdu)

Note

Publishing can be done without a sniffer running in the background, i.e. the with statement can be ignored.

Added in version 0.2.3.

Parameters:

  • iface (str | list[str] | None) – Optional capture interface or list of interfaces to sniff on. If multiple interfaces are provided, publishing requires explicit configuration of iface or all_interfaces=True.

  • callback (Callable[[Ether, PDU], None] | None) – Optional callback invoked for each received GOOSE frame. The callback receives the raw Ether frame and the decoded PDU.

  • ether_type (int) – EtherType filter for GOOSE traffic. Defaults to GOOSE_ETHER_TYPE.

  • inputs (list[str] | None) – Optional list of input files (pcap) for offline analysis.

  • app_id (int | None) – Default application identifier (AppID) to use when publishing.

  • vlan_id (int | None) – Default VLAN identifier to apply when publishing. If None, packets are sent without VLAN tagging unless overridden in the publish call.

property pkt_in: Queue[PDU]#

Queue of decoded PDUs captured by the observer.

Returns:

A thread-safe queue containing PDU objects.

Return type:

Queue[PDU]

start() → None[source]#

Start the observer and begin sniffing packets.

This resets the incoming PDU queue and clears the stop event.

stop(join: bool = False)[source]#

Stop the observer and terminate packet sniffing.

Tip

Use the join parameter to read out all remaining packets from PCAP files if specified in the constructor.

Parameters:

join (bool) – If True, block until the sniffer thread terminates.

listen_forever() → None[source]#

Continuously capture GOOSE packets until interrupted.

This method blocks the calling thread until stop() is invoked or a keyboard interrupt is received.

recv_next() → PDU[source]#

Retrieve the next decoded PDU from the capture queue.

Returns:

The next available PDU.

Return type:

PDU

Raises:

ConnectionError – If the sniffer is not currently running.

publish_pdu(addr: str, pdu: PDU, vlan_id: int | None = None, vlan_priority: int | None = None, iface: str | None = None, all_interfaces: bool = False) → None[source]#

Transmit a fully constructed PDU to the given destination address.

This is the low-level publishing method. It requires the caller to provide a complete PDU object (including encoded APDU). VLAN tagging and priority handling are supported.

Parameters:

  • addr (str) – Destination MAC address for the frame (typically a GOOSE multicast address).

  • pdu (PDU) – The protocol data unit to serialize and publish.

  • vlan_id (int | None) – VLAN identifier to use for this transmission. If None, the instance’s default VLAN ID is used. If still None, the frame is sent without VLAN tagging.

  • vlan_priority (int | None) – Optional VLAN priority code point (PCP) to apply. Ignored if vlan_id is None.

  • iface (str | None) – Explicit interface to publish on. If not provided, the default interface(s) configured in the client are used.

  • all_interfaces (bool) – If multiple interfaces were configured and this flag is True, the PDU is transmitted on all interfaces. If False and multiple interfaces exist, an explicit iface must be given.

Raises:

ValueError – If multiple interfaces are configured but no target interface was specified and all_interfaces is False.

publish(addr: str, aodu: Any, app_id: int | None = None, vlan_id: int | None = None, vlan_priority: int | None = None, iface: str | None = None, all_interfaces: bool = False) → None[source]#

Publish an APDU (Application Protocol Data Unit) directly as a GOOSE PDU.

This higher-level publishing method simplifies transmission by constructing the PDU automatically from the given APDU. The APDU may be a raw ASN.1 object (with a ber_encode() method) or already-encoded bytes.

Note

This method automatically wraps the APDU in a PDU with the appropriate AppID.

Parameters:

  • addr (str) – Destination MAC address for the frame (typically a GOOSE multicast address).

  • aodu (Any) – The APDU to embed in the outgoing PDU. Can be an ASN.1 object or raw bytes.

  • app_id (int | None) – Application identifier to use. If None, the default app_id set on the client instance is applied.

  • vlan_id (int | None) – VLAN identifier to use for this transmission. Overrides the instance default if provided.

  • vlan_priority (int | None) – Optional VLAN priority code point (PCP) to apply. Ignored if vlan_id is None.

  • iface (str | None) – Explicit interface to publish on. If not provided, the default interface(s) configured in the client are used.

  • all_interfaces (bool) – If multiple interfaces were configured and this flag is True, the PDU is transmitted on all interfaces. If False and multiple interfaces exist, an explicit iface must be given.

class icspacket.proto.iec61850.goose.Data#

ASN.1 Data type

PRESENT#

alias of PRESENT

array_TYPE#

alias of array

structure_TYPE#

alias of structure

class icspacket.proto.iec61850.goose.MMSString#

ASN.1 MMSString type

class icspacket.proto.iec61850.goose.FloatingPoint#

ASN.1 FloatingPoint type

class icspacket.proto.iec61850.goose.TimeOfDay#

ASN.1 TimeOfDay type

class icspacket.proto.iec61850.goose.IEC61850_Specific_Protocol#

ASN.1 IEC61850_Specific_Protocol type

PRESENT#

alias of PRESENT

class icspacket.proto.iec61850.goose.GSEMngtPdu#

ASN.1 GSEMngtPdu type

class icspacket.proto.iec61850.goose.GSERequestResponse#

ASN.1 GSERequestResponse type

PRESENT#

alias of PRESENT

class icspacket.proto.iec61850.goose.GSEMngtRequests#

ASN.1 GSEMngtRequests type

PRESENT#

alias of PRESENT

class icspacket.proto.iec61850.goose.GSEMngtResponses#

ASN.1 GSEMngtResponses type

PRESENT#

alias of PRESENT

class icspacket.proto.iec61850.goose.GetReferenceRequestPdu#

ASN.1 GetReferenceRequestPdu type

offset_TYPE#

alias of offset

class icspacket.proto.iec61850.goose.GetElementRequestPdu#

ASN.1 GetElementRequestPdu type

references_TYPE#

alias of references

class icspacket.proto.iec61850.goose.GSEMngtResponsePdu#

ASN.1 GSEMngtResponsePdu type

class positiveNegative_TYPE#

ASN.1 anonymous type GSEMngtResponsePdu__positiveNegative_TYPE part of GSEMngtResponsePdu

PRESENT#

alias of PRESENT

class responsePositive_TYPE#

ASN.1 anonymous type GSEMngtResponsePdu__positiveNegative__responsePositive_TYPE part of positiveNegative

result_TYPE#

alias of result_ANON_7

class icspacket.proto.iec61850.goose.RequestResults#

ASN.1 RequestResults type

PRESENT#

alias of PRESENT

class icspacket.proto.iec61850.goose.GlbErrors#

ASN.1 GlbErrors type

VALUES#

alias of VALUES

class icspacket.proto.iec61850.goose.ErrorReason#

ASN.1 ErrorReason type

VALUES#

alias of VALUES

class icspacket.proto.iec61850.goose.IECGoosePdu#

ASN.1 IECGoosePdu type

allData_TYPE#

alias of allData

class icspacket.proto.iec61850.goose.UtcTime#

ASN.1 UtcTime type