+Finding your MesoWest `station` values
+--------------------------------------
+
+MesoWest has great documentation which can be found here:
+
+https://developers.synopticdata.com/mesonet/v2/getting-started/
+
+To complete the [station] configuration section for a MesoWest station,
+you must fill in the attributes of the MesoWest station ID from which
+you want to import data. Here are the steps to do that:
+
+1. Firstly, get set up with MesoWest's API by going to the above
+ 'Getting Started' link. Once you're set up, you can copy a token from
+ the MesoWest web portal into your configuration file's `token` value.
+
+2. Next, you will want to find the Station ID for the MesoWest weather
+ station of interest and copy it to the `station_id` value.
+
+3. Finally, you must choose what data types you want to push into
+ InfoEx and compile them into a comma-separated list. MesoWest refers
+ to these as 'field names' or 'station variables' and a list is
+ available here:
+
+https://developers.synopticdata.com/about/station-variables/
+
+The MesoWest API supports on-the-fly unit conversion. If desired, that
+can be specified to infoex-autowx via the configuration option `units`.
+This can be either 'english' or 'metric', with 'english' meaning
+imperial units as used in the United States.
+
+A complete [station] section example:
+
+`[station]`
+`type = mesowest`
+`token = # token id copied from MesoWest web account #`
+`station_id = OD110`
+`desired_data = air_temp,snow_depth`
+`units = english`
+
+indicates that I'd like to import "Temperature" and "Precipitation
+accumulated" from the MesoWest station at Santiam Pass, OR, into InfoEx,
+and that I want that data in imperial units.
+
+Three- versus 24-hour ranges
+----------------------------
+
+By default, this program will fetch three hours of data from the
+provider. This way, if the most recent record has any missing data, it
+can examine the two hours prior, using whatever data it can find.
+
+There are two features which will cause the program to expand the time
+range of fetched data from three to 24 hours. Please be aware of this
+expansion as it may cause a rise in data/API usage.
+
+**NOTE: Only MesoWest stations have the benefit of wind averaging and
+ HN24 calculation at this time, because generally NRCS SNOTEL
+ stations do not provide wind data. HN24 support for NRCS SNOTEL
+ is planned.
+
+### Wind mode
+If you go to submit a Wx observation in InfoEx at e.g. 05:05, and have
+so configured InfoEx, it will take the wind speed, wind gust speed, and
+wind direction, from that hour and auto-fill it for the observation.
+
+Some operations may find it more important to know the averages for
+those values over the prior 24 hour period. Setting `wind_mode` to
+`average` will enable that.
+
+### HN24
+As most stations do not provide HN24 on their own, this program provides
+a configuration option for calculating this. Simply add `hn24 = true` to
+the configuration file.
+
+*NOTE: This is its own configuration option, rather than a new value for
+ desired_data, because it's not technically provided by MesoWest
+ or NRCS SNOTEL.*
+
+Custom weather station support
+------------------------------
+
+This program supports custom weather station data by allowing the user
+to specify the path to an external Python program. The external Python
+program should emit its data in the form expected by infoex-autowx.
+
+This is a powerful feature which enables the user to upload data from
+any source imaginable into InfoEx. Common examples are a local database
+or a remote web page which requires some custom parsing.
+
+Please see the program located at examples/custom-wx.example.py for a
+complete description of what's required.
+
+A note on time zones
+--------------------
+
+This program is aware of time zones via the pytz library. The way in
+which NRCS and MesoWest deal with time zones differs as follows:
+
+NRCS expects the request to come in the appropriate time zone, and the
+data retrieved will be in the same time zone (no transformation
+required before sending to InfoEx).
+
+MesoWest expects the request to come in UTC, and the data retrieved will
+be in the same time zone (transformation from UTC to the desired time
+zone is required before sending to InfoEx).
+
+As long as you specify the correct timezone in your configuration file,
+all will be handled correctly. The list of time zones comes from the
+Olson tz database. See that for more information.
+
+If you specify an invalid time zone, the program will exit and inform
+you of such.
+
+Lastly, InfoEx itself is timezone aware. If you notice that the data
+which makes it into your operation is inaccurate, start your
+investigation with time zone-related issues and move on only once you've
+ruled this out as a cause of the inaccuracy.
+
+Unit conversions
+----------------
+
+Desired units may be specified in the configuration file.
+
+For MesoWest, the desired unit will be passed along in the API request
+and the conversion will take place through the MesoWest/Synoptic API.
+
+For NRCS, this program will do the conversion manually, as NRCS does not
+permit specifying the desired unit.
+
+There is an "American" units mode in which precip data is converted to
+metric, and wind data is converted to imperial units.
+
+A note on supported measurements
+--------------------------------
+
+While this program supports several measurements, and will faithfully
+request all of the ones you specify (provided they're supported), the
+weather station may not record them. In this case, the data will simply
+be ignored (i.e. it will NOT log "0" when there's no measurement
+available).
+
+InfoEx provides a mechanism for inspecting your automated weather
+station data, so use that after setting this program up and compare it
+with the data you see in your web browser.
+
+Here's the list of measurements currently supported:
+
+**NRCS:**
+PREC
+TOBS
+SNWD
+PRES
+RHUM
+WSPD
+WDIR
+
+**MesoWest:**
+precip\_accum
+air\_temp
+snow\_depth
+pressure
+relative\_humidity
+wind\_speed
+wind\_direction
+wind\_gust
+
+**Custom Wx program**
+*infoex-autowx expects a custom Wx data provider to provide at least one
+of the following:*
+precipitationGauge
+tempPres
+tempMaxHour
+tempMinHour
+hS
+baro
+rH
+windSpeedNum
+windDirectionNum
+windGustSpeedNum
+
+Version history
wylark / infoex-autowx.git / blobdiff