vorto-metamorph v0.11.0

Mapping arbitrary JSON to Vorto JSON Spec

Vorto allows application developers to create IoT solutions without having to customize their code to deal with the variety of json sent by different kinds of IoT devices. So a temperature reading from a toaster or an aircon will always have the same structure. Vorto achieves this by defining a semantic which abstracts device data using Function Blocks.

Sounds interesting, check out the Eclipse Vorto project here.

The package is an effort to making it easier for developers to map arbitrary device json into vorto compliant json structure.

Installation

npm install vorto-metamorph

Example Scenario

I want to create a cool mobile app which shows room temperature. The challenge is there are a wide range of connectable temperature sensors available in the market and my app should be able to work with most of them. A perfect scenario for using Vorto.

To test my setup I bought a connectable temperature sensor, unfortunately it only reads in Fahrenheit. I am not going to change my application code to adjust to this json format, I will just map it to the desired json format.

Device JSON:

{
  "temperature" : "82.4f"
}

Desired Vorto compliant JSON structure:

{
  "temperature": {
    "status": {
      "sensorValue": "28"
    }
  }
}

Prerequisite

To work through this tutorial, you will need:

• BoschID Account or GitHub to log in to Vorto Repository
• A Vorto Information Model, for your IoT device
• You are a collaborator/owner of a namespace

Step 1: Create Mapping Specification

Mapping adds device specific information to an Information Model. Since the representation of data can vary from one device to another, we will create a mapping specification to standardize the data.

To create a mapping go to your newly created model and press the Create Mapping Spec Button.

Now add a Mapping key to uniquely identify your mapping to the device it belongs to, like acme_temperature_monitor (connected temperature sensor from Acme Corporation).

Click Create and the web editor opens allowing you to add mapping expression for the Function Blocks you added. You can write XPath 3.1 like notation. Behind the scenes the engine uses fotonxpath to apply XPath expressions on the DOM created using the device json. To add functionality that may not be possible using xpath alone, you can also use/create custom JavaScript functions (courtesy fotonxpath) . Once you have written your xpath expressions, press Save.

Custom function to convert Fahrenheit to Celsius and round-off to two decimal places.

Step 2: Test the Mapping Specification

On the right hand-side, define the device payload(in JSON format) and click Map:

Satisfied with the results, save it.

Step 3: Download & Execute Mapping Specification

Download it to use with our nodejs library:

Usage

const VortoMapper = require("vorto-metamorph")

const vortoMapper = new VortoMapper();

const rawPayload = {
    "temperature": "82.4f"
};

const mappingSpec = {}; // copy the downloaded mapping spec

vortoMapper.setMappingSpec(mappingSpec);
vortoMapper.transform(rawPayload);

Registering Custom Functions

To register user defined functions for the mapping, we will leverage on the functionality provided by fontoxpath. Note the additional parameter 'dynamicContext' which needs to be added as the first parameter of the function.

vortoMapper.registerCustomXPathFunction(
    'temperature:fToC',
    ['xs:string'], 'xs:string',
    function fToC(dynamicContext, fahrenheit) 
    {
          var fTemp = fahrenheit.substr(0, fahrenheit.length -1);
          var cel = (fTemp - 32) * 5 / 9;
          return Math.round(cel * 100) /100;
    }
);

Debug Logs

The library internally uses loglevel npm package. To enable debug level logs set the corresponding log level.

vortoMapper.setLogLevel("debug");