Add a timeout to the FTP operation

[infoex-autowx.git] / README.md

diff --git a/README.md b/README.md
index 170e2ed69927ee7f5bf0295247068793c9ee28f9..99c1c7a41f57afb514d8bb850a5a3baa6c011369 100644 (file)
--- a/README.md
+++ b/README.md
@@ -82,9 +82,11 @@ options.
 `token = # MesoWest API token -- only applies when type is mesowest #`  
 `station_id = # the NRCS/MesoWest identifier for a particular station #`  
 `desired_data = # a comma-delimited list of fields you're interested in #`  
 `token = # MesoWest API token -- only applies when type is mesowest #`  
 `station_id = # the NRCS/MesoWest identifier for a particular station #`  
 `desired_data = # a comma-delimited list of fields you're interested in #`  

-`units = # either english or metric -- only applies when type is mesowest #`  
+`units = # either english, metric, or american #`  

 `tz = # any entry from the Olson tz database e.g. America/Denver #`  
 `path = # the filesystem path to the Python program -- only applies when type is python #`  
 `tz = # any entry from the Olson tz database e.g. America/Denver #`  
 `path = # the filesystem path to the Python program -- only applies when type is python #`  

+`wind_mode = # normal or average -- only applies when type is mesowest #`  
+`hn24 = # true or false -- only applies when type is mesowest #`  

 
 `[infoex]`  
 `host = # InfoEx FTP host address #`  
 
 `[infoex]`  
 `host = # InfoEx FTP host address #`  


@@ -193,6 +195,40 @@ indicates that I'd like to import "Temperature" and "Precipitation
 accumulated" from the MesoWest station at Santiam Pass, OR, into InfoEx,
 and that I want that data in imperial units.
 
 accumulated" from the MesoWest station at Santiam Pass, OR, into InfoEx,
 and that I want that data in imperial units.
 

+Three- versus 24-hour ranges
+----------------------------
+
+By default, this program will fetch three hours of data from the
+provider. This way, if the most recent record has any missing data, it
+can examine the two hours prior, using whatever data it can find.
+
+There are two features which will cause the program to expand the time
+range of fetched data from three to 24 hours. Please be aware of this
+expansion as it may cause a rise in data/API usage.
+
+**NOTE: Only MesoWest stations have the benefit of wind averaging and
+        HN24 calculation at this time, because generally NRCS SNOTEL
+               stations do not provide wind data. HN24 support for NRCS SNOTEL
+               is planned.
+
+### Wind mode
+If you go to submit a Wx observation in InfoEx at e.g. 05:05, and have
+so configured InfoEx, it will take the wind speed, wind gust speed, and
+wind direction, from that hour and auto-fill it for the observation.
+
+Some operations may find it more important to know the averages for
+those values over the prior 24 hour period. Setting `wind_mode` to
+`average` will enable that.
+
+### HN24
+As most stations do not provide HN24 on their own, this program provides
+a configuration option for calculating this. Simply add `hn24 = true` to
+the configuration file.
+
+*NOTE: This is its own configuration option, rather than a new value for
+          desired_data, because it's not technically provided by MesoWest
+          or NRCS SNOTEL.*
+

 Custom weather station support
 ------------------------------
 
 Custom weather station support
 ------------------------------
 


@@ -244,6 +280,9 @@ and the conversion will take place through the MesoWest/Synoptic API.
 For NRCS, this program will do the conversion manually, as NRCS does not
 permit specifying the desired unit.
 
 For NRCS, this program will do the conversion manually, as NRCS does not
 permit specifying the desired unit.
 

+There is an "American" units mode in which precip data is converted to
+metric, and wind data is converted to imperial units.
+

 A note on supported measurements
 --------------------------------
 
 A note on supported measurements
 --------------------------------
 


@@ -292,14 +331,68 @@ windSpeedNum
 windDirectionNum  
 windGustSpeedNum  
 
 windDirectionNum  
 windGustSpeedNum  
 

-Future plans
-------------
-
-- Implement unit conversion for NRCS stations
-

 Version history
 ---------------
 
 Version history
 ---------------
 

+- 3.4.4 (Sep 2024)
+
+  "Import" all unit variables from custom program
+
+- 3.4.3 (Sep 2024)
+
+  A few fixes for custom providers
+
+- 3.4.2 (Dec 2022)
+
+  Fix mm/cm bug with Mesowest stations in American units mode.
+
+- 3.4.1 (Dec 2022)
+
+  Reverse "American" units mode such that precip values are in metric,
+  and wind values are in imperial/English.
+
+- 3.4.0 (Mar 2022)
+
+  Implement HN24 for NRCS SNOTEL stations, and implement "American"
+  units mode.
+
+- 3.3.1 (Jan 2022)
+
+  Fix bug in which HN24 values under certain circumstances could be
+  inaccurate.
+
+- 3.3.0 (Nov 2021)
+
+  Implement wind averaging and auto-calculation of HN24. These are
+  opt-in via two new configuration options.
+
+- 3.2.4 (Mar 2021)
+
+  Fix a small bug that allowed MesoWest HS values to flow through in
+  millimeters when metric was the specified unit. MesoWest metric HS
+  values are now correctly in centimeters.
+
+- 3.2.3 (Feb 2021)
+
+  Fix a small bug that allowed a TypeError to be raised with some
+  regularity.
+
+- 3.2.2 (Feb 2021)
+
+  Various small fixes.
+
+  - Round precipitation accumulation values to 2 decimal places.
+  - Catch requests' ConnectionException.
+  - Improve logging output when using stdout.
+
+- 3.2.1 (Feb 2021)
+
+  Fix config validation bug with units and custom Python program.
+
+- 3.2.0 (Feb 2021)
+
+  Implement NRCS unit conversion.
+

 - 3.1.1 (Feb 2021)
 
   Fix relative humidity rounding.
 - 3.1.1 (Feb 2021)
 
   Fix relative humidity rounding.