From: Alexander Vasarab Date: Sat, 20 Jun 2020 21:02:58 +0000 (-0700) Subject: Make README a proper markdown file X-Git-Tag: v1.0.0^2~1 X-Git-Url: https://wylark.com/src/infoex-autowx.git/commitdiff_plain/64929d40db7dc9acb29005ac624f8dd13aefc335?hp=-c Make README a proper markdown file --- 64929d40db7dc9acb29005ac624f8dd13aefc335 diff --git a/README b/README deleted file mode 100644 index 39ce7bc..0000000 --- a/README +++ /dev/null @@ -1,139 +0,0 @@ -============= -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. - -License under the MIT 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. - -Installation -============ - -It's recommended to use venv and pip with this program. Here's a typical -sequence of commands for a new setup: - -$ cd /path/to/src -$ python3 -m venv env -$ . env/bin/activate -$ pip install -r requirements.txt - -How to use it -============= - -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. - -To run ad-hoc (be sure to activate the virtual environment, as detailed in the -Installation section): - - ./infoex-autowx.py --config - -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): - -2 * * * * /usr/bin/env bash -c 'cd /home/user/infoex-autowx && source env/bin/activate && ./infoex-autowx.py --config laurance-lake.ini' -4 * * * * /usr/bin/env bash -c 'cd /home/user/infoex-autowx && source env/bin/activate && ./infoex-autowx.py --config mud-ridge.ini' - -Configuration File -================== - -The configuration file is separated into two parts, the [wxsite] -portion, and the [ftp] portion. - -The [wxsite] values describe which NRCS SNOTEL site'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. - -[wxsite] -station_triplet = -desired_data = -location_uuid = -csv_filename = - -[ftp] -host = -uuid = -api_key = - -Finding Your WXSITE values -========================== - -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: - - https://www.wcc.nrcs.usda.gov/snow/sntllist.html - - Or by using the interactive map: - - https://www.nrcs.usda.gov/wps/portal/wcc/home/quicklinks/imap - -2. Once you've found your station, look for the "Station ID" (a 3- or - 4-digit number). - -3. Combine your Station ID, state abbreviation, and the network type - "SNTL" to get your station triplet (station_triplet, in the - configuration file). For example: - - 655:OR:SNTL - - would represent the Mud Ridge station (Station ID 655) in the state - 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. - -For that, visit the NRCS web service: - -https://wcc.sc.egov.usda.gov/awdbWebService/webservice/testwebservice.jsf?webserviceName=/awdbWebService - -Click "getElements" on the left, and then click, "Test Operation." This -will return a long list of elements to your web browser from which you -can choose. Each returned element has its identifier and a description. - -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: - -station_triplet = 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 -=============== - -1.0.0 (Jun 2020) - * First released version. Cleaned up the program and design. - Implemented configuration file, added LICENSE, README, docs, etc. - -0.8.0 (Apr 2020) - * First finished (unreleased) version. - -pre-0.8.0 (Apr 2020) - * First (private) finished implementation with successful NRCS -> - InfoEx importation. diff --git a/README.md b/README.md new file mode 100644 index 0000000..258c70a --- /dev/null +++ b/README.md @@ -0,0 +1,141 @@ +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. + +License under the MIT 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. + +Installation +------------ + +It's recommended to use venv and pip with this program. Here's a typical +sequence of commands for a new setup: + +`$ cd /path/to/src` +`$ python3 -m venv env` +`$ . env/bin/activate` +`$ pip install -r requirements.txt` + +How to use it +------------- + +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. + +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]` + +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): + +`2 * * * * /usr/bin/env bash -c 'cd /home/user/infoex-autowx && source env/bin/activate && ./infoex-autowx.py --config laurance-lake.ini'` +`4 * * * * /usr/bin/env bash -c 'cd /home/user/infoex-autowx && source env/bin/activate && ./infoex-autowx.py --config mud-ridge.ini'` + +Configuration File +------------------ + +The configuration file is separated into two parts, the [wxsite] +portion, and the [ftp] portion. + +The [wxsite] values describe which NRCS SNOTEL site'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. + +`[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]` + +`[ftp]` +`host = [InfoEx FTP host address]` +`uuid = [InfoEx-supplied UUID]` +`api_key = [InfoEx-supplied API Key]` + +Finding Your WXSITE values +-------------------------- + +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: + + https://www.wcc.nrcs.usda.gov/snow/sntllist.html + + Or by using the interactive map: + + https://www.nrcs.usda.gov/wps/portal/wcc/home/quicklinks/imap + +2. Once you've found your station, look for the "Station ID" (a 3- or + 4-digit number). + +3. Combine your Station ID, state abbreviation, and the network type + "SNTL" to get your station triplet (`station_triplet`, in the + configuration file). For example: + + 655:OR:SNTL + + would represent the Mud Ridge station (Station ID 655) in the state + 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. + +For that, visit the NRCS web service: + +https://wcc.sc.egov.usda.gov/awdbWebService/webservice/testwebservice.jsf?webserviceName=/awdbWebService + +Click "getElements" on the left, and then click, "Test Operation." This +will return a long list of elements to your web browser from which you +can choose. Each returned element has its identifier and a description. + +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: + +`station_triplet = 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 +--------------- + +- 1.0.0 (Jun 2020) + + First released version. Cleaned up the program and design. + Implemented configuration file, added LICENSE, README, docs, etc. + +- 0.8.0 (Apr 2020) + + First finished (unreleased) version. + +- pre-0.8.0 (Apr 2020) + + First (private) finished implementation with successful importation of + NRCS data into InfoEx.