README.md

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