OptionParser -> ArgumentParser

[infoex-autowx.git] / README.md

diff --git a/README.md b/README.md
index 8dde3f0887cbe4f5dcb0b9d6a00ac5f8f1cca45a..a02bfba816e401e406934f29ed862b3a3d62d982 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,17 +1,18 @@
 InfoEx AutoWx (IEAW)
 =============
 
 InfoEx AutoWx (IEAW)
 =============
 

-This program fetches data from an NRCS SNOTEL site 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 and
+pushes it into the InfoEx system using the new automated weather system
+implementation.

 
 

-License under the MIT license (see file: LICENSE).
+Licensed under the ISC license (see file: LICENSE).

 
 Disclaimer
 ----------
 
 
 Disclaimer
 ----------
 

-Your usage of the NRCS and InfoEx systems is bound by their respective
-terms and this software makes no attempt or claim to abide by any such
-terms.
+Your usage of the NRCS, MesoWest, and/or InfoEx systems is bound by
+their respective terms and this software makes no attempt or claim to
+abide by any such terms.

 
 Installation
 ------------
 
 Installation
 ------------


@@ -31,16 +32,29 @@ This program is designed to be run from the command line (or via
 cron(8)) and administered via a simple, concise configuration file.
 
 This design allows you to run a separate program instance for each NRCS
 cron(8)) and administered via a simple, concise configuration file.
 
 This design allows you to run a separate program instance for each NRCS

-weather station from which you'd like to automate the importation of
-data into your InfoEx subscriber account.
+or MesoWest weather station from which you'd like to automate the
+importation of data into your InfoEx subscriber account.
+
+To get started, copy the included example config file
+(`config.ini.example` in the root source directoy) and modify the values
+for your own use.

 
 To run ad-hoc (be sure to activate the virtual environment, as detailed in the
 Installation section):
 
 
 To run ad-hoc (be sure to activate the virtual environment, as detailed in the
 Installation section):
 

-`./infoex-autowx.py --config [path/to/config-file.ini] [--dry-run]`
+`./infoex-autowx.py --config path/to/config-file.ini [--dry-run] [--log-level debug|info|warning]`
+
+**NOTE: Specifying --dry-run will not clean up the generated CSV file.**
+This is so that you can more easily debug any issues that arise in the
+setup process.
+
+You can also specify `--log-level` as debug, info, warning. The
+log messages produced by the program will try to be logged to journald,
+but if that's not available, they will be printed to stdout. This output
+can be helpful early on in the setup process.

 
 

-**NOTE: Specifying --dry-run will also not clean up the generated CSV
-file.** This is so that you can debug any issues more easily.
+Automation
+----------

 
 Here's an example of a crontab(5) with two SNOTEL sites, each of which
 will run once per hour (note that this will activate the virtual environment
 
 Here's an example of a crontab(5) with two SNOTEL sites, each of which
 will run once per hour (note that this will activate the virtual environment


@@ -52,33 +66,37 @@ created earlier):
 Configuration File
 ------------------
 
 Configuration File
 ------------------
 

-The configuration file is separated into two parts, the
-[nrcs]/[mesowest] portion, and the [infoex] portion.
+The configuration file is separated into two parts, the [station]
+portion, and the [infoex] portion.

 
 

-The [nrcs]/[mesowest] values describe which weather station's data
-you're after. See the next section in this README for instructions on
-obtaining these values.
+The [station] values describe which weather station's data you're after.
+See the next section in this README for instructions on obtaining these
+values.

 
 The [infoex] values describe your credentials for the InfoEx automated
 weather station FTP server and other InfoEx-related configuration
 options.
 
 
 The [infoex] values describe your credentials for the InfoEx automated
 weather station FTP server and other InfoEx-related configuration
 options.
 

-`[nrcs]`  
-`station_triplet = [The NRCS identifier for a particular SNOTEL site]`  
-`desired_data = [A comma-delimited list of NRCS elements you're interested in]`  
+`[station]`  
+`type = # either mesowest or nrcs #`  
+`token = # MesoWest API token -- ignored when type is nrcs #`  
+`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 #`  

 
 `[infoex]`  
 
 `[infoex]`  

-`host = [InfoEx FTP host address]`  
-`uuid = [InfoEx-supplied UUID]`  
-`api_key = [InfoEx-supplied API Key]`  
-`csv_filename = [Arbitrary name of the file that will be uploaded to InfoEx]`  
-`location_uuid = [The UUID used by InfoEx to identify your automated Wx site]`  
+`host = # InfoEx FTP host address #`  
+`uuid = # InfoEx-supplied UUID #`  
+`api_key = # InfoEx-supplied API Key #`  
+`csv_filename = # arbitrary name of the file that will be uploaded to InfoEx #`  
+`location_uuid = # the UUID used by InfoEx to identify your automated Wx site #`  

 
 

-Finding Your NRCS values
-------------------------
+Finding your NRCS `station` values
+----------------------------------

 
 

-To complete the [nrcs] configuration section, you must fill in the
-attributes of the NRCS SNOTEL site from which you want to import data.
+To complete the [station] configuration section for an NRCS station, you
+must fill in the attributes of the NRCS SNOTEL site from which you want
+to import data.

 
 Here are the steps to do that:
 
 
 Here are the steps to do that:
 


@@ -94,7 +112,7 @@ Here are the steps to do that:
    4-digit number).
 
 3. Combine your Station ID, state abbreviation, and the network type
    4-digit number).
 
 3. Combine your Station ID, state abbreviation, and the network type

-   "SNTL" to get your station triplet (`station_triplet`, in the
+   "SNTL" to get your NRCS station triplet (`station_id`, in the

    configuration file). For example:
 
    655:OR:SNTL
    configuration file). For example:
 
    655:OR:SNTL


@@ -103,9 +121,9 @@ Here are the steps to do that:
    of Oregon (OR). SNTL just represents that the station is in the
    SNOTEL network and is used internally by NRCS.
 
    of Oregon (OR). SNTL just represents that the station is in the
    SNOTEL network and is used internally by NRCS.
 

-Once you have your station triplet, fill in the field in your
-configuration file. Now you must select which data you'd like to pull
-from NRCS to push into InfoEx.
+Once you have your station ID, fill in the field in your configuration
+file. Now you must select which data you'd like to pull from NRCS to
+push into InfoEx.

 
 For that, visit the NRCS web service:
 
 
 For that, visit the NRCS web service:
 


@@ -119,48 +137,53 @@ Once you've chosen your elements, combine all of their respective
 "elementCd" values into a comma-delimited string and put that into your
 configuration file as the `desired_data` value.
 
 "elementCd" values into a comma-delimited string and put that into your
 configuration file as the `desired_data` value.
 

-For example:
+A complete [station] section example:

 
 

-`station_triplet = 655:OR:SNTL`  
+`[station]`  
+`type = nrcs`  
+`station_id = 655:OR:SNTL`  

 `desired_data = TOBS,PREC`
 
 indicates that I'd like to import "AIR TEMPERATURE OBSERVED" and
 "PRECIPITATION ACCUMULATION" from the NRCS SNOTEL site at Mud Ridge, OR,
 into InfoEx.
 
 `desired_data = TOBS,PREC`
 
 indicates that I'd like to import "AIR TEMPERATURE OBSERVED" and
 "PRECIPITATION ACCUMULATION" from the NRCS SNOTEL site at Mud Ridge, OR,
 into InfoEx.
 

-Finding your MesoWest values
-----------------------------
+Finding your MesoWest `station` values
+--------------------------------------

 
 MesoWest has great documentation which can be found here:
 
 https://developers.synopticdata.com/mesonet/v2/getting-started/
 
 
 MesoWest has great documentation which can be found here:
 
 https://developers.synopticdata.com/mesonet/v2/getting-started/
 

-To complete the [mesowest] configuration section, you must fill in the
-attributes of the MesoWest station ID from which you want to import
-data. Here are the steps to do that:
+To complete the [station] configuration section for a MesoWest station,
+you must fill in the attributes of the MesoWest station ID from which
+you want to import data. Here are the steps to do that:

 
 1. Firstly, get set up with MesoWest's API by going to the above
    'Getting Started' link. Once you're set up, you can copy a token from
    the MesoWest web portal into your configuration file's `token` value.
 
 2. Next, you will want to find the Station ID for the MesoWest weather
 
 1. Firstly, get set up with MesoWest's API by going to the above
    'Getting Started' link. Once you're set up, you can copy a token from
    the MesoWest web portal into your configuration file's `token` value.
 
 2. Next, you will want to find the Station ID for the MesoWest weather

-   station of interest and copy it to the `stid` value.
+   station of interest and copy it to the `station_id` value.

 
 3. Finally, you must choose what data types you want to push into
 
 3. Finally, you must choose what data types you want to push into

-   InfoEx.  MesoWest refers to these as 'field names' and a list is
+   InfoEx and compile them into a comma-separated list. MesoWest refers
+   to these as 'field names' or 'station variables' and a list is

    available here:
 
 https://developers.synopticdata.com/about/station-variables/
 
    available here:
 
 https://developers.synopticdata.com/about/station-variables/
 

-The MesoWest API supports on-the-fly unit conversion, so that can be
-specified to infoex-autowx via the configuration option `units`. This
-can be either 'english' or 'metric', with 'english' meaning imperial
-units as used in the United States.
+The MesoWest API supports on-the-fly unit conversion. If desired, that
+can be specified to infoex-autowx via the configuration option `units`.
+This can be either 'english' or 'metric', with 'english' meaning
+imperial units as used in the United States.

 
 

-For example:
+A complete [station] section example:

 
 

-`token = (token id)`  
-`stid = OD110`  
+`[station]`  
+`type = mesowest`  
+`token = # token id copied from MesoWest web account #`  
+`station_id = OD110`  

 `desired_data = air_temp,snow_depth`  
 `units = english`
 
 `desired_data = air_temp,snow_depth`  
 `units = english`
 


@@ -168,9 +191,58 @@ 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.
 

-Version History
+A note on supported measurements
+--------------------------------
+
+While this program supports several measurements, and will faithfully
+request all of the ones you specify (provided they're supported), the
+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.
+
+Here's the list of measurements currently supported:
+
+**NRCS:**  
+PREC  
+TOBS  
+SNWD  
+PRES  
+RHUM  
+WSPD  
+WDIR  
+
+**MesoWest:**  
+precip\_accum  
+air\_temp  
+snow\_depth  
+pressure  
+relative\_humidity  
+wind\_speed  
+wind\_direction  
+wind\_gust  
+
+Future plans
+------------
+
+- Improve the documentation
+- Implement unit conversion for NRCS stations
+
+Version history

 ---------------
 
 ---------------
 

+- 2.0.1 (Jul 2020)
+
+  Major restructuring, but nothing which should impact the end user.
+
+  - Took the monolithic main () routine and broke it out into logical
+    components.
+  - Improved the names of variables.
+

 - 2.0.0 (Jul 2020)
 
   Implement MesoWest integration.
 - 2.0.0 (Jul 2020)
 
   Implement MesoWest integration.


@@ -179,6 +251,12 @@ Version History
   hence the major version bump. Such changes are not taken lightly but
   given the desire to support multiple data sources, were necessary.
 
   hence the major version bump. Such changes are not taken lightly but
   given the desire to support multiple data sources, were necessary.
 

+  Other minor changes include:
+
+  - New switches: --log-level and --version.
+  - Better documentation.
+  - Expanded supported measurement types (from three to eight, in number).
+

 - 1.0.0 (Jun 2020)
 
   First released version. Cleaned up the program and design.
 - 1.0.0 (Jun 2020)
 
   First released version. Cleaned up the program and design.