Mapping device payload to standardized Vorto Function Blocks

IoT Devices may not always send their data to the cloud in the structure and protocol that is required by the IoT platform that the devices are integrating with, e.g. AWS IoT, Azure IoT or Eclipse IoT. Eclipse Vorto provides the tools and libraries for you to achieve that.

In this tutorial you are going to learn, how you create a Vorto Mapping Specification that maps a Distance Sensor JSON payload to standardized IPSO Vorto Function Blocks and execute the mapping specification with the Vorto Mapping Engine. You will integrate the Distance Sensor payload with the Eclipse Ditto Digital Twin service but also learn how to extend the Vorto Mapping Engine to map to other IoT platforms.

Prerequisite

1. Create a Payload Mapping Specification

In this step, we are going to create a mapping specification for the Distance Sensor, that maps a very simple distance JSON payload to IPSO compliant data representation that can be immediately processed by the Eclipse Ditto Service.

For example, the Distance Sensor sends the following JSON payload:

{"distance": "100m"} 

Let’s take this example and create a mapping specification for it:

  1. In the Vorto Repository, click the Create Model Button and select Mapping.
  2. Enter a name, for example DistancePayloadMapping.
  3. Adjust the entries for the input fields Namespace and Version, if necessary.
  4. Click Create.
  5. In the Model Editor add the following mapping rules and click Save:


    > Source Code

You may have spotted, that we are using a set of different xpath functions to define the mapping rule. You can find more information about all available functions and how to use them in the Function Reference Documentation

Create another mapping to correlate it to the Distance Sensor:

Up to now, we have merely created a specification for the payload of the distance data. Now, we must assign it to the actual Distance Sensor Device Information Model:

  1. In the Vorto Repository, click the Create Model Button and select Mapping.
  2. Enter a name, for example DistanceSensorPayloadMapping
  3. Adjust the entries for the input fields Namespace and Version, if necessary.
  4. Click Create.
  5. In the Model Editor add add the following mapping rules and click Save:

    > Source Code

3. Execute the Payload Mapping

Now, let’s process the mapping specification with the Vorto Mapping Engine. The Mapping Engine performs a two-phase mapping:

Phase 1 (Normalization): Maps the arbitrary device payload to standardized Vorto Function Block payload.

Phase 2 (Target Platform Mapping): Maps the Vorto Function Block payload to the target IoT platform - specific data model.

The Vorto Mapping Engine supports Eclipse Ditto as the target platform mapping out-of-the-box. However, we will show you later, how can you easily plug in your own IoT platform data model mapper (see appendix).

  1. First, add the following Maven dependency to your Maven Project:

    <dependency>
       <groupId>org.eclipse.vorto</groupId>
       <artifactId>mapping-engine-all</artifactId>
       <version>${vorto.version}</version>
    </dependency>
    
  2. Download the Mapping Specification via the Payload Mapping Specification Editor in the Vorto Repository

  3. Code snippet that transforms a sample Distance Sensor JSON to Eclipse Vorto/Eclipse Ditto compliant data:

    //load mapping specification from inputstream, e.g. classpath
    MappingEngine engine = MappingEngine.createFromInputStream(is);
    
    String sampleDevicePayload = "{\"distance\": \"100m\"}";
    
    InfomodelData mappedResult mappingEngine.map(DataInput.newInstance().fromJson(sampleDevicePayload));
    
    System.out.println(mappedResult.toJson());
    
  4. The console shows the following mapped result:

    {
        "distance":{
                "status":{
                    "sensorValue": 100,
                    "sensorUnits": "m"
                }
        }
    }
    

4. Test the integration

We are now ready to send the mapped JSON payload and modify an Eclipse Ditto managed thing:

 curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
            "distance":{ \
                "properties":{ \ 
                    "status":{ \ 
                        "sensorValue":100, \ 
                        "sensorUnits":"m" \ 
                    } \ 
                } \ 
            } \ 
        }' 'https://ditto.eclipse.org/api/1/things/org.eclipse.vorto.tutorial%3distancesensor/features'

Voila! Your digital twin of the Distance Sensor is now stored as standardized data, described as Vorto Function Blocks.