Integration with the Geo2Tag platform

Geo2Tag is an open-source location-based service platform. It provides API for geodata (queries and filters) that are needed for deploying location-based and location-context services.

Steps for integrating the Geo2Tag platform to the IoT Hub

Development of the Geo2Tag platform plugin for the IoT

IoT Hub plugins are simple Javascript object with a set of defined functions. Here is an example for an hello world plugin which requires to be be configured:

Hello world plugin example
      
var HelloWorldPluginConfiguration = { 
  needConfiguration: true,
  checkConfiguration: function(data) { 
    var config = JSON.parse(data);
    if (typeof(config.name) !== 'string') { return false; } 
    return true; 
  },
  configure: function(config) {
    if (this.checkConfiguration(config)) {
      var config = JSON.parse(data);
      var name = config.name;
      this.config = { name: name }; 
    }
  },
  isFeatureSupported: function(name) { return typeof(this.config) !== "undefined"; },
  isFeatureAvailable: function(name) { return isFeatureSupported(name); },
  isFeatureReadable: function(name) { return isFeatureSupported(name); },
  isFeatureWritable: function(name) { return false; },
  getNumberOfFeatures: function() { return 1; },
  postFeatureValue: function(name, data) { return false; },
  getFeatureDescription: function(index) {
    if (index == 0) { 
      return JSON.stringify({name: "message", type: "string"});
    } else {return null;}
  },
  getFeatureValue: function (name) {
    if (!isFeatureSupported(name) || name !== "message") { return null; }
    return JSON.stringify('Hello ' + this.config.name);
  }
};

The functions that need to be available for an IoT Hub plugin are:

needConfiguration: a variable that defines if the plugin requires to be configured. In the case of the Geo2Tag plugin, this will be set to true.
checkConfiguration: a function that takes a JSON parsable param that checks whether or not the input configuration is valid. Must return a boolean.
configure: a function that takes a JSON parsable param that applies the configuration to the running instance of the plugin. In the case of Geo2Tag, we need the url of the Geo2Tag platform.
getNumberOfFeatures: a function that returns the number of features provided by the plugin. This function will be only called when the plugin would have been configured.
getFeatureDescription: a function that returns the IoT data type description of the feature provided by the plugin. As the Geo2Tag and the IoT Hub use jsonschema for their data type definition. The plugin could either use the IoT hub data format or add to the IoT Hub the schema provided by the Geo2Tag platform. This function will be only called when the plugin would have been configured.
isFeatureSupported: a function that returns if the feature is supported on the current IoT platform. This function will be only called when the plugin would have been configured.
isFeatureAvailable: a function that returns if the feature is available on the current IoT platform. This function will be only called when the plugin would have been configured.
isFeatureReadable: a function that returns if the feature is readable on the current IoT platform. This function will be only called when the plugin would have been configured.
isFeatureWritable: a function that returns if the feature is writable on the current IoT platform. This function will be only called when the plugin would have been configured.
getFeatureValue: a function that returns the content provided by the feature if the feature is available and readable. This function will be only called when the plugin would have been configured.
postFeatureValue: a function that post content provided to the feature if the feature is available and writable. This function will be only called when the plugin would have been configured.

In the case of the Geo2Tag plugin, the configuration includes the JSON Web Signature to enable to Google OAuth 2.0 authentication of the plugin to the Geo2Tag platform and then listing the features available via a GET request on either //channel for the channels, //service for the services

Deploying the Geo2Tag plugin in the IoT Hub

Deploying the plugin on the IoT Hub platform is easy and can be done with POST /plugins

Data
      
{
  "plugin": "Geo2Tag",
  "type": "iothub",
  "file": a base64 string of the Geo2Tag plugin,
  "isService": false
}

Configuring the Geo2Tag plugin via the Hub enabler

Create an enabler for the plugin via the REST API: POST /enablers

Data
      
{
  "plugin": Geo2TagPluginId,
  "configuration": the configuration of the Geo2Tag plugin for this enabler
}

Exposing Geo2Tag features as IoT Hub atomic feeds

Once the GeoTag enabler has been created in the IoT Hub, the hub admin can expose the selected features of the plugin via the hub REST API. It requires just a simple POST request to the IoT Hub API POST /enablers/${enabler_id}/feature/${feature_name}/atomic

The function will return the description of the created atomic feed for the feature ${feature_name} of the enabler ${enabler_id}. If it did not exist, the atomic feed will be created

Interacting with Geo2Tag via the IoT Hub API

The Hub users can interact with the Geo2Tag platform via the created atomic feeds if they have the necessary permissions to do so

Solmuhub