X-Git-Url: https://wylark.com/src/infoex-autowx.git/blobdiff_plain/51f9aa84d2877d488dbf8600323e95f1c1a0fec6..84b9766b747b9310e73cda1d746b7a52250cb67c:/README.md diff --git a/README.md b/README.md index eeb9e86..edd134b 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,18 @@ 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 ISC license (see file: LICENSE). +Licensed under the ISC license (see file: LICENSE). 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 ------------ @@ -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 -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): -`./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. -**NOTE: Specifying --dry-run will also not clean up the generated CSV -file.** This is so that you can debug any issues more easily. +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. + +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 @@ -77,7 +91,7 @@ options. `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 `station` values +Finding your NRCS `station` values ---------------------------------- To complete the [station] configuration section for an NRCS station, you @@ -123,7 +137,7 @@ 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. -A complete example: +A complete [station] section example: `[station]` `type = nrcs` @@ -159,17 +173,17 @@ you want to import data. Here are the steps to do that: 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. -A complete example: +A complete [station] section example: `[station]` `type = mesowest` `token = # token id copied from MesoWest web account #` -`stid = OD110` +`station_id = OD110` `desired_data = air_temp,snow_depth` `units = english` @@ -177,7 +191,48 @@ 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. -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.0 (Jul 2020) @@ -188,6 +243,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. + 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.