From 91e9f79f6a14578ba00190afe0bd9704bc7fbda0 Mon Sep 17 00:00:00 2001 From: "Ethan L. Miller" Date: Thu, 16 Jan 2025 12:49:36 -0800 Subject: [PATCH] Documenting code --- LICENSE | 2 +- davisconditions.py | 40 ++++++++++++++++++--- riverconditions.py | 90 +++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 126 insertions(+), 6 deletions(-) mode change 100644 => 100755 davisconditions.py mode change 100644 => 100755 riverconditions.py diff --git a/LICENSE b/LICENSE index 2873c39..fb952ce 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2025 elm +Copyright (c) 2025 Ethan L. Miller Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/davisconditions.py b/davisconditions.py old mode 100644 new mode 100755 index 6031638..b9f312d --- a/davisconditions.py +++ b/davisconditions.py @@ -1,4 +1,36 @@ #!/usr/home/homeassistant/bin/python3 +# +# Gather data from the Davis WeatherLink Live and output 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. +# +#========================================================================== +# Copyright 2025 Ethan L. Miller (code@ethanmiller.us) +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# 1. Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. import sys import json @@ -19,9 +51,8 @@ mappings = { 'uv_index': 'uv_index', } if __name__ == '__main__': - vals = dict() + exit_code = 1 for i in range(4): - ok = False try: vals = dict() davis_ip = sys.argv[1] @@ -33,7 +64,8 @@ if __name__ == '__main__': vals = vals | c result = {mappings[k]: vals[k] for k in mappings.keys() if k in vals} print (json.dumps ({'data': result})) - ok = True + exit_code = 0 + break except: pass - if ok: sys.exit(0) + sys.exit(exit_code) diff --git a/riverconditions.py b/riverconditions.py old mode 100644 new mode 100755 index 4481480..c51bf0f --- a/riverconditions.py +++ b/riverconditions.py @@ -1,4 +1,92 @@ -#!/usr/home/homeassistant/bin/python3 +#!/usr/bin/env python3 +# +# Description: +# +# Retrieves data from waterdata.usgs.gov +# and outputs it in JSON format for use in Home Assistant. +# Designed to be run as a command_line integration. +# +# Requirements: +# - Python 3.9+ +# - requests +# +# 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) +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# 1. Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. import sys import json