pytradfri Documentation

Installation depends on whether your application is synchronous or asynchronous.

Asynchronous Applications (Recommended)

For async applications, install the library with the [async] extra:

pip install pytradfri[async]

Synchronous Applications

For sync applications, you must first install libcoap using the provided script:

./script/install-coap-client.sh

Then install the base package via pip.

Security Note: Do not store the security code printed on the gateway permanently in your application. Use the Pre-Shared Key (PSK) for communication.

A Docker script is provided to create a containerized development environment that supports both synchronous and asynchronous modes. This is the easiest way to start developing or testing without local dependency issues.

Run the following command to build and launch the container:

./script/dev_docker

The working directory inside the container is /usr/src/app, where the repository is checked out and installed as a Python dependency.

You can monitor any connected device or group for state changes by using the .observe() method and providing a callback function. This is useful for reacting to physical interactions (like pressing a remote) or automated changes.

Example of observing a light and printing its state when it changes:

def change_listener(device):
  print(device.name + " is now " + str(device.light_control.lights[0].state))

# Use api() to execute the observation in the interactive prompt
api(lights[0].observe(change_listener))

You can test the library in a stand-alone interactive mode using the CLI. This is useful for verifying connectivity and exploring device attributes.

Run the following command, replacing IP with your gateway's IP address:

python3 -i -m pytradfri IP

Upon first run, you will be prompted to enter the 'Security Code' located on the back of your IKEA gateway.

Once in the interactive prompt, you can use the api() wrapper to execute commands. Common tasks include:

• lights: Lists all connected lights.
• api(lights[index].light_control.set_dimmer(level)): Sets brightness for a specific light.
• api(lights[index].observe(callback)): Sets up an observer to listen for state changes on a device.

python3 -i -m pytradfri 192.168.1.XX