loxwebsocket

https://pypi.org/project/loxwebsocket/
Admin
loxwebsocket is a Python library for connecting to Loxone Smart Home systems via WebSocket, offering...
Tokens:5,312
Snippets:79
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Quickstart: Connect to Loxone Miniserver

Source: https://pypi.org/project/loxwebsocket/0.6.0

A basic asynchronous example demonstrating how to connect to a Loxone Miniserver using the LoxWs client. Ensure you have aiohttp installed and provide your Loxone credentials and URL.

```python
import asyncio
from loxwebsocket import LoxWs

async def main():
    ws = LoxWs()
    await ws.connect(
        user="your-username",
        password="your-password",
        loxone_url="http://miniserver-ip-or-host",
        receive_updates=True,
        max_reconnect_attempts=5,
    )
    # ...
    await ws.stop()

asyncio.run(main())
```

--------------------------------

### Development Setup

Source: https://pypi.org/project/loxwebsocket/0.6.0

Clones the repository and installs the package in editable mode with development dependencies.

```bash
git clone https://github.com/Jakob-Gliwa/loxwebsocket.git
cd loxwebsocket
pip install -e .[dev]
# or using uv
uv pip install -e .[dev]
```

--------------------------------

### Install loxwebsocket

Source: https://pypi.org/project/loxwebsocket/0.6.0

Install the loxwebsocket library using pip. This command installs version 0.6.0.

```bash
pip install loxwebsocket==0.6.0
```

--------------------------------

### Install loxwebsocket with uv

Source: https://pypi.org/project/loxwebsocket/0.6.0

Install the loxwebsocket library using the uv package manager. This command adds the library to your project dependencies.

```bash
uv add loxwebsocket
```

--------------------------------

### Connect to Loxone Miniserver

Source: https://pypi.org/project/loxwebsocket

Connect to a Loxone Miniserver using the LoxWs client. This example demonstrates establishing a WebSocket connection with authentication and enabling update reception.

```python
import asyncio
from loxwebsocket import LoxWs

async def main():
    ws = LoxWs()
    await ws.connect(
        user="your-username",
        password="your-password",
        loxone_url="http://miniserver-ip-or-host",
        receive_updates=True,
        max_reconnect_attempts=5,
    )
    # ...
    await ws.stop()

asyncio.run(main())

```

--------------------------------

### Install LoxWebSocket using pip

Source: https://pypi.org/project/loxwebsocket

Install the loxwebsocket library using pip. This is the standard method for adding Python packages to your project.

```bash
pip install loxwebsocket

```

--------------------------------

### Check Miniserver Reachability

Source: https://pypi.org/project/loxwebsocket

Verifies if the Miniserver base URL is reachable by sending an HTTP GET request. Returns true if a 200 OK response is received.

```python
await http_ping() -> bool
```

--------------------------------

### http_ping

Source: https://pypi.org/project/loxwebsocket/0.6.0

Checks if the Miniserver base URL is reachable via an HTTP GET request.

```APIDOC
## http_ping() -> bool

### Description
Returns whether the Miniserver base URL is reachable (HTTP 200).

### Response
#### Success Response (True)
Returns True if the Miniserver is reachable (HTTP 200).
#### Success Response (False)
Returns False if the Miniserver is not reachable.
```

--------------------------------

### LoxWs Constructor

Source: https://pypi.org/project/loxwebsocket/0.6.0

Initializes the LoxWs client. The version parameter influences authentication hashing.

```APIDOC
## LoxWs(version: float = 15.0)

### Description
Initializes the LoxWs client. The version parameter influences authentication hashing.

### Parameters
#### Path Parameters
* **version** (float) - Optional - Miniserver compatibility used for auth hashing selection.
```

--------------------------------

### LoxWs Constructor

Source: https://pypi.org/project/loxwebsocket/0.6.0

Instantiates the LoxWs client. The version parameter influences authentication hashing.

```python
LoxWs(version: float = 15.0)
```

--------------------------------

### connect

Source: https://pypi.org/project/loxwebsocket/0.6.0

Establishes the encrypted WebSocket connection, acquires or uses an authentication token, and optionally enables status updates.

```APIDOC
## connect(user: str, password: str, loxone_url: str, receive_updates: bool = True, max_reconnect_attempts: int = 0) -> None

### Description
Establishes the encrypted WebSocket connection, acquires or uses an authentication token, and optionally enables status updates.

### Parameters
#### Path Parameters
* **user** (str) - Required - User credentials for authentication.
* **password** (str) - Required - Password for authentication.
* **loxone_url** (str) - Required - The URL of the Loxone Miniserver.
* **receive_updates** (bool) - Optional - Whether to enable status updates. Defaults to True.
* **max_reconnect_attempts** (int) - Optional - Maximum number of reconnection attempts. Defaults to 0 (unlimited).
```

--------------------------------

### Low-Level Loxone Command Helper

Source: https://pypi.org/project/loxwebsocket

A low-level helper for sending encrypted Loxone commands and receiving responses. Use this for advanced or custom command interactions.

```python
await send_command(command: str) -> str | bytes
```

--------------------------------

### Add Event Callback

Source: https://pypi.org/project/loxwebsocket

Registers an asynchronous callback for selected connection events. Use EventType.ANY to subscribe to all events.

```python
add_event_callback(callback: Callable[[], Awaitable[None]], event_types: list[EventType]) -> None
```

--------------------------------

### Connect to Loxon Server

Source: https://pypi.org/project/loxwebsocket

Establishes an encrypted WebSocket connection, handles authentication, and optionally enables status updates. Set max_reconnect_attempts to 0 for unlimited retries.

```python
await connect(user: str, password: str, loxone_url: str, receive_updates: bool = True, max_reconnect_attempts: int = 0) -> None
```

--------------------------------

### Send Immediate WebSocket Command

Source: https://pypi.org/project/loxwebsocket

Sends a command directly to the WebSocket, useful for immediate actions like device control.

```python
await send_websocket_command(device_uuid: str | bytes, value: str) -> None
```

--------------------------------

### Register Event Callback for Connection Events

Source: https://pypi.org/project/loxwebsocket

Defines and subscribes to connection lifecycle events, such as successful connection or reconnection. Callbacks must be async.

```python
from loxwebsocket import LoxWs
```

```python
async def on_connected():
    ...
```

```python
ws = LoxWs()
ws.add_event_callback(on_connected, event_types=[LoxWs.EventType.CONNECTED])
```

--------------------------------

### send_websocket_command_to_visu_password_secured_control

Source: https://pypi.org/project/loxwebsocket/0.6.0

Sends a command to a visualization-password protected control, handling necessary authentication steps.

```APIDOC
## send_websocket_command_to_visu_password_secured_control(device_uuid: str, value: str, visu_pw: str) -> None

### Description
Sends a command to a visualization-password protected control. The client requests the required salt/key and sends the queued command.

### Parameters
#### Path Parameters
* **device_uuid** (str) - Required - The unique identifier of the control.
* **value** (str) - Required - The command value to send.
* **visu_pw** (str) - Required - The password for the visualization control.
```

--------------------------------

### send_websocket_command

Source: https://pypi.org/project/loxwebsocket/0.6.0

Sends an immediate command to a device via the WebSocket connection.

```APIDOC
## send_websocket_command(device_uuid: str | bytes, value: str) -> None

### Description
Sends an immediate command, e.g., "jdev/sps/io//", to a specified device.

### Parameters
#### Path Parameters
* **device_uuid** (str | bytes) - Required - The unique identifier of the target device.
* **value** (str) - Required - The command value to send.
```

--------------------------------

### Send Command to Password-Secured Control

Source: https://pypi.org/project/loxwebsocket

Sends a command to a visualization control that requires a password. The client handles salt and key retrieval for secure transmission.

```python
await send_websocket_command_to_visu_password_secured_control(device_uuid: str, value: str, visu_pw: str) -> None
```

--------------------------------

### stop

Source: https://pypi.org/project/loxwebsocket

Closes the WebSocket and HTTP session gracefully.

```APIDOC
## stop

```python
await stop() -> None | int
```

### Description
Closes WebSocket and HTTP session.

### Returns
Returns -1 on error, otherwise None.
```

--------------------------------

### send_command

Source: https://pypi.org/project/loxwebsocket/0.6.0

A low-level helper for sending encrypted Loxone commands and receiving their responses.

```APIDOC
## send_command(command: str) -> str | bytes

### Description
Low-level encrypted request/response helper for Loxone commands.

### Parameters
#### Path Parameters
* **command** (str) - Required - The Loxone command to send.

### Response
#### Success Response (str | bytes)
Returns the response from the Miniserver, which can be a string or bytes.
```

--------------------------------

### Add Message Callback

Source: https://pypi.org/project/loxwebsocket/0.6.0

Registers a callback for specific message types. Callbacks must be async functions.

```python
async def on_value_update(data, message_type: int):
    ...

ws.add_message_callback(on_value_update, message_types=[2])
```

--------------------------------

### Add Event Callback

Source: https://pypi.org/project/loxwebsocket/0.6.0

Registers a callback for specific connection events. Event types can be specified using the LoxWs.EventType enum.

```python
from loxwebsocket import LoxWs

async def on_connected():
    ...

ws = LoxWs()
ws.add_event_callback(on_connected, event_types=[LoxWs.EventType.CONNECTED])
```

--------------------------------

### add_event_callback

Source: https://pypi.org/project/loxwebsocket/0.6.0

Registers an asynchronous callback function to be executed for specific connection lifecycle events.

```APIDOC
## add_event_callback(callback: Callable[[], Awaitable[None]], event_types: list[EventType]) -> None

### Description
Registers an event callback for selected events (or `ANY`). Callbacks are executed when connection lifecycle events occur.

### Parameters
#### Path Parameters
* **callback** (Callable[[], Awaitable[None]]) - Required - The asynchronous callback function to register.
* **event_types** (list[EventType]) - Required - A list of `EventType` enums to subscribe to.
```

--------------------------------

### stop

Source: https://pypi.org/project/loxwebsocket/0.6.0

Closes the WebSocket and HTTP session gracefully. Returns an integer indicating success or failure.

```APIDOC
## stop() -> None | int

### Description
Closes the WebSocket and HTTP session gracefully. Returns -1 on error, otherwise None.

### Response
#### Success Response (None)
Returns None on successful closure.
#### Error Response (-1)
Returns -1 if an error occurred during closure.
```

--------------------------------

### LxToken Properties

Source: https://pypi.org/project/loxwebsocket

Details the properties of the LxToken object, which holds authentication token information including its validity and hashing algorithm.

```python
token: str
valid_until: int (seconds since 2009-01-01 in Loxone epoch)
hash_alg: str (e.g., "SHA1" or "SHA256")
get_seconds_to_expire() -> int
```

--------------------------------

### LoxWebSocket Exceptions

Source: https://pypi.org/project/loxwebsocket

Lists the custom exceptions provided by the loxwebsocket package for error handling, including base errors and specific HTTP or request errors.

```python
loxwebsocket.exceptions.LoxoneException: Base package error
loxwebsocket.exceptions.LoxoneHTTPStatusError: Non-OK HTTP response from Miniserver
loxwebsocket.exceptions.LoxoneRequestError: Error during HTTP request
```

--------------------------------

### Stop LoxWebSocket Connection

Source: https://pypi.org/project/loxwebsocket

Closes the WebSocket and HTTP session. Returns -1 on error, otherwise None.

```python
await stop() -> None | int
```

--------------------------------

### add_message_callback

Source: https://pypi.org/project/loxwebsocket/0.6.0

Registers an asynchronous callback function to be executed when specific message types are received.

```APIDOC
## add_message_callback(callback: Callable[[Any, int], Awaitable[None]], message_types: list[int]) -> None

### Description
Registers a coroutine callback for the specified message types. Callbacks receive parsed data and the numeric message type.

### Parameters
#### Path Parameters
* **callback** (Callable[[Any, int], Awaitable[None]]) - Required - The asynchronous callback function to register.
* **message_types** (list[int]) - Required - A list of numeric message types to subscribe to.
```

--------------------------------

### add_message_callback

Source: https://pypi.org/project/loxwebsocket

Registers a coroutine callback to be executed for specific message types received over the WebSocket.

```APIDOC
## add_message_callback

```python
add_message_callback(callback: Callable[[Any, int], Awaitable[None]], message_types: list[int]) -> None
```

### Description
Registers a coroutine callback for the specified message types. Callbacks receive parsed data and the numeric message type.

### Parameters
* **callback** (Callable[[Any, int], Awaitable[None]]) - Required - The async callable to register.
* **message_types** (list[int]) - Required - A list of message types (integers) to subscribe to.
```

--------------------------------

### Register Message Callback for Value Updates

Source: https://pypi.org/project/loxwebsocket

Registers an asynchronous callback function to handle specific message types, such as high-frequency value updates (message type 2).

```python
async def on_value_update(data, message_type: int):
    ...
```

```python
ws.add_message_callback(on_value_update, message_types=[2])
```

--------------------------------

### Add Message Callback

Source: https://pypi.org/project/loxwebsocket

Registers a coroutine callback for specified message types. Callbacks receive parsed data and the message type.

```python
add_message_callback(callback: Callable[[Any, int], Awaitable[None]], message_types: list[int]) -> None
```

--------------------------------

### Remove Message Callback

Source: https://pypi.org/project/loxwebsocket

Unregisters a previously added message callback for specific message types.

```python
remove_message_callback(callback, message_types: list[int]) -> None
```

--------------------------------

### remove_message_callback

Source: https://pypi.org/project/loxwebsocket/0.6.0

Unregisters a previously added message callback for specific message types.

```APIDOC
## remove_message_callback(callback, message_types: list[int]) -> None

### Description
Unregisters a previously added callback for the specified message types.

### Parameters
#### Path Parameters
* **callback** - Required - The callback function to unregister.
* **message_types** (list[int]) - Required - A list of numeric message types for which to unregister the callback.
```
Tokens:
Raw