82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# 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
|
|
|