RealVirtualInteraction

DATE: 07 Sep 2015
This version:
http://polls.apiblueprint.org/v01
Previous version:
http://polls.apiblueprint.org/NA
Latest version:
http://polls.apiblueprint.org/latest

Editors

All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the publisher, except in the case of brief quotations embodied in critical reviews and certain other noncommercial uses permitted by copyright law. For permission requests, write to the publisher, addressed “Attention: Permissions Coordinator,” at the address below.


Abstract

This specification defines the RealVirtualInteraction API.

Status of this document

This is completed API for virtual Interaction.

This specification is licensed under the FIWARE Open Specification License.


RealVirtualInteraction

Real Virtual Interaction generic enabler (GE) provides means for connecting real world devices consisting of sensors and actuators in to augmented or virtual reality applications. Since the real world sensors and actuators are not complex enough to contain necessary logic to publish themselves outside their immediate domain there needs to be a external service that is able to access these devices and to be able to share the access to other services and also directly to end-users. This service provides security, data base for storing history and offline data, scalability and other cloud-like features that make it easier for application and service developers to make use of the devices in various purposes. This GE also provides a practical prototype for publishing sensor and actuator information application developers derived from NGSI 9/10 format developed earlier in FIWARE.

This GE will provide two APIs for accessing sensors or actuators:

  • API for service developers
  • API for application developers

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. The key word REMOTEHOST can be replaced by either IP address or DNS host name. Also port number for middleware service can differ from IANA standard which is 80 for the WebSocket and 8080 for HTTP. The key words GET,POST,PUT and DELETE are http methods and appear capitalized each time they occur in the specifications.

Security implementations are not included in this specifications as they are highly dependable on type of middleware service and chosen security level. For controlled public access api-keys or session-ids could be used. Alternatively for private access login information could be included in queries.

API examples for device application developers

The Realvirtualinteraction backend will listen to incoming UDP packets and will drop packets that do not conform to the RESTful data format specification (version 1.0). The payload string MAY be Gzip compressed.

Below JSON string is an example how the device developers should public sensor/actuator information to the server. The "dataformat_version" field will be removed after the packet is being received by the server and will not be passed on to possible clients subscribed listening for incoming events. For instance the existing logic could be extended to include other fields such as API-KEY to ensure that only registered devices may publish to server. This could be the first step to add a layer of security.

{  
  "dataformat_version":"1.0",
  "d23c058698435eff":{  
    "d23c058698435eff":{  
      "sensors":[  
        {  
          "value":{  
            "unit":"uT",
            "primitive":"3DPoint",
            "time":"2014-02-19 09:40:06",
            "values":[  
              17.819183349609375,
              0.07265311479568481,
              -0.4838427007198334
            ]
          },
          "configuration":[  
            {  
              "interval":"ms",
              "toggleable":"boolean"
            }
          ],
          "attributes":{  
            "type":"orientation",
            "power":0.5,
            "vendor":"Invensense",
            "name":"MPL magnetic field"
          }
        },
        {  
          "value":{  
            "unit":"uT",
            "primitive":"3DPoint",
            "time":"2014-02-19 09:40:06",
            "values":[  
              17.819183349609375,
              0.07265311479568481,
              -0.4838427007198334
            ]
          },
          "configuration":[  
            {  
              "interval":"ms",
              "toggleable":"boolean"
            }
          ],
          "attributes":{  
            "type":"gyroscope",
            "power":0.5,
            "vendor":"Invensense",
            "name":"MPL magnetic field"
          }
        },
        {  
          "value":{  
            "unit":"uT",
            "primitive":"3DPoint",
            "time":"2014-02-19 09:40:06",
            "values":[  
              17.819183349609375,
              0.07265311479568481,
              -0.4838427007198334
            ]
          },
          "configuration":[  
            {  
              "interval":"ms",
              "toggleable":"boolean"
            }
          ],
          "attributes":{  
            "type":"magneticfield",
            "power":0.5,
            "vendor":"Invensense",
            "name":"MPL magnetic field"
          }
        },
        {  
          "value":{  
            "unit":"m/s2",
            "primitive":"3DPoint",
            "time":"2014-02-19 09:40:06",
            "values":[  
              0.006436614785343409,
              0.003891906701028347,
              -0.5983058214187622
            ]
          },
          "configuration":[  
            {  
              "interval":"ms",
              "toggleable":"boolean"
            }
          ],
          "attributes":{  
            "type":"linearacceleration",
            "power":1.5,
            "vendor":"Google Inc.",
            "name":"Linear Acceleration Sensor"
          }
        }
      ],
      "actuators":[  
        {  
          "configuration":[  
            {  
              "value":"100",
              "unit":"percent",
              "name":"viewsize"
            }
          ],
          "actions":[  
            {  
              "value":"[marker1,marker2,marker3]",
              "primitive":"array",
              "unit":"string",
              "parameter":"viewstate"
            }
          ],
          "callbacks":[  
            {  
              "target":"viewstate",
              "return_type":"boolean"
            }
          ],
          "attributes":{  
            "dimensions":"[480,800]"
          }
        }
      ],
      "attributes":{  
        "name":"Android device"
      }
    }
  }
}

API examples for application developers

Following code and header samples enable a real-time connection over TCP/IP to be formed with a server application. Once a connection is established, sensor events MAY be pushed to clients from server in real-time. The connection is full-duplex meaning that also a client MAY send messages directly to sensors in through a web server. This sort of full-duplex connection MAY be considered as publish/subscribe type of connection where client MAY choose which sensor to subscribe to receive event updates from. The web service SHALL provide the client a list of available sensors or OPTIONALLY a client MAY use third party service to find sensors. WebSocket SHOULD be then used to form direct connection to the sensors through a IoT Broker type of web server component.

JavaScript client sample:

function CreateWebSocket() {
    if ("WebSocket" in window) {
     ws = new WebSocket("ws://REMOTEHOST");

     ws.onopen = function() {
       alert("Connection established to web server");
     };
     ws.onmessage = function (evt) {
       alert("Message received from web server: " + evt.data); 
     };
     ws.onclose = function() {
        alert("Connection is closed...");
     };
  }
  else {
     alert("WebSocket NOT supported by your Browser!");
  }
}

API Specification

API for Service developers

Following shows how backend services SHALL communicate between each other using HTTP GET/POST methods.

loadBySpatial [/?action=loadBySpatial&lat={lat}&lon={lon}&radius={radius}&maxResults={maxResults}]

loadBySpatial can be used for requestuesting all sensors within specific spatial bounding area. geo-coordinate center point and radius in meters.

Parameters
lat (Required, Center latitude)
lon (Required, Center longitude)
radius (Required, Search circle radius)
maxResults (Required, Max number of search results)

loadById [/?action=loadById&device_id=440cd2d8c18d7d3a&maxResults=1]

loadById is used for requesting sensor data based on the device uuid. A device MAY contain any number of sensors and actuators, and in any combination. If the requested sensor or actuator does not have uuid the request MUST target the device containing the desired sensor or actuator.

Load sensor by Id - GET /?action=loadById&device_id=440cd2d8c18d7d3a&maxResults=1

Example shows how a middleware service retrieves all available information regarding a specific device by using an uuid string identifier.

Response 200 (application/json)

update [/?action=update&device_id={device_id}&sensor_id=display&parameter={parameter}&value={value}]

update HTTP POST method can be used for changing updatable sensor values. Real virtual interaction backend uses the device_id parameter and looks up the IP address from reference table and passes only the content of the query forward to the particular sensor. If an IP address is found from the reference table, the server will respond with 200 OK without actually knowing whether the message reached its destination as the transport mechanism is UDP. Otherwise server will respond with 404 NOT FOUND.

Parameters
device_id (Required, )
parameter (Required, string)
Parameter to be updat
value (Required, string)
new value

Update device by Id - POST /?action=update&device_id={device_id}&sensor_id=display&parameter={parameter}&value={value}

Example shows how to use HTTP POST request to turn change augmented reality marker on an Android application remotely.

Response 200

Examples

API for Service developers

loadBySpatial [/?action=loadBySpatial&lat={lat}&lon={lon}&radius={radius}&maxResults={maxResults}]

Parameters
lat (Required, Center latitude)
lon (Required, Center longitude)
radius (Required, Search circle radius)
maxResults (Required, Max number of search results)

Load sensors by spatial search - GET /?action=loadBySpatial&lat={lat}&lon={lon}&radius={radius}&maxResults={maxResults}

Response 200 (application/json)

Headers

Content-Type: application/json

Body

[
    {
        "8587cdb9a135fa2a": {
            "sensors": [
                {
                    "values": [
                        {
                            "unit": "lx",
                            "time": "2014-02-17 14:35:53",
                            "values": 58.607452,
                            "primitive": "double"
                        }
                    ],
                    "attributes": {
                        "vendor": "Sharp",
                        "name": "GP2A Light sensor",
                        "power": 0.75,
                        "type": "light"
                    },
                    "configuration": [
                        {
                            "interval": "ms",
                            "toggleable": "boolean"
                        }
                    ]
                },
                {
                    "values": [
                        {
                            "unit": "uT",
                            "time": "2014-02-17 14:35:53",
                            "values": [
                                10.400009155273438,
                                -16.688583374023438,
                                -37.505584716796875
                            ],
                            "primitive": "3DPoint"
                        }
                    ],
                    "attributes": {
                        "vendor": "Invensense",
                        "name": "MPL Magnetic Field",
                        "power": 4,
                        "type": "magneticfield"
                    },
                    "configuration": [
                        {
                            "interval": "ms",
                            "toggleable": "boolean"
                        }
                    ]
                },
                {
                    "values": [
                        {
                            "unit": "hPa",
                            "time": "2014-02-17 14:35:53",
                            "values": 989.56,
                            "primitive": "double"
                        }
                    ],
                    "attributes": {
                        "vendor": "Bosch",
                        "name": "BMP180 Pressure sensor",
                        "power": 0.6700000166893005,
                        "type": "pressure"
                    },
                    "configuration": [
                        {
                            "interval": "ms",
                            "toggleable": "boolean"
                        }
                    ]
                }
            ],
            "attributes": {
                "name": "Android device"
            },
            "actuators": [
                {
                    "callbacks": [
                        {
                            "target": "viewstate",
                            "return_type": "boolean"
                        }
                    ],
                    "attributes": {
                        "dimensions": "[720,1184]"
                    },
                    "configuration": [
                        {
                            "unit": "percent",
                            "name": "viewsize",
                            "value": "100"
                        }
                    ],
                    "actions": [
                        {
                            "unit": "string",
                            "parameter": "viewstate",
                            "value": "[marker1,marker2,marker3,]",
                            "primitive": "array"
                        }
                    ]
                }
            ]
        }
    }
]

loadById [/?action=loadById&device_id=440cd2d8c18d7d3a&maxResults=1]

Load sensor by Id - GET /?action=loadById&device_id=440cd2d8c18d7d3a&maxResults=1

Response 200 (application/json)

Headers

Content-Type: application/json

Body

[
    {
        "440cd2d8c18d7d3a": {
            "actuators": [
                {
                    "configuration": [
                        {
                            "unit": "percent",
                            "name": "viewsize",
                            "value": "100"
                        }
                    ],
                    "callbacks": [
                        {
                            "return_type": "boolean",
                            "target": "viewstate"
                        }
                    ],
                    "attributes": {
                        "dimensions": "[480,800]"
                    },
                    "actions": [
                        {
                            "unit": "string",
                            "primitive": "array",
                            "parameter": "viewstate",
                            "value": "[marker1,marker2,marker13]"
                        }
                    ]
                }
            ],
            "sensors": [
                {
                    "configuration": [
                        {
                            "toggleable": "boolean",
                            "interval": "ms"
                        }
                    ],
                    "values": {
                        {
                            "unit": "rads",
                            "primitive": "3DPoint",
                            "values": [
                                21.117462158203125,
                                -0.9801873564720154,
                                -0.6045787930488586
                            ],
                            "time": "2013-12-10 10:07:30"
                        }
                    },
                    "attributes": {
                        "vendor": "Invensense",
                        "name": "MPL Gyro",
                        "power": 0.5,
                        "type": "gyroscope"
                    }
                },
                {
                    "configuration": [
                        {
                            "toggleable": "boolean",
                            "interval": "ms"
                        }
                    ],
                    "values": {
                        {
                            "unit": "ms2",
                            "primitive": "3DPoint",
                            "values": [
                                149.10000610351562,
                                420.20001220703125,
                                -1463.9000244140625
                            ],
                            "time": "2013-12-10 10:07:30"
                        }
                    },
                    "attributes": {
                        "vendor": "Invensense",
                        "name": "MPL accel",
                        "power": 0.5,
                        "type": "accelerometer"
                    }
                },
                {
                    "configuration": [
                        {
                            "toggleable": "boolean",
                            "interval": "ms"
                        }
                    ],
                    "values": {
                        {
                            "unit": "uT",
                            "primitive": "3DPoint",
                            "values": [
                                -0.08577163517475128,
                                0.16211289167404175,
                                9.922416687011719
                            ],
                            "time": "2013-12-10 10:07:30"
                        }
                    },
                    "attributes": {
                        "vendor": "Invensense",
                        "name": "MPL magnetic field",
                        "power": 0.5,
                        "type": "magneticfield"
                    }
                },
                {
                    "configuration": [
                        {
                            "toggleable": "boolean",
                            "interval": "ms"
                        }
                    ],
                    "values": {
                        {
                            "unit": "orientation",
                            "primitive": "3DPoint",
                            "values": [
                                -0.004261057823896408,
                                -0.017044231295585632,
                                0.019174760207533836
                            ],
                            "time": "2013-12-10 10:07:30"
                        }
                    },
                    "attributes": {
                        "vendor": "Invensense",
                        "name": "MPL Orientation (android deprecated format)",
                        "power": 9.699999809265137,
                        "type": "orientation"
                    }
                }
            ],
            "attributes": {
                "name": "Android device"
            }
        }
    }
]

update [/?action=update&device_id={device_id}&sensor_id=display&parameter={parameter}&value={value}]

Parameters
device_id (Required, )
parameter (Required, string)
Parameter to be updat
value (Required, string)
new value

Update device by Id - POST /?action=update&device_id={device_id}&sensor_id=display&parameter={parameter}&value={value}

Response 200

References