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] [--dry-run]`

**NOTE: Specifying --dry-run will also not clean up the generated CSV
file.** This is so that you can debug any issues more easily.

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.

`[nrcs]`  
`station_triplet = [The NRCS identifier for a particular SNOTEL site]`  
`desired_data = [A comma-delimited list of NRCS elements you're interested in]`  

`[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]`  

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
---------------

- 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.
  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.