Client module

The Client module provides the main interface to the OpenWebNet gateway.

pyown.client.BaseClient

BaseClient(
    host: str,
    port: int,
    password: str,
    session_type: SessionType = CommandSession,
    *,
    loop: Optional[AbstractEventLoop] = None,
)

Bases: ABC

Abstract base class for OpenWebNet gateway clients.

Defines the connection, authentication, and message exchange logic shared by client implementations. It should not be instantiated directly; use the Client class instead.

This class should not be instantiated directly, use the Client class instead.

Parameters:

Name	Type	Description	Default
host	str	The host to connect to (ip address)	required
port	int	The port to connect to	required
password	str	The password to authenticate with	required
session_type	SessionType	The session type to use	CommandSession
loop	Optional[AbstractEventLoop]	The event loop to use	None

is_cmd_session

is_cmd_session() -> bool

Checks if the session is a command session.

Returns:

Name	Type	Description
bool	bool	True if the session is a command session, False otherwise

start async

start() -> None

Creates a connection with the gateway and does the initial handshake.

Raises:

Type	Description
TimeoutError	if the server does not respond
InvalidSession	if the server requires an unknown authentication algorithm

send_message async

send_message(
    message: BaseMessage, *, force: bool = False
) -> None

Sends a message to the server.

Parameters:

Name	Type	Description	Default
message	BaseMessage	send to the server a subclass of BaseMessage	required
force	bool	if True, the message will be sent even if the client is set as an event session	False

Raises:

Type	Description
InvalidSession	if the client is set as an event session or if the client is not started

read_message async

read_message(timeout: int | None = 5) -> BaseMessage

Awaits a message from the server and returns it.

Returns:

Name	Type	Description
BaseMessage	BaseMessage	the message from the server, it will be a subclass of BaseMessage.

Raises:

Type	Description
TimeoutError	if the server does not respond in the given time.
InvalidSession	if the client is not started.

close async

close() -> None

Close the client.

loop abstractmethod async

loop()

Runs the client loop.

This is a loop that runs the entire event system for the client, it will read messages from the gateway and dispatch them to the correct callbacks.

pyown.client.Client

Client(
    host: str,
    port: int,
    password: str,
    session_type: SessionType = CommandSession,
    *,
    loop: Optional[AbstractEventLoop] = None,
)

Bases: BaseClient

              flowchart TD
              pyown.client.Client[Client]
              pyown.client.base.BaseClient[BaseClient]

                              pyown.client.base.BaseClient --> pyown.client.Client
                


              click pyown.client.Client href "" "pyown.client.Client"
              click pyown.client.base.BaseClient href "" "pyown.client.base.BaseClient"
            

Client connection to an OpenWebNet gateway.

Used to send commands and receive events from the gateway, and to instantiate and cache the items exposed by it.

This class can be used to send commands and receive events from the gateway.

Parameters:

Name	Type	Description	Default
host	str	The host to connect to (ip address)	required
port	int	The port to connect to	required
password	str	The password to authenticate with	required
session_type	SessionType	The session type to use, can be a command session or an event session. Default is CommandSession	CommandSession
loop	Optional[AbstractEventLoop]	The event loop to use	None

is_cmd_session

is_cmd_session() -> bool

Checks if the session is a command session.

Returns:

Name	Type	Description
bool	bool	True if the session is a command session, False otherwise

start async

start() -> None

Creates a connection with the gateway and does the initial handshake.

Raises:

Type	Description
TimeoutError	if the server does not respond
InvalidSession	if the server requires an unknown authentication algorithm

send_message async

send_message(
    message: BaseMessage, *, force: bool = False
) -> None

Sends a message to the server.

Parameters:

Name	Type	Description	Default
message	BaseMessage	send to the server a subclass of BaseMessage	required
force	bool	if True, the message will be sent even if the client is set as an event session	False

Raises:

Type	Description
InvalidSession	if the client is set as an event session or if the client is not started

read_message async

read_message(timeout: int | None = 5) -> BaseMessage

Awaits a message from the server and returns it.

Returns:

Name	Type	Description
BaseMessage	BaseMessage	the message from the server, it will be a subclass of BaseMessage.

Raises:

Type	Description
TimeoutError	if the server does not respond in the given time.
InvalidSession	if the client is not started.

close async

close() -> None

Close the client.

get_item

get_item(
    who: Who, where: Where, *, client: BaseClient
) -> BaseItem

Instantiates an item if it is not already cached in the client and returns it.

Parameters:

Name	Type	Description	Default
who	Who	The type of the item.	required
where	Where	The location of the item.	required
client	BaseClient	The client to assign to the item if it's not already defined.	required

Returns:

Type	Description
BaseItem	The item requested.

Raises:

Type	Description
KeyError	if the item WHO is not supported.

loop async

loop(*, client: BaseClient | None = None)

Runs the client loop.

This is a loop that runs the entire event system for the client, it will read messages from the gateway and dispatch them to the correct callbacks.

Typical usage:

client = Client(host, port, password, SessionType.EventSession)
client.add_callback(lambda item, event: print(item, event))
await client.connect()
own_loop = asyncio.create_task(client.loop())

# Do something else

await client.close()

Parameters:

Name	Type	Description	Default
client	BaseClient | None	The client to use to declare the items for the callbacks. Default is self. This is useful when you want the items to have a command client to allow sending commands with them.	None

Raises:

Type	Description
InvalidSession	if called when the client is set as a command client and not as an event client or if the client is not connected

pyown.client.SessionType

Bases: StrEnum

Represents the all allowed values for session types in the OpenWebNet protocol.

Attributes:

Name	Type	Description
OldCommandSession		Legacy command session value not present in the official OpenWebNet documentation.
CommandSession		Official command session value. Used to create a session for sending commands.
EventSession		Event session value. Used to create a session for receiving events, sending commands is not allowed.

to_message

to_message() -> GenericMessage

Convert the session type to the session message to send to the gateway.

Returns:

Name	Type	Description
GenericMessage	GenericMessage	The message to send to the gateway.