aircon/README.md

# Overview

![aircon.sh in action](https://cube.nethack.net/images/aircon_control.png "aircon.sh in action")

Script to automate control of an home reverse cycle aircon system based on custom logic and temperature measurements.

This was originally written for an [AdvantageAir](https://www.advantageair.com.au/) system.   It just calls an external script to interface with the aircon, so should be easily adaptable to other systems.

It can also log to an influxdb database for easy integration into Grafana or similar.

![grafana integration](https://cube.nethack.net/images/aircon_grafana.png "grafana integration")


# Requirements

- [pymyair](https://github.com/smallsam/pymyair)


# Features

- Define temperature rules based on weekday and/or time
- Automatically adjust aircon settings based on defined temperature thresholds
- Control zone temperature by opening/closing vents
- Open/close vents in adjacent zones to assist in temperature control
- Turn the entire aircon system on/off as needed to control temperature
- Turn zones on/off based on ARP table entries for specific MAC addresses (for example, if a TV is turned on or a person's phone is detected)
- Log temperature measurements to a CSV file or InfluxDB

# Usage

```text
root@gridbug:~# scripts/aircon.sh -h
usage:  scripts/aircon.sh [options]

    Modifies aircon based on configured parameters in /root/.airconrc.

    -h          Show this text.
    -c          Cron mode.  Only show output if actions were taken.
    -i x.x.x.x  Specify IP address for aircon (default is 10.99.99.1)
    -D dbhost   Specify influxdb hostname for -I and -A options (default: localhost)
    -I db       Log all zone temperatures to given influxdb database, then exit (see -o).
    -A db       Log actions to given influxdb database.
    -f file     Specify an alternate config file.
    -k file     If file exists, never change aircon settings (default: /root/.aircon_noaction).
    -l num      Set number of too hot/cold zones at which to taking action.
    -L          Log all zone temperatures to CSV file, then exit (see -o).
    -o file     Specify CSV output file.  Default:  /root/acstats.csv
    -m          Generate a config file based on current aircon setup.
    -p          Profiler mode.
    -s          Validate config file then exit.
    -S[H]       Show configured rules in human-readable format
                (HTML if -H given, otherwise ANSI).
    -w          List which people are available then exit.
    -W          List zone-owning devices are available then exit.
    -t num      Specify degrees below min temperature before taking action.
    -T num      Specify degrees above max temperature before taking action.
    -y          Actually run commands/db inserts.  By default, commands are just displayed.
```

# Examples

## Sample .airconrc file

```text
root@gridbug:~# cat .airconrc

options -t 0.5

modelock heat

constant Family

owner Study robsphone
owner Rob&Beth robsphone bethsphone
owner Brendan brendansphone
owner Media lgtv_wifi

@Thu-Fri;0830-1630 force Nursery close   # Childcare hours
@1830-0630 temp Nursery 17-19


@0600-2359 temp Family 18-21
temp Media 18-22
temp Rob&Beth 18-22
@Mon-Fri;0830-1730 temp Study 18-22 # Rob working
@Sat-Sun ignore Study               # Not working

adj Brendan Family
adj Media Brendan
adj Rob&Beth Family
adj Study Family

person Rob robsphone
person Beth bethsphone
person Mel melsphone
person Brendan brendansphone
```

## Generate ~/.airconrc based on your actual aircon zones
```text
    bash$ aircon.sh -m
```

## Log temperature for each zone to csv then exit
```text
    bash$ aircon.sh -L -o /root/acstats.csv -x /usr/local/bin/pymyair -f /root/.airconrc
```

## Preview influxdb inserts for zone temperatures
```text
    bash$ aircon.sh -I myinfluxdb
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Family value=18.7
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Brendan value=19.1
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Media value=21
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Rob&Beth value=18.4
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Study value=19.2
    /usr/local/bin/influx -database myinfluxdb -execute INSERT temperature,room=Nursery value=17.8
    /usr/local/bin/influx -database myinfluxdb -execute INSERT attendance,person=Rob value=1
    /usr/local/bin/influx -database myinfluxdb -execute INSERT attendance,person=Beth value=1
    /usr/local/bin/influx -database myinfluxdb -execute INSERT aircon running=0
    /usr/local/bin/influx -database myinfluxdb -execute INSERT aircon mode=0
```

## Log temperature for each zone to local influxdb then exit
```text
    bash$ aircon.sh -I myinfluxdb -y
```

## Determine required aircon changes and display them only (dry run)
```text
    bash$ aircon.sh
    Aircon mode:    heat (locked to heat)
    Current myzone: Family (zone 1)
    Tolerance: 0.5 degrees low, 0 degrees high
                    Valid          Set    Actual Proposed
    Zone            Temp   State   Temp   Temp   Action
    Family (C)      18-21  open    19     21.6   close_vent
    Brendan         n/a    close   19     19.3   n/a
    Media           18-22  close   20     21.6   n/a
    Rob&Beth        18-22  close   18     19.5   n/a
    Study           n/a    close   19     20.6   n/a
    Mel&Rob         18-21  close   18     19.5   n/a
    Nursery         17-19  open    19     18.9   set_myzone

    Analysis:
    - Family is too hot (constant zone)

    Proposed commands:
    myair 10.99.99.1 set --zone 1 --state off --temp 19    # In zone Family, close vent
    myair 10.99.99.1 myzone --zone 7                       # Set MyZone to Nursery
```

## Make required aircon changes
```text
    bash$ aircon.sh -y
    Aircon mode:    heat (locked to heat)
    Current myzone: Family (zone 1)
    Tolerance: 0.5 degrees low, 0 degrees high
                    Valid          Set    Actual Proposed
    Zone            Temp   State   Temp   Temp   Action
    Family (C)      18-21  open    19     21.6   close_vent
    Brendan         n/a    close   19     19.3   n/a
    Media           18-22  close   20     21.6   n/a
    Rob&Beth        18-22  close   18     19.5   n/a
    Study           n/a    close   19     20.6   n/a
    Mel&Rob         18-21  close   18     19.5   n/a
    Nursery         17-19  open    19     18.9   set_myzone

    Analysis:
    - Family is too hot (constant zone)

    Proposed commands:
    myair 10.99.99.1 set --zone 1 --state off --temp 19    # In zone Family, close vent
    myair 10.99.99.1 myzone --zone 7                       # Set MyZone to Nursery

    Running action: In zone Family, close vent
    RUNNING myair 10.99.99.1 set --zone 1 --state off --temp 19
    Running action: Set MyZone to Nursery
    RUNNING myair 10.99.99.1 myzone --zone 7
```


## Make required aircon changes and log actions to influxdb
```text
    bash$ aircon.sh -y -A myinfluxdb
```

## Make required aircon changes and only produce output if actions taken (cron mdoe)
```text
    bash$ aircon.sh -y -c
```

## Show which zone owners are detected, then exit
```text
    bash$ aircon.sh  -W
    Devices         Availability
    bethsphone      Available
    brendansphone   Available
    lg-wifi         Unavailable
    robsphone       Available
```

## Dump current rules, showing which ones are active (use -SH for HTML format)
```text
    root@gridbug:scripts# ./aircon.sh  -S
    >> Querying aircon... ok
    - Only operate the aircon in heat mode
    - Close vent in Media if lg-wifi isn't online
    - Close vent in Study if robsphone isn't online
    - Close vent in Rob&Beth if one of (robsphone bethsphone) aren't online
    - Close vent in Brendan if brendansphone isn't online
    - Ignore Brendan temperature when deciding what to do
    - Ignore Nursery temperature when deciding what to do
    - Force the vent in Nursery to be closed
    - [out-of-hours] From Mon to Fri between 08:30 and 18:00, Close vent in Ben/Sewing if brendanslaptop isn't online
    - Prevent Nursery from being the MyZone
    - Prevent Ben/Sewing from being the MyZone
    - [out-of-hours] From Mon to Tue between 08:30 and 16:30, Force the vent in Nursery to be closed
    - [out-of-hours] Between 08:30 and 16:30, Force the vent in Nursery to be closed
    - [ignored] Keep temperature of Nursery between 25-26 degrees
    - From Sat to Sun, Ignore Study temperature when deciding what to do
    - [out-of-hours] From Mon to Fri between 08:30 and 18:00, Close vent in Ben/Sewing if brendansphone isn't online
    - Between 06:00 and 23:59, Keep temperature of Family between 18-21 degrees
    - [ignored] Keep temperature of Brendan between 18-20 degrees
    - [out-of-hours] Between 20:00 and 07:00, Keep temperature of Rumpus between 18-22 degrees
    - Keep temperature of Media between 18-21 degrees
    - Keep temperature of Rob&Beth between 18-22 degrees
    - [out-of-hours] From Mon to Fri between 08:30 and 17:30, Keep temperature of Study between 18-22 degrees
    - [out-of-hours] Between 19:30 and 06:30, Keep temperature of Nursery between 18-19 degrees
    - [out-of-hours] Between 20:00 and 07:00, Keep temperature of Ben/Sewing between 18-22 degrees
    - [out-of-hours] From Mon to Fri between 08:30 and 17:30, Keep temperature of Ben/Sewing between 17-22 degrees
```