Update README

[infoex-autowx.git] / README.md

diff --git a/README.md b/README.md
index 8bbe60e022b00e9286ad87910cc2a3f824c442cd..2a988b302e03ad5c392c02688e718d256a70a3c0 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
 InfoEx AutoWx (IEAW)
 =============
 
 InfoEx AutoWx (IEAW)
 =============
 

-This program fetches data from an NRCS SNOTEL or MesoWest station and
-pushes it into the InfoEx system using the new automated weather system
-implementation.
+This program fetches data from an NRCS SNOTEL or MesoWest station, or
+your own custom data source, and pushes it into the InfoEx system using
+the new automated weather system implementation.

 
 Licensed under the ISC license (see file: LICENSE).
 
 
 Licensed under the ISC license (see file: LICENSE).
 


@@ -82,8 +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 #`  
 `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 #`  


@@ -192,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
 ------------------------------
 


@@ -199,6 +236,53 @@ This program supports custom weather station data by allowing the user
 to specify the path to an external Python program. The external Python
 program should emit its data in the form expected by infoex-autowx.
 
 to specify the path to an external Python program. The external Python
 program should emit its data in the form expected by infoex-autowx.
 

+This is a powerful feature which enables the user to upload data from
+any source imaginable into InfoEx. Common examples are a local database
+or a remote web page which requires some custom parsing.
+
+Please see the program located at examples/custom-wx.example.py for a
+complete description of what's required.
+
+A note on time zones
+--------------------
+
+This program is aware of time zones via the pytz library. The way in
+which NRCS and MesoWest deal with time zones differs as follows:
+
+NRCS expects the request to come in the appropriate time zone, and the
+data retrieved will be in the same time zone (no transformation
+required before sending to InfoEx).
+
+MesoWest expects the request to come in UTC, and the data retrieved will
+be in the same time zone (transformation from UTC to the desired time
+zone is required before sending to InfoEx).
+
+As long as you specify the correct timezone in your configuration file,
+all will be handled correctly. The list of time zones comes from the
+Olson tz database. See that for more information.
+
+If you specify an invalid time zone, the program will exit and inform
+you of such.
+
+Lastly, InfoEx itself is timezone aware. If you notice that the data
+which makes it into your operation is inaccurate, start your
+investigation with time zone-related issues and move on only once you've
+ruled this out as a cause of the inaccuracy.
+
+Unit conversions
+----------------
+
+Desired units may be specified in the configuration file.
+
+For MesoWest, the desired unit will be passed along in the API request
+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.
+
+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
 --------------------------------
 


@@ -208,7 +292,6 @@ weather station may not record them. In this case, the data will simply
 be ignored (i.e. it will NOT log "0" when there's no measurement
 available).
 
 be ignored (i.e. it will NOT log "0" when there's no measurement
 available).
 

-

 InfoEx provides a mechanism for inspecting your automated weather
 station data, so use that after setting this program up and compare it
 with the data you see in your web browser.
 InfoEx provides a mechanism for inspecting your automated weather
 station data, so use that after setting this program up and compare it
 with the data you see in your web browser.


@@ -234,15 +317,99 @@ wind\_speed
 wind\_direction  
 wind\_gust  
 
 wind\_direction  
 wind\_gust  
 

-Future plans
-------------
-
-- Improve the documentation
-- Implement unit conversion for NRCS stations
+**Custom Wx program**  
+*infoex-autowx expects a custom Wx data provider to provide at least one
+of the following:*  
+precipitationGauge  
+tempPres  
+tempMaxHour  
+tempMinHour  
+hS  
+baro  
+rH  
+windSpeedNum  
+windDirectionNum  
+windGustSpeedNum  

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

+- 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.0 (Jan 2021)
+
+  Implement time zone support.
+
+- 3.0.2 (Jan 2021)
+
+  Use UTC time when asking MesoWest for data.
+
+- 3.0.1 (Jan 2021)
+
+  General fixes.
+
+  - MesoWest wind data (speed and gust speed) units are now transformed
+    from their origin unit (meters per second) to the unit expected by
+    InfoEx (miles per hour).
+
+  - Relative humidity is now rounded to one decimal place, preventing
+    InfoEx from reddening the auto-filled value.
+
+- 3.0.0 (Nov 2020)
+
+  Implement Custom Wx data providers.
+
+  This release enables the user to write their own Python programs and
+  specify them to infoex-autowx as a data provider.
+
+  This in turn enables the user to pull data from e.g. a local database
+  or an HTML page and push it into their InfoEx auto station data,
+  limited only by the imagination.
+

 - 2.2.0 (Nov 2020)
 
   Add support for Tmin/Tmax values (directly from MesoWest/NRCS).
 - 2.2.0 (Nov 2020)
 
   Add support for Tmin/Tmax values (directly from MesoWest/NRCS).