huelib-rs

Rust bindings for the Philips Hue API.

Documentation

License

Licensed under the MIT License.

lib.rs:

Rust bindings for the Philips Hue API.

About

The minimum supported API version is 1.37.

This library sends HTTP requests to the bridge using the ureq crate. The responses/requests are deserialized/serialized using the serde, serde_json and serde_repr crates.

Features

• upnp-description: Adds support for accessing the UPnP description of a bridge. See the bridge::Description struct for more information.
• old-api: Minimal effort support for older api versions. Useful for users of the no longer supported Hue v1 bridge. This lowers the supported API version to 1.16 not all features are guarenteed to work.

Connecting to a bridge

To connect to a bridge, the IP address of the bridge and the name of a registered user is needed. You can use the bridge::discover_nupnp function to get the IP addresses of bridges that are in the local network and the bridge::register_user function to register a new user on a bridge.

To able to send requests to the bridge, a Bridge must be created. For example:

use huelib::Bridge;
use std::net::{IpAddr, Ipv4Addr};

let bridge = Bridge::new(IpAddr::V4(Ipv4Addr::new(192, 168, 1, 2)), "username");

You can then send requests using either the methods of Bridge or the different traits (Creator, Modifier, etc.).

Sending requests using Bridge methods

The methods of Bridge can be used to send requests.

Methods beginning with create, set, and search_new take either a creator, modifier, or scanner as parameter which has to be constructed before sending the request. For example, you can construct a group::Creator with the new function and then pass it to the Bridge::create_group method as a parameter.

For a list of available methods, view the documentation of Bridge.

Sending requests using trait methods

Some trait methods can be used to send requests instead of calling a Bridge method.

• Creator::execute: Can be used instead of Bridge::create_* methods.
• Modifier::execute: Can be used instead of Bridge::set_* methods.
• Scanner::execute: Can be used instead of Bridge::search_new_* methods

Examples

Note: In the following examples the creation of bridge is abbreviated to reduce irrelevant code.

Creating a group

Creates a new group with the name example and puts the light with the identifier 1 into the group and sets the class to Office.

• Using the Bridge::create_group method:

  use huelib::resource::group;
  
  // let bridge = Bridge::new(...);
  let creator = group::Creator::new("example".into(), vec!["1".into()])
      .with_class(group::Class::Office);
  let id = bridge.create_group(&creator)?;
  println!("Created group with id `{}`", id);
  

• Using the Creator::execute trait method:

  // Note that the trait `Creator` has to be in scope because the `execute` method is called.
  use huelib::resource::{group, Creator};
  
  // let bridge = Bridge::new(...);
  let id = group::Creator::new("example".into(), vec!["1".into()])
      .with_class(group::Class::Office)
      .execute(&bridge)?;
  println!("Created group with id `{}`", id);
  

Modifying a light state

Turns the light with the identifier 1 on and sets the color to red.

• Using the Bridge::set_light_state method:

  use huelib::{resource::light, Color};
  
  // let bridge = Bridge::new(...);
  let modifier = light::StateModifier::new()
      .with_on(true)
      .with_color(Color::from_rgb(255, 0, 0));
  let responses = bridge.set_light_state("1", &modifier)?;
  

• Using the Modifier::execute trait method:

  // Note that the trait `Modifier` has to be in scope because the `execute` method is called.
  use huelib::resource::{light, Modifier};
  use huelib::Color;
  
  // let bridge = Bridge::new(...);
  let responses = light::StateModifier::new()
      .with_on(true)
      .with_color(Color::from_rgb(255, 0, 0))
      .execute(&bridge, "1".into())?;
  

Getting a light

Print the light with the identifier 1:

// let bridge = Bridge::new(...);
let light = bridge.get_light("1")?;
println!("Light 1: {:?}", light);

Searching for new sensors

Start searching for new sensors:

use huelib::resource::sensor;

// let bridge = Bridge::new(...);
let scanner = sensor::Scanner::new();
bridge.search_new_sensors(&scanner)?;

Print the discovered sensors:

// let bridge = Bridge::new(...);
let scan = bridge.get_new_sensors()?;
for resource in scan.resources {
    println!("Discovered sensor `{}` with ID `{}`", resource.name, resource.id);
}