Live Objects
Boost your IoT potential ! Live Objects manages your objects , collects, stores, secures and processes your IoT data.

To go deeper...

You can find all resources and documentation (Dev guide, Swagger, video tutorials….) for Live Objects here and ask us questions here.

Getting Started Guide

This getting started guide will help you to send your first data payload to Live Objects (LO), and retrieve data from it. You will find all the informations needed in the following points :

Create a Live Objects account

Before doing anything, you must create a Live Objects account. To do that you just need to go there : Live Objects subscription. You simply have to fill the form and send it. Live Objects team will answer you if your demand is validated and finalize your subscription.

Create an API Key

Once you have your account, you must create an API key. The API key is the only way given to access to LO in the range of roles that it belongs to. To create a new API key, go to Configuration panel (LO interface), and select Api keys, on the menu at your left. Click on Add button, and then fill the form. The API key will be shown to you in a panel in two types : a QR code and an alpha-numeric value that you can copy. Find informations about all the roles : API Key Roles.

NOTE CARREFULLY :

  • Keep your API key somewhere (securely) to be sure to retrieve it if you want later. Because for security, LO won't show it again, once you will close the panel.
  • You can use the same API Key for two (or more) devices.

Configure Namespace/Id of your LO device

A LO device is an entity managed by LO which represents (and is linked to) your physical connected object. It is uniquely identified by a couple namespace/id.
In the Devices panel (LO interface), you can add a new device to LO by clicking on the Add device button.

Note : the definition of the both (namespace and id) is up to you.

Examples :

    * Namespace : Mydevice1, Id : 22-11-20-16  
    * Namespace : 001, Id : myID
    * Namespace : identifier, Id : identifier

There is no special structure for them. But they must be unique in your fleet of devices on LO (the namespace and the id, can even have the same value if you want to use them like that, but it is not a good habit). With the prefix urn:lo:nsid and the namespace/id you get a client ID which is (according to the previous examples) :

Examples :

    * Client ID :  urn:lo:nsid:Mydevice1:22-11-20-16   
    * Client ID :  urn:lo:nsid:001:myID  
    * Client ID :  urn:lo:nsid:identifier:identifier

But with MQTT interface, you just have to put your configurations (see next point) in your connected device (during programming). At your first connection, LO will automatically create and add the device corresponding.

Configure your connected object

This point is done out of LO interface, in your IDE, according to the language that you choose, once you have already configured your LO device. It is done while programming your connected object.
You have to configure your object with these configurations to make it access LO services by MQTT interface in device mode :

  • Address Broker : liveobjects.orange-business.com
  • Port Broker : 1883
  • Connection protocol : tcp://
  • Client Id : urn:lo:nsid:putYourNameSpace:putYourId
  • User Name : json+device (it's the ''device mode'' , see here for more informations)
  • Secret Code : enter the API Key you have just created
  • QoS : 0

Refer to MQTT documentations adapted to the language you use, to know how to configure your object.

Note : the complete broker url is : tcp://liveobjects.orange-business.com:1883

Send data payload to Live Objects

To store data collected by your connected device, they must be sent to the topic dev/data. You can store data by both interfaces : MQTT and REST interfaces (see the Swagger for REST API). MQTT is suitable for devices, while REST is best for server-server communications.
Data are sent in JSON format, and must match the following structure :

{
   "s":  "<<streamId>>",
   "ts": "<<timestamp>>",
   "m":  "<<model>>",
   "v": {
          ... <<value>> JSON objects ...
   },
   "t" : [<<tag1>>,<<tag2>>,...]
   "loc": [<<latitude>>, <<longitude>>]
}
  • streamId : identifier of the timeseries this message belongs to,
  • timestamp : data/time (UTC) associated with the message, is ISO 8601 format,
  • model : a string identifying the schema used for the "value" part of the message, to avoid conflict at data indexing,
  • value : a free JSON object describing the collected information,
  • tags : list of strings associated to the message to convey extra-information,
  • latitude, longitude : details of the geo location associated with the message (in degrees),

NB : the latitude values are between [-90, 90], and longitude ones between [-180, 180].

Example : Data about temperature, humidity, and GPS position, and the place (city.NYC) where we got them.

{
   "s":   "mydevice!temp16",
   "ts":  "2016-12-01T12:15:02Z",
   "m":   "tempV1",
   "loc": [45.4535, 4.5032],
   "v": {
      "temp":     12.75,
      "humidity": 62.1,
      "gpsFix":   true,
      "gpsSats":   [45.4535, 4.5032, 21]
   },
   "t" : [ "City.NYC", "Model.Prototype" ]
}

All data sent to LO at dev/data topic can be managed with Elasticsearch.

==>Do not pay attention to the concordance between the Location and GPS values in Examples. They are fake.

Business Application

Your Business application can access all LO services (devices list, data, configuration..) within REST API. See the Swagger. To communicate with Live Objects, and access to the differents LO services, your Business Application just need an API key, no necessary different from key used for one of your devices.
In the two following points we will see some Business Application fonctions : how to retrieve your stored data from you devices fleet, and how to explore your data through Elasticsearch.

Retrieve data from Live Objects

You can retrieve all data stored by your device through your business application. But note that : data can only be retrieved, or explored by REST interface. To do that you need:
1- an API key for your business application (like we did before for your connected device),
2- the stream used to store the data you want to get,
3- the maximum number of result (limited to 1000), and
1- the time range of data stored.
See the Swagger at section Data management data store : APIs to store and retrieve data and read the Get method.

Example : Retrieving two last results stored under streamID "mydevice!temp16".

  • Curl code :

      curl -X GET --header 'Accept: application/json' --header 'X-API-KEY: PutYourAPIKeyHere' 
      'https://liveobjects.orange-business.com/api/v0/data/streams/TemperaturePerZoneNew?limit=2'
    
  • Request URL :

      https://liveobjects.orange-business.com/api/v0/data/streams/
      mydevice!temp16?limit=2
    
  • Response Body :

      [
        {
          "id": "5853c4c60cf272057fa0d2d9",
          "streamId": "mydevice!temp16",
          "timestamp": "2016-01-01T14:00:02Z",
          "location": {
            "lat": 80,
            "lon": 62
          },
          "model": "tempV1",
          "value": {
            "temp": 12.75,
            "humidity": 62.1,
            "gpsFix": true,
            "gpsSats": [
              80,
              62,
              21
            ]
          },
          "tags": [
            "City.NYC",
            "Model.Prototype"
          ],
          "metadata": {
            "source": "urn:lo:nsid:Demo17:Rapido2017"
          },
          "created": "2016-12-16T10:41:10.467Z"
        },
        {
          "id": "5853ecb80cf272057fa46a0c",
          "streamId": "mydevice!temp16",
          "timestamp": "2016-01-01T12:15:02Z",
          "location": {
            "lat": 42,
            "lon": 70.43
          },
          "model": "tempV1",
          "value": {
            "temp": 12.75,
            "humidity": 62.1,
            "gpsFix": true,
            "gpsSats": [
              42,
              70.43,
              21
            ]
          },
          "tags": [
            "City.NYC",
            "Model.Prototype"
          ],
          "metadata": {
            "source": "urn:lo:nsid:Demo17:Rapido2017"
      },
      "created": "2016-12-16T13:31:36.389Z"
      }
    

    ]

Make Queries for Elasticsearch (ELS) on your data

Live Objects integrates Elasticsearch which permits you to do researches into your data. You can find here tutorial about Elasticsearch query structure. To make a query for the LO Elasticsearch, you need an API key (no need to be new) and the body of your query. See the Elasticsearch manual.

Example: the query gives you the two last results (sorted by date), without any distinction, of all the data stored under streamID "mydevice!temp16".

  • Elasticsearch query :

      {
          "size" : 2,
          "query" :
          {
                  "term" : { "streamId": "mydevice!temp16" }
          },
          "aggs" :{}
      }
    
  • Curl code :

      curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-API-KEY: PutYourAPIKeyHere' -d '{ \ 
           "size" : 2, \ 
           "query" : \ 
           { \ 
                   "term" : { "streamId": "mydevice!temp16" } \ 
           }, \ 
           "aggs" : \ 
           { \ 
            } \ 
       }' 'https://liveobjects.orange-business.com/api/v0/data/search/hits'
    
  • Response body :

              {
        "took": 5,
        "hits": {
          "total": 4,
          "hits": [
            {
              "_source": {
                "metadata": {
                  "source": "urn:lo:nsid:Demo17:Rapido2017"
                },
                "streamId": "mydevice!temp16",
                "created": "2016-12-16T10:40:43.205Z",
                "location": {
                  "lon": 80,
                  "lat": 62
                },
                "model": "tempV1",
                "id": "5853c4ab0cf272057fa0d0a7",
                "value": {
                  "humidity": 62.1,
                  "gpsFix": true,
                  "temp": 12.75,
                  "gpsSats": [
                    80,
                    62,
                    21
                  ]
                },
                "timestamp": "2016-01-01T14:00:02Z",
                "tags": [
                  "City.NYC",
                  "Model.Prototype"
                ]
              }
            },
            {
              "_source": {
                "metadata": {
                  "source": "urn:lo:nsid:Demo17:Rapido2017"
                },
                "streamId": "mydevice!temp16",
                "created": "2016-12-16T10:40:18.633Z",
                "location": {
                  "lon": 42,
                  "lat": 70.43
                },
                "model": "tempV1",
                "id": "5853c4920cf272057fa0cfcb",
                "value": {
                  "humidity": 62.1,
                  "gpsFix": true,
                  "temp": 12.75,
                  "gpsSats": [
                    42,
                    70.43,
                    21
                  ]
                },
                "timestamp": "2016-01-01T12:15:02Z",
                "tags": [
                  "City.NYC",
                  "Model.Prototype"
                ]
              }
            }
          ]
        }
      }