scapy.contrib.ethercat

EtherCat automation protocol

author

Thomas Tannhaeuser, hecke@naberius.de

license

GPLv2

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

description

This module provides Scapy layers for the EtherCat protocol.

normative references:
  • IEC 61158-3-12 - data link service and topology description

  • IEC 61158-4-12 - protocol specification

Currently only read/write services as defined in IEC 61158-4-12, sec. 5.4 are supported.

TODO
  • Mailbox service (sec. 5.5)

  • Network variable service (sec. 5.6)

NOTES
  • EtherCat frame type defaults to TYPE-12-PDU (0x01) using xxx bytes of padding

  • padding for minimum frame size is added automatically

class scapy.contrib.ethercat.EtherCat

Bases: scapy.packet.Packet

Common EtherCat header layer

ETHERCAT_HEADER_LEN = 2
ETHERCAT_TYPE12_DLPDU_TYPES = {1: <class 'scapy.contrib.ethercat.EtherCatAPRD'>, 2: <class 'scapy.contrib.ethercat.EtherCatAPWR'>, 3: <class 'scapy.contrib.ethercat.EtherCatAPRW'>, 4: <class 'scapy.contrib.ethercat.EtherCatFPRD'>, 5: <class 'scapy.contrib.ethercat.EtherCatFPWR'>, 6: <class 'scapy.contrib.ethercat.EtherCatFPRW'>, 7: <class 'scapy.contrib.ethercat.EtherCatBRD'>, 8: <class 'scapy.contrib.ethercat.EtherCatBWR'>, 9: <class 'scapy.contrib.ethercat.EtherCatBRW'>, 10: <class 'scapy.contrib.ethercat.EtherCatLRD'>, 11: <class 'scapy.contrib.ethercat.EtherCatLWR'>, 12: <class 'scapy.contrib.ethercat.EtherCatLRW'>, 13: <class 'scapy.contrib.ethercat.EtherCatARMW'>, 14: <class 'scapy.contrib.ethercat.EtherCatFRMW'>}
ETHER_FRAME_MIN_LEN = 64
ETHER_FSC_LEN = 4
ETHER_HEADER_LEN = 14
FRAME_TYPES = {1: 'TYPE-12-PDU', 4: 'NETWORK-VARIABLES', 5: 'MAILBOX'}
aliastypes
fields_desc
EtherCat fields

length

LEBitField (11 bits)

0

_reserved

LEBitField (1 bit)

0

type

LEBitField (4 bits)

0

guess_payload_class(payload)
payload_guess

Possible sublayers: EtherCatAPRD, EtherCatAPRW, EtherCatAPWR, EtherCatARMW, EtherCatBRD, EtherCatBRW, EtherCatBWR, EtherCatFPRD, EtherCatFPRW, EtherCatFPWR, EtherCatFRMW, EtherCatLRD, EtherCatLRW, EtherCatLWR

post_build(pkt, pay)

need to set the length of the whole PDU manually to avoid any bit fiddling use a dummy class to build the layer content

also add padding if frame is < 64 bytes

Note: padding only handles Ether/n*Dot1Q/EtherCat

(no special mumbo jumbo)

Parameters
  • pkt – raw string containing the current layer

  • pay – raw string containing the payload

Returns

<new current layer> + payload

class scapy.contrib.ethercat.EtherCatAPRD

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

APRD - Auto Increment Physical Read (IEC 61158-5-12, sec. 5.4.1.2 tab. 14 / p. 32)

aliastypes
fields_desc
EtherCatAPRD fields

_cmd

ByteField

1

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatAPRW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

APRW - Auto Increment Physical Read Write (IEC 61158-5-12, sec. 5.4.3.1 tab. 22 / p. 41)

aliastypes
fields_desc
EtherCatAPRW fields

_cmd

ByteField

3

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatAPWR

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

APWR - Auto Increment Physical Write (IEC 61158-5-12, sec. 5.4.2.2 tab. 18 / p. 37)

aliastypes
fields_desc
EtherCatAPWR fields

_cmd

ByteField

2

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatARMW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

ARMW - Auto increment physical read multiple write (IEC 61158-5-12, sec. 5.4.3.5 tab. 26 / p. 46)

aliastypes
fields_desc
EtherCatARMW fields

_cmd

ByteField

13

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatBRD

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

BRD - Broadcast read (IEC 61158-5-12, sec. 5.4.1.4 tab. 16 / p. 34)

aliastypes
fields_desc
EtherCatBRD fields

_cmd

ByteField

7

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatBRW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

BRW - Broadcast read write (IEC 61158-5-12, sec. 5.4.3.3 tab. 24 / p. 39)

aliastypes
fields_desc
EtherCatBRW fields

_cmd

ByteField

9

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatBWR

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

BWR - Broadcast read (IEC 61158-5-12, sec. 5.4.2.4 tab. 20 / p. 39)

aliastypes
fields_desc
EtherCatBWR fields

_cmd

ByteField

8

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatFPRD

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

FPRD - Configured address physical read (IEC 61158-5-12, sec. 5.4.1.3 tab. 15 / p. 33)

aliastypes
fields_desc
EtherCatFPRD fields

_cmd

ByteField

4

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatFPRW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

FPRW - Configured address physical read write (IEC 61158-5-12, sec. 5.4.3.2 tab. 23 / p. 43)

aliastypes
fields_desc
EtherCatFPRW fields

_cmd

ByteField

6

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatFPWR

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

FPWR - Configured address physical write (IEC 61158-5-12, sec. 5.4.2.3 tab. 19 / p. 38)

aliastypes
fields_desc
EtherCatFPWR fields

_cmd

ByteField

5

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatFRMW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

FRMW - Configured address physical read multiple write (IEC 61158-5-12, sec. 5.4.3.6 tab. 27 / p. 47)

aliastypes
fields_desc
EtherCatFRMW fields

_cmd

ByteField

14

idx

ByteField

0

adp

LEShortField

0

ado

LEShortField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatLRD

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

LRD - Logical read (IEC 61158-5-12, sec. 5.4.1.5 tab. 17 / p. 36)

aliastypes
fields_desc
EtherCatLRD fields

_cmd

ByteField

10

idx

ByteField

0

adr

LEIntField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatLRW

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

LRW - Logical read write (IEC 61158-5-12, sec. 5.4.3.4 tab. 25 / p. 45)

aliastypes
fields_desc
EtherCatLRW fields

_cmd

ByteField

12

idx

ByteField

0

adr

LEIntField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatLWR

Bases: scapy.contrib.ethercat.EtherCatType12DLPDU

LWR - Logical write (IEC 61158-5-12, sec. 5.4.2.5 tab. 21 / p. 40)

aliastypes
fields_desc
EtherCatLWR fields

_cmd

ByteField

11

idx

ByteField

0

adr

LEIntField

0

len

LEBitFieldLenField (11 bits)

None

_reserved

LEBitField (3 bits)

0

c

LEBitEnumField (1 bit)

0

next

LEBitEnumField (1 bit)

None

irq

LEShortField

0

data

FieldListField

[]

wkc

LEShortField

0

class scapy.contrib.ethercat.EtherCatType12DLPDU

Bases: scapy.packet.Packet

Type12 message base class

BROADCAST_ADDRESSING_DESC = [<Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).idx>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).adp>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).ado>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).len>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW)._reserved>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).c>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).next>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).irq>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).data>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).wkc>]
LOGICAL_ADDRESSING_DESC = [<Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).idx>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).adr>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).len>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW)._reserved>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).c>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).next>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).irq>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).data>, <Field (EtherCatLRD,EtherCatLWR,EtherCatLRW).wkc>]
PHYSICAL_ADDRESSING_DESC = [<Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).idx>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).adp>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).ado>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).len>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW)._reserved>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).c>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).next>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).irq>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).data>, <Field (EtherCatAPRD,EtherCatFPRD,EtherCatBRD,EtherCatAPWR,EtherCatFPWR,EtherCatBWR,EtherCatAPRW,EtherCatFPRW,EtherCatBRW,EtherCatARMW,EtherCatFRMW).wkc>]
aliastypes
guess_payload_class(payload)
post_build(pkt, pay)

set next attr automatically if not set explicitly by user

Parameters
  • pkt – raw string containing the current layer

  • pay – raw string containing the payload

Returns

<new current layer> + payload

class scapy.contrib.ethercat.LEBitEnumField(name, default, size, enum)

Bases: scapy.contrib.ethercat.LEBitField, scapy.fields._EnumField

i2s
i2s_cb
s2i
s2i_cb
class scapy.contrib.ethercat.LEBitField(name, default, size)

Bases: scapy.fields.BitField

a little endian version of the BitField

addfield(pkt, s, val)
Parameters
  • pkt – packet instance the raw string s and field belongs to

  • s – raw string representing the frame

  • val – value

Returns

final raw string, tuple (s, bitsdone, data) if in between bit field # noqa: E501

as we don’t know the final size of the full bitfield we need to accumulate the data. # noqa: E501 if we reach a field that ends at a octet boundary, we build the whole string # noqa: E501

getfield(pkt, s)

extract data from raw str

collect all instances belonging to the bit field set. if we reach a field that ends at a octet boundary, dissect the whole bit field at once # noqa: E501

Parameters
  • pkt – packet instance the field belongs to

  • s – raw string representing the frame -or- tuple containing raw str, number of bits and array of fields # noqa: E501

Returns

tuple containing raw str, number of bits and array of fields -or- remaining raw str and value of this # noqa: E501

class scapy.contrib.ethercat.LEBitFieldLenField(name, default, size, length_of=None, count_of=None, adjust=<function LEBitFieldLenField.<lambda>>)

Bases: scapy.contrib.ethercat.LEBitField

adjust
count_of
i2m(pkt, x)
length_of
exception scapy.contrib.ethercat.LEBitFieldSequenceException

Bases: scapy.error.Scapy_Exception

thrown by EtherCat structure tests