diff --git a/README.md b/README.md index 50551afc..bc9bace1 100644 --- a/README.md +++ b/README.md @@ -16,23 +16,47 @@ Full documentation is available at **[imicknl.github.io/python-overkiz-api](http ## Supported hubs -- Atlantic Cozytouch -- Bouygues Flexom -- Brandt Smart Control † -- Hitachi Hi Kumo -- Nexity Eugénie -- Rexel Energeasy Connect ‡ -- Sauter Cozytouch -- Simu (LiveIn2) -- Somfy Connexoon IO -- Somfy Connexoon RTS -- Somfy TaHoma -- Somfy TaHoma Switch -- Thermor Cozytouch +| Vendor | Cloud | Local | +| --- | :-: | :-: | +| Atlantic Cozytouch | ✓ | | +| Bouygues Flexom | ✓ | | +| Brandt Smart Control † | ✓ | | +| Hexaom HexaConnect | ✓ | | +| Hitachi Hi Kumo | ✓ | | +| Nexity Eugénie | ✓ | | +| Rexel Energeasy Connect ‡ | ✓ | ✓ | +| Sauter Cozytouch | ✓ | | +| Simu LiveIn2 | ✓ | | +| Somfy | ✓ | ✓ | +| Thermor Cozytouch | ✓ | | +| Ubiwizz | ✓ | | + +Local API availability depends on your specific gateway. See the [Getting started guide](https://imicknl.github.io/python-overkiz-api/getting-started/) for the supported gateways and setup. † _This server's authentication method isn't supported yet. To use it, obtain an access token (by sniffing the original app) and create a local user on the Overkiz API platform._ -‡ _Requires OAuth credentials provided by Rexel._ +‡ _The cloud API requires OAuth credentials provided by Rexel; the local API uses a token from the EConnect app instead._ + +### Somfy + +| Gateway | Cloud | Local | +| --- | :-: | :-: | +| Connexoon IO | ✓ | ✓ | +| Connexoon RTS | ✓ | ✓ | +| TaHoma v2 | ✓ | ✓ | +| TaHoma Beecon | ✓ | ✓ | +| TaHoma Switch | ✓ | ✓ | +| Connectivity Kit | ✓ | | + +### Rexel Energeasy Connect + +| Gateway | Cloud | Local | +| --- | :-: | :-: | +| Energeasy Connect | ✓ | | +| Energeasy Connect Rail Din | ✓ | ✓ | +| Energeasy Connect V2 | ✓ | ✓ | +| Energeasy Connect V3 | ✓ | ✓ | +| Energeasy Connect V3 Rail Din | ✓ | ✓ | ## Installation diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 3c36439a..1e02a498 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -85,7 +85,7 @@ The library supports multiple authentication methods depending on the server: - **Username/Password**: Most cloud servers (Somfy, Cozytouch, Hitachi, Nexity) - **Bearer Token**: Cloud servers with pre-issued tokens -- **Local Token**: Somfy Developer Mode (local gateways) +- **Local Token**: local gateways (Somfy Developer Mode, Rexel Energeasy Connect) - **OAuth2 with PKCE**: Rexel (Azure AD B2C) Each server automatically selects the appropriate authentication strategy based on the credentials provided. diff --git a/docs/getting-started.md b/docs/getting-started.md index ff8e2a2b..45fa3aff 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -78,6 +78,14 @@ Use a cloud server when you want to connect through the vendor’s public API. U Local authentication requires a token generated via the official mobile app. For details on obtaining a token, refer to [Somfy TaHoma Developer Mode](https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode). + The local API is available on the following gateways: + + - Somfy Connexoon IO + - Somfy Connexoon RTS + - Somfy TaHoma v2 + - Somfy TaHoma Beecon + - Somfy TaHoma Switch + Use the helper function `create_local_server_config` to create a `Server` with `LocalTokenCredentials` to provide your token. ```python @@ -273,3 +281,50 @@ Use a cloud server when you want to connect through the vendor’s public API. U gateway_id="STORED_GATEWAY_ID", ) ``` + +=== "Rexel (local)" + + Rexel Energeasy Connect gateways expose a local API that third-party + software can connect to over your local network. Supported by the following + gateways: + + - Energeasy Connect Rail Din (`48`) + - Energeasy Connect V2 (`57`) + - Energeasy Connect V3 (`120`) + - Energeasy Connect V3 Rail Din (`125`) + + To obtain a token, enable the local API of your Energeasy Connect Box from + the EConnect mobile app: + + 1. Open the EConnect app. + 2. Go to **Settings** » **My home** » **Maintenance**. + 3. Select your gateway » **Local API**. + 4. Generate a token to authenticate your API requests. + 5. Use the generated token below, and set the host to your gateway PIN code + (e.g. `gateway-xxxx-xxxx-xxxx.local:8443`) or its IP address. + + Use the helper function `create_local_server_config` to create a `Server` + with `LocalTokenCredentials` to provide your token. + + ```python + import asyncio + + from pyoverkiz.auth.credentials import LocalTokenCredentials + from pyoverkiz.client import OverkizClient + from pyoverkiz.utils import create_local_server_config + + + async def main() -> None: + async with OverkizClient( + server=create_local_server_config( + host="gateway-xxxx-xxxx-xxxx.local:8443", + name="Rexel Energeasy Connect (local)", + manufacturer="Rexel", + ), + credentials=LocalTokenCredentials("token-from-the-econnect-app"), + verify_ssl=True, # disable if you connect via IP + ) as client: + await client.login() + + asyncio.run(main()) + ``` diff --git a/docs/index.md b/docs/index.md index 1392a0ad..bc4c25f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,20 +22,44 @@ pyOverkiz is an async Python library for interacting with Overkiz-based platform ## Supported hubs -- Atlantic Cozytouch -- Bouygues Flexom -- Brandt Smart Control † -- Hitachi Hi Kumo -- Nexity Eugénie -- Rexel Energeasy Connect ‡ -- Sauter Cozytouch -- Simu (LiveIn2) -- Somfy Connexoon IO -- Somfy Connexoon RTS -- Somfy TaHoma -- Somfy TaHoma Switch -- Thermor Cozytouch +| Vendor | Cloud | Local | +| --- | :-: | :-: | +| Atlantic Cozytouch | ✓ | | +| Bouygues Flexom | ✓ | | +| Brandt Smart Control † | ✓ | | +| Hexaom HexaConnect | ✓ | | +| Hitachi Hi Kumo | ✓ | | +| Nexity Eugénie | ✓ | | +| Rexel Energeasy Connect ‡ | ✓ | ✓ | +| Sauter Cozytouch | ✓ | | +| Simu LiveIn2 | ✓ | | +| Somfy | ✓ | ✓ | +| Thermor Cozytouch | ✓ | | +| Ubiwizz | ✓ | | + +Local API availability depends on your specific gateway. See the [Getting started guide](getting-started.md) for the supported gateways and setup. † _This server's authentication method isn't supported yet. To use it, obtain an access token (by sniffing the original app) and create a local user on the Overkiz API platform._ -‡ _Requires OAuth credentials provided by Rexel._ +‡ _The cloud API requires OAuth credentials provided by Rexel; the local API uses a token from the EConnect app instead._ + +### Somfy + +| Gateway | Cloud | Local | +| --- | :-: | :-: | +| Connexoon IO | ✓ | ✓ | +| Connexoon RTS | ✓ | ✓ | +| TaHoma v2 | ✓ | ✓ | +| TaHoma Beecon | ✓ | ✓ | +| TaHoma Switch | ✓ | ✓ | +| Connectivity Kit | ✓ | | + +### Rexel Energeasy Connect + +| Gateway | Cloud | Local | +| --- | :-: | :-: | +| Energeasy Connect | ✓ | | +| Energeasy Connect Rail Din | ✓ | ✓ | +| Energeasy Connect V2 | ✓ | ✓ | +| Energeasy Connect V3 | ✓ | ✓ | +| Energeasy Connect V3 Rail Din | ✓ | ✓ | diff --git a/pyoverkiz/const.py b/pyoverkiz/const.py index 366b7da6..e2e7e4bb 100644 --- a/pyoverkiz/const.py +++ b/pyoverkiz/const.py @@ -48,6 +48,7 @@ Server.SOMFY_EUROPE, Server.SOMFY_OCEANIA, Server.SOMFY_AMERICA, + Server.REXEL, ] SUPPORTED_SERVERS: MappingProxyType[str, ServerConfig] = MappingProxyType(