Monalyse Plugins Documentation

Rev. 7

General conventions

DateTime times are UTC
Strings are UTF-8 encoded

Response format

Reponses shall always have the three fields code, message, more_info.

message ProtoError {
  int32  error_code      = 1;   // Error code
  string error_message   = 2;   // Error message
  string error_more_info = 3;   // Optional link to more info
}

error_code Error code, error_code == 0 indicates success.
error_message Human readable error message. It shall be populated when error_code != 0.
error_more_info optional link to (human readable) page explaining the error

DateTime format

message DateTime {
  float days = 1;       // Origin: Midnight, 30 Dec 1899
}

Use the definition of DateTime.FromOADate and DateTime.ToOADate:

… [DateTime is a] floating-point number whose integral component is the number of days before or after midnight, 30 December 1899, and whose fractional component represents the time on that day divided by 24.

Service discovery

Get available services

GET /v1/plugins

Response

message Plugins {
    int32      error_code      = 1;  // Error code, 0 is success
    string     error_message   = 2;  // Error message
    string     error_more_info = 3;  // Optional link to more info
    repeated PluginInfo plugin_infos    = 4;  // List of PluginInfo
}

plugin_infos List of PluginInfo

message PluginInfo {
    string name      = 1; // Plugin name
    string info_text = 2; // Human readable info
}

name Name of the plugin, case insensitive, built from letters, numbers, - and _
info_text Human readable info about the plugin

Get plugin definition

GET /v1/plugins/<plugin-name>/interface

<plugin-name> is the name in the PluginInfo message above.

Response

message PluginDefinition
{
    int32       error_code      = 1;  // Error code, 0 is success
    string      error_message   = 2;  // Error message
    string      error_more_info = 3;  // Optional link to more info
    string      name            = 4;
    string      description     = 5;
    repeated PluginInput plugin_inputs   = 6;
}

name Name of the plugin
description Description of the plugin
plugin_inputs is a list of objects containing the PluginInputs

where

message PluginInput
{
    string           id                 = 1; // e.g. Heat group has id "HG" -> first meter will be HG1, then HG2, etc.
    PluginInputType plugin_input_type   = 2;
    bool            is_optional     = 3;
    string          label               = 4;
    uint32          max_input           = 5;
    uint32          min_input           = 6;
    Units           allowed_units       = 7; // filters on the ui will apply based on this setting
}

enum PluginInputType
{
    Textbox     = 0;
    Meterlist   = 1;
}

enum Units
{
    Any         = 0;
    Energy      = 1;
    Temperature = 2;
    Percent     = 3;
    Boolean     = 4;
}

plugin_input_type is the input type, i.e. one of Textbox, Meterlist
is_optional boolean telling whether this input is optional or not
label is the label shown in the GUI
max_input Maximum number of allowed imputs
min_input Minimum number of allowed imputs
allowed_units List of units (energy, temperature)

Plugin execution

Run plugin

POST /v1/plugins/<plugin-name>

<plugin-name> is the name in the PluginInfo message above.

Payload: Request

message Request {
    repeated TimeSeries metervalues = 1;
    repeated UserValue uservalues   = 2;
}

data is the input to the plugin, i.e. a list of timeseries (see below)

Response

message Alerts
{
    int32  error_code       = 1;  // Error code, 0 is success
    string error_message    = 2;  // Error message
    string error_more_info  = 3;  // Optional link to more info
    repeated Alert  alerts  = 4;
}

alerts is a list of alerts

where

message Alert
{
    AlertType alert_type = 1;
    DateTime  datetime   = 2;
    string    message    = 3;
}

enum AlertType
{
    Information = 0;
    Warning     = 1;
    Error       = 2;
}

alert_type can be one of information, warning, error
datetime timeseries time at which alert occurs
message describes the alert

A timeseries is basically a list of rows. A row contains a datetime and a value.

message TimeSeries
{
    string input_id = 1;  // id from PluginInput (e.g. HG1)
    string unit     = 2; // even if in Units "Energy" was defined, we have to know if it is kWh / MWh
    int32 period        = 3; // the period defined in Monalyse (e.g. 15, 5, 60)
    repeated TimeSeriesRow rows = 4;
}

message TimeSeriesRow
{
    DateTime datetime = 1;
    double   value    = 2; // contains double.nan if gaps exist
    optional double   rawvalue = 3; // contains double.nan if gaps exist or meter is a virtual meter
}

message UserValue {
    string input_id =  1;   // id from PluginInput (e.g. THRESHOLD_WHATEVER)
    string value     = 2;
}

Schedules

GET /v1/plugins/<plugin-name>/schedule

<plugin-name> is the name in the PluginInfo message above.

Response

// This object describes the schedule of the calculation done by the plugin.
message PluginSchedule
{
    TimePeriod recurrence       = 1; // How often to schedule
    TimePeriod data_range       = 2; // The TimePeriod to use as unit to get the range to calculate
    int32      data_range_count = 3; // How many of TimePeriods defined in DateRange back to calculate
}

recurrence: How often to schedule
data_range: The TimePeriod to use as unit to get the range to calculate
data_range_count: How many of TimePeriods defined in DateRange back to calculate

where

enum TimePeriod {
    Day   = 0;
    Week  = 1;
    Month = 2;
    Year  = 3;
}

Bugs

A makeshift bugtracker is on google docs

The service source code is on bitbucket.