
pywws.WeatherStation
********************

Get data from WH1080/WH3080 compatible weather stations.

Derived from wwsr.c by Michael Pendec (michael.pendec@gmail.com),
wwsrdump.c by Svend Skafte (svend@skafte.net), modified by Dave Wells,
and other sources.


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

This is the module that actually talks to the weather station base
unit. I don't have much understanding of USB, so copied a lot from
Michael Pendec's C program wwsr.

The weather station memory has two parts: a "fixed block" of 256 bytes
and a circular buffer of 65280 bytes. As each weather reading takes 16
bytes the station can store 4080 readings, or 14 days of 5-minute
interval readings. (The 3080 type stations store 20 bytes per reading,
so store a maximum of 3264.) As data is read in 32-byte chunks, but
each weather reading is 16 or 20 bytes, a small cache is used to
reduce USB traffic. The caching behaviour can be over-ridden with the
``unbuffered`` parameter to ``get_data`` and ``get_raw_data``.

Decoding the data is controlled by the static dictionaries
``reading_format``, ``lo_fix_format`` and ``fixed_format``. The keys
are names of data items and the values can be an ``(offset, type,
multiplier)`` tuple or another dictionary. So, for example, the
reading_format dictionary entry ``'rain' : (13, 'us', 0.3)`` means
that the rain value is an unsigned short (two bytes), 13 bytes from
the start of the block, and should be multiplied by 0.3 to get a
useful value.

The use of nested dictionaries in the ``fixed_format`` dictionary
allows useful subsets of data to be decoded. For example, to decode
the entire block ``get_fixed_block`` is called with no parameters:

   ws = WeatherStation.weather_station()
   print ws.get_fixed_block()

To get the stored minimum external temperature, ``get_fixed_block`` is
called with a sequence of keys:

   ws = WeatherStation.weather_station()
   print ws.get_fixed_block(['min', 'temp_out', 'val'])

Often there is no requirement to read and decode the entire fixed
block, as its first 64 bytes contain the most useful data: the
interval between stored readings, the buffer address where the current
reading is stored, and the current date & time. The
``get_lo_fix_block`` method provides easy access to these.

For more examples of using the WeatherStation module, see the
TestWeatherStation program.


Detailed API
============

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| ``apparent | Compute apparent temperature (real feel), using formula from                               |
| _temp``(te |                                                                                            |
| mp, rh,    |                                                                                            |
| wind)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| ``dew_poin | Compute dew point, using formula from                                                      |
| t``(temp,  |                                                                                            |
| hum)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| ``get_wind | Return an array to convert wind direction integer to a string.                             |
| _dir_text` |                                                                                            |
| `()        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| ``pressure | Convert pressure trend to a string, as used by the UK met                                  |
| _trend_tex |                                                                                            |
| t``(trend) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| ``wind_chi | Compute wind chill, using formula from                                                     |
| ll``(temp, |                                                                                            |
| wind)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| ``CUSBDriv | Low level interface to weather station via USB.                                            |
| e``(librar |                                                                                            |
| y)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| ``weather_ | Class that represents the weather station to user program.                                 |
| station``( |                                                                                            |
| [ws_type,  |                                                                                            |
| library,   |                                                                                            |
| params])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

pywws.WeatherStation.dew_point(temp, hum)

   Compute dew point, using formula from
   http://en.wikipedia.org/wiki/Dew_point.

pywws.WeatherStation.wind_chill(temp, wind)

   Compute wind chill, using formula from
   http://en.wikipedia.org/wiki/wind_chill

pywws.WeatherStation.apparent_temp(temp, rh, wind)

   Compute apparent temperature (real feel), using formula from
   http://www.bom.gov.au/info/thermal_stress/

pywws.WeatherStation.get_wind_dir_text()

   Return an array to convert wind direction integer to a string.

pywws.WeatherStation.pressure_trend_text(trend)

   Convert pressure trend to a string, as used by the UK met office.

class class pywws.WeatherStation.CUSBDrive(library)

   Low level interface to weather station via USB.

   Loosely modeled on a C++ class obtained from http://site.ambientwea
   therstore.com/easyweather/ws_1080_2080_protocol.zip. I don't know
   the provenance of this, but it looks as if it may have come from
   the manufacturer.

   read_block(address)

      Read 32 bytes from the weather station.

      If the read fails for any reason, ``None`` is returned.

      Parameters:
         * **address** (*int*) -- address to read from.

      Returns:
         the data from the weather station.

      Return type:
         list(int)

   write_byte(address, data)

      Write a single byte to the weather station.

      Parameters:
         * **address** (*int*) -- address to write to.

         * **data** (*int*) -- the value to write.

      Returns:
         success status.

      Return type:
         bool

class class pywws.WeatherStation.weather_station(ws_type='1080', library='auto', params=None)

   Class that represents the weather station to user program.

   Connect to weather station and prepare to read data.

   live_data(logged_only=False)

   inc_ptr(ptr)

      Get next circular buffer data pointer.

   dec_ptr(ptr)

      Get previous circular buffer data pointer.

   get_raw_data(ptr, unbuffered=False)

      Get raw data from circular buffer.

      If unbuffered is false then a cached value that was obtained
      earlier may be returned.

   get_data(ptr, unbuffered=False)

      Get decoded data from circular buffer.

      If unbuffered is false then a cached value that was obtained
      earlier may be returned.

   current_pos()

      Get circular buffer location where current data is being
      written.

   get_raw_fixed_block(unbuffered=False)

      Get the raw "fixed block" of settings and min/max data.

   get_fixed_block(keys=[], unbuffered=False)

      Get the decoded "fixed block" of settings and min/max data.

      A subset of the entire block can be selected by keys.

   write_data(data)

      Write a set of single bytes to the weather station. Data must be
      an array of (ptr, value) pairs.
