Extensibility

Add SmartPlugs

In order to add a SmartPlug these are the steps to follow:

  1. Install the SmartPlug.

  2. Assign an IP to the SmartPlug.

  3. In the Virtual Machine IoToad is deployed, go to ~/toad_main/config/toad_sp_data/config.ini and edit the IP_RANGE_START < ip < IP_RANGE_STOP, so that it includes the new SmartPlug IP.

  4. Update ETCD database so that it includes MAC–>SmartPlugID mapping. In order to update it, the ETCD REST API must be used: curl http://<ip>:2379/v2/keys/smartplugs/mac_to_id/<mac-address> -XPUT -d value="<smartplug-id>". e.g. curl http://127.0.0.1:2379/v2/keys/smartplugs/mac_to_id/AC:84:C6:59:D9:A1 -XPUT -d value="sp_w.r0.c1".

Add devices

Adding a device, means to integrate the device into the current system. As the system is composed of modular components that are connected by an MQTT broker, you only need to create an agent that communicates with the device and it publishes to a specific MQTT topic where the data is stored into InfluxDB.

For fully integrating the devices with InfluxDB and its REST API, you must publish your devices data to the following MQTT topics:

data/<source-name>/influx_data/<database>

Apart from using specific topics, the published data must obey the SenML format, where:

  • BaseName+Name must be <id>/<measurement>, e.g. sp_w.r1.c1/power.

  • The id must obey <device-type>_<type><number> or <device-type>_<location-type>.r<row-number>.c<column-number>, e.g. sp_g3 or sp_w.r1.c1.

  • It is possible to create your own device and location types and use them on the IDs, e.g. alexa_x2 or alexa_y.r120.c902

Some examples:

data/sp_data/influx_data/sp

[
  {"bn":"sp_w.r1.c1/power", "u":"W","v":120.1},
]

data/sp_data/influx_data/sp

[
  {"bn":"sp_", "u":"W",},
  {"n":"w.r1.c1/power","v":1.2},
  {"n":"g7/power","v":3.4}
]

data/amazon_devices/influx_data/alexa

[
  {"bn":"echo-dot_", "u":"W",},
  {"n":"g2/power","v":1.2},
  {"n":"x.r1.c0/power","v":90.87},
]

Add API calls

We have only implemented an API for controlling the SmartPlugs and a second API for querying data from InfluxDB.

You must realize that the REST API component does not implement any logic for executing those requests, it is a dumb component that takes the API call and it transforms it into a MQTT topic and payload. So, for adding new API calls you must know how are the API calls transformed into MQTT messages, and you have to implement a component that listens to them, and returns an answer correctly.

For example, if you want to add an API that is used for querying Alexa devices rankings, such as:

  • api/out/alexa_rankings/id/echo-dot-12313?ordered=high-to-low

The api module would automatically relay the API call to MQTT formatted as:

MQTT topic: query/alexa_rankings/id/echo-dot-12313 MQTT payload:

{
    "response_topic": "responses/api/809bd939baa44f1f87fdd1099ea05a62",
    "data": {
        "ordered": "high-to-low",
    }
}

So, in order to handle the query, the new hook must listen in the MQTT topic:

  • query/alexa_rankings/#

And then:

  • Grab the information from the topic or the payload data field.

  • Perform the query: querying a database, doing some calculations, etc.

  • Return the query result, publishing a message into responses/api/809bd939baa44f1f87fdd1099ea05a62 MQTT topic.

Check api to understand how the REST API calls are transformed into MQTT messages, and MQTT to understand how MQTT messages and topics must be specified.

Add others: frameworks, databases, etc.

For adding new frameworks such as Linksmart, Fiware or any other, the best approach is to implement a component that listens to the topics where data is published, so that intercepts the data and republishes to the required framework. Also, you can listen to the topics where control commands or data queries are published.

By default, the data is solely published to Influx, so these are the topics, where your framework middleware should listen:

  • query/influx_query/#: queries to InfluxDB.

  • command/sp_command/#: commands to turn ON/OFF SmartPlugs.

  • data/sp_data/influx_data/#: data sent from SmartPlugs to InfluxDB.

  • data/+/influx_data/#: data sent from anywhere to InfluxDB.