Communicators

enocean.communicators.serialcommunicator.SerialCommunicator

SerialCommunicator(
    port: str,
    callback: Callable[[Packet], None] | None = None,
    teach_in: bool = True,
    devices: DeviceRegistry | None = None,
)

Bases: Communicator

Serial port communicator class for EnOcean radio.

Open the serial port of the module; start() the communicator to begin reading and writing.

Parameters:

Name	Type	Description	Default
port	str	Serial port of the module, e.g. /dev/serial/by-id/usb-EnOcean_GmbH_EnOcean_USB_300_... or /dev/ttyUSB0 (Linux), /dev/cu.usbserial-... (macOS).	required
callback	Callable[[Packet], None] | None	See Communicator.	None
teach_in	bool	See Communicator.	True
devices	DeviceRegistry | None	See Communicator.	None

Raises:

Type	Description
SerialException	The port can't be opened.

run

run() -> None

Thread body: write queued packets, read and parse bytes until stopped or the device disconnects.

enocean.communicators.tcpcommunicator.TCPCommunicator

TCPCommunicator(
    host: str = '',
    port: int = 9637,
    callback: Callable[[Packet], None] | None = None,
    teach_in: bool = True,
    devices: DeviceRegistry | None = None,
)

Bases: Communicator

TCP server receiving ESP3 packets from clients, e.g. a serial-to-TCP bridge (see examples/serial_to_tcp.py).

Receive-only: packets passed to send() (including UTE teach-in responses) are not transmitted anywhere. Clients are served one at a time.

Parameters:

Name	Type	Description	Default
host	str	Address to listen on ('' for all).	''
port	int	TCP port to listen on.	9637
callback	Callable[[Packet], None] | None	See Communicator.	None
teach_in	bool	See Communicator.	True
devices	DeviceRegistry | None	See Communicator.	None

run

run() -> None

Thread body: accept clients and parse the bytes they send until stopped.

enocean.communicators.communicator.Communicator

Communicator(
    callback: Callable[[Packet], None] | None = None,
    teach_in: bool = True,
    devices: DeviceRegistry | None = None,
)

Bases: Thread

Base class of the transports: a thread parsing ESP3 bytes into packets and sending packets.

Use SerialCommunicator or TCPCommunicator. Received packets are put in the receive queue, or passed to callback; send() queues packets for the transport to write. Every communicator keeps stats and reports its health().

Parameters:

Name	Type	Description	Default
callback	Callable[[Packet], None] | None	Called with each received packet (from the communicator thread) instead of queueing it in receive.	None
teach_in	bool	Answer UTE teach-in requests at any time. With False, only during learn().	True
devices	DeviceRegistry | None	Decode received telegrams with the profile of their device, and drop those of ignored devices.	None

learning property

learning: bool

Whether a teach-in window opened by learn() is ongoing.

base_id property writable

base_id: list[int] | None

The module's base ID, the first of the 128 IDs it can send from; asked to the module when unknown.

Waits up to a second for the module's response, except from the communicator thread itself, which can't wait for a response only it can read: there the request is sent and None returned until it arrives.

send

send(packet: Packet) -> bool

Queue a packet for the transport to write.

Returns:

Type	Description
bool	False if packet isn't a Packet.

stop

stop() -> None

Ask the communicator thread to stop; join() it to wait until it has.

parse

parse() -> PARSE_RESULT

Parses messages and puts them to receive queue.

learn

learn(
    timeout: float = 30, max_devices: int | None = None
) -> list[Device]

Open a teach-in window: answer UTE teach-in requests, even with teach_in=False.

Put the devices in learn mode meanwhile (e.g. press their learn button). Taught-in devices are added to devices (a DeviceRegistry is created if there is none). Blocks: call it from another thread than the communicator's.

Parameters:

Name	Type	Description	Default
timeout	float	How long the window stays open, in seconds.	30
max_devices	int | None	Close the window once this many devices are taught in.	None

Returns:

Type	Description
list[Device]	The devices taught in.

health

health(max_silence: float | None = None) -> Health

Current state, e.g. for a liveness/readiness probe.

Parameters:

Name	Type	Description	Default
max_silence	float | None	Seconds without receiving any packet that count as a problem (after startup, the delay counts from the communicator's creation). None to ignore silence.	None

Returns:

Type	Description
Health	The state; healthy is False and problems says why when something is wrong.