Hass-Rs
A simple async Rust client library for interacting with Home Assistant websocket API.
Configure:
hass-rs supports tokio and async-std runtimes, by default it uses async-std, to use tokio change the feature flags in Cargo.toml
with async-std support
[]
= { = "0.2", = ["async-std-runtime"] }
with tokio support
[]
= { = "0.2", = ["tokio-runtime"] }
Example usage
use env_logger;
use client;
use lazy_static;
use var;
lazy_static!
async
Test environment
Use docker to easily bootstrap a test environment.
Steps:
- clone the hass_rs github repository
- execute the below command, which runs the docker homeassistant container in background
- login to Home Assistant web interface: http://localhost:8123/
- go to
Profile
-->Long-Lived Access Tokens
and create a token to be used by hass_rs client - set the environment variable export HASS_TOKEN=<YOUR_TOKEN_HERE>
- run the tests with
cargo test
- run the example scripts:
cargo run --example ping
orcargo run --example fetch_items
orcargo run --example subscribe_event
API reference
- client::connect(host, port) -- establish the websocket connection to Home Assistant server.
- client.auth_with_longlivedtoken(token) - authenticate the session using a long-lived access token.
- client.ping() - can serve as a heartbeat, to ensure the connection is still alive.
- client.subscribe_event(event_name, callback) - subscribe the client to the event bus. the callback is a closure, of type Fn(WSEvent), which is executed every time when a specific event is received.
- client.unsubscribe_event(subscription_id) - unsubscribe the client from the event bus.
- client.get_config() - it gets a dump of the current config in Home Assistant.
- client.get_states() - it gets a dump of all the current states in Home Assistant.
- client.get_services() - it gets a dump of the current services in Home Assistant.
- client.call_service(domain, service, service_data) - it calls call a service in Home Assistant.
Development status
- Create the client
- Automatic reconnection (TBD)
- Authenticate using long-lived access tokens
- Authenticate using OAuth2 (TBD)
- Call a service
- Subscribe
- Events
- Config (you need this?, raise an Issue)
- Services (you need this?, raise an Issue)
- UnSubscribe
- Fetch Commands
- Fetching states
- Fetching config
- Fetching services
- Fetching pannels (you need this?, raise an Issue)
- Fetching media player thumbnails (you need this?, raise an Issue)
- Ping - Pong