Working on documentation

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.

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)