GOOSE Client

icspacket.proto.iec61850.goose.GOOSE_ETHER_TYPE = 35000

EtherType value assigned to IEC 61850 GOOSE (Generic Object Oriented Substation Event)

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

Protocol Data Unit (PDU) representing the ISO/IEC 8802-3 frame structure used for GSE management and GOOSE communication.

The PDU wraps the Application Protocol Data Unit (APDU) carried in an Ethernet frame. The frame contains reserved fields in addition to the application identifier and APDU payload.

app_id: int = 0

Application identifier (AppID). This field uniquely identifies the application instance for which the message is intended.

length: int = 0

Total length of the PDU in bytes, including the 8-byte header (AppID, Length, Reserved1, Reserved2).

raw_apdu: bytes = b''

Encoded APDU (Application Protocol Data Unit). This may contain ASN.1 BER-encoded payloads or raw bytes depending on context.

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