README

   1 =============
   2 InfoEx AutoWx (IEAW)
   3 =============
   4
   5 This program fetches data from an NRCS SNOTEL site and pushes it into
   6 the InfoEx system using the new automated weather system implementation.
   7
   8 License under the MIT license (see file: LICENSE).
   9
  10 Disclaimer
  11 ==========
  12
  13 Your usage of the NRCS and InfoEx systems is bound by their respective
  14 terms and this software makes no attempt or claim to abide by any such
  15 terms.
  16
  17 Installation
  18 ============
  19
  20 It's recommended to use venv and pip with this program. Here's a typical
  21 sequence of commands for a new setup:
  22
  23 $ cd /path/to/src
  24 $ python3 -m venv env
  25 $ . env/bin/activate
  26 $ pip install -r requirements.txt
  27
  28 How to use it
  29 =============
  30
  31 This program is designed to be run from the command line (or via
  32 cron(8)) and administered via a simple, concise configuration file.
  33
  34 This design allows you to run a separate program instance for each NRCS
  35 weather station from which you'd like to automate the importation of
  36 data into your InfoEx subscriber account.
  37
  38 To run ad-hoc:
  39
  40   ./infoex-autowx.py --config <path/to/config-file.ini>
  41
  42 Here's an example of a crontab(5) with two SNOTEL sites, each of which
  43 will run once per hour:
  44
  45 2 * * * * /home/alv/infoex-autowx/infoex-autowx.py --config laurance-lake.ini
  46 4 * * * * /home/alv/infoex-autowx/infoex-autowx.py --config mud-ridge.ini
  47
  48 Configuration File
  49 ==================
  50
  51 The configuration file is separated into two parts, the [wxsite]
  52 portion, and the [ftp] portion.
  53
  54 The [wxsite] values describe which NRCS SNOTEL site's data you're after.
  55 See the next section in this README for instructions on obtaining these
  56 values.
  57
  58 The [ftp] values describe your credentials for the InfoEx automated
  59 weather station FTP server.
  60
  61 [wxsite]
  62 station_triplet = <The NRCS identifier for a particular SNOTEL site>
  63 desired_data = <A comma-delimited list of NRCS elements you're interested in>
  64 location_uuid = <The UUID used by InfoEx to identify your automated Wx site>
  65 csv_filename = <Arbitrary name of the file that will be uploaded to InfoEx>
  66
  67 [ftp]
  68 host = <InfoEx FTP host address>
  69 uuid = <InfoEx-supplied UUID>
  70 api_key = <InfoEx-supplied API Key>
  71
  72 Finding Your WXSITE values
  73 ==========================
  74
  75 To complete the [wxsite] configuration section, you must fill in the
  76 attributes of the NRCS SNOTEL site from which you want to import data.
  77 Here are the steps to do that:
  78
  79 1. Find your station by clicking through this website:
  80
  81    https://www.wcc.nrcs.usda.gov/snow/sntllist.html
  82
  83    Or by using the interactive map:
  84
  85    https://www.nrcs.usda.gov/wps/portal/wcc/home/quicklinks/imap
  86
  87 2. Once you've found your station, look for the "Station ID" (a 3- or
  88    4-digit number).
  89
  90 3. Combine your Station ID, state abbreviation, and the network type
  91    "SNTL" to get your station triplet (station_triplet, in the
  92    configuration file). For example:
  93
  94    655:OR:SNTL
  95
  96    would represent the Mud Ridge station (Station ID 655) in the state
  97    of Oregon (OR). SNTL just represents that the station is in the
  98    SNOTEL network and is used internally by NRCS.
  99
 100 Once you have your station triplet, fill in the field in your
 101 configuration file. Now you must select which data you'd like to pull
 102 from NRCS to push into InfoEx.
 103
 104 For that, visit the NRCS web service:
 105
 106 https://wcc.sc.egov.usda.gov/awdbWebService/webservice/testwebservice.jsf?webserviceName=/awdbWebService
 107
 108 Click "getElements" on the left, and then click, "Test Operation." This
 109 will return a long list of elements to your web browser from which you
 110 can choose. Each returned element has its identifier and a description.
 111
 112 Once you've chosen your elements, combine all of their respective
 113 "elementCd" values into a comma-delimited string and put that into your
 114 configuration file as the "desired_data" value.
 115
 116 For example:
 117
 118 station_triplet = 655:OR:SNTL
 119 desired_data = TOBS,PREC
 120
 121 indicates that I'd like to import "AIR TEMPERATURE OBSERVED" and
 122 "PRECIPITATION ACCUMULATION" from the NRCS SNOTEL site at Mud Ridge, OR,
 123 into InfoEx.
 124
 125 Version History
 126 ===============
 127
 128 1.0.0 (Jun 2020)
 129   * First released version. Cleaned up the program and design.
 130         Implemented configuration file, added LICENSE, README, docs, etc.
 131
 132 0.8.0 (Apr 2020)
 133   * First finished (unreleased) version.
 134
 135 pre-0.8.0 (Apr 2020)
 136   * First (private) finished implementation with successful NRCS ->
 137     InfoEx importation.