tradfri_gateway

A rust crate for connecting to the Ikea TRÅDFRI gateway, and for controlling your home devices through the gateway.

It also allows to optionally auto discover the IP of your Gateway via mDNS to simplify configuration.

The purpose of this crate was to create a stable build where several of the related crates relied on external binaries or C bindings that made the build more complicated than needed. The crate includes the coap/dtls code that works for this application, the only system dependency is openssl via the openssl crate. Also the idea is to make it as simple as possible to connect to the gateway rather than exposing all low level details.

The crate is under initial development so count on breaking changes every now and then until the best API has been found.

Usage example

Example of a simple planing program (from examples/light.rs):

use tradfri_gateway::{Device, TradfriGateway};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect with gateway code
    let gateway_code = "enter gateway code from the underside of your TRÅDFRI gateway";
    let mut gateway = TradfriGateway::from_gateway_code(gateway_code)?;
    println!("{:#?}", gateway);

    // Connect with identifier and session key once created
    // let session_key = "enter pre shared key generated from gateway code";
    // let identifier = "enter identifier generated along with the pre shared key";
    // let mut gateway =
    //     TradfriGateway::from_identifier_and_session_key(identifier, session_key)?;
    // println!("{:#?}", gateway);

    // Toggle all your lights
    for i in 0..10 {
        for device in gateway.devices()? {
            match device {
                Ok(Device::RemoteControl) => (),
                Ok(Device::Light(mut light)) => {
                    if i % 2 == 0 {
                        light.on()?;
                    } else {
                        light.off()?;
                    }
                    println!("light {:#?}", light);
                }
                Err(error) => panic!("{}", error),
            }
        }
    }

    // Turn on one specific light, if id exists
    for i in 0..10 {
        if let Ok(Device::Light(mut light)) = gateway.device(65568) {
            if i % 2 == 0 {
                light.on()?;
            } else {
                light.off()?;
            }
        }
    }

    Ok(())
}

Enter your credentials in the example tile and run the example with:

$ cargo run --example light

Whishlist for new features

• Support for more devices.
• Add optional automatic storage of session key and identifier on disk to simplify connection process.
• Add cli to control the gateway from a terminal, it would also be a good demo.
• Add relevant debug logs.
• Support for the newer Ikea DIRIGERA hub.

Contributing

You can help out in several ways:

1. Try out the crate
2. Report any issues, bugs, missing documentation or examples
3. Create issues with feedback on the ergonomy of the crate APIs
4. Extend the documentation or examples
5. Contribute code changes

Feedback on the ergonomics of this crate or its features/lack there of might be as valuable as code contributions.

Code contributions

That being said, code contributions are more than welcome. Create a merge request, with your new cuts, tools, programs or other improvements and create a pull request.

Ensure that any new/changed publicly facing APIs have proper documentation comments.

Once a pull request is ready for merge, also squash the commits into a single commit per feature or fix.

The commit messages in this project should comply with the Conventional Commits standard so that the semver versions can be automatically calculated and the release changelog can be automatically generated.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Serde by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.