X-Git-Url: https://wylark.com/src/infoex-autowx.git/blobdiff_plain/a585efb4e491a6a2dab7df5e858b34fe5235f662..62bc17588a07fbc64d9b02c275769b2bf0d44637:/README.md diff --git a/README.md b/README.md index 4433828..cda54b9 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 MIT license (see file: LICENSE). +License 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,17 +32,22 @@ 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 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 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 +resultant log messages 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. + 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 created earlier): @@ -52,32 +58,38 @@ created earlier): Configuration File ------------------ -The configuration file is separated into two parts, the [wxsite] -portion, and the [ftp] portion. +The configuration file is separated into two parts, the [station] +portion, and the [infoex] portion. -The [wxsite] values describe which NRCS SNOTEL site's data you're after. +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 [ftp] values describe your credentials for the InfoEx automated -weather station FTP server. +The [infoex] values describe your credentials for the InfoEx automated +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 #` +`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 #` -`[wxsite]` -`station_triplet = [The NRCS identifier for a particular SNOTEL site]` -`desired_data = [A comma-delimited list of NRCS elements you're interested in]` -`location_uuid = [The UUID used by InfoEx to identify your automated Wx site]` -`csv_filename = [Arbitrary name of the file that will be uploaded to 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 #` -`[ftp]` -`host = [InfoEx FTP host address]` -`uuid = [InfoEx-supplied UUID]` -`api_key = [InfoEx-supplied API Key]` +Finding your NRCS `station` values +---------------------------------- -Finding Your WXSITE values --------------------------- +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. -To complete the [wxsite] configuration section, 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: 1. Find your station by clicking through this website: @@ -92,7 +104,7 @@ Here are the steps to do that: 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 @@ -101,9 +113,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. -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: @@ -117,18 +129,112 @@ 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. -For example: +A complete 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. -Version History +Finding your MesoWest `station` values +-------------------------------------- + +MesoWest has great documentation which can be found here: + +https://developers.synopticdata.com/mesonet/v2/getting-started/ + +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 + station of interest and copy it to the `station_id` value. + +3. Finally, you must choose what data types you want to push into + 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/ + +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. + +A complete example: + +`[station]` +`type = mesowest` +`token = # token id copied from MesoWest web account #` +`station_id = OD110` +`desired_data = air_temp,snow_depth` +`units = english` + +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. + +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) + + Implement MesoWest integration. + + This release also makes significant changes to the configuration file, + hence the major version bump. Such changes are not taken lightly but + given the desire to support multiple data sources, were necessary. + - 1.0.0 (Jun 2020) First released version. Cleaned up the program and design.