Telemetry

Models

class enhydris.telemetry.models.Telemetry

Information about how to automatically fetch data.

Telemetry has a OneToOneField to Station. Every minute Celery Beat runs a task that iterates through the records of Telemetry; for each record, if the time for fetching data has arrived, it fetches the data by calling the fetch() method.

Telemetry objects have the following attributes, properties and methods:

station: OneToOneField

The Station to which the record refers.

type: CharField

The type of the API, such as Adcon AddUPI or Metrica MeteoView2. See Telemetry API types for more information.

data_time_zone: CharField

Enhydris has the requirement that all time stamps in TimeseriesRecord must be stored in the same offset from UTC, i.e. without switching to Daylight Saving Time (DST). This offset is specified by enhydris.models.TimeseriesGroup.time_zone.

It is recommended that data loggers also do not switch to DST. However, if they do, Enhydris can convert their time stamps as needed. If, for example, data_time_zone is set to Europe/Athens, then any DST offset will be removed before storing in TimeseriesRecord.

data_time_zone is used only in order to know when the DST switches occur. The timestamp, after removing any DST, is entered as is. There is no conversion from data_time_zone to enhydris.models.TimeseriesGroup.time_zone. Therefore, whether data_time_zone is Europe/Athens or Europe/Berlin, the effect will be exactly the same, since Athens and Berlin (as of 2021) switch to DST in exactly the same dates.

Enhydris assumes that the time change occurs exactly when it is supposed to occur, not a few hours earlier or later. For the switch towards DST, things are simple. For the switch from DST to winter time, things are more complicated, because there’s an hour that appears twice. If the ambiguous hour occurs twice, Enhydris will usually do the correct thing; it will consider that the second occurence is after the switch and the first is before the switch. If according to the system’s clock the switch hasn’t occurred yet, any references to the ambiguous hour are considered to have occurred before the switch.

fetch_interval_minutes: PositiveSmallIntegerField

This can be, e.g., 60 to fetch data every 60 minutes, 1440 to fetch data once a day, etc.

fetch_offset_minutes: PositiveSmallIntegerField

If fetch_interval_minutes is 10 and fetch_offset_minutes is 2, then data will be fetched at :02, :12, :22, etc. If fetch_interval_minutes is 1440 and fetch_offset_minutes is 125, then data will be fetched every day at 02:05 in the morning. Generally fetch_offset_minutes counts from midnight.

fetch_offset_time_zone: CharField

The time zone to which fetch_offset_minutes refers; a tz database name such as Europe/Athens.

configuration: JSONField

Any additional configuration. The exact contents depend on the API type. However, configuration contains (among other things) a timeseries key, which is a list. See Telemetry.wizard_steps for more information.

property is_due: Boolean

True if according to fetch_interval_minutes, fetch_offset_minutes, fetch_offset_time_zone and the current system time it’s time to fetch data.

fetch() None

Connects to the API, fetches the data, and inserts them to TimeseriesRecord. Essentially this merely calls Telemetry.fetch().

Telemetry API types

Each API type is one Python file in the enhydris/telemetry/types. The Python file must contain a Telemetry class with all required functionality to retrieve data from the API.

When it starts, Enhydris scans the enhydris/telemetry/types directory and imports all Python files it contains. The result of this scanning goes to enhydris.telemetry.drivers.

enhydris.telemetry.drivers

A dictionary that contains all Telemetry classes imported from the enhydris/telemetry/types directory. Each dictionary item maps the telemetry type’s slug (the base name of the Python file) to the Telemetry class.

class Telemetry(telemetry_model)

Should inherit from enhydris.telemetry.TelemetryBase. The base class __init__() method initializes the object with a enhydris.telemetry.models.Telemetry object, which becomes the telemetry_model attribute.

Telemetry classes must define following attributes, methods and properties:

name: string

The name of the API, such as Adcon AddUPI or Metrica MeteoView2. This is what is stored in enhydris.telemetry.models.Telemetry.type.

wizard_steps: list

When the user wants to configure telemetry for a station, we show him a wizard. The first step essentially asks what type of telemetric system there is for the station at hand, i.e. asks the user to select a value for enhydris.telemetry.models.Telemetry.type. The wizard then continues with steps that are specific to the chosen telemetry type. wizard_steps, a class attribute, is a list of django.forms.Form subclasses, containing the forms for these steps. These forms are instantiated with the configuration specified so far as their initial parameter, and the configuration is updated with the cleaned_data once the form is posted.

fetch() None

Connects to the API, fetches the data, and inserts them to TimeseriesRecord.