Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup readme file #555

Merged
merged 2 commits into from
Sep 18, 2022
Merged

Cleanup readme file #555

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0943500
Cleanup readme
ggravlingen Sep 18, 2022
7594633
Small fix
ggravlingen Sep 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 45 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,28 @@
[![PyPI version](https://badge.fury.io/py/pytradfri.svg)](https://badge.fury.io/py/pytradfri)
[![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/home-assistant-libs/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 and wall plugs.
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.

Some of the features include:
This library is [strictly typed](https://docs.python.org/3/library/typing.html).

- Get information on the gateway
- Observe lights, groups and other resources and get notified when they change
- Control wall plugs
- List all devices connected to gateway
- List all lights and get attributes of lights (name, state, color temp, dimmer level etc)
- Change attribute values of lights (name, state, color temp, dimmer level etc)
- Restart and reset the gateway
- 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)
<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:

Expand All @@ -23,38 +32,44 @@ Table of contents:
4. [Implement in your own Python platform](#implement-in-your-own-python-platform)
5. [Docker support](#docker-support)
6. [Known issues](#known-issues)
7. [Acknowledgements](#acknowledgements)
7. [Contributions](#contributions)

## Installation
You might have to use superuser privileges (sudo) for some commands to work when installing.

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.
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.8.25|
|TRADFRI bulb E14 WS opal 400lm|1.2.217|
|TRADFRI bulb E27 WS opal 980lm|1.2.217|
|TRADFRI bulb E27 W opal 1000lm|1.2.214|
|TRADFRI remote control|1.2.214|
|TRADFRI motion sensor|1.2.214|
|TRADFRI wall plug|2.0.022|
|Starkvind air purifier|1.0.033|
| 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)

![Screenshot of command line interface](./docs/pytradfri_cli.png)

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.
Expand Down Expand Up @@ -93,10 +108,12 @@ There is a Docker script available to bootstrap a dev environment. Run `./script
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.

## Acknowledgements
## Contributions

This is an implementation based on analysis [I](https://github.com/ggravlingen/) found [here](https://bitsex.net/software/2017/coap-endpoints-on-ikea-tradfri/) by [vidarlo](https://bitsex.net/).
We encourage contributions to this library. Please make sure contributions meet these requirements:

Paulus Schoutsen ([@balloob](https://github.com/balloob)) made a working Python library of the initial code concept. Lewis Juggins ([@lwis](https://github.com/lwis)) added support for asyncio and improved management of dependencies and consistency around return types. Many others have [contributed](https://github.com/ggravlingen/pytradfri/graphs/contributors) too.
- 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.