Packets¶

enocean.protocol.packet.Packet ¶

Packet(
    packet_type: int,
    data: list[int] | bytes | bytearray | None = None,
    optional: list[int] | bytes | bytearray | None = None,
)

An ESP3 packet: its type, data and optional data bytes.

Packet.parse_msg() reads packets from the byte stream, returning the subclass matching their type (RadioPacket, UTETeachInPacket, ResponsePacket, EventPacket); Packet.create() / RadioPacket.create() build radio telegrams from EEP field values. Once a profile is applied (parse_eep()), parsed holds the decoded fields.

Parameters:

Name	Type	Description	Default
`packet_type`	`int`	The ESP3 packet type (PACKET).	required
`data`	`list[int] \| bytes \| bytearray \| None`	The data bytes.	`None`
`optional`	`list[int] \| bytes \| bytearray \| None`	The optional data bytes.	`None`

Raises:

Type	Description
`TypeError`	data or optional isn't a list of ints, bytes, bytearray or tuple.

eep_id `property` ¶

eep_id: EEPId | None

The profile selected with select_eep()/parse_eep() (or announced by a teach-in telegram), if any.

command `property` ¶

command: int | None

Command of the selected profile variant, for profiles with several commands (e.g. D2-01-12).

parse_msg `staticmethod` ¶

parse_msg(
    buf: bytes | bytearray | list[int],
    on_error: Callable[[str], None] | None = None,
) -> tuple[PARSE_RESULT, list[int], Packet | None]

Parse the first packet of a byte stream.

Bytes before the first sync byte (0x55) are dropped; on a CRC error only the sync byte is skipped, so parsing resynchronizes on the next packet. Call it again on the remaining buffer until it returns INCOMPLETE.

Parameters:

Name	Type	Description	Default
`buf`	`bytes \| bytearray \| list[int]`	Bytes read from the module.	required
`on_error`	`Callable[[str], None] \| None`	Called with HEADER_CRC_ERROR, DATA_CRC_ERROR or MALFORMED_PACKET on errors.	`None`

Returns:

Type	Description
`PARSE_RESULT, the remaining bytes, the packet or None`	OK with a packet, INCOMPLETE if more bytes are
`list[int]`	needed, CRC_MISMATCH if corrupted bytes were skipped.

create `staticmethod` ¶

create(
    packet_type: int,
    rorg: int,
    rorg_func: int,
    rorg_type: int,
    direction: int | None = None,
    command: int | None = None,
    destination: list[int] | None = None,
    sender: list[int] | None = None,
    learn: bool = False,
    **kwargs: Any,
) -> Packet

Build a radio telegram from the field values of its profile.

Parameters:

Name	Type	Description	Default
`packet_type`	`int`	Only PACKET.RADIO_ERP1 is supported.	required
`rorg`	`int`	The telegram type: RORG.RPS, BS1, BS4 or VLD.	required
`rorg_func`	`int`	The profile's FUNC.	required
`rorg_type`	`int`	The profile's TYPE.	required
`direction`	`int \| None`	The direction, for profiles with direction-specific layouts.	`None`
`command`	`int \| None`	The command, for profiles with several commands (e.g. D2-01-12).	`None`
`destination`	`list[int] \| None`	The recipient's ID; broadcast (FF:FF:FF:FF) by default.	`None`
`sender`	`list[int] \| None`	The ID to send from, e.g. the module's base ID; DE:AD:BE:EF by default.	`None`
`learn`	`bool`	For 1BS and 4BS telegrams, send a teach-in telegram (learn bit).	`False`
`**kwargs`	`Any`	The field values by shortcut: raw ints, enum descriptions or their labels, numbers for values (see EEP().describe()).	`{}`

Returns:

Type	Description
`Packet`	The packet, decoded as it will be received.

Raises:

Type	Description
`ValueError`	Unsupported packet type or RORG, invalid sender or destination, unknown enum value, or unknown VLD profile.

parse ¶

parse() -> OrderedDict[str, FieldValue]

Read the fields common to the packet type (e.g. sender, status); called on construction.

select_eep ¶

select_eep(
    rorg_func: int,
    rorg_type: int,
    direction: int | None = None,
    command: int | None = None,
) -> bool

Select the profile (and its variant) to decode or encode the telegram with.

Parameters:

Name	Type	Description	Default
`rorg_func`	`int`	The profile's FUNC (the RORG is the telegram's).	required
`rorg_type`	`int`	The profile's TYPE.	required
`direction`	`int \| None`	The direction, for profiles with direction-specific layouts.	`None`
`command`	`int \| None`	The command variant; by default it is recognized from the telegram.	`None`

Returns:

Type	Description
`bool`	Whether the profile is known.

parse_eep ¶

parse_eep(
    rorg_func: int | None = None,
    rorg_type: int | None = None,
    direction: int | None = None,
    command: int | None = None,
) -> list[str]

Decode the telegram's fields into parsed.

Parameters:

Name	Type	Description	Default
`rorg_func`	`int \| None`	The profile's FUNC; if omitted, the profile selected before (select_eep()) is used.	`None`
`rorg_type`	`int \| None`	The profile's TYPE.	`None`
`direction`	`int \| None`	See select_eep().	`None`
`command`	`int \| None`	See select_eep().	`None`

Returns:

Type	Description
`list[str]`	The shortcuts of the decoded fields.

set_eep ¶

set_eep(data: dict[str, Any]) -> None

Encode field values, by shortcut, into the telegram with the selected profile.

to_dict ¶

to_dict() -> dict[str, Any]

JSON-serializable view of the packet.

Hex strings for bytes and IDs, enum names (hex for unknown values), ISO 8601 reception time and, once decoded, the EEP and field values.

build ¶

build() -> list[int]

The packet's ESP3 bytes, with header and CRCs, as written to the module.

enocean.protocol.packet.RadioPacket ¶

RadioPacket(
    packet_type: int,
    data: list[int] | bytes | bytearray | None = None,
    optional: list[int] | bytes | bytearray | None = None,
)

Bases: Packet

A radio telegram (ERP1).

Attributes set when parsing: sender / destination (4-byte IDs, also as sender_hex / destination_hex), dbm (signal strength of the received telegram, None if the module didn't report it and for telegrams to send) and learn.

learn tells whether the telegram can be used to teach the device in. 1BS and 4BS telegrams carry a learn bit, UTE telegrams a teach-in request; RPS and VLD telegrams have no learn bit, so learn is always True for them: any of their telegrams may be used to teach the device in (e.g. pressing a rocker switch).

dBm `property` ¶

dBm: int

Deprecated: use dbm (None instead of 0 when the module didn't report the signal strength).

sender_int `property` ¶

sender_int: int

The sender's ID as an integer.

sender_hex `property` ¶

sender_hex: str

The sender's ID as text, e.g. '05:99:77:AF'.

destination_int `property` ¶

destination_int: int

The destination ID as an integer.

destination_hex `property` ¶

destination_hex: str

The destination ID as text; 'FF:FF:FF:FF' for broadcast telegrams.

create `staticmethod` ¶

create(
    rorg: int,
    rorg_func: int,
    rorg_type: int,
    direction: int | None = None,
    command: int | None = None,
    destination: list[int] | None = None,
    sender: list[int] | None = None,
    learn: bool = False,
    **kwargs: Any,
) -> RadioPacket

Build a radio telegram (ERP1): see Packet.create(), without its packet_type argument.

to_dict ¶

to_dict() -> dict[str, Any]

See Packet.to_dict(); adds the radio fields, the EEP, the decoded values and the device.

parse ¶

parse() -> OrderedDict[str, FieldValue]

Read sender, destination, signal strength and learn bit; see Packet.parse().

enocean.protocol.packet.UTETeachInPacket ¶

UTETeachInPacket(
    packet_type: int,
    data: list[int] | bytes | bytearray | None = None,
    optional: list[int] | bytes | bytearray | None = None,
)

Bases: RadioPacket

A Universal Teach-in (UTE) request: a device asking to be taught in (or out), announcing its profile.

Communicators answer them (see Communicator.learn()); eep_id is the announced profile.

eep_id `property` ¶

eep_id: EEPId | None

The profile the device announces in its teach-in request.

channel `property` ¶

channel: int

Deprecated alias of number_of_channels.

bidirectional `property` ¶

bidirectional: bool

Whether the device expects bidirectional communication.

teach_in `property` ¶

teach_in: bool

Whether the request may be a teach-in (a teach-in or a not-specific request).

delete `property` ¶

delete: bool

Whether the request is a deletion (teach-out).

to_dict ¶

to_dict() -> dict[str, Any]

See RadioPacket.to_dict(); adds the teach-in request fields.

parse ¶

parse() -> OrderedDict[str, FieldValue]

Read the request: type, announced profile, manufacturer, channels.

create_response_packet ¶

create_response_packet(
    sender_id: list[int],
    response: list[bool] = TEACHIN_ACCEPTED,
) -> RadioPacket

The UTE response to this request.

Parameters:

Name	Type	Description	Default
`sender_id`	`list[int]`	The ID to answer from, usually the module's base ID.	required
`response`	`list[bool]`	TEACHIN_ACCEPTED, DELETE_ACCEPTED, EEP_NOT_SUPPORTED or NOT_ACCEPTED.	`TEACHIN_ACCEPTED`

Returns:

Type	Description
`RadioPacket`	The response packet, addressed to the requesting device.

enocean.protocol.packet.ResponsePacket ¶

ResponsePacket(
    packet_type: int,
    data: list[int] | bytes | bytearray | None = None,
    optional: list[int] | bytes | bytearray | None = None,
)

Bases: Packet

The module's response to a command: response is the return code (RETURN_CODE), response_data the rest.

parse ¶

parse() -> OrderedDict[str, FieldValue]

Read the return code and the response data.

to_dict ¶

to_dict() -> dict[str, Any]

See Packet.to_dict(); adds the return code and response data.

enocean.protocol.packet.EventPacket ¶

EventPacket(
    packet_type: int,
    data: list[int] | bytes | bytearray | None = None,
    optional: list[int] | bytes | bytearray | None = None,
)

Bases: Packet

An event reported by the module: event is the event code (EVENT_CODE), event_data the rest.

parse ¶

parse() -> OrderedDict[str, FieldValue]

Read the event code and data.

to_dict ¶

to_dict() -> dict[str, Any]

See Packet.to_dict(); adds the event code and data.

Packets¶

enocean.protocol.packet.Packet ¶

eep_id property ¶

command property ¶

parse_msg staticmethod ¶

create staticmethod ¶

parse ¶

select_eep ¶

parse_eep ¶

set_eep ¶

to_dict ¶

build ¶

enocean.protocol.packet.RadioPacket ¶

dBm property ¶

sender_int property ¶

sender_hex property ¶

destination_int property ¶

destination_hex property ¶

create staticmethod ¶

to_dict ¶

parse ¶

enocean.protocol.packet.UTETeachInPacket ¶

eep_id property ¶

channel property ¶

bidirectional property ¶

teach_in property ¶

delete property ¶

to_dict ¶

parse ¶

create_response_packet ¶

enocean.protocol.packet.ResponsePacket ¶

parse ¶

to_dict ¶

enocean.protocol.packet.EventPacket ¶

parse ¶

to_dict ¶

eep_id `property` ¶

command `property` ¶

parse_msg `staticmethod` ¶

create `staticmethod` ¶

dBm `property` ¶

sender_int `property` ¶

sender_hex `property` ¶

destination_int `property` ¶

destination_hex `property` ¶

create `staticmethod` ¶

eep_id `property` ¶

channel `property` ¶

bidirectional `property` ¶

teach_in `property` ¶

delete `property` ¶