From 21556d3a6f65bbfc3a61597bcece4f9003c7c793 Mon Sep 17 00:00:00 2001 From: "Ethan L. Miller" Date: Sat, 18 Jan 2025 11:44:18 -0800 Subject: [PATCH] Working on documentation --- README.md | 57 ++++++++++++++++++++++++++++++++++++++-- davisconditions.py | 65 +++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 116 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0dc56fd..8374513 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,56 @@ -# hass_command_line_scripts +# HomeAssistant command line scripts + +## Overview + +This repository contains scripts for the `command_line` integration in 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: + +- `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/) + +## Installation + +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`. + +## Usage + +### 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 -Scripts for the command_line integration in HomeAssistant. \ No newline at end of file diff --git a/davisconditions.py b/davisconditions.py index b9f312d..7c1de54 100755 --- a/davisconditions.py +++ b/davisconditions.py @@ -1,11 +1,68 @@ -#!/usr/home/homeassistant/bin/python3 +#!/usr/bin/env python3 # -# Gather data from the Davis WeatherLink Live and output it +# Description: +# +# Gathers data from the Davis WeatherLink Live and outputs it # in JSON format for use in Home Assistant. # Designed to be run as a command_line integration. # -# Requires Python3 and the requests package. -# Update the first line to the python3 binary used by HomeAssistant. +# Requirements: +# - Python 3.9+ +# - requests package +# - Update the first line to the python3 binary used by HomeAssistant. +# +# Usage/installation: +# +# Takes a single argument: the 8-digit code identifying the station. +# This is part of the URL you'd use to view the information on the web, +# and is listed on the web page. For example, +# https://waterdata.usgs.gov/monitoring-location/14339000/ +# is for measurement station 14339000. +# The web page title is: +# Rogue River at Dodge Bridge, Near Eagle Point, OR - 14339000 +# This means that the command line would be: +# /path/to/binary/riverconditions.py 14339000 +# +# +# Update the first line of this script to be the same python3 executable as +# your Home Assistant instance uses. +# +# To use the integration, add the following to your configuration.yaml file +# (without the comments, obviously!) +# ------------------------ +# command_line: +# - sensor: +# name: "River conditions" +# unique_id: river_conditions +# command: '/home/homeassistant/bin/riverconditions.py 14339000' +# scan_interval: 1800 +# json_attributes: +# - data +# value_template: 'Rogue River conditions at Dodge Bridge' +# ------------------------ +# You can use any value you want for value_template. +# Scan interval should be relatively long, since the values aren't updated +# frequently. Minimum interval should be 600 seconds (every 10 minutes). +# +# Next, add one or more sensors corresponding to the conditions you want to +# track in your system. For example, +# ------------------------ +# template: +# - sensors: +# river_height: +# friendly_name: "River height" +# device_class: distance +# value_template: "{{ state_attr('sensor.river_conditions', 'data')['height'] | round(1) }}" +# river_flow: +# friendly_name: "River flow" +# device_class: volume_flow_rate +# unit_of_measurement: "cfs" +# value_template: "{{ state_attr('sensor.river_conditions', 'data')['flow'] | round(0) }}" +# ------------------------ +# Note that height and flow are both contained within the 'data' attribute of the river_conditions +# sensor populated by the command. +# +# # #========================================================================== # Copyright 2025 Ethan L. Miller (code@ethanmiller.us)