[](https://badge.fury.io/py/pytradfri)
Python package to communicate with the [IKEA Trådfri](http://www.ikea.com/us/en/catalog/products/00337813/) (Tradfri) ZigBee gateway compatible with ZigBee light link products. By using this library you can communicate with the gateway and control IKEA's lights, wall plugs and other peripherals.
This library is [strictly typed](https://docs.python.org/3/library/typing.html).
<b>Some of the features include:</b>
- Gateway:
- Get information on the gateway, list all devices connected to the gateway, and restart and reset the gateway
- Any connected device or group:
- Observe state and get notified when it changes
- Lights:
- List all lights, get and control attributes of lights (name, state, color temp, dimmer level etc)
- Wall plugs:
- List all wall plungs, and control wall plugs
- Air purifier
- List all purifiers, control fan level, and get air quality level
- Window blind
- List all blinds, control cover level, and get battery level
- Smart tasks:
- List smart tasks (wake up, on/off and not home) and their attributes
- Alter values in smart tasks (some of these features not available in app yet)
Table of contents:
1. [Installation](#installation)
2. [Verified Device Compatibility](#verified-device-compatibility)
3. [Stand-alone use (command-line interface)](#stand-alone-use-command-line-interface)
4. [Implement in your own Python platform](#implement-in-your-own-python-platform)
5. [Docker support](#docker-support)
6. [Known issues](#known-issues)
7. [Contributions](#contributions)
## Installation
The easiest way of getting started is by running this library in [VS Code online](https://open.vscode.dev/home-assistant-libs/pytradfri), or by installing it locally using the included containerized development environment for VS Code.
For other installation methods, you might have to use superuser privileges (sudo) for some commands to work when installing.
To use the library in a synchronous application, you first need to install [libcoap](https://github.com/obgm/libcoap) using [this script](script/install-coap-client.sh). Use [examples/example_sync.py](https://github.com/ggravlingen/pytradfri/blob/master/examples/example_sync.py) when testing this.
For asynchronous applications you will need to install `pytradfri[async]`, for instance using the requirements file: `pip install pytradfri[async]`. Please note that install might take considerable time on slow devices. Use [examples/example_async.py](https://github.com/ggravlingen/pytradfri/blob/master/examples/example_async.py) when testing this.
Security best practice is to **_not_** store the security code that is printed on the gateway permanently in your application. Please always use the PSK when communicating with the gateway.
## Verified Device Compatibility
| Device | Version |
| ------------------------------ | ------- |
| IKEA Gateway (E1526) | 1.19.32 |
| TRADFRI bulb E14 WS opal 400lm | 1.2.217 |
| TRADFRI bulb E14 WS 470lm | 2.3.087 |
| TRADFRI bulb E27 WS opal 980lm | 2.3.087 |
| TRADFRI bulb E27 W opal 1000lm | 2.3.086 |
| TRADFRI remote control | 2.3.014 |
| TRADFRI motion sensor | 1.2.214 |
| TRADFRI wall plug | 2.0.022 |
| Starkvind air purifier | 1.1.001 |
## Stand-alone use (command-line interface)
If you want to test this library stand-alone in a command-line interface:
```shell
$ python3 -i -m pytradfri IP
```
Where **IP** is substituted by the IP-address to your gateway.
The first time running pytradfri you will be asked to input the 'Security Code' found on the back of your IKEA gateway.
### Examples of commands in the stand-alone prompt:
List all lights:
```python
lights
```
Set the brightness of item 1 to 50 in lights list:
```python
api(lights[1].light_control.set_dimmer(50))
```
Observe a light for changes:
```python
def change_listener(device):
print(device.name + " is now " + str(device.light_control.lights[0].state))
api(lights[0].observe(change_listener))
```
## Implement in your own Python platform
Please see the example files.
## Docker support
There is a Docker script available to bootstrap a dev environment. Run `./script/dev_docker` and you will build and launch a container that is ready to go for both sync and async. After launching, follow the above instructions to test the library stand-alone.
The working directory of the Docker image is `/usr/src/app`. The checked out version of this repo is added there and installed as a Python dependency for easy development and testing. When you want to use the latest stable version from pip, you only have to change to another working directory.
## Known issues
We are aware of issues some users face with their gateways. Anecdotal evicence suggests sending many requests (spamming) the gateway, or an unreliable network connection can be the culprit. As a first solution, try to limit the number of requests, and move the Gateway closer to the device running pytradfri on the nework. Other than that, there is unfortunately not anything this project can do to support or resolve these issues at this time. As this progresses, we will ensure the project is kept up-to-date.
## Contributions
We encourage contributions to this library. Please make sure contributions meet these requirements:
- Your contribution contains [type annotations](https://docs.python.org/3/library/typing.html). This is a strictly typed library: new contributions will not be merged unless they contain type annotations.
- Your contribution is covered by tests.
Raw data
{
"_id": null,
"home_page": "https://github.com/home-assistant-libs/pytradfri",
"name": "pytradfri",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "ikea tradfri api iot light homeautomation",
"author": "balloob, lwis, ggravlingen, janiversen",
"author_email": "no@email.com",
"download_url": "https://files.pythonhosted.org/packages/48/e3/f610746c4a0a7f78c117168d5fa14a7771b9e050d1076a977ff22785dd74/pytradfri-13.0.0.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/pytradfri)\n\nPython package to communicate with the [IKEA Tr\u00e5dfri](http://www.ikea.com/us/en/catalog/products/00337813/) (Tradfri) ZigBee gateway compatible with ZigBee light link products. By using this library you can communicate with the gateway and control IKEA's lights, wall plugs and other peripherals.\n\nThis library is [strictly typed](https://docs.python.org/3/library/typing.html).\n\n<b>Some of the features include:</b>\n\n- Gateway:\n - Get information on the gateway, list all devices connected to the gateway, and restart and reset the gateway\n- Any connected device or group:\n - Observe state and get notified when it changes\n- Lights:\n\n - List all lights, get and control attributes of lights (name, state, color temp, dimmer level etc)\n\n- Wall plugs:\n - List all wall plungs, and control wall plugs\n- Air purifier\n - List all purifiers, control fan level, and get air quality level\n- Window blind\n - List all blinds, control cover level, and get battery level\n- Smart tasks:\n - List smart tasks (wake up, on/off and not home) and their attributes\n - Alter values in smart tasks (some of these features not available in app yet)\n\nTable of contents:\n\n1. [Installation](#installation)\n2. [Verified Device Compatibility](#verified-device-compatibility)\n3. [Stand-alone use (command-line interface)](#stand-alone-use-command-line-interface)\n4. [Implement in your own Python platform](#implement-in-your-own-python-platform)\n5. [Docker support](#docker-support)\n6. [Known issues](#known-issues)\n7. [Contributions](#contributions)\n\n## Installation\n\nThe easiest way of getting started is by running this library in [VS Code online](https://open.vscode.dev/home-assistant-libs/pytradfri), or by installing it locally using the included containerized development environment for VS Code.\n\nFor other installation methods, you might have to use superuser privileges (sudo) for some commands to work when installing.\n\nTo use the library in a synchronous application, you first need to install [libcoap](https://github.com/obgm/libcoap) using [this script](script/install-coap-client.sh). Use [examples/example_sync.py](https://github.com/ggravlingen/pytradfri/blob/master/examples/example_sync.py) when testing this.\n\nFor asynchronous applications you will need to install `pytradfri[async]`, for instance using the requirements file: `pip install pytradfri[async]`. Please note that install might take considerable time on slow devices. Use [examples/example_async.py](https://github.com/ggravlingen/pytradfri/blob/master/examples/example_async.py) when testing this.\n\nSecurity best practice is to **_not_** store the security code that is printed on the gateway permanently in your application. Please always use the PSK when communicating with the gateway.\n\n## Verified Device Compatibility\n\n| Device | Version |\n| ------------------------------ | ------- |\n| IKEA Gateway (E1526) | 1.19.32 |\n| TRADFRI bulb E14 WS opal 400lm | 1.2.217 |\n| TRADFRI bulb E14 WS 470lm | 2.3.087 |\n| TRADFRI bulb E27 WS opal 980lm | 2.3.087 |\n| TRADFRI bulb E27 W opal 1000lm | 2.3.086 |\n| TRADFRI remote control | 2.3.014 |\n| TRADFRI motion sensor | 1.2.214 |\n| TRADFRI wall plug | 2.0.022 |\n| Starkvind air purifier | 1.1.001 |\n\n## Stand-alone use (command-line interface)\n\n\n\nIf you want to test this library stand-alone in a command-line interface:\n\n```shell\n$ python3 -i -m pytradfri IP\n```\n\nWhere **IP** is substituted by the IP-address to your gateway.\n\nThe first time running pytradfri you will be asked to input the 'Security Code' found on the back of your IKEA gateway.\n\n### Examples of commands in the stand-alone prompt:\n\nList all lights:\n\n```python\nlights\n```\n\nSet the brightness of item 1 to 50 in lights list:\n\n```python\napi(lights[1].light_control.set_dimmer(50))\n```\n\nObserve a light for changes:\n\n```python\ndef change_listener(device):\n print(device.name + \" is now \" + str(device.light_control.lights[0].state))\n\napi(lights[0].observe(change_listener))\n```\n\n## Implement in your own Python platform\n\nPlease see the example files.\n\n## Docker support\n\nThere is a Docker script available to bootstrap a dev environment. Run `./script/dev_docker` and you will build and launch a container that is ready to go for both sync and async. After launching, follow the above instructions to test the library stand-alone.\n\nThe working directory of the Docker image is `/usr/src/app`. The checked out version of this repo is added there and installed as a Python dependency for easy development and testing. When you want to use the latest stable version from pip, you only have to change to another working directory.\n\n## Known issues\n\nWe are aware of issues some users face with their gateways. Anecdotal evicence suggests sending many requests (spamming) the gateway, or an unreliable network connection can be the culprit. As a first solution, try to limit the number of requests, and move the Gateway closer to the device running pytradfri on the nework. Other than that, there is unfortunately not anything this project can do to support or resolve these issues at this time. As this progresses, we will ensure the project is kept up-to-date.\n\n## Contributions\n\nWe encourage contributions to this library. Please make sure contributions meet these requirements:\n\n- Your contribution contains [type annotations](https://docs.python.org/3/library/typing.html). This is a strictly typed library: new contributions will not be merged unless they contain type annotations.\n- Your contribution is covered by tests.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "IKEA Tr\u00e5dfri/Tradfri API. Control and observe your lights from Python.",
"version": "13.0.0",
"split_keywords": [
"ikea",
"tradfri",
"api",
"iot",
"light",
"homeautomation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a6d1106a4ea0939f8753b393c6b993085eb1241528e2f627ef290189039d3fb",
"md5": "079b2d06ef764c49ef94a2a378079b0e",
"sha256": "cab76c588a5b5a79b7705ab6192cad73843012de28d20cca01c172d3fec38372"
},
"downloads": -1,
"filename": "pytradfri-13.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "079b2d06ef764c49ef94a2a378079b0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 40275,
"upload_time": "2023-02-05T12:34:04",
"upload_time_iso_8601": "2023-02-05T12:34:04.530217Z",
"url": "https://files.pythonhosted.org/packages/4a/6d/1106a4ea0939f8753b393c6b993085eb1241528e2f627ef290189039d3fb/pytradfri-13.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "48e3f610746c4a0a7f78c117168d5fa14a7771b9e050d1076a977ff22785dd74",
"md5": "05f72d7cc65e105fc905619b88f7ef7b",
"sha256": "c6677b5f2189518a2ed83b5d3aa92dce5fc4cfdbba530904fbebf2c6aee93411"
},
"downloads": -1,
"filename": "pytradfri-13.0.0.tar.gz",
"has_sig": false,
"md5_digest": "05f72d7cc65e105fc905619b88f7ef7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 32665,
"upload_time": "2023-02-05T12:34:05",
"upload_time_iso_8601": "2023-02-05T12:34:05.924909Z",
"url": "https://files.pythonhosted.org/packages/48/e3/f610746c4a0a7f78c117168d5fa14a7771b9e050d1076a977ff22785dd74/pytradfri-13.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 12:34:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "home-assistant-libs",
"github_project": "pytradfri",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "aiocoap",
"specs": [
[
"==",
"0.4.5"
]
]
},
{
"name": "DTLSSocket",
"specs": [
[
"==",
"0.1.12"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"1.10.4"
]
]
}
],
"tox": true,
"lcname": "pytradfri"
}
JSON
