Dirigera Python Client

Pypi Downloads

This repository provides an unofficial Python client for controlling the IKEA Dirigera Smart Home Hub. Current features:

Dirigera Python Client
Devices
Scene

Support for other features will be added in the future and your input in form of issues and PRs is greatly appreciated.

Installation

pip install dirigera

Quickstart

Find out the ip-address of your Dirigera (check your router)
Once you installed dirigera with pip you can run the included generate-token script. Here you can directly set the ip-address of you dirigera as parameter.
```
generate-token <Dirigera ip-address>
```
The script starts the auth process. When prompted, you must push the action button on the bottom of your 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:
mgwB.aXqwpzV89N0aUwBhZMJjD8a.UBPyzy2InGtqgwo2MO5.xX4ug7.uBcVJquwYzLnAijF7SdYKvNxTo0uzQKahV10A-3ZQOz-UAubGP6sHWt1CJx3QmWZyE7ZcMZKgODXjSzWL1lumKgGz5dUIwFi3rhNxgK-IsBGeGVhNXPt8vGrYEcZePwPvNAIg8RqmlH27L-JZPnkAtP2wHoOdW72Djot3yJsohtEsb0p9mJvoZFSavTlTr4LDuf584vuH5fha5xoR9QhhIvvgbAP-s4EHFqENNi6vrYLHKR.sdqnv4sYw6UH-l6oiPnnRLxinoqBPOlWhlcL9doFviXQE.tZ9X8WVqyBrd0NYHlo9iorEvUbnZuD02BEJrg4NLwgh3rZtyF0Mi46HenynzBohbPn4RnuSYYCiHt5EZnWedxBtDqc7mSTm1ZtyD

Done. Use this token in the hub setup.

dirigera.Hub(
   token="mgwB.aXqwpzV89N0aUwBhZMJjD8a...",
   ip_address="192.1..."
)

Dirigera Hub

Setting up the client works by providing the token and ip address.

import dirigera

dirigera_hub = dirigera.Hub(
    token="mgwB.aXqwpzV89N0aUwBhZMJjD8a...",
    ip_address="192.1..."
)

<details> <summary>List dirigera_hub functions</summary>

# Send a PATCH request to the hub
response = dirigera_hub.patch(route="/devices/1", data=[{"attributes": {"customName": "new name"}}])

# Send a GET request to the hub
response = dirigera_hub.get(route="/devices")

# Send a POST request to the hub
response = dirigera_hub.post(route="/scenes", data={"name": "new scene"})

# Send a DELETE request to the hub
response = dirigera_hub.delete(route="/scenes/1")

# Fetch all air purifiers registered in the hub
air_purifiers = dirigera_hub.get_air_purifiers()

# Fetch an air purifier by its ID
air_purifier = dirigera_hub.get_air_purifier_by_id(id_="1")

# Fetch all lights registered in the hub
lights = dirigera_hub.get_lights()

# Fetch a light by its name
light = dirigera_hub.get_light_by_name(lamp_name="kitchen light")

# Fetch a light by its ID
light = dirigera_hub.get_light_by_id(id_="1")

# Fetch all outlets registered in the hub
outlets = dirigera_hub.get_outlets()

# Fetch an outlet by its name
outlet = dirigera_hub.get_outlet_by_name(outlet_name="kitchen outlet")

# Fetch an outlet by its ID
outlet = dirigera_hub.get_outlet_by_id(id_="1")

# Fetch all environment sensors registered in the hub
sensors = dirigera_hub.get_environment_sensors()

# Fetch an environment sensor by its ID
sensor = dirigera_hub.get_environment_sensor_by_id(id_="1")

# Fetch all motion sensors registered in the hub
sensors = dirigera_hub.get_motion_sensors()

# Fetch a motion sensor by its name
light = dirigera_hub.get_motion_sensor_by_name(motion_sensor_name="kitchen motion sensor")

# Fetch a motion sensor by its ID
sensor = dirigera_hub.get_motion_sensor_by_id(id_="1")

# Fetch all open/close sensors registered in the hub
sensors = dirigera_hub.get_open_close_sensors()

# Fetch an open/close sensor by its ID
sensor = dirigera_hub.get_open_close_by_id(id_="1")

# Fetch all blinds registered in the hub
blinds = dirigera_hub.get_blinds()

# Fetch a blind by its name
blind = dirigera_hub.get_blind_by_name(blind_name="living room blind")

# Fetch a blind by its ID
blind = dirigera_hub.get_blinds_by_id(id_="1")

# Fetch all controllers registered in the hub
controllers = dirigera_hub.get_controllers()

# Fetch a controller by its name
controller = dirigera_hub.get_controller_by_name(controller_name="remote control")

# Fetch a controller by its ID
controller = dirigera_hub.get_controller_by_id(id_="1")

# Fetch all scenes
scenes = dirigera_hub.get_scenes()

# Fetch a scene by its ID
scene = dirigera_hub.get_scene_by_id(scene_id="1")

# Fetch all water sensors registered in the hub
water_sensors = dirigera_hub.get_water_sensors()

# Fetch a water sensor by its ID
water_sensor = dirigera_hub.get_water_sensor_by_id(id_="1")

# Fetch all occupancy sensors registered in the hub
occupancy_sensors = dirigera_hub.get_occupancy_sensors()

# Fetch an occupancy sensor by its ID
occupancy_sensor = dirigera_hub.get_occupancy_sensor_by_id(id_="1")

# Fetch all light sensors registered in the hub
light_sensors = dirigera_hub.get_light_sensors()

# Fetch a light sensor by its ID
light_sensor = dirigera_hub.get_light_sensor_by_id(id_="1")

# Fetch all devices registered in the hub
devices = dirigera_hub.get_all_devices()

# Create a new scene
scene = dirigera_hub.create_scene(
    info=Info(name="New Scene", icon=Icon.SCENES_BOOK),
    scene_type=SceneType.USER_SCENE,
    triggers=[],
    actions=[]
)

# Delete a scene by its ID
dirigera_hub.delete_scene(scene_id="1")

</details>

Devices

All available devices (Light, Controller, Outlet, ...) consist of the core data defined in device.py:

Core Device Data

id: str
relation_id: Optional[str] = None
type: str
device_type: str
created_at: datetime.datetime
is_reachable: bool
last_seen: datetime.datetime
attributes: Attributes
capabilities: Capabilities
room: Optional[Room] = None
device_set: List
remote_links: List[str]
is_hidden: Optional[bool] = None

Attributes

All devices have attributes. Some devices have special attributes (for example Light has `is_on``). These are the core attributes each device has:

custom_name: str
model: str
manufacturer: str
firmware_version: str
hardware_version: str
serial_number: Optional[str] = None
product_code: Optional[str] = None
ota_status: Optional[str] = None
ota_state: Optional[str] = None
ota_progress: Optional[int] = None
ota_policy: Optional[str] = None
ota_schedule_start: Optional[datetime.time] = None
ota_schedule_end: Optional[datetime.time] = None

Capabilities

All devices have capabilities (for some it is just empty lists). Capabilities desrcibe what send/receive actions can be performed:

can_send: List[str]
can_receive: List[str]

All devices have a room with the corresponging infos.

Room

id: str
name: str
color: str
icon: str

Controlling Lights

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

lights = dirigera_hub.get_lights()

The light object has the following attributes (additional to the core attributes):

startup_on_off: Optional[StartupEnum] = None # Optional attributes are not present on all lights
is_on: bool
light_level: Optional[int] = None
color_temperature: Optional[int] = None
color_temperature_min: Optional[int] = None
color_temperature_max: Optional[int] = None
color_hue: Optional[int] = None
color_saturation: Optional[float] = None

Available methods for light are:

# Reload the light data from the hub
light.reload()

# Set the name of the light
light.set_name(name="kitchen light 1")

# Turn the light on or off
light.set_light(lamp_on=True)

# Set the light level (1-100)
light.set_light_level(light_level=90)

# Set the color temperature
light.set_color_temperature(color_temp=3000)

# Set the light color using hue (0-360) and saturation (0.0-1.0)
light.set_light_color(hue=128, saturation=0.5)

# Set the startup behavior of the light
light.set_startup_behaviour(behaviour=StartupEnum.START_OFF)

Controlling Outlets

To get information about the available outlets, you can use the get_outlets() method:

outlets = dirigera_hub.get_outlets()

The outlet object has the following attributes (additional to the core attributes):

is_on: bool
startup_on_off: Optional[StartupEnum] = None
status_light: Optional[bool] = None
identify_period: Optional[int] = None
permitting_join: Optional[bool] = None
energy_consumed_at_last_reset: Optional[float] = None
current_active_power: Optional[float] = None
current_amps: Optional[float] = None
current_voltage: Optional[float] = None
total_energy_consumed: Optional[float] = None
total_energy_consumed_last_updated: Optional[datetime.datetime] = None
time_of_last_energy_reset: Optional[datetime.datetime] = None

Available methods for outlet are:

Dirigera

Install / Use

README