Writing Measurement Scripts

In this page, we will show how to write a few simple measurement scripts.

You do not need to have the full Python development environment setup for this. LinkComm will suffice.

The manual has crucial information about how scripts work.
https://www.ott.com/download/operations-maintenance-manual-sutron-satlink-3-1/

Please take the time to read the chapter on Python scripts. Without that knowledge, it is going to be difficult to work with Satlink 3 and XLink 500 scripts.

Flow Measurement

In this example, our goal is to produce a water flow reading.

  • The flow is based on stage, and we have an SDI-12 stage sensor.
  • We are only interested in flow; we do not want to record stage.
  • The flow is computed using a rating table.

These are the steps that the station will take:

  • The measurement will collect data from the SDI-12 stage sensor
  • The measurement provide the stage result to the script
  • The script will look up the stage value in the rating table
  • The script will produce a flow result
  • The system will log and transmit the flow result

Below is an illustrative example for the script:

@MEASUREMENT
def rating_table(stage):
   flow = table_lookup(stage)
   return flow

Here are the principles for measurement scripts:

  • The @MEASUREMENT decorator must be on the line preceding the Python function.
  • A value is passed into the python function (stage in our example)
  • That value was collected from the sensor setup in the measurement (SDI-12 stage sensor in our example)
  • A value is returned from the script function (flow in our example)
  • The returned value is the final result of the measurement. It will be logged and transmitted.

Here is a completed Python script that does a rating table lookup:

Let us go through the steps to complete this setup with LinkComm.

  • Run LinkComm
LinkCommSL3Connect
  • Choose Station Type XLink 500
  • Click Work offline.
LinkCommOpenScript
  • Go to the Script tab of LinkComm and open the rating table script.
LinkCommFlowMeas
  • Go to the Measurement tab of LinkComm.
  • Setup a measurement that interfaces to the SDI-12 stage sensor.
  • Name the measurement Flow; not Stage. Flow is what gets logged and transmitted.
  • Plug in the rating table script into the measurement.
  • The measurement will collect the data form the SDI-12 sensor, execute the script function, and produce the final result.
Setup file:

Flow measurement setup and script are complete.

Dew Point Measurement

This setup will produce a dew point reading. Dew point is a function of air temperature and relative humidity. When the setup is complete, the system will produce three measurement readings: - Air temperature - Relative humidity - Dew point

Scripts do not have direct access to analog and digital sensor inputs. Instead, measurements need to be setup to collect data from those sensors. Python scripts then do processing on the measurement results.

This is why we will create a total of three measurements:

  • One measurement is setup to read air temperature.
  • A second measurement will interface to a relative humidity sensor.
  • The last measurement computes dew point. This one will use a script.

First, we will use LinkComm to create the three measurements.

LinkCommAt

Air temperature and relative humidity are trivial setups. In our case, we are using analog 0-5V sensors. All three measurements should be scheduled at the same time to produce an accurate dew point result.

LinkCommRh

The setup for air temperature and relative humidity should be identical except for the analog channel.

  • We will use the label AT for air temperature
  • RH for relative humidity
  • The script will reference these exact labels
LinkCommDpNoScript

For the DP (dew point) measurement, we will use a manual entry measurement type. Since the system will not read a sensor, it does not really matter what type we use. Manual entry is ideal as it does not interface to a sensor.

As we setup the DP measurement, we know that we want to use a script, but we do not have it written yet. We will have to come back to that once the script is ready.

This is the script that we use to compute dew point:

@MEASUREMENT
def dew_point(inval):
    """
    Computes dew point based on relative humidity and air temperature.

    :param inval: this value is ignored
    :return: dew point
    :rtype: float
    """
    from math import log10

    # retrieve relative humidity from another measurement which must be labeled RH
    rh = measure("RH").value

    # retrieve temperature from meas labeled AT
    at = measure("AT").value

    # compute dew point
    dp = 0.057906 * (log10(rh / 100) / 1.1805) + (at / (at + 238.3))
    dp = dp * 238.3 / (1 - dp)  # Formula for Dew point temperature

    return dp

For the script, these are the important steps:

  • Retrieve the air temperature and relative humidity readings:

    • For that, we use the measure() function
    • Scripts reference other measurements by index or by label. Our script uses labels.
    • We expect air temperature to be labeled AT, and relative humidity to be RH.

  • Compute dew point using an equation that is a function of AT and RH

Here is the completed script file

Once we have the script file written and saved, we can load it into LinkComm.

LinkCommDpScript
  • On the LinkComm Script tab, click Open Script File.
  • Choose the dew point script file.
LinkCommDpYesScript
  • Go to LinkComm’s Measurement tab.
  • Choose the dew point measurement.
  • Hook in the dew point script.
  • Setup and script are complete!
This is the script file that we end up with:

That completes this example. For more example scripts, please see