
pywws.toservice
***************

Post weather update to services such as Weather Underground

   usage: python RunModule.py toservice [options] data_dir service_name
   options are:
    -h or --help     display this help
    -c or --catchup  upload all data since last upload
    -v or --verbose  increase amount of reassuring messages
   data_dir is the root directory of the weather data
   service_name is the service to upload to, e.g. underground


Introduction
============

Several organisations allow weather stations to upload data using a
simple HTTP 'POST' or 'GET' request, with the data encoded as a
sequence of "key=value" pairs separated by "&" characters.

This module enables pywws to upload readings to these organisations.
It is highly customisable using configuration files. Each 'service'
requires a configuration file and two templates in "pywws/services"
(that should not need to be edited by the user) and a section in
"weather.ini" containing user specific data such as your site ID and
password.

There are currently six services for which configuration files have
been written.

+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| organisation                                                            | service name            | config file                                                  |
+=========================================================================+=========================+==============================================================+
| UK Met Office                                                           | "metoffice"             | "../../code/pywws/services/metoffice.ini"                    |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| Open Weather Map                                                        | "openweathermap"        | "../../code/pywws/services/openweathermap.ini"               |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| Stacja Pogody                                                           | "stacjapogodywawpl"     | "../../code/pywws/services/stacjapogodywawpl.ini"            |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| temperatur.nu                                                           | "temperaturnu"          | "../../code/pywws/services/temperaturnu.ini"                 |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| Weather Underground                                                     | "underground"           | "../../code/pywws/services/underground.ini"                  |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+
| wetter.com                                                              | "wetterarchivde"        | "../../code/pywws/services/wetterarchivde.ini"               |
+-------------------------------------------------------------------------+-------------------------+--------------------------------------------------------------+


Configuration
=============

If you haven't already done so, visit the organisation's web site and
create an account for your weather station. Make a note of any site ID
and password details you are given.

Stop any pywws software that is running and then run "toservice" to
create a section in "weather.ini":

   python RunModule.py toservice data_dir service_name

"service_name" is a single word service name, such as "metoffice",
"data_dir" is your weather data directory, as usual.

Edit "weather.ini" and find the section corresponding to the service
name, e.g. "[underground]". Copy your site details into this section,
for example:

   [underground]
   password = secret
   station = ABCDEFG1A

Now you can test your configuration:

   python RunModule.py toservice -vvv data_dir service_name

This should show you the data string that is uploaded. Any failure
should generate an error message.


Upload old data
===============

Now you can upload your last 7 days' data, if the service supports it.
Edit your "weather.ini" file and remove the "last update" line from
the appropriate section, then run "toservice" with the catchup option:

   python RunModule.py toservice -cvv data_dir service_name

This may take 20 minutes or more, depending on how much data you have.


Add service(s) upload to regular tasks
======================================

Edit your "weather.ini" again, and add a list of services to the
"[live]", "[logged]", "[hourly]", "[12 hourly]" or "[daily]" section,
depending on how often you want to send data. For example:

   [live]
   twitter = []
   plot = []
   text = []
   services = ['underground']

   [logged]
   twitter = []
   plot = []
   text = []
   services = ['metoffice', 'stacjapogodywawpl']

   [hourly]
   twitter = []
   plot = []
   text = []
   services = ['underground']

Note that the "[live]" section is only used when running "LiveLog.py".
It is a good idea to repeat any service selected in "[live]" in the
"[logged]" or "[hourly]" section in case you switch to running
"Hourly".

Restart your regular pywws program ("Hourly" or "LiveLog") and visit
the appropriate web site to see regular updates from your weather
station.


Notes on the services
=====================


UK Met Office
-------------

* Create account: https://register.metoffice.gov.uk/WaveRegistrationCl
  ient/public/register.do?service=weatherobservations

* API:
  http://wow.metoffice.gov.uk/support?category=dataformats#automatic

* Example "weather.ini" section:

     [metoffice]
     site id = 12345678
     aws pin = 987654


Open Weather Map
----------------

* Create account: http://openweathermap.org/login

* API: http://openweathermap.org/API

* Example "weather.ini" section:

     [openweathermap]
     lat = 51.501
     long = -0.142
     alt = 10
     user = Elizabeth Windsor
     password = corgi
     id = Buck House

The default behaviour is to use your user name to identify the weather
station. However, it's possible for a user to have more than one
weather station, so there is an undocumented "name" parameter in the
API that can be used to identify the station. This appears as "id" in
"weather.ini". Make sure you don't choose a name that is already in
use.


Weather Underground
-------------------

* Create account: http://www.wunderground.com/members/signup.asp

* API:
  http://wiki.wunderground.com/index.php/>>PWS_<<-_Upload_Protocol

* Example "weather.ini" section:

     [underground]
     station = ABCDEFGH1
     password = xxxxxxx


API
===

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "ToService | Upload weather data to weather services such as Weather                                    |
+------------+--------------------------------------------------------------------------------------------+

class class pywws.toservice.ToService(params, calib_data, service_name=None)

   Upload weather data to weather services such as Weather
   Underground.

   Parameters:
      * **params** ("pywws.DataStore.params") -- pywws configuration.

      * **calib_data** ("pywws.DataStore.calib_store") -- 'calibrated'
        data.

      * **service_name** (*string*) -- name of service to upload to.

   translate_data(current, fixed_data)

      Convert a weather data record to upload format.

      The "current" parameter contains the data to be uploaded. It
      should be a 'calibrated' data record, as stored in
      "pywws.DataStore.calib_store".

      The "fixed_data" parameter contains unvarying data that is site
      dependent, for example an ID code and authentication data.

      Parameters:
         * **current** (*dict*) -- the weather data record.

         * **fixed_data** (*dict*) -- unvarying upload data.

      Returns:
         converted data, or "None" if invalid data.

      Return type:
         dict(string)

   send_data(data, server, fixed_data)

      Upload a weather data record.

      The "data" parameter contains the data to be uploaded. It should
      be a 'calibrated' data record, as stored in
      "pywws.DataStore.calib_store".

      The "fixed_data" parameter contains unvarying data that is site
      dependent, for example an ID code and authentication data.

      Parameters:
         * **data** (*dict*) -- the weather data record.

         * **server** (*string*) -- web address to upload to.

         * **fixed_data** (*dict*) -- unvarying upload data.

      Returns:
         success status

      Return type:
         bool

   Upload(catchup)

      Upload one or more weather data records.

      This method uploads either the most recent weather data record,
      or all records since the last upload (up to 7 days), according
      to the value of "catchup".

      It sets the "last update" configuration value to the time stamp
      of the most recent record successfully uploaded.

      Parameters:
         **catchup** (*bool*) -- upload all data since last upload.

      Returns:
         success status

      Return type:
         bool

   RapidFire(data, catchup)

      Upload a 'Rapid Fire' weather data record.

      This method uploads either a single data record (typically one
      obtained during 'live' logging), or all records since the last
      upload (up to 7 days), according to the value of "catchup".

      It sets the "last update" configuration value to the time stamp
      of the most recent record successfully uploaded.

      The "data" parameter contains the data to be uploaded. It should
      be a 'calibrated' data record, as stored in
      "pywws.DataStore.calib_store".

      Parameters:
         * **data** (*dict*) -- the weather data record.

         * **catchup** (*bool*) -- upload all data since last upload.

      Returns:
         success status

      Return type:
         bool

pywws.toservice.main(argv=None)
