We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Real Virtual Open API Specification - FIWARE Forge Wiki

Real Virtual Open API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

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,marker4,marker6,marker7,marker8,marker9,marker10,marker11,marker12,marker13,marker14,marker15,marker15,marker16,marker17,marker18,marker19]",
                            "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 such as point-of-interest(POI) 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!");
      }
}

The above JavaScript example initiates a connection to a webserver and starts handshake with following HTTP header.

REQUEST HEADER:

GET /chat HTTP/1.1
Host: REMOTEHOST
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: LOCALHOST
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13

Server MUST respond with following HTTP header or handshake fails. Notice that the Sec-WebSocket-Accept key is unique and MUST be created by server instance. Detailed instructions can be found from RFC6455.

RESPONSE HEADER:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat


API examples for service developers:

Following example show how backend services SHALL communicate between each other using HTTP GET/POST methods. OPTIONALLY other HTTP methods such as PUT and DELETE MAY be used, but they are not supported by the real virtual interaction backend deliverable.


Request all sensors with bound by a specific spatial bounds

A middleware web service SHOULD offer ways for other middleware services to specify retrievable devices by location and spatial bounds or OPTIONALLY by an IP address space. The spatial bound SHALL be either a square area with minimum and maximum values for coordinates, a circle with a centerpoint and radius or a complex shape.

Following example shows an example where POI middleware service requests all devices available within a specific circular area with a geo-coordinate center point and radius in meters.


Below is a sample code that can be used to form the following request query:

<form action="http://127.0.0.1:44446/" method="get">
<input type="hidden" name="action" value="loadById">
Device id: <input type="text" name="device_id"><br>
Maxresults: <input type="text" name="maxResults"><br>
<input type="submit" value="Submit">
</form>

Below is a sample request header as received by the real virtual interaction backend:

REQUEST HEADER:

GET /?action=loadBySpatial&lat=65.4&lon=25.4&radius=1500&maxResults=1 HTTP/1.1
Host: 127.0.0.1:44446
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

Below is a sample reponse header as send by the real virtual interaction backend.

RESPONSE HEADER:

 HTTP/1.1 200 OK
 Access-Control-Allow-Origin: * 
 Content-Type: text/plain; charset=utf-8
 Content-Length: 1767

 Connection: close
  
{
    "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,marker4,marker6,marker7,marker8,marker9,marker10,marker11,marker12,marker13,marker14,marker15,marker15,marker16,marker17,marker18,marker19]",
                        "primitive": "array"
                    }
                ]
            }
        ]
    }
}

The response header returns radius and geo-coordinates which were set by the original request query. Devices JSONArray object contains all devices matching the query. Each device MAY contain multiple sensors and actuators.


Request all data from a specific device by device UUID

A device SHOULD be considered as a micro controller board with capabilitis required to generate an 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.

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

Below is a sample code that can be used to form the following request query:

<form action="http://127.0.0.1:44446/" method="get">
<input type="hidden" name="action" value="loadBySpatial">
Latitude: <input type="text" name="lat"><br>
Longitude: <input type="text" name="lon"><br>
Radius: <input type="text" name="radius"><br>
Maxresults: <input type="text" name="maxResults"><br>
<input type="submit" value="Submit">
</form>

Below is a sample request header as received by the real virtual interaction backend. 

REQUEST HEADER:

GET /?action=loadById&device_id=440cd2d8c18d7d3a&maxResults=1 HTTP/1.1
Host: 127.0.0.1:44446
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive

Below is a sample response header as send by the real virtual interaction backend.

RESPONSE HEADER:

 HTTP/1.1 200 OK
 Access-Control-Allow-Origin: * 
 Content-Type: text/plain; charset=utf-8
 Content-Length: 1767

 Connection: close
  
 {
    "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,marker3,marker4,marker6,marker7,marker8,marker9,marker10,marker11,marker12,marker13,marker14,marker15,marker15,marker16,marker17,marker18,marker19]"
                    }
                ]
            }
        ],
        "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"
        }
    }
}

The above response shows a general description how a JSON object returned by the middleware service could look like.


Change value of a specific attribute of a sensor by ID, controller name, new value

Middleware service MUST offer a way to change state of sensors or actuators. Sensors and actuators SHOULD publish configurable parameters. Middleware services MUST send state change requests as HTTP POST calls. POST request content MUST start with action definition.

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

Below is a sample code that can be used to form the following request query:

<form action="http://127.0.0.1:44446/upload" enctype="multipart/form-data" method="post">
Device id: <input type="text" name="device_id"><br>
Choose marker to upload: <input type="file" name="datafile" size="40"></br>
<input type="submit" value="Send">

REQUEST HEADER:

POST / HTTP/1.1
Host: 127.0.0.1:44446
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Type: application/x-www-form-urlencoded
Content-Length: 92

action=update&device_id=440cd2d8c18d7d3a&sensor_id=display&parameter=viewstate&value=marker5

RESPONSE HEADER:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: * 
Content-Type: text/plain; charset=utf-8
Content-Length: 6

Connection: close

200 OK

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.

REQUEST RECEIVED BY SENSOR:

action=update&device_id=440cd2d8c18d7d3a&sensor_id=display&parameter=viewstate&value=marker5

Possible response codes from sensors

Following list includes those HTTP codes supported by the CoAP protocol. These codes SHOULD be returned by sensors or actuators if they are able. The middleware service MUST respond to all requests even if there is no response from a sensor. In such case the middleware SHALL implement time-out after which a appropriate response MUST be generated.

| Code | Description                     | Reference |
+------+---------------------------------+-----------+
| 2.01 | Created                         | [RFCXXXX] |
| 2.02 | Deleted                         | [RFCXXXX] |
| 2.03 | Valid                           | [RFCXXXX] |
| 2.04 | Changed                         | [RFCXXXX] |
| 2.05 | Content                         | [RFCXXXX] |
| 4.00 | Bad Request                     | [RFCXXXX] |
| 4.01 | Unauthorized                    | [RFCXXXX] |
| 4.02 | Bad Option                      | [RFCXXXX] |
| 4.03 | Forbidden                       | [RFCXXXX] |
| 4.04 | Not Found                       | [RFCXXXX] |
| 4.05 | Method Not Allowed              | [RFCXXXX] |
| 4.06 | Not Acceptable                  | [RFCXXXX] |
| 4.12 | Precondition Failed             | [RFCXXXX] |
| 4.13 | Request Entity Too Large        | [RFCXXXX] |
| 4.15 | Unsupported Content-Format      | [RFCXXXX] |
| 5.00 | Internal Server Error           | [RFCXXXX] |
| 5.01 | Not Implemented                 | [RFCXXXX] |
| 5.02 | Bad Gateway                     | [RFCXXXX] |
| 5.03 | Service Unavailable             | [RFCXXXX] |
| 5.04 | Gateway Timeout                 | [RFCXXXX] |
| 5.05 | Proxying Not Supported          | [RFCXXXX] |
+------+---------------------------------+-----------+
Personal tools
Create a book