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

Post weather update to services such as Weather Underground

   usage: python toservice.py [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.py``
to create a section in ``weather.ini``:

   python pywws/toservice.py 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 pywws/toservice.py -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.py`` with the
catchup option:

   python pywws/toservice.py -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 ]-

+------------+--------------------------------------------------------------------------------------------+
| ``ToServic | Upload weather data to weather services such as Weather                                    |
| e``(params |                                                                                            |
| , calib_da |                                                                                            |
| ta[, servi |                                                                                            |
| ce_name])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

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)
