=============================
WMS Interface Developer Guide
=============================

.. image:: diagrams/WeatherStation_UML.svg

---------------------------
Running a simulation server
---------------------------

To start up a Modbus server running the WMS simulation, run the
``wms_sim_server.py`` script as follows:

.. code-block:: bash

    cd src/ska_mid_wms_interface/simulator  
    python wms_sim_server.py [-h] -c CONFIG -s SERVER -d DEVICE

* CONFIG: The path to a json configuration file (see `Pymodbus 
  <https://pymodbus.readthedocs.io/en/latest/source/library/simulator/config.html>`_ 
  for details)
* SERVER: The name of a server in this file to start
* DEVICE: The name of the device to simulate

The Dockerfile in this repository allows you to build and run the simulator as an image
using the json configuration file stored at tests/data/wms_simulation.json:

.. code-block:: bash

    docker image build -t wms-simulator .
    docker run -ite WMS_SIM_HOST=0.0.0.0 -p 1502:1502 wms-simulator

-----------------------------
Configuring a Weather Station
-----------------------------
By default, a weather station will use an in-built configuration.

The WMS interface can also be configured with a YAML file which specifies details about
the sensors to be read. The Modbus addresses must all be sourced from the same register
section (for an Acromag 961EN-4006 the normalised addresses are 9-14).
They can either be specified in hexadecimal by using the 0x prefix, or in decimal.
The YAML has the following format:

.. code-block:: YAML

    Weather_Station:
      slave_id: 0           # Modbus slave id (int)
      poll_interval: 0.2    # Optional poll interval (float) - defaults to 1 second
      sensors:              # Repeat block for each sensor to be read
        windSpeed:         # Sensor name (str) - should match a value in SensorEnum
          address: 15       # Modbus register address (int) - can be in hex or decimal
          description: "..."# Sensor description (str)
          unit: m/s         # Engineering unit (str)
          scale_low: 0.0    # Value in engineering units corresponding to min ADC reading (float)
          scale_high: 70.0  # Value in engineering units corresponding to max ADC reading (float)

A full example configuration file can be found `here <https://gitlab.com/ska-telescope/ska-mid-wms-interface/-/blob/main/tests/data/weather_station.yaml>`_.

-----------------------------
Using the Weather Station API
-----------------------------

Here is a brief example demonstrating how to use the WMS Python interface:

.. code-block:: py

    import logging
    import pprint
    from ska_mid_wms_interface import WeatherStation, SensorEnum

    logger = logging.getLogger()
    
    # Create the WeatherStation interface, specifying:
    #   - path to a YAML configuration file (see above)
    #   - hostname of the Modbus server
    #   - port number of the Modbus server
    #   - Logger object to use for logging
    weather_station = WeatherStation("localhost", 502, logger)

    # Set the polling interval (defaults to 1 second)
    weather_station.polling_interval = 2

    # Set the sensors to poll if required (defaults to the full set)
    sensors = [SensorEnum.PRESSURE, SensorEnum.RAINFALL]
    weather_station.configure_poll_sensors(sensors)

    # Connect to the station and start polling
    weather_station.connect()
    weather_station.start_polling()

    # Subscribe to data and error updates
    def callback(result):
        # Result is a nested dict with the following keys:
        #    value: converted value (float)
        #    unit: engineering unit (str)
        #    timestamp: Time the response was received (datetime object)
        pprint.pprint(result, indent=2)

    def error_callback(event):
        # event is a dict with the following keys:
        #    sensor_failures: the sensor names that could not be read (list[str])
        #    message: error message (str)
        #    timestamp: time the response was received (datetime object)
        pprint.pprint(event, indent=2)
    id = weather_station.subscribe_data(callback, error_callback)

    # Unsubscribe and disconnect
    weather_station.unsubscribe_data(id)
    weather_station.stop_polling()
    weather_station.disconnect()

-------------------
Tango Device Server
-------------------

A :ref:`ska-mid-wms:tango_device` has been developed to publish the Weather Station automatically
to interested clients.