airtouch5 0.2.0

# airtouch5

[![Latest](https://img.shields.io/crates/v/airtouch5.svg)](https://crates.io/crates/airtouch5)
[![Docs](https://docs.rs/airtouch5/badge.svg)](https://docs.rs/airtouch5)
![License](https://img.shields.io/crates/l/airtouch5.svg)
![Tests](https://codeberg.org/kbriggs/airtouch5/badges/workflows/test.yml/badge.svg?label=tests)
![Lint](https://codeberg.org/kbriggs/airtouch5/badges/workflows/lint.yml/badge.svg?label=lint)

A rust library for communicating with [AirTouch 5] air conditioning system
control consoles.

[AirTouch 5]: <https://www.airtouch.net.au/smart-air-conditioning/airtouch-5/>

## Status

This library is a work in progress, and should not be considered stable or
ready for production use.

## Basic usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
airtouch5 = "0.2.0"
```

and `use` the `airtouch5` crate (or one of its members):

```rust
use airtouch5;
use airtouch5::AirTouch5;
use airtouch5::discovery;
```

The [`AirTouch5`] struct is the primary interface to connect to a console. See
the [full documentation](https://docs.rs/airtouch5) for more information.

[`AirTouch5`]: <https://docs.rs/airtouch5/latest/airtouch5/struct.AirTouch5.html>

### Discovery

The [`airtouch5::dicovery`](https://docs.rs/airtouch5/latest/airtouch5/discovery/index.html)
module provides functions to discover an AirTouch 5 console on the local network.

### Current status

The [`AirTouch5`] struct provides functions to query the current state of the
AirTouch 5 console and the air conditioning units it controls, as well as to
subscribe to channels that broadcast changes to the current state.

### Take control

If the optional `control` feature is enabled, the [`AirTouch5`] struct gains
[`control_ac()`] and [`control_zone()`] functions to request state changes of
the AirTouch 5 console, including turning air conditioning units or zones on or
off, or adjusting target temperatures.

> [!CAUTION]
> This feature is disabled by default, because misuse could have significant
> consequences. For instance, turning a system on inappropriately could run up
> large energy bills, or turning a system off inappropriately could lead to
> medical complications such as heatstroke! Use this feature with caution.

[`control_ac()`]: <https://docs.rs/airtouch5/latest/airtouch5/struct.AirTouch5.html#method.control_ac>
[`control_zone()`]: <https://docs.rs/airtouch5/latest/airtouch5/struct.AirTouch5.html#method.control_zone>

## Examples

Discover an AirTouch 5 console on the local network:

```rust
use airtouch5::AirTouch5;
use airtouch5::discovery::discover;

let console = cached_console.unwrap_or(discover().await?);
println!("Connecting to {} at {}", console.name, console.address);
let at5 = AirTouch5::with_ipaddr(console.address);
```

List the different zones and whether they are active:

```rust
// query the zones names and status
let names = at5.zone_names().await?;
let status = at5.zone_status().await?;

// find the longest zone name
let w = names.by_index().map(|(_, z)| z.len()).max().unwrap_or(0);

let UNNAMED_ZONE = "<unknown>".to_string();
for (idx, zone) in status.zones {
    println!(
        "{:>w$}: {}",
        names.zones.get(&idx).unwrap_or(&UNNAMED_ZONE),
        zone.power
    );
}
```

And print the full zone state again whenever the current state changes:

```rust
// subscribe to the current status
let mut watch = at5.subscribe_status()?;
loop {
    // fetch the current status
    let status = watch.borrow_and_update();

    // print it
    for (idx, zone) in status.zones().iter() {
        println!(
            "{:>w$}: {}",
            names.zones.get(idx).unwrap_or(&UNNAMED_ZONE),
            zone
        );
    }

    // then wait for the status to change
    drop(status);
    watch.changed().await?;
}
```

With the `control` Cargo feature, turn the first air conditioning unit on with
automatic fan speed control:

```toml
[dependencies]
airtouch5 = { version = "0.2.0", features = ["control"] }
```

```rust
use airtouch5::types::control::{AcControl, AcPower, FanSpeed}
at5.control_ac(
    0,
    AcControl {
        power: Some(AcPower::On),
        mode: None,
        fan_speed: Some(FanSpeed::Auto),
        setpoint: None,
    },
)
.await?;
```

## Cargo features

The `airtouch5` crate defines the following Cargo features:

* `control`: Enable functions that request state changes. Disabled by default.
* `timeout`: Enable `_timeout` versions of several functions that return an
  error if a response is not received in a given period. Enabled by default.

## Disclaimer

AirTouch is a registered trade mark of Polyaire Pty Ltd. This library is
provided for educational and interoperability purposes.

## License

Licensed under either of

* Apache License, Version 2.0
  ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license
  ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

## Contribution

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