Metadata-Version: 2.1
Name: dirigera
Version: 0.0.1
Summary: An unofficial Python client for controlling the IKEA Dirigera Smart Home Hub
Author-email: Leggin <legginsun@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Leggin
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Leggin/dirigera
Keywords: python,iot,smarthome,hub,lighting,ikea,tradfri,dirigera
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

# Dirigera Python client

This repository provides an unofficial Python client for controlling the IKEA Dirigera Smart Home Hub. Currently, only light control is supported, but support for other features will be added in the future.

## Installation

```bash
pip install dirigera
```

## Quickstart

1. Find out the ip-address of your Dirigera (check your router)
2. Copy the address and set the value of `DIRIGERA_IP_ADDRESS` in the `.env-template` file to the ip
3. Rename the `.env-template` file to `.env`
4. Run the authentication script:
   ```bash
   bash auth.sh
   ```
   When prompted, you must push the action button on Dirigera. After that hit ENTER and your `token` will be printed to the console.  
   Example:
   ```
    Press the action button on Dirigera then hit ENTER ...
    Your Token (put this into your .env file):
    mgwB.aXqwpzV89N0aUwBhZMJjD8a.UBPyzy2InGtqgwo2MO5.xX4ug7.uBcVJquwYzLnAijF7SdYKvNxTo0uzQKahV10A-3ZQOz-UAubGP6sHWt1CJx3QmWZyE7ZcMZKgODXjSzWL1lumKgGz5dUIwFi3rhNxgK-IsBGeGVhNXPt8vGrYEcZePwPvNAIg8RqmlH27L-JZPnkAtP2wHoOdW72Djot3yJsohtEsb0p9mJvoZFSavTlTr4LDuf584vuH5fha5xoR9QhhIvvgbAP-s4EHFqENNi6vrYLHKR.sdqnv4sYw6UH-l6oiPnnRLxinoqBPOlWhlcL9doFviXQE.tZ9X8WVqyBrd0NYHlo9iorEvUbnZuD02BEJrg4NLwgh3rZtyF0Mi46HenynzBohbPn4RnuSYYCiHt5EZnWedxBtDqc7mSTm1ZtyD
   ```
5. Copy your full token and set the value of `DIRIGERA_TOKEN` in the `.env` file
6. Run the example
    ```bash
    bash run-example.sh
    ```

## Dirigera Hub

Setting up the client works by providing the token and ip address that is read from your .env file by the `config.py`

```python
import dirigera

dirigera_hub = dirigera.Hub(
    token=config.DIRIGERA_TOKEN,
    base_url=config.DIRIGERA_IP_ADDRESS
)
```

## [Controlling Lights](./src/devices/light.py)

To get information about the available lights, you can use the `get_lights()` method:

```python
light = dirigera_hub.get_lights()
```

The light object has the following attributes:

```python
    light_id: str
    is_reachable: bool
    custom_name: str
    is_on: bool
    startup_on_off: StartupEnum
    light_level: int | None  # not all lights have a light level
    color_temp: int | None  # not all lights have a color temperature
    color_temp_min: int | None
    color_temp_max: int | None
    color_hue: int | None  # not all lights have a color hue
    color_saturation: float | None  # not all lights have a color saturation
    can_receive: List[str]  # list of all available commands ["customName", "isOn", "lightLevel", ...]
```

Available methods for light are:

```python
    light.set_name(name="kitchen light 1")

    light.set_light(lamp_on=True)

    light.set_light_level(light_level=90)

    light.set_color_temperature(color_temp=3000)

    light.set_light_color(hue=128, saturation=0.5)

    light.set_startup_behaviour(behaviour=StartupEnum.START_OFF)
```


## Event Listener
The event listener allows you to listen to events that are published by your Dirigera hub. This is useful if you want to automate tasks based on events such as when a light is turned on or off, or when the color temperature of a light is changed.

```python

def on_message(ws: Any, message: str):
    message_dict = json.loads(message)
    data = message_dict["data"]
    if data["id"] == bed_light.light_id:
        print(f"{message_dict['type']} event on {bed_light.custom_name}, attributes: {data['attributes']}")

def on_error(ws: Any, message: str):
    print(message)

dirigera_hub.create_event_listener(
    on_message=on_message, on_error=on_error
)
```
```
deviceStateChanged event on Bed Light, attributes: {'isOn': False}
```

## Motivation
The primary motivation for this project was to provide users with the ability to control the startup behavior of their smart home lamps when there is a power outage.  
The default behavior of the hub is to turn on all lights when power is restored, which can be problematic if the user is away from home or on vacation, and a small power fluctuation causes all lights to turn on and stay on. Unfortunately, the IKEA app does not offer a way to change this default behavior.  
The `set_startup_behaviour()` function enables users to override the default behavior and choose the startup behavior that best suits their needs (START_ON = turn on light when power is back, START_OFF = light stays off when power is back).  
I can not guarantee that all IKEA lamps offer this functionality.

## Contributing

Contributions are welcome! If you have an idea for a new feature or a bug fix, please submit a pull request.

## License

The MIT License (MIT)

Copyright (c) 2023 Leggin
