Merge branch 'release-3.0.0' into develop

[infoex-autowx.git] / README.md

diff --git a/README.md b/README.md
index b2af012fab839c0dc861b4e842f85a3c2b543e1b..8d9da91bed3d7ad0b2c4ad1c6ebab513a5ad204b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
 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).
 
@@ -78,11 +78,12 @@ weather station FTP server and other InfoEx-related configuration
 options.
 
 `[station]`  
-`type = # either mesowest or nrcs #`  
-`token = # MesoWest API token -- ignored when type is nrcs #`  
+`type = # mesowest, nrcs, or python #`  
+`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 -- ignored when type is nrcs #`  
+`units = # either english or metric -- only applies when type is mesowest #`  
+`path = # the filesystem path to the Python program -- only applies when type is python #`  
 
 `[infoex]`  
 `host = # InfoEx FTP host address #`  
@@ -191,6 +192,20 @@ 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.
 
+Custom weather station support
+------------------------------
+
+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.
+
+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 supported measurements
 --------------------------------
 
@@ -200,7 +215,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).
 
-
 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.
@@ -226,15 +240,39 @@ wind\_speed
 wind\_direction  
 wind\_gust  
 
+**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  
+
 Future plans
 ------------
 
-- Improve the documentation
 - Implement unit conversion for NRCS stations
 
 Version history
 ---------------
 
+- 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).