readme.txt

# WS-3000 WeeWx driver

## Description

The following references were useful for developing this driver. More than simply useful,
in fact, since a lot of material has been directly reused:
    
From Matthew Wall:
  https://github.com/matthewwall/weewx-hp3000

From Tom Keffer, the WMR100 driver for weewx
  http://www.weewx.com

Many thanks to the following contributers:
- RistoK for helping with troubleshooting and testing on RPi

NOTE: The HP3000 driver developed by Matthew Wall should also be working
for the WS-3000 station. But various issues led me to rewrite a new driver
on the model of the one for the WMR100. One benefit is that this driver will
work with the "default" version of weewx and doesn't require the usb branch.

NOTE: Since the station doesn't distinguish between loop and archive packets,
only genLoopPackets is implemented. It doesn't make sense to implement the other
AbstractDevice methods such as genArchiveRecords.
As a result, weewx should be configured with record_generation = software

NOTE: It seems that when packets are generated (data is fetch from the console) too quickly, errors can
occur, causing the station to 'hang' and potentially crashing weewx (error handling in this
driver is not the best!). Make sure that the loop interval is large enough to avoid any
potential issue.

NOTE: *For Raspberry Pi*: if the usb read/write timeout is too small (100ms), errors
might occur when sending/fetching data from the console. It has been increased to 1000 by default,
but if this is still not sufficient futher increase the timeout in the weewx configuration file.

For additional information, please refer to the `ws3000.py` file.

## Installation

1) Download the WS-3000 extension package from the Releases page:

wget -O weewx-ws3000.tar.gz https://github.com/hublol/ws3000-weewx/archive/refs/tags/weewx-ws3000-0.3.tar.gz

2) Install the extension:

wee_extension --install weewx-ws3000.tar.gz

3) Check if weewx correctly detects the driver:

./bin/wee_config --list-drivers

This should produce output similar to (look for `user.ws3000`):

Module name              Driver name    Version  Status                   
  user.cmon                ComputerMonitor0.16
  user.ws3000              WS3000         0.2
  weewx.drivers.acurite    AcuRite        0.24

4) Edit the `weewx.conf` file to add a new station section.

NOTE: For a brand new installation only (no already configured `weex.conf`), this can be done using the following command:

./bin/wee_config --reconfigure

Add the following section to the configuration file (this is the minimal configuration required):

[WS3000]
    # This section is for the Ambient Weather WS3000

    # The driver to use
    driver = user.ws3000

    # The station model, e.g., WS3000, WS3000-X3, WS3000-X5 (all the same...)
    model = WS3000

    # [Optional] USB read/write timeout (helps on Raspberry Pi)
    # Default is 1000
    timeout =  1000

5) Test the driver to check if it can successfully retrieve the data from the station:

cd /home/weewx
PYTHONPATH=bin python bin/user/ws3000.py

## Configuration options

The full list of configuration options is:

----
[WS3000]
    # This section is for the Ambient Weather WS3000

    # The driver to use
    driver = user.ws3000

    # [Optional] Fetch data from the console or generate it
    # Useful to test without a console plugged in
    # Values are: 'hardware' or 'simulation'
    # mode = simulation

    # The station model, e.g., WS3000, WS3000-X3, WS3000-X5 (all the same...)
    model = WS3000
    
    # [Optional] The interval at which loop packets should be generated by the driver
    # Default is 10
    loop_interval = 30
    
    # [Optional] USB vendor ID and product ID, as returned by lsusb. Only required if the device
    # cannot be found with the default values
    # Defaults are 0x0483 and 0x5750
    vendor_id =  0x0483
    product_id = 0x5750
    
    # [Optional] USB read/write timeout (helps on Raspberry Pi)
    # Default is 1000
    timeout =  1000
    
    # [Optional] By default, all the sensor values are stored in the extraTemp or extraHumid columns. 
    # The assumption here is that the WS3000 is used as a secondary station used 
    # to enhance another existing station with additional temperature sensors, 
    # and that the usual inTemp, outTemp, etc. are already used by the primary station.
    # NOTE: of course, the database schema must be modified to include the missing columns.
    [[sensor_map]]
        extraTemp1 = t_1
        extraTemp2 = t_2
        extraTemp3 = t_3
        extraTemp4 = t_4
        extraTemp5 = t_5
        extraTemp6 = t_6
        extraTemp7 = t_7
        extraTemp8 = t_8
        extraHumid1 = h_1
        extraHumid2 = h_2
        extraHumid3 = h_3
        extraHumid4 = h_4
        extraHumid5 = h_5
        extraHumid6 = h_6
        extraHumid7 = h_7
        extraHumid8 = h_8
----