Lighting

The Lighting module provides the main interface to the OpenWebNet lighting system.

pyown.items.lighting.base.WhatLight

WhatLight(string: str | int = '', *args, **kwargs)

Bases: What, StrEnum

This enum contains the possible commands for the lights. It is used only internally to send the correct command to the gateway.

Attributes:

Name	Type	Description
OFF		Turns the light off.
ON		Turns the light on.
ON_20_PERCENT		Turns the light on at 20%.
ON_30_PERCENT		Turns the light on at 30%.
ON_40_PERCENT		Turns the light on at 40%.
ON_50_PERCENT		Turns the light on at 50%.
ON_60_PERCENT		Turns the light on at 60%.
ON_70_PERCENT		Turns the light on at 70%.
ON_80_PERCENT		Turns the light on at 80%.
ON_90_PERCENT		Turns the light on at 90%.
ON_100_PERCENT		Turns the light on at 100%.
ON_1_MIN		Turns the light on for 1 minute.
ON_2_MIN		Turns the light on for 2 minutes.
ON_3_MIN		Turns the light on for 3 minutes.
ON_4_MIN		Turns the light on for 4 minutes.
ON_5_MIN		Turns the light on for 5 minutes.
ON_15_MIN		Turns the light on for 15 minutes.
ON_30_MIN		Turns the light on for 30 minutes.
ON_0_5_SEC		Turns the light on for 0.5 seconds.
BLINKING_0_5_SEC		Blinks the light every 0.5 seconds.
BLINKING_1_0_SEC		Blinks the light every 1.0 seconds.
BLINKING_1_5_SEC		Blinks the light every 1.5 seconds.
BLINKING_2_0_SEC		Blinks the light every 2.0 seconds.
BLINKING_2_5_SEC		Blinks the light every 2.5 seconds.
BLINKING_3_0_SEC		Blinks the light every 3.0 seconds.
BLINKING_3_5_SEC		Blinks the light every 3.5 seconds.
BLINKING_4_0_SEC		Blinks the light every 4.0 seconds.
BLINKING_4_5_SEC		Blinks the light every 4.5 seconds.
BLINKING_5_0_SEC		Blinks the light every 5.0 seconds.
UP_1_PERCENT		Increases the light luminosity by 1
DOWN_1_PERCENT		Decreases the light luminosity by 1
COMMAND_TRANSLATION		Not clear what this does.

string property

string: str

Returns the value of the tag

tag property

tag: str

Returns the value of the tag without its parameters or prefix

parameters property

parameters: list[str]

Returns the parameters of the tag

with_parameter

with_parameter(parameter: str | int) -> Self

Returns the tag with the specified parameter

pyown.items.lighting.base.LightEvents

Bases: Enum

This enum is used internally to register the callbacks to the correct event.

Attributes:

Name	Type	Description
STATUS_CHANGE		The light status has changed.
LUMINOSITY_CHANGE		The light luminosity has changed.
LIGHT_TEMPORIZATION		The light temporization has changed.
HSV_CHANGE		The light color has changed.
WHITE_TEMP_CHANGE		The white temperature has changed.

pyown.items.lighting.base.BaseLight

BaseLight(
    client: BaseClient,
    where: Where | str,
    *,
    who: Who | str | None = None
)

Bases: BaseItem, ABC

Base class for all light items.

client: The client to use to communicate with the server.
where: The location of the item.
who: The type of item.

where property

where: Where

Returns the where value of the item.

who classmethod property

who: Who

Returns the who value of the item.

client property writable

client: BaseClient

Returns the client used to communicate with the server.

create_normal_message

create_normal_message(what: What | str) -> NormalMessage

Creates a normal message for the item. Args: what: The action to perform. Returns: A normal message.

create_status_message

create_status_message() -> StatusRequest

Creates a status message for the item.

Returns:

Type	Description
StatusRequest	A status message.

create_dimension_writing_message

create_dimension_writing_message(
    dimension: Dimension, *args: Value
) -> DimensionWriting

Creates a dimension message for the item. Args: dimension: the dimension value to set. *args: the values to set.

Returns:

create_dimension_request_message

create_dimension_request_message(
    dimension: Dimension,
) -> DimensionRequest

Creates a dimension request message for the item. Args: dimension: the dimension value to request.

Returns:

send_normal_message async

send_normal_message(what: What | str) -> None

Sends a normal message to the server and check the response.

Parameters:

Name	Type	Description	Default
what	What | str	The action to perform.	required

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

send_status_request async

send_status_request() -> AsyncIterator[NormalMessage]

Sends a status request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[NormalMessage]	The responses from the server.

send_dimension_request async

send_dimension_request(
    dimension: Dimension | str,
) -> AsyncIterator[DimensionResponse]

Sends a dimension request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[DimensionResponse]	The responses from the server.

send_dimension_writing async

send_dimension_writing(
    dimension: Dimension | str, *args: Value
) -> None

Sends a dimension writing message to the server and check the response.

Parameters:

Name	Type	Description	Default
dimension	Dimension | str	the dimension value to set.	required
*args	Value	the values to set.	()

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

turn_on async

turn_on()

Turns the light on.

turn_off async

turn_off()

Turns the light off.

turn_on_1_min async

turn_on_1_min()

Turns the light on for 1 minute.

turn_on_2_min async

turn_on_2_min()

Turns the light on for 2 minutes.

turn_on_3_min async

turn_on_3_min()

Turns the light on for 3 minutes.

turn_on_4_min async

turn_on_4_min()

Turns the light on for 4 minutes.

turn_on_5_min async

turn_on_5_min()

Turns the light on for 5 minutes.

turn_on_15_min async

turn_on_15_min()

Turns the light on for 15 minutes.

turn_on_30_min async

turn_on_30_min()

Turns the light on for 30 minutes.

turn_on_0_5_sec async

turn_on_0_5_sec()

Turns the light on for 0.5 seconds.

get_status abstractmethod async

get_status() -> AsyncIterator[tuple[Where, bool | int]]

Gets the status of the light

temporization_command async

temporization_command(hour: int, minute: int, second: int)

Sends a temporization command

It will turn the light immediately on and then off after the specified time passed.

Parameters:

Name	Type	Description	Default
hour	int	It indicates show many hours the actuator has to stay ON	required
minute	int	It indicates show many minutes the actuator has to stay ON	required
second	int	It indicates show many seconds the actuator has to stay ON	required

temporization_request async

temporization_request() -> (
    AsyncIterator[tuple[Where, int, int, int]]
)

Requests the gateway the current temporization settings of the actuator.

Yields:

Type	Description
AsyncIterator[tuple[Where, int, int, int]]	A tuple with the hour, minute, and second of the temporization.

request_working_time_lamp async

request_working_time_lamp() -> (
    AsyncIterator[tuple[Where, int]]
)

Requests the gateway for how long the light has been on.

Yields:

Type	Description
AsyncIterator[tuple[Where, int]]	The time in hours the light has been on. The value is in the range [1-100000].

on_status_change classmethod

on_status_change(
    callback: Callable[
        [Self, bool], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the light status changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, bool]	The callback function to call. It will receive as arguments the item and the status.	required

on_temporization_change classmethod

on_temporization_change(
    callback: Callable[
        [Self, int, int, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the temporization changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int, int, int]	The callback function to call. It will receive as arguments the item, the hour, the minute, and the second.	required

call_callbacks async classmethod

call_callbacks(
    item: BaseItem, message: BaseMessage
) -> list[Task]

Calls the registered callbacks for the event. Used internally by the client to dispatch the events to the correct callbacks.

Parameters:

Name	Type	Description	Default
item	BaseItem	The item that triggered the event.	required
message	BaseMessage	The message that triggered the event.	required

Returns:

Type	Description
list[Task]	list[Task]: A list of tasks scheduled to run the callbacks.

pyown.items.lighting.light.Light

Light(
    client: BaseClient,
    where: Where | str,
    *,
    who: Who | str | None = None
)

Bases: BaseLight

Light items are item with only two states: on and off.

client: The client to use to communicate with the server.
where: The location of the item.
who: The type of item.

where property

where: Where

Returns the where value of the item.

who classmethod property

who: Who

Returns the who value of the item.

client property writable

client: BaseClient

Returns the client used to communicate with the server.

call_callbacks async classmethod

call_callbacks(
    item: BaseItem, message: BaseMessage
) -> list[Task]

Calls the registered callbacks for the event. Used internally by the client to dispatch the events to the correct callbacks.

Parameters:

Name	Type	Description	Default
item	BaseItem	The item that triggered the event.	required
message	BaseMessage	The message that triggered the event.	required

Returns:

Type	Description
list[Task]	list[Task]: A list of tasks scheduled to run the callbacks.

create_normal_message

create_normal_message(what: What | str) -> NormalMessage

Creates a normal message for the item. Args: what: The action to perform. Returns: A normal message.

create_status_message

create_status_message() -> StatusRequest

Creates a status message for the item.

Returns:

Type	Description
StatusRequest	A status message.

create_dimension_writing_message

create_dimension_writing_message(
    dimension: Dimension, *args: Value
) -> DimensionWriting

Creates a dimension message for the item. Args: dimension: the dimension value to set. *args: the values to set.

Returns:

create_dimension_request_message

create_dimension_request_message(
    dimension: Dimension,
) -> DimensionRequest

Creates a dimension request message for the item. Args: dimension: the dimension value to request.

Returns:

send_normal_message async

send_normal_message(what: What | str) -> None

Sends a normal message to the server and check the response.

Parameters:

Name	Type	Description	Default
what	What | str	The action to perform.	required

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

send_status_request async

send_status_request() -> AsyncIterator[NormalMessage]

Sends a status request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[NormalMessage]	The responses from the server.

send_dimension_request async

send_dimension_request(
    dimension: Dimension | str,
) -> AsyncIterator[DimensionResponse]

Sends a dimension request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[DimensionResponse]	The responses from the server.

send_dimension_writing async

send_dimension_writing(
    dimension: Dimension | str, *args: Value
) -> None

Sends a dimension writing message to the server and check the response.

Parameters:

Name	Type	Description	Default
dimension	Dimension | str	the dimension value to set.	required
*args	Value	the values to set.	()

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

turn_on_1_min async

turn_on_1_min()

Turns the light on for 1 minute.

turn_on_2_min async

turn_on_2_min()

Turns the light on for 2 minutes.

turn_on_3_min async

turn_on_3_min()

Turns the light on for 3 minutes.

turn_on_4_min async

turn_on_4_min()

Turns the light on for 4 minutes.

turn_on_5_min async

turn_on_5_min()

Turns the light on for 5 minutes.

turn_on_15_min async

turn_on_15_min()

Turns the light on for 15 minutes.

turn_on_30_min async

turn_on_30_min()

Turns the light on for 30 minutes.

turn_on_0_5_sec async

turn_on_0_5_sec()

Turns the light on for 0.5 seconds.

temporization_command async

temporization_command(hour: int, minute: int, second: int)

Sends a temporization command

It will turn the light immediately on and then off after the specified time passed.

Parameters:

Name	Type	Description	Default
hour	int	It indicates show many hours the actuator has to stay ON	required
minute	int	It indicates show many minutes the actuator has to stay ON	required
second	int	It indicates show many seconds the actuator has to stay ON	required

temporization_request async

temporization_request() -> (
    AsyncIterator[tuple[Where, int, int, int]]
)

Requests the gateway the current temporization settings of the actuator.

Yields:

Type	Description
AsyncIterator[tuple[Where, int, int, int]]	A tuple with the hour, minute, and second of the temporization.

request_working_time_lamp async

request_working_time_lamp() -> (
    AsyncIterator[tuple[Where, int]]
)

Requests the gateway for how long the light has been on.

Yields:

Type	Description
AsyncIterator[tuple[Where, int]]	The time in hours the light has been on. The value is in the range [1-100000].

on_status_change classmethod

on_status_change(
    callback: Callable[
        [Self, bool], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the light status changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, bool]	The callback function to call. It will receive as arguments the item and the status.	required

on_temporization_change classmethod

on_temporization_change(
    callback: Callable[
        [Self, int, int, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the temporization changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int, int, int]	The callback function to call. It will receive as arguments the item, the hour, the minute, and the second.	required

turn_on async

turn_on()

Turns the light on.

turn_off async

turn_off()

Turns the light off.

blink_0_5_sec async

blink_0_5_sec()

Blinks the light every 0.5 seconds.

blink_1_0_sec async

blink_1_0_sec()

Blinks the light every 1.0 seconds.

blink_1_5_sec async

blink_1_5_sec()

Blinks the light every 1.5 seconds.

blink_2_0_sec async

blink_2_0_sec()

Blinks the light every 2.0 seconds.

blink_2_5_sec async

blink_2_5_sec()

Blinks the light every 2.5 seconds.

blink_3_0_sec async

blink_3_0_sec()

Blinks the light every 3.0 seconds.

blink_3_5_sec async

blink_3_5_sec()

Blinks the light every 3.5 seconds.

blink_4_0_sec async

blink_4_0_sec()

Blinks the light every 4.0 seconds.

blink_4_5_sec async

blink_4_5_sec()

Blinks the light every 4.5 seconds.

blink_5_0_sec async

blink_5_0_sec()

Blinks the light every 5.0 seconds.

get_status async

get_status() -> AsyncIterator[tuple[Where, bool]]

Gets the status of the light.

Yields:

Type	Description
AsyncIterator[tuple[Where, bool]]	tuple[Where, bool]: The where and the status of the light.

pyown.items.lighting.dimmer.Dimmer

Dimmer(
    client: BaseClient,
    where: Where | str,
    *,
    who: Who | str | None = None
)

Bases: BaseLight

Dimmer items are items that can have their brightness level changed or colors changed.

client: The client to use to communicate with the server.
where: The location of the item.
who: The type of item.

where property

where: Where

Returns the where value of the item.

who classmethod property

who: Who

Returns the who value of the item.

client property writable

client: BaseClient

Returns the client used to communicate with the server.

call_callbacks async classmethod

call_callbacks(
    item: BaseItem, message: BaseMessage
) -> list[Task]

Calls the registered callbacks for the event. Used internally by the client to dispatch the events to the correct callbacks.

Parameters:

Name	Type	Description	Default
item	BaseItem	The item that triggered the event.	required
message	BaseMessage	The message that triggered the event.	required

Returns:

Type	Description
list[Task]	list[Task]: A list of tasks scheduled to run the callbacks.

create_normal_message

create_normal_message(what: What | str) -> NormalMessage

Creates a normal message for the item. Args: what: The action to perform. Returns: A normal message.

create_status_message

create_status_message() -> StatusRequest

Creates a status message for the item.

Returns:

Type	Description
StatusRequest	A status message.

create_dimension_writing_message

create_dimension_writing_message(
    dimension: Dimension, *args: Value
) -> DimensionWriting

Creates a dimension message for the item. Args: dimension: the dimension value to set. *args: the values to set.

Returns:

create_dimension_request_message

create_dimension_request_message(
    dimension: Dimension,
) -> DimensionRequest

Creates a dimension request message for the item. Args: dimension: the dimension value to request.

Returns:

send_normal_message async

send_normal_message(what: What | str) -> None

Sends a normal message to the server and check the response.

Parameters:

Name	Type	Description	Default
what	What | str	The action to perform.	required

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

send_status_request async

send_status_request() -> AsyncIterator[NormalMessage]

Sends a status request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[NormalMessage]	The responses from the server.

send_dimension_request async

send_dimension_request(
    dimension: Dimension | str,
) -> AsyncIterator[DimensionResponse]

Sends a dimension request and receive multiple responses from the server.

Raises:

Type	Description
ResponseError	If the server responds with an invalid message.

Returns:

Type	Description
AsyncIterator[DimensionResponse]	The responses from the server.

send_dimension_writing async

send_dimension_writing(
    dimension: Dimension | str, *args: Value
) -> None

Sends a dimension writing message to the server and check the response.

Parameters:

Name	Type	Description	Default
dimension	Dimension | str	the dimension value to set.	required
*args	Value	the values to set.	()

Raises:

Type	Description
ResponseError	If the server does not acknowledge the message.

turn_on_1_min async

turn_on_1_min()

Turns the light on for 1 minute.

turn_on_2_min async

turn_on_2_min()

Turns the light on for 2 minutes.

turn_on_3_min async

turn_on_3_min()

Turns the light on for 3 minutes.

turn_on_4_min async

turn_on_4_min()

Turns the light on for 4 minutes.

turn_on_5_min async

turn_on_5_min()

Turns the light on for 5 minutes.

turn_on_15_min async

turn_on_15_min()

Turns the light on for 15 minutes.

turn_on_30_min async

turn_on_30_min()

Turns the light on for 30 minutes.

turn_on_0_5_sec async

turn_on_0_5_sec()

Turns the light on for 0.5 seconds.

temporization_command async

temporization_command(hour: int, minute: int, second: int)

Sends a temporization command

It will turn the light immediately on and then off after the specified time passed.

Parameters:

Name	Type	Description	Default
hour	int	It indicates show many hours the actuator has to stay ON	required
minute	int	It indicates show many minutes the actuator has to stay ON	required
second	int	It indicates show many seconds the actuator has to stay ON	required

temporization_request async

temporization_request() -> (
    AsyncIterator[tuple[Where, int, int, int]]
)

Requests the gateway the current temporization settings of the actuator.

Yields:

Type	Description
AsyncIterator[tuple[Where, int, int, int]]	A tuple with the hour, minute, and second of the temporization.

request_working_time_lamp async

request_working_time_lamp() -> (
    AsyncIterator[tuple[Where, int]]
)

Requests the gateway for how long the light has been on.

Yields:

Type	Description
AsyncIterator[tuple[Where, int]]	The time in hours the light has been on. The value is in the range [1-100000].

on_status_change classmethod

on_status_change(
    callback: Callable[
        [Self, bool], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the light status changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, bool]	The callback function to call. It will receive as arguments the item and the status.	required

on_temporization_change classmethod

on_temporization_change(
    callback: Callable[
        [Self, int, int, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the temporization changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int, int, int]	The callback function to call. It will receive as arguments the item, the hour, the minute, and the second.	required

turn_on async

turn_on(speed: int | None = None)

Turns the light on.

Parameters:

Name	Type	Description	Default
speed	int | None	turn on the light with a specific speed [0-255]	None

turn_off async

turn_off(speed: int | None = None)

Turns the light off.

Parameters:

Name	Type	Description	Default
speed	int | None	turn off the light with a specific speed [0-255]	None

set_20_percent async

set_20_percent()

Sets the light to 20%.

set_30_percent async

set_30_percent()

Sets the light to 30%.

set_40_percent async

set_40_percent()

Sets the light to 40%.

set_50_percent async

set_50_percent()

Sets the light to 50%.

set_60_percent async

set_60_percent()

Sets the light to 60%.

set_70_percent async

set_70_percent()

Sets the light to 70%.

set_80_percent async

set_80_percent()

Sets the light to 80%.

set_90_percent async

set_90_percent()

Sets the light to 90%.

set_100_percent async

set_100_percent()

Sets the light to 100%.

up_percent async

up_percent(
    value: int | None = None, speed: int | None = None
)

Increases the light percentage.

Parameters:

Name	Type	Description	Default
value	int | None	the percentage to increase, by default, 1	None
speed	int | None	increase the light percentage with a specific speed [0-255]	None

down_percent async

down_percent(
    value: int | None = None, speed: int | None = None
)

Decreases the light percentage.

Parameters:

Name	Type	Description	Default
value	int | None	the percentage to decrease, by default 1	None
speed	int | None	decrease the light percentage with a specific speed [0-255]	None

get_status async

get_status() -> AsyncIterator[tuple[Where, int]]

Gets the status of the light.

Yields:

Type	Description
AsyncIterator[tuple[Where, int]]	tuple[Where, int]: the first element is the location of the light,
AsyncIterator[tuple[Where, int]]	the second is the brightness level [0-100]

set_brightness_with_speed async

set_brightness_with_speed(
    brightness: int | str, speed: int | str
)

Sets the brightness of the light with a specific speed.

Parameters:

Name	Type	Description	Default
brightness	int | str	the brightness to set	required
speed	int | str	the speed to set the brightness	required

set_hsv async

set_hsv(hue: int, saturation: int, value: int)

Sets the color of the light in HSV format.

Parameters:

Name	Type	Description	Default
hue	int	the hue value to set [0-359]	required
saturation	int	the saturation value [0-100]	required
value	int	the value to set [0-100]	required

set_white_temperature async

set_white_temperature(temperature: int)

Sets the white temperature of the light.

Parameters:

Name	Type	Description	Default
temperature	int	the temperature to set [1-65534] using the Mired scale.	required

request_current_brightness_speed async

request_current_brightness_speed() -> (
    AsyncIterator[tuple[Where, int, int]]
)

Requests the current brightness and speed of the light.

Yields:

Type	Description
AsyncIterator[tuple[Where, int, int]]	A tuple with the where of the item, its brightness level, and its current speed.
AsyncIterator[tuple[Where, int, int]]	The speed is in the range [0-255].
AsyncIterator[tuple[Where, int, int]]	The brightness is in the range [100-200].

request_current_hsv async

request_current_hsv() -> (
    AsyncIterator[tuple[Where, int, int, int]]
)

Requests the current HSV of the light, valid only for RGB lights.

Yields:

Type	Description
AsyncIterator[tuple[Where, int, int, int]]	A tuple with the where of the item, the hue, the saturation, and the value. The hue is in the range [0-359]. The saturation is in the range [0-100]. The value is in the range [0-100].

request_current_white_temperature async

request_current_white_temperature() -> (
    AsyncIterator[tuple[Where, int]]
)

Requests the current white temperature of the light.

Yields:

Type	Description
AsyncIterator[tuple[Where, int]]	The where of the item and the temperature. The temperature is in the range [1-65534] using the Mired scale.

on_luminosity_change classmethod

on_luminosity_change(
    callback: Callable[
        [Self, int, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the luminosity changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int, int], Coroutine[None, None, None]]	The callback function to call. It will receive as arguments the item, dimmer level and speed	required

on_hsv_change classmethod

on_hsv_change(
    callback: Callable[
        [Self, int, int, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the HSV changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int, int, int], Coroutine[None, None, None]]	The callback function to call. It will receive as arguments the item, the hue, the saturation, and the value.	required

on_white_temp_change classmethod

on_white_temp_change(
    callback: Callable[
        [Self, int], Coroutine[None, None, None]
    ]
)

Registers a callback function to be called when the white temperature changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[Self, int], Coroutine[None, None, None]]	The callback function to call. It will receive as arguments the item and the temperature.	required