# HomeAssistant command line scripts

## Overview

This repository contains scripts to integrate Davis Weatherlink and USGS water data
into HomeAssistant.
The scripts access external resources, typically via the Internet, and print various
values as elements of `data` in a JSON output. The output can be captured by a
HomeAssistant "sensor" and then included into individual sensors.

Scripts include:

### Command line
- `davisconditions.py`: weather conditions from a [Davis WeatherLink Live](https://www.davisinstruments.com/pages/weatherlink-live) (local network)
- `riverconditions.py`: river conditions from the [USGS National Water Information System](https://waterdata.usgs.gov/)

### REST
- `waterconditions.py`: simple Python web server that gathers data from the [USGS National Water Information System](https://waterdata.usgs.gov/) and makes it available via a JSON-encoded REST interface.

## Using the REST scripts

The scripts can be installed on any machine visible to the HomeAssistant server.
The only non-standard Python library is `requests`, which is something you should
make available in your standard installation anyway.

The script needs to be executable (`chmod 755 waterconditions.py`), but has no other
special requirements.

### Water conditions

`waterconditions.py` queries the [USGS National Water Information System](https://waterdata.usgs.gov/) for
current conditions of US lakes (including reservoirs) and rivers. URLs are of the form
`https://_my.server.address_:8999/river-01234567`, where the URL path is either `lake` or
`river` followed by the 8 digit USGS identifier for the water sensor.
You can find the 8 digit identifier using the [USGS web page](https://waterdata.usgs.gov/).

The script only sends an actual query for each site at most every `request_interval` (default 599) seconds.
It returns a cached value if `waterconditions.py` is queried more frequently; this avoids overloading
the USGS server, and prevents them from throttling your queries. You may change this value in the script
if you want; I'd recommend no less than 599, but longer may be OK if you need less frequent updates.

## Using the command line scripts

The scripts can be installed into any directory that HomeAssistant can run scripts from.
Make sure they're executable (*e.g.*, `chmod 755 riverconditions.py`).

The first line of the scripts should be changed to:
```
#!/path/to/homeassistant/python3
```
where the path is for the Python executable used by HomeAssistant. This might be
`/usr/bin/python3`, or it might be something like `/home/homeassistant/bin/python3`.

The only non-standard package that's needed is `requests`, though you shouldn't need to
install it if you're using HomeAssistant's `python3` executable, since HomeAssistant already
installs `requests`.

### Running the scripts

Each script takes a single argument that specifies the resource being accessed. `riverconditions.py`
takes the station identifier, which is an 8-digit number. For example, to get statistics for the
Rogue River at Raygold near Central Point, OR, you would run:
```
riverconditions.py 14359000
```
because the station identifier is 14359000. Note that this identifier is part of the URL for the
[(human-readable) station page](https://waterdata.usgs.gov/monitoring-location/14359000/),
and is prominently listed on the page as well.

To get data from a [Davis WeatherLink Live](https://www.davisinstruments.com/pages/weatherlink-live),
run `davisconditions.py` as follows:
```
davisconditions.py 192.168.1.200
```
where `192.168.1.200` is the address of the WeatherLink Live device. You can use the IP address or,
if you've assigned a DNS name to the device, the DNS name. This address must remain constant
across reboots of the device and/or router, so you may want to use a static IP address or reserve
an address in your DHCP server.

### HomeAssistant configuration