Plugins¶
Before IoT Relay can do anything useful, it needs plugins. There are plugin types: source and handler. Source plugins generate data. Handler plugins handle or do something with data that source plugins produce. These definitions are intended to be open-ended. Although IoT Relay was developed with the intention of relaying time-series type data between remote sources and remote destinations, a handler could instead view each datum as an event and trigger some action. Likewise, data source plugins do not have to simply pass the data they are collecting. They may process the data in some way before making it available to interested handlers.
Available Plugins¶
iotrelay-influxdb | A handler for sending data to InfluxDB |
iotrelay-eagle | Pull data from an Eagle™ Home Energy Gateway |
iotrelay-pywws | Pull weather data from a weather station via pywws |
iotrelay-nest | Pull temperature and humidity from a Nest thermostat |
Plugin Configuration¶
Each plugin will typically have its own configuration options. All plugins share the same .iotrelay.cfg configuration file. On plugin initialization, each plugin is provided with the options contained in its section.
Each plugin must at least be represented by a section in the configuration file. If no section exists for a given plugin, it is assumed to be disabled.
Plugin section names match the plugin name. For example, the following configuration file would enable (but not necessarily configure) the iotrelay-sample-source and iotrelay-sample-handler plugins.
; ~/.iotrelay.cfg
[iotrelay]
[iotrelay-sample-source]
[iotrelay-sample-handler]
Handler plugins must list the types of readings they’re interested in.
If a reading_type
for a handler plugin is left unset, that plugin
will not receive any readings. The following example shows that the
iotrelay-sample-handler is interested in receiving weather and power
readings. Note that this handler may receive more than two time series
with this configuration. Reading type represents a category of possible
readings.
; ~/.iotrelay.cfg
[iotrelay]
[iotrelay-sample-handler]
reading types = weather, power, random
This example configuration file would cause the
iotrelay-sample-hanlder
to receive data from three reading types:
weather, power, and random. Weather and power reading types are
produced by the plugins referenced earlier: iotrelay-pywws
and
iotrelay-eagle
. Readings of type random
are produced by the
data source sample plugin shown in the next section.
Data Source Sample Plugin¶
A data source definition is a class which provides a get_reading()
method and a constructor which accepts a config
parameter. The
get_reading()
method must return one or more instances of the
Reading()
class or None. In this example, create a file called
iotrelay_sample_source.py
and enter the following code.
# source/iotrelay_sample_source.py
import random
from iotrelay import Reading
class DataSource(object):
def __init__(self, config):
self.config = config
def get_readings(self):
value = random.randint(1, 100)
return Reading(reading_type='random', value=value)
IoT Relay uses setuptools to find plugins registered in the
iotrelay
group. Data-sources should use the entry-point name
source
. The following configuration should be placed in
setup.py
and in the same directory as
iotrelay_sample_source.py
.
# source/setup.py
from setuptools import setup
setup(name='iotrelay-sample-source',
install_requires=['iotrelay'],
py_modules=['iotrelay_sample_source'],
entry_points={
'iotrelay': ['source=iotrelay_sample_source:DataSource']
}
)
Install the source plugin by typing:
$ python setup.py install
Data Handler Sample Plugin¶
Like the previous example, create a new directory with two files:
# handler/iotrelay_sample_handler.py
class Handler(object):
def __init__(self, config):
self.config = config
def set_reading(self, reading):
print(reading)
# handler/setup.py
from setuptools import setup
setup(name='iotrelay-sample-handler',
install_requires=['iotrelay'],
py_modules=['iotrelay_sample_handler'],
entry_points={
'iotrelay': ['handler=iotrelay_sample_handler:Handler']
}
)
Install the handler plugin by typing:
$ python setup.py install