Initial Implementation

README.md

@@ -1,2 +1,86 @@
 # pimatic-filter
-Pimatic Plugin which provides various filtering functions for sensor data
+
+Pimatic Plugin which provides various filtering functions to achieve digital filtering or smoothing of sensor data.
+It is useful, for example, if the sensor data is not accurate and you wish to disregard potential outliers at
+the minimum and maximum of sensor values processed.
+
+## Status of Implementation
+
+To date, the plugin provides two basic filter types. More filters can be added on request. If you wish to get involved
+you're welcome to make contributions. If you're not familiar with programming please open issue to describe your  
+request as detailed as possible including references to background material and possibly an algorithmic description.
+
+## Plugin Configuration
+
+You can load the plugin by editing your `config.json` to include the following in the `plugins` section.
+
+    {
+       "plugin": "filter",
+    }
+
+## Filters Configuration
+
+A filter basically is a pimatic device instance which takes an input value from another device which is processed to
+produce an output value. Depending on the type of filter the number of output values produced may different from the
+number of inputs provided.
+
+### Simple Moving Average
+
+The Simple Moving Average filter, is the unweighted mean of a given number of previous sensor values processed. For a
+general discussion see [Wikipedia on Moving Average](https://en.wikipedia.org/wiki/Moving_average).
+
+The number previous sensor values processed by the filter is also called sliding window. You can specify the "size" of
+the sliding window. By default, the window takes five elements. Initially, when the number of data values processed is
+smaller than the window size, the mean will be calculated from the existing values.
+
+The "output" property defines the attribute which represents the output produced by the filter. It must have a "name"
+and a "expression" which defines a reference to the input value. In the simplest case, the expression contains a
+variable, but it can also contain a calculation or a string interpolation which finally produces the input value.
+Note, however, the resulting value must be a number to be processed by the filter. The "output" may also contain a 
+"label", "acronym", and "unit".
+
+    {
+        "class": "SimpleMovingAverageFilter",
+        "id": "filter1",
+        "name": "Filter",
+        "size": 5,
+        "output": {
+            "name": "temperature",
+            "label": "Temperature",
+            "expression": "$unipi-2.temperature",
+            "acronym": "T",
+            "type": "number",
+            "unit": "°C"
+        }
+    }
+
+### Simple Truncated Mean
+
+The Simple Truncated Mean is a truncated mean, where the highest and lowest value of a given number of previous
+sensor values is disregarded and the remaining values are used to calculate the arithmetic mean. For a
+general discussion see [Wikipedia on Truncated Mean](https://en.wikipedia.org/wiki/Truncated_mean).
+
+The number previous sensor values processed by the filter is also called sliding window. You can specify the "size" of
+the sliding window. By default, the window takes five elements. Initially, when the number of data values processed is
+smaller than the window size the mean will be calculated, as follows:
+ * if there are less than three values no truncating is perform and the mean is calculated from the existing values
+ * if there are three or more values truncating is performed and the mean is calculated from the existing values.
+
+The "output" property defines the attribute which represents the output produced by the filter. It must have a "name"
+and a "expression" which defines a reference to the input value. In the simplest case, the expression contains a
+variable, but it can also contain a calculation or a string interpolation which finally produces the input value.
+Note, however, the resulting value must be a number to be processed by the filter. The "output" may also contain a
+"label", "acronym", and "unit".
+
+    {
+        "class": "SimpleTruncatedMeanFilter",
+        "id": "filter1",
+        "name": "Filter",
+        "output": {
+            "name": "Temperature",
+            "expression": "$unipi-2.temperature",
+            "acronym": "T",
+            "type": "number",
+            "unit": "°C"
+        }
+    }

device-config-schema.coffee

@@ -0,0 +1,79 @@
+module.exports = {
+  title: "pimatic-filter device config schemas"
+  SimpleMovingAverageFilter: {
+    title: "SimpleMovingAverageFilter config options"
+    type: "object"
+    extensions: ["xLink", "xAttributeOptions"]
+    properties:
+      size:
+        description: "Size of the sliding window of samples used for the calculation"
+        type: "number"
+        default: "5"
+      output:
+        type: "object"
+        required: ["name", "expression"]
+        properties:
+          name:
+            description: "Name for the corresponding output attribute."
+            type: "string"
+          expression:
+            description: "
+                The expression to use to get the input value. Can be just a variable name ($myVar),
+                a calculation ($myVar + 10) or a string interpolation (\"Test: {$myVar}!\")
+                "
+            type: "string"
+          unit:
+            description: "The unit of the variable. Only works if type is a number."
+            type: "string"
+          label:
+            description: "A custom label to use in the frontend."
+            type: "string"
+          discrete:
+            description: "
+                Should be set to true if the value does not change continuously over time.
+                "
+            type: "boolean"
+          acronym:
+            description: "Acronym to show as value label in the frontend"
+            type: "string"
+            required: false
+  }
+  SimpleTruncatedMeanFilter: {
+    title: "SimpleTruncatedMeanFilter config options"
+    type: "object"
+    extensions: ["xLink", "xAttributeOptions"]
+    properties:
+      size:
+        description: "Size of the sliding window of samples used for the calculation"
+        type: "number"
+        default: "5"
+      output:
+        type: "object"
+        required: ["name", "expression"]
+        properties:
+          name:
+            description: "Name for the corresponding output attribute."
+            type: "string"
+          expression:
+            description: "
+                The expression to use to get the input value. Can be just a variable name ($myVar),
+                a calculation ($myVar + 10) or a string interpolation (\"Test: {$myVar}!\")
+                "
+            type: "string"
+          unit:
+            description: "The unit of the variable. Only works if type is a number."
+            type: "string"
+          label:
+            description: "A custom label to use in the frontend."
+            type: "string"
+          discrete:
+            description: "
+                Should be set to true if the value does not change continuously over time.
+                "
+            type: "boolean"
+          acronym:
+            description: "Acronym to show as value label in the frontend"
+            type: "string"
+            required: false
+  }
+}

filter-config-schema.coffee

@@ -0,0 +1,6 @@
+# #pimatic-probe plugin config options
+module.exports = {
+  title: "pimatic-filter plugin config options"
+  type: "object"
+  properties: {} #no
+}

filter.coffee

@@ -0,0 +1,183 @@
+module.exports = (env) ->
+  Promise = env.require 'bluebird'
+  assert = env.require 'cassert'
+  _ = env.require('lodash')
+
+  class FilterPlugin extends env.plugins.Plugin
+
+    init: (app, @framework, @config) =>
+      deviceConfigDef = require("./device-config-schema")
+
+      @framework.deviceManager.registerDeviceClass("SimpleMovingAverageFilter", {
+        configDef: deviceConfigDef.SimpleMovingAverageFilter,
+        createCallback: (config, lastState) =>
+          return new SimpleMovingAverageFilter(config, lastState)
+      })
+
+      @framework.deviceManager.registerDeviceClass("SimpleTruncatedMeanFilter", {
+        configDef: deviceConfigDef.SimpleTruncatedMeanFilter,
+        createCallback: (config, lastState) =>
+          return new SimpleTruncatedMeanFilter(config, lastState)
+      })
+
+  plugin = new FilterPlugin
+
+  class SimpleMovingAverageFilter extends env.devices.Device
+
+    filterValues: []
+    sum: 0.0
+    mean: 0.0
+    attributeValue: null
+
+    constructor: (@config, lastState) ->
+      @id = config.id
+      @name = config.name
+      @size = config.size
+      @output = config.output
+
+      @varManager = plugin.framework.variableManager #so you get the variableManager
+      @_exprChangeListeners = []
+
+      name = @output.name
+      info = null
+
+      if lastState[name]?
+        @attributeValue = lastState[name]
+
+      #@attributes = _.cloneDeep(@attributes)
+      @attributes[name] = {
+        description: name
+        label: (if @output.label? then @output.label else "$#{name}")
+        type: "number"
+      }
+
+      if @output.unit? and @output.unit.length > 0
+        @attributes[name].unit = @output.unit
+
+      if @output.discrete?
+        @attributes[name].discrete = @output.discrete
+
+      if @output.acronym?
+        @attributes[name].acronym = @output.acronym
+
+      @_createGetter(name, =>
+        return Promise.resolve @attributeValue
+      )
+
+      evaluate = ( =>
+        # wait till VariableManager is ready
+        return Promise.delay(10).then( =>
+          unless info?
+            info = @varManager.parseVariableExpression(@output.expression)
+            @varManager.notifyOnChange(info.tokens, evaluate)
+            @_exprChangeListeners.push evaluate
+
+          switch info.datatype
+            when "numeric" then @varManager.evaluateNumericExpression(info.tokens)
+            when "string" then @varManager.evaluateStringExpression(info.tokens)
+            else
+              assert false
+        ).then((val) =>
+          if val
+            val = Number(val)
+            @filterValues.push val
+            @sum = @sum + val
+            if @filterValues.length > @size
+              @sum = @sum - @filterValues.shift()
+            @mean = @sum / @filterValues.length
+
+            env.logger.debug @mean, @filterValues
+            @_setAttribute name, @mean
+          return @attributeValue
+        )
+      )
+      evaluate()
+      super()
+
+    _setAttribute: (attributeName, value) ->
+      @attributeValue = value
+      @emit attributeName, value
+
+
+  class SimpleTruncatedMeanFilter extends env.devices.Device
+
+    filterValues: []
+    mean: 0.0
+    attributeValue: null
+
+    constructor: (@config, lastState) ->
+      @id = config.id
+      @name = config.name
+      @size = config.size
+      @output = config.output
+
+      @varManager = plugin.framework.variableManager #so you get the variableManager
+      @_exprChangeListeners = []
+
+      name = @output.name
+      info = null
+
+      if lastState[name]?
+        @attributeValue = lastState[name]
+
+      #@attributes = _.cloneDeep(@attributes)
+      @attributes[name] = {
+        description: name
+        label: (if @output.label? then @output.label else "$#{name}")
+        type: "number"
+      }
+
+      if @output.unit? and @output.unit.length > 0
+        @attributes[name].unit = @output.unit
+
+      if @output.discrete?
+        @attributes[name].discrete = @output.discrete
+
+      if @output.acronym?
+        @attributes[name].acronym = @output.acronym
+
+      @_createGetter(name, =>
+        return Promise.resolve @attributeValue
+      )
+
+      evaluate = ( =>
+        # wait till VariableManager is ready
+        return Promise.delay(10).then( =>
+          unless info?
+            info = @varManager.parseVariableExpression(@output.expression)
+            @varManager.notifyOnChange(info.tokens, evaluate)
+            @_exprChangeListeners.push evaluate
+
+          switch info.datatype
+            when "numeric" then @varManager.evaluateNumericExpression(info.tokens)
+            when "string" then @varManager.evaluateStringExpression(info.tokens)
+            else
+              assert false
+        ).then((val) =>
+          if val
+            val = Number(val)
+            @filterValues.push val
+            if @filterValues.length > @size
+              @filterValues.shift()
+
+            processedValues = _.clone(@filterValues)
+            if processedValues.length > 2
+              processedValues.sort()
+              processedValues.shift()
+              processedValues.pop()
+
+            @mean = processedValues.reduce(((a, b) => return a + b), 0) / processedValues.length
+
+            env.logger.debug @mean, @filterValues, processedValues
+            @_setAttribute name, @mean
+          return @attributeValue
+        )
+      )
+      evaluate()
+      super()
+
+    _setAttribute: (attributeName, value) ->
+      @attributeValue = value
+      @emit attributeName, value
+
+  return plugin