Add README and LICENSE

diff --git a/LICENSE b/LICENSE
new file mode 100644 (file)
index 0000000..d8d006f
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+Copyright 2020 Alexander Vasarab, WYLARK MOUNTAINEERING LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..a36125f
--- /dev/null
+++ b/README
@@ -0,0 +1,137 @@
+=============
+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 virtualenv and pip with this program. Here's a
+typical sequence of commands for a new setup:
+
+$ cd /path/to/src
+$ virtualenv venv
+$ . venv/bin/activate
+$ pip3 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:
+
+  ./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:
+
+2 * * * * /home/alv/infoex-autowx/infoex-autowx.py --config laurance-lake.ini
+4 * * * * /home/alv/infoex-autowx/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 NRCS ->
+    InfoEx importation.