Hive Client

The Hive Client crate provides a client for interfacing with Hive smart home systems.

Usage

[dependencies]
hive-client = "0.0.5"

Capabilities

1. Authenticate with Hive.
2. Setup trusted devices in a Hive account.
3. Request live Weather information directly from Hive.
4. List Quick Actions configured in a Hive account.
5. Activate Quick Actions on demand.
6. List Devices associated with a Hive account (Hubs, Thermostats, Hubs, etc).
7. List Products currently running in a Hive account.
8. Change state of Products in a Hive account (Boost heating/hot water, change target temperature, etc).

Examples

More in-depth examples can be found in documentation comments on the Client methods.

Trigger a Quick Action

use hive_client::authentication::{TrustedDevice, User};

let client = hive_client::Client::new("Home Automation");

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example"), trusted_device).await;

if let Ok(_) = attempt {
    // Login was successful

    let mut actions = client.get_actions()
        .await
        .expect("Quick action should be retrieved");

    if let Some(mut first_action) = actions.first_mut() {
        let was_activated = first_action.activate()
            .await
            .expect("Quick action should be activated");
    }
}

Set Target Temperature of Heating

use hive_client::authentication::{TrustedDevice, User};
use hive_client::products::{Product, ProductData, State, States};

let client = hive_client::Client::new("Home Automation");

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example"), trusted_device).await;

if let Ok(_) = attempt {
    // Login was successful

    let products = client.get_products()
        .await
        .expect("Products should be retrieved");

    if let Some(mut heating) = products.into_iter().find(|Product { data, .. }| matches!(data, ProductData::Heating { .. })) {
        let was_set = heating.set_state(States(vec!(State::TargetTemperature(18.0))))
            .await
            .expect("Product state should be set");
    }
}

Retrieve Current Weather

use hive_client::authentication::{TrustedDevice, User};
use hive_client::products::{Product, ProductData, State, States};

let client = hive_client::Client::new("Home Automation");

let trusted_device = Some(TrustedDevice::new(
    "device_password",
    "device_group_key",
    "device_key"
));

let attempt = client.login(User::new("example@example.com", "example"), trusted_device).await;

if let Ok(_) = attempt {
    // Login was successful

    let postcode = "SW1A 1AA";

    let weather = client.get_weather(postcode)
        .await
        .expect("Weather should be retrieved");

    // Example: It is currently 18.0C with clear skies at Buckingham Palace
    println!("It is currently {} with {} at Buckingham Palace", weather.data.temperature, weather.data.description);
}

Contributing

There are tons of features which could be added to the crate. If you'd like to contribute, please feel free to open an issue or a pull request.

Examples of features which could be added:

1. Better parity between the Hive API and the structs.
2. Support for controlling Holiday Mode.
3. Support for modifying the schedule of a Hive Device.
4. Support for other Hive products (e.g. Hive Lights, Smart Plugs, Motion Sensors, etc).

Testing

Many of the tests require that an AWS Cognito User Pool, configured with SRP authentication and device tracking, be available to act as a mock server.

The setup of a suitable User Pool is fully automated with Terraform (see the infrastructure folder).

Set up

In order to setup the test environment, Terraform needs to be installed and AWS credentials need to be configured locally.

Once this is done, running apply should setup the Terraform backend, and the user pool and app client in the correct state:

# Setup state backend
cd infrastructure/state && terraform init && terraform apply

# Setup user pool
cd infrastructure/tests && terraform init --backend-config="./local.config" && terraform apply

After the user pool is set up, multiple environment variables need to be set in a .env file.

The .env file can be created by using .env.example as a template:

cp .env.example .env

Running tests

The tests can be run with:

cargo test

Tear down

The test environment can be torn down at any point with:

cd infrastructure/tests && terraform destroy