Messages data model

Summary

Live Objects platform relies on message processing to provide services such as data storage, event detection, and device management. Messages are ingested via HTTPS APIs and MQTT(S), and can be viewed or delivered through the web portal and webhooks. Understanding the platform’s message models is essential to build business use cases.

In Live Objects, a data message carries data sent by devices over supported network connectors (HTTPS, MQTT(S), LoRa®, SMS, …). These messages are stored and may be processed by other services. The data message format is the platform’s standard internal representation for storage, search, processing, and routing; even if devices publish connector-specific payloads, Live Objects normalizes them before storage.

This chapter provides an overview of the supported models:

Refer to the dedicated sections for detailed schemas and field semantics.

By default, and without message routing, messages are stored in the standard format. When you need to deliver them to a business application or trigger notifications, use the message routing service. In that case, the delivered payload is extended with routing metadata (e.g., rule context, target, delivery info).

The detailed routed message format is described in the Message routing chapter and is not covered here.

Stored data message

Summary

When the devices publish the messages, they are processed by the data transformation and then the data analysis services, they will be stored according to output formats depending on the connectivity and the applied process. Consumers can access them through API requests.

Interactive
Figure 1. Data journey of unrouted data message.

Depending on your connectivity interface, the data message model stored in Live Objects may have a dedicated sections to describe the parameters of your datas'.

dataMessageid:StringstreamId:Stringmodel:Stringversion:Intcreated:Datetimestamp:DatetagsEnum[]valueJson object: {"any_field": "any_value",.....}If the device publishesan encoded datamessage, see thedecoding sectionto learn more aboutencoded payloads.metadataconnector:Stringsource:Stringencoding:String- The metadata section is providedbyEnrichment process..extraJson object: {"any_field": "any_value",.....}groupid:Stringpath:Stringtransformationpipeline:Stringdecoder:Stringpublished:StringcellularGeoloc:Stringdeviceprovider:"static"alt:Floatlon:Floatlat:FloatIf the device have astatic location.networkEx : some parameters of LoRa® network----------------------------devEUI:Stringport:Intfcnt:IntmissingFcnt:Intrssi:Doublesnr:Doubleesp:Doublesf:Intfrequency:DoublesignalLevel:Intack:BoolmessageType:Stringroaming: : {   "operatorNetId":String,   "operatorName":String,}gatewayCnt:intbestGatewayId:Stringgateways:List<GatewayLora>batteryLevel:Intlocation provided by network: {   "alt": 0,   "accuracy": 10000,   "lon": 2.314306,   "lat": 48.853233}depending on your connectivity :the network provides theconnectivity informations LoRa® network informationsMQTT connections informationsSMS network informationslocationprovider:Stringaccuracy:Intalt:Floatlon:Floatlat:FloatSee priority rules aboutassigned "location".
Figure 2. Stored data message object model overview.

The Data message is a JSON object. Please find below a description of its fields.

Field Description

type

dataMessage. This field is set by Live Objects in the routed Data message. In the store/search section, this field is not set.

version

Version number. See the existing versions in the summary. In the store/search section, this field is not set.

streamId

String identifying a timeseries /stream. Enriched by default if not set. Should not contain following characters: ' " \ ; { } ( ) and ' ' (space).

timestamp

Timestamp associated with the collected information. Generally set by the device, enriched by default if not set. Should follow ISO-8601 date time format.

created

Timestamp reflecting the date on which the data was collected by Live Objects.

location

Geo location (lat, lon, alt, accuracy, provider) associated with the declared and/or collected location infos.

model

String used to indicate which schema is used for the value part of the message, more about model field. Can be empty, but can not contains ' ' (space) or '.' (dot) character.

value

Structured representation (JSON object) of the transported info. This field is usually filled with the useful payload (device measurements). Be a JSON object (not a primitive like number or string). Do not contains field name with '.' (dot) character. Size in bytes can not exceed 1 MiB (1024*1024 bytes).

tags

List of strings associated with the message. Used for extra-information.

extra

Enriched by Live Objects and can contains device inventory information like device’s properties.

metadata

Section enriched by Live Objects.

* source: unique identifier of the device, usually the URN (urn:lo:nsid:<namespace>:<id>) * group: group to which the device belongs, defined by its id and its path * connector: lora, mqtt, …​ * network: information from the network, depends on the connector
When the LoRa® device send message to Live Objects, the network set timestamp value and when the message is processed by Live Objects, it set the created field value by his own timer. Live Objects does not process messages according to the chronological order of transmission (timestamp value set by the network provider timestamp) but according to the order of processing (created value set by Live objects).

LoRa® output

Data Message example : Original message sent by device through LoRa® interface

payload sent by device :

e17aae4133333942bc8b0100

stored data after decoding :

{
  "metadata": {
    "source": "urn:lo:nsid:lora:4883C7DF3001114B",
    "encoding": "siconia_temperature_humidity_pressure",
    "group": {
        "path": "/",
        "id": "root"
    },
    "device": {
      "location": {
        "provider": "static",
        "lon": 2.545599,
        "lat": 48.82198
      }
    },
    "network": {
      "lora": {
        "rssi": -110,
        "esp": -111.76,
        "ack": false,
        "fcnt": 27517,
        "devEUI": "20635F0108000C8D",
        "frequency": 868.5,
        "signalLevel": 5,
        "gatewayCnt": 5,
        "sf": 10,
        "messageType": "UNCONFIRMED_DATA_UP",
        "port": 10,
        "snr": 3,
        "location": {
          "provider": "lora",
          "alt": 0,
          "accuracy": 10000,
          "lon": 2.526197,
          "lat": 48.83361
        },
        "roaming" : {
            "operatorNetId": "600031",
            "operatorName": "Stratis IoT"
        },
        "missingFcnt": 0
      }
    }
  },
  "streamId": "urn:lora:20635F0108000C8D!uplink",
  "created": "2021-05-30T19:02:46.789Z",
  "extra": {
    "_outdoor_source_alt_lat_lon",
  },
  "location": {
    "provider": "static",
    "alt": null,
    "accuracy": null,
    "lon": 2.545599,
    "lat": 48.82198
  },
  "model": "lora_v0",
  "id": "60b3e15603b409370d2d2b10",
  "value": {
    "payload": "e17aae4133333942bc8b0100",
    "temperature": 21.81,
    "humidity": 46.3,
    "pressure": 1013.08
  },
  "timestamp": "2021-05-30T19:02:46.161Z",
  "tags": []
}

LoRa® network signal infos

The LoRa® decoded message contains the additional fields added by Live Objects enrichment logic. The network section in the LoRa® decoded message (metadata.network) will be enriched by adding the parameter values collected by network. Here is the description of specific fields (network infos) of LoRa® decoded message :

Parameter (field) Description Notes

SNR

The "Signal Noise Ratio" provides an indication on the level of perturbations compare to the signal itself received by the field gateway.

A bad value of SNR may indicates that the device is in a perturbed environment (for example industrial machines that produce high level of electromagnetic radiations), or that the power of the signal is simply too weak to overcome the ambiant noise. A bad SNR is very likely to cause frame loss.

We consider these typical values for SNR:

  1. bad < -13

  2. average [-13 ; -9]

  3. good > -9

RSSI

The "Received Signal Strength Indication" indicates the strength of the "raw signal" that is to say the signal who contains the util information plus the background noise and the interferences due to the transmission.

It is used to estimate if a device is close or not to a gateway and to automatically adapt the data rate for a best compromise between signal quality and battery consumption. So that a strong RSSI is not necessarily better. It has to be considered globally.

We consider these typical values for RSSI:

  1. weak< -115

  2. average [-115 ; -95]

  3. strong > -95

ESP

The "Estimated Signal Power" represents the strength of the useful signal. Basically it can be considered as a measurement of how well a receiver can “hear” a signal from a sender.

It is computed based on the RSS and the SNR with the formula:

ESP=RSSI-10×log(1+10(--SNR10))

We consider these typical values for RSSI:

  1. weak< -110

  2. average [-110 ; -100]

  3. strong > -100

It’s not necessary to have a strong ESP if the level of SNR is low. The signal will be well received but could be more sensible on the environment changes.

SF

The "Spreading Factor" represents the "effort" that a device do to send a message.

If it is useful for a device to use the highest SF (12) when JOINing to maximize the chance to be heared by a gateway, it is better further to use the lowest SF as possible to save the battery . The network server tells automatically to the device to set the appropriate SF depending on the power of the received signal (RSSI).

Minimum SF is 7, maximum is 12.

gatewayCnt

It is the number of LoRa gateway who "heard" the message sent by the device. It is an indicator of network coverage.

It’s better for reliability to have a space redundancy :

> 1 and even

> 3 for a more precise geolocation

signalLevel

This value is a "Signal level" computed from last uplink.

It’s an Orange computation based on previous indicators to estimate the overall quality of the signal on a scale from 1 (very poor) to 5 (very good).

roaming

Field provided if the message is transmitted by a foreign operator network

operatorNetId : Unique identifier of the operator

operatorName : Optional Name of the operator

In practice:

In most cases the network will pilot the device to automatically adapt the strength of the transmission depending on the radio conditions to keep the best compromise between quality and battery saving. This mechanism is called the Adaptative Data Rate (ADR).

Actions who can improve bad communications would be:

  1. Improve Network coverage by adding local gateways

  2. Improve environment or isolate the device from noise if possible

  3. Improve the device: The quality of the antenna is crucial !

LoRa® device battery infos

In some cases, LoRa® devices may publish their battery level if the device supports it, 2 ways are then possible :

  • Using the standard Lorawan mechanism: The device publishes the batterie level in a devStatusAns frame. This frame is published in response to a devStatusAns issued by the network. The lora core network on which Live Objects relies sends a devStatusAns only every week, and the battery level is added into the Live Objects data message (metadata.network.lora.batteryLevel) only if the next payload sent by the device is not empty. Otherwise the battery information is not retrieved by Live Objects.

Datamessage sample:
{
  "metadata": {
    "source": "urn:lo:nsid:lora:4883C7DF3001114B",
    "encoding": "siconia_temperature_humidity_pressure",
    "group": {
        "path": "/",
        "id": "root"
    },
    "device": {
      "location": {
        "provider": "static",
        "lon": 2.545599,
        "lat": 48.82198
      }
    },
    "network": {
      "lora": {
        "rssi": -110,
        "esp": -111.76,
        "ack": false,
        "fcnt": 27517,
        "devEUI": "20635F0108000C8D",
        "frequency": 868.5,
        "signalLevel": 5,
        "gatewayCnt": 5,
        "sf": 10,
        "messageType": "UNCONFIRMED_DATA_UP",
        "port": 10,
        "snr": 3,
        "batteryLevel": 53, --> The value is collected by network and enriched in the datamessage
        "location": {
          "provider": "lora",
          "alt": 0,
          "accuracy": 10000,
          "lon": 2.526197,
          "lat": 48.83361
        },
        "missingFcnt": 0
      }
    }
  },
  "streamId": "urn:lora:20635F0108000C8D!uplink",
  "created": "2021-05-30T19:02:46.789Z",
  "extra": {
    "_outdoor_source_alt_lat_lon",
  },
  "location": {
    "provider": "static",
    "alt": null,
    "accuracy": null,
    "lon": 2.545599,
    "lat": 48.82198
  },
  "model": "lora_v0",
  "id": "60b3e15603b409370d2d2b10",
  "value": {
    "payload": "e17aae4133333942bc8b0100",
    "temperature": 21.81,
    "humidity": 46.3,
    "pressure": 1013.08
  },
  "timestamp": "2021-05-30T19:02:46.161Z",
  "tags": []
}

  • Passing the information into the payload itself (field value.payload of the Live Objects datamessage). In this case a decoder is necessary to extract the information from the hexadecimal sequence

Datamessage sample:
{
  "metadata": {
    "source": "urn:lo:nsid:lora:4883C7DF3001114B",
    "encoding": "siconia_temperature_humidity_pressure",
    "group": {
        "path": "/",
        "id": "root"
    },
    "device": {
      "location": {
        "provider": "static",
        "lon": 2.545599,
        "lat": 48.82198
      }
    },
    "network": {
      "lora": {
        "rssi": -110,
        "esp": -111.76,
        "ack": false,
        "fcnt": 27517,
        "devEUI": "20635F0108000C8D",
        "frequency": 868.5,
        "signalLevel": 5,
        "gatewayCnt": 5,
        "sf": 10,
        "messageType": "UNCONFIRMED_DATA_UP",
        "port": 10,
        "snr": 3,
        "location": {
          "provider": "lora",
          "alt": 0,
          "accuracy": 10000,
          "lon": 2.526197,
          "lat": 48.83361
        },
        "missingFcnt": 0
      }
    }
  },
  "streamId": "urn:lora:20635F0108000C8D!uplink",
  "created": "2021-05-30T19:02:46.789Z",
  "extra": {
    "_outdoor_source_alt_lat_lon",
  },
  "location": {
    "provider": "static",
    "alt": null,
    "accuracy": null,
    "lon": 2.545599,
    "lat": 48.82198
  },
  "model": "lora_v0",
  "id": "60b3e15603b409370d2d2b10",
  "value": {
    "payload": "e17aae4133333942bc8b0100",
    "temperature": 21.81,
    "humidity": 46.3,
    "pressure": 1013.08
    "CustomBatteryLevel": 52, --> The value is published by device in the payload and readable only after decoding
  },
  "timestamp": "2021-05-30T19:02:46.161Z",
  "tags": []
}

MQTT output

Data Message example : Original message sent by device or published by business application through MQTT interface

payload sent by device :

{
   "value" : {
      "revmin":9992,
      "CO2":683,
      "doorOpen":false,
      "hygrometry":45,
      "temperature":139,
      "pressure":1367
  },
   "location":{
      "provider":"GPS",
      "lon":2.30886,
      "lat":48.81839
   }
}

stored data :

{
  "metadata": {
    "connector": "mqtt",
    "source":"urn:lo:nsid:mqtt:12345",
    "transformation": {
      "published": {
        "location": {
          "provider": "GPS",
          "lon": 2.30886,
          "lat": 48.81839
        }
      }
    },
    "group": {
      "path": "/",
      "id": "root"
    },
    "network": {
      "mqtt": {
        "clientId":"<my_mqtt_client_id>"
      }
    }
  },
  "streamId":"urn:lo:nsid:mqtt:12345",
  "created": "2021-06-17T09:21:54.377Z",
  "extra": {
    "propertyDevice1":"12:1b:2e"
  },
  "location": {
    "provider": "GPS",
    "lon": 2.30886,
    "lat": 48.81839
  },
  "id": "60cb14322b9f5a61388d3b3b",
  "value": {
    "revmin": 9992,
    "CO2": 683,
    "doorOpen": false,
    "hygrometry": 45,
    "temperature": 139,
    "pressure": 1367
  },
  "timestamp": "2021-06-17T09:21:54.372Z",
  "tags": []
}

binary payload sent by device :

2101120000011006

stored data after decoding :

{
   "metadata": {
      "connector": "mqtt",
      "source": "urn:lo:nsid:mySensor:11",
      "encoding": "decoder_microtracker_v1.0",
      "device": {
        "location": {
            "provider": "static",
            "alt": 12,
            "lon": 164.7337728,
            "lat": 80.8596736
        }
      },
      "group": {
         "path": "/Binary devices",
         "id": "41Uo8K"
      },
      "network": {
         "mqtt": {
            "clientId": "urn:lo:nsid:mySensor:11"
         }
      }
   },
   "streamId": "urn:lo:nsid:mySensor:11",
   "created": "2020-09-11T12:33:17.465Z",
   "extra": {
      "GPS : DOWN": "GEO_CELLULAR : DOWN"
   },
   "location": {
        "provider": "static",
        "alt": 12,
        "accuracy": null,
        "lon": 164.7337728,
        "lat": 80.8596736
   },
   "model": "my_microtracker_v1",
   "id": "5f5b6e8db112b210b85e4012",
   "value": {
      "messageType": "TRACKER_HEARTBEAT",
      "payload": "32313031313230303030303131303036",
      "battery": {
         "energyLevel": 49,
         "charging": false,
         "unmeasurable": false
      },
      "trackerMode": "CLASSIC"
   },
   "timestamp": "2020-09-11T12:33:17.450Z",
   "tags": []
}
The binary payload sent by device will be generated as hexBinary type, see MQTT binary data push.

SMS ouput

Data Message example : Original message sent by device through SMS interface

payload sent by device :

{<<my payload>>}

stored data :

{
   "metadata": {
      "connector": "sms",
      "source": "urn:lo:nsid:sms:331010101",
      "group": {
         "path": "/",
         "id": "root"
      },
      "network": {
         "mobile": {
            "serverPhoneNumber": "20406",
            "msisdn": "331010101",
            "contentType": "TEXT"
         }
      }
   },
   "streamId": "urn:lo:nsid:sms:331010101",
   "created": "2019-08-27T12:29:27.655Z",
   "extra": {},
   "location": null,
   "model": "sms_v0",
   "id": "5d652227a1a7e80da8b4635e",
   "value": {
      "payload": "{<<my payload>>}"
   },
   "timestamp": "2019-08-27T12:29:22Z",
   "tags": []
}

binary payload sent by device :

056096850001010500020700

stored data after decoding :

{
   "metadata": {
      "connector": "sms",
      "source": "urn:lo:nsid:sms:mySensor",
      "encoding": "my_decoder_tracker_v1.3",
      "group": {
         "path": "/binary_devices",
         "id": "An4NOl"
      },
      "network": {
         "mobile": {
            "serverPhoneNumber": "20259",
            "msisdn": "337000003040131",
            "contentType": "BINARY"
         }
      }
   },
   "streamId": "urn:lo:nsid:sms:mySensorData",
   "created": "2020-09-09T10:00:25.696Z",
   "extra": {},
   "location": null,
   "model": "mySensor_v5",
   "id": "5f58a7b9b112b277cb82d34d",
   "value": {
      "adt": "UNUSED",
      "bleFirmwareVersion": "2.7.0",
      "messageType": "HEARTBEAT",
      "payload": "303536303936383530303031303130353030303230373030",
      "temperature": {
         "unit": "°C",
         "value": 23.28
      },
      "ack": 0,
      "deviceModel": "mySensor_v5",
      "resetCause": "POWER-ON-RESET",
      "battery": {
         "unit": "V",
         "valueFirmwarePrev15": 3.39,
         "value": 3.62,
         "inCharge": false
      },
      "firmwareVersion": "1.5.0",
      "status": {
         "onDemand": false,
         "appState": "idle",
         "userAlert": false,
         "periodic": false,
         "moving": false,
         "appMode": "motionStartEndTrack"
      }
   },
   "timestamp": "2020-09-09T10:00:21Z",
   "tags": []
}

Bulk injection output

Data Message example : Original message published through HTTP interface

data push payload :

   {
      "revmin":9992,
      "CO2":683,
      "doorOpen":false,
      "hygrometry":45,
      "temperature":139,
      "pressure":1367
   }

stored data :

{
   "metadata": {
      "connector": "http"
   },
   "streamId": "urn:lo:nsid:sensor:2327398!measures",
   "created": "2020-06-09T15:18:58.050Z",
   "extra": null,
   "location": null,
   "model": "data_model_v1",
   "id": "5edfa862682ee74e3e297595",
   "value": {
      "revmin": 9992,
      "CO2": 683,
      "doorOpen": false,
      "hygrometry": 45,
      "temperature": 139,
      "pressure": 1367
   },
   "timestamp": "2020-06-09T15:18:58.033Z",
   "tags": []
}

Alarm output

Depending on the type of alarm activated, Live Objects store a second output message which is an additional message that describes the rules that triggered the alarm.

For more information about the IoT device and data alarming service, read.

Matching rule output

Fired Event data representation

To learn more about Simple event alarm see.

{
  "tenantId": "String",
  "timestamp": "String",
  "firingRule": {
    // The originating firing rule
  },
  "matchingContext": {
    "tenantId": "(String) the id of the tenant",
    "timestamp": "(String) iso-8601 timestamp of the originating matching event",
    "matchingRule": {
      // the originating matching rule
    },
    "data": {
      // the data message that triggered the matching rule and the firing rule
    }
  }
}
storedDataMessageid:StringtenantId:Stringtimestamp:DatetagsEnum[]valueJson object:{"any_field": "any_valueField",.....}matchingContexttenantId:Stringtimestamp:DatefiringRuleid:Stringname:StringmatchingRuleid:Stringname:StringextraJson object:{"any_field": "any_valueField",.....}datatype:Stringversion:StringstreamId:Stringtimestamp:Datemetadatasource:Stringconnector:Stringgroupid:Stringpath:Stringlocationprovider:Stringalt:Floataccuracy:Intlon:Floatlat:Floatdevicetransformationnetwork
Figure 3. Output Fired Event data model.

Fired event object model description:

tenantId

String the tenant that issued the fired event,

timestamp

iso-8601 formatted timestamp, representing the date of emission of the fired event,

firingRule

The firing rule that triggered the event,

matchingContext.tenantId

String the tenant that issued the upstream matching event,

matchingContext.timestamp

ISO-8601 timestamp of the upstream matching event,

matchingContext.matchingRule

The rule that triggered the upstream matching event,

matchingContext.data

The Data Message that triggered the event chain,

State rule output

To learn more about State event alarm see.

State Changed Event data structure
{
  "stateKey": "String",
  "previousState": "String",
  "newState":  "String",
  "timestamp": "ISO-8601 Date Strin"g,
  "stateProcessingRuleId": "String",
  "data": "xref:lo_manual/messages-model/adoc/stored_data_msg.adoc#DATANEWMODEL[Data Message]"
}
storedDataMessageid:StringtenantId:StringstateKey:StringpreviousState:StringnewState:Stringtimestamp:DatestateProcessingRuleId:StringtagsEnum[]valueJson object:{"any_field": "any_valueField",.....}stateProcessingRuleid:Stringname:StringextraJson object:{"any_field": "any_valueField",.....}datatype:Stringversion:StringstreamId:Stringtimestamp:Datemetadatasource:Stringconnector:Stringgroupid:Stringpath:Stringdevicetransformationnetworklocationprovider:Stringalt:Floataccuracy:Intlon:Floatlat:Float
Figure 4. Output State Event data model.

State event object model description:

stateKey

The state key value,

previousState

Name of the previous state of the stateKey,

newState

Name the new state of the stateKey,

timestamp

ISO-8601 timestamp of the state change event,

stateProcessingRuleId

id of the rule that generated this state change event,

data

the Data Message that triggered the state change,

Activity rule output

To learn more about Activity event alarm see.

Activity Event data structure.
{
  "deviceId": "String",
  "deviceAdditionalInfo": {
      "deviceName": "String",
      "groupPath": "String"
  },
  "activityRule": "ActivityRule",
  "state":  "String 'SILENT' or 'ACTIVE'",
  "numberOfAlarmReminders": "Integer",
  "timestamp": "ISO-8601 Date String"
}
storedDataMessagedeviceid:Stringstate:StringnumberOfAlarmReminders:Inttimestamp:DateactivitygRuleid:Stringname:Stringenabled:Booltimestamp:DatetargetdeviceAdditionalInfodeviceName:StringgroupPath:StringsilentPolicyduration:TimerepeatInterval:TimegroupPaths[{"path":String,","includeSubPath":Bool...}]
Figure 5. Output State Event data model.

Activity event object model description:

deviceId

Id of the device triggering this activity event

deviceAdditionalInfo

Additional information on the device. Consists of the name of the device and the path of the group it belongs to.

activityRule

ActivityRule triggering this activity event

state

Current state of device, either 'SILENT' or 'ACTIVE'

numberOfAlarmReminders

The number of times a reminder has been sent for the current state.

timestamp

ISO-8601 timestamp of the state change event

Location infos

Device location data in Live Objects is based on the information reported by the published messages, by the data communicated by the network, by Live Objects data processing steps (Decoders, Custom Pipelines), but it can also be declared as a static location when provisioning each device.

The location field in each dataMessage (IOT data) is optional, but when ordered according the timestamp of the dataMessage, it is possible to track the successive locations of the device in time.

Location JSON format section

When the location data is present in the message, it is structured in a location section according to the following format:

   "location": {
      "provider": "lora",
      "alt": 0,
      "accuracy": 10000,
      "lon": 2.314306,
      "lat": 48.853233
   },
Field Description

provider

optional. This field indicates the origin of the provided location data. Can be set by device, by network (enrichment process), by decoder, or by custom pipeline (External Enricher).

alt

optional. Altitude measurement value.

accuracy

optional. Accuracy is the tendency of the measurements to agree with the true value.

lon

mandatory. Longitude measurement value.

lat

mandatory. Latitude measurement value.

The structured data of the location in the location fields makes it possible to standardize the processing of this information:

  • By using the geolocation aggregation to build various aggregates of the devices.

  • To display the last known position of the device in a map (Live Objects portal), by taking the last message sent by the device.

  • To display tracking information, by using location data associated with the message timestamps.

See more about the datamodel and location section above.

Static device location (provisioned)

The static location can be added in the device representation. Cf. device representation with the staticLocation section.

This section can be added or updated on an existing device by using:
PATCH /api/v1/deviceMgt/devices/<myDeviceId>
 {
    "id": "<myDeviceId>",
    "description": "Device 123",
    "name": "My Device",
    "staticLocation": {
        "lat": <<Latitude value>>,
        "lon": <<Longitude value>>,
        "alt": <<Altitude value>>
    }
}

Once defined, the static location will also be collected in the stored datamessage after enrichment.

Also, it can be "chosen" as the last kwnown location of a device. In this case, it will be set in the "location" field of a data message. (Cf. Chapter "Assigned location values").

The static location is used to locate the LoRa® gateways in order to optimize the installation and the activation of devices.

Input datamessage
{
    "value": {
        "temperature" : 14.6,
        "battery" : 53,
        "messageAlert":"low battery"
    },

    "location": {
        "lat": 48.86667,
        "lon": 2.33333,
        "alt": 35.2,
        "accuracy": 12.3,
        "provider": "My_embedded_GPS"
    },
    "tags": [ "production", "Orange Live Objects" ]
}
Output datamessage
{
  "metadata": {
    "connector": "mqtt",
    "source": "urn:lo:nsid:my_device",
    "transformation": {
      "published": {
        "location": {
          "provider": "My_embedded_GPS",
          "alt": 35.2,
          "accuracy": 12.3,
          "lon": 2.33333,
          "lat": 48.86667
        }
      }
    },
    "device": {
      "location": {
        "provider": "static",
        "alt": 12,
        "lon": 164.7337728,
        "lat": 80.8596736
      }
    },
    "group": {
      "path": "/",
      "id": "root"
    },
    "network": {
      "mqtt": {
        "clientId": "urn:lo:nsid:my_device"
      }
    }
  },
  "streamId": "urn:lo:nsid:my_stream",
  "created": "2021-06-01T08:02:56.240Z",
  "extra": {
    "_outdoor_source_alt_lat_lon": "appAndroid;48.8737361;2.3610431;83.42344672858451",
    "_indoor_source_building_floor_room": "how to save"
  },
  "location": {
    "provider": "static",
    "alt": 12,
    "accuracy": null,
    "lon": 164.7337728,
    "lat": 80.8596736
  },
  "model": null,
  "id": "60b5e9b08f85ad1604f37662",
  "value": {
    "temperature": 14.6,
    "messageAlert": "low battery",
    "battery": 53
  },
  "timestamp": "2021-06-01T08:02:56.234Z",
  "tags": [
    "production",
    "Orange Live Objects"
  ]
}
Disable enriched staticLocation values in your device data messages

When you need to use realtime tracking without staticLocation values as last known location, you must delete staticLocation section from your device representation:

PATCH /api/v1/deviceMgt/devices/<myDeviceId>
 {
    "id": "<myDeviceId>",
    "description": "Device 123",
    "name": "My Device",
    "staticLocation": {
    }
}
The staticLocation section must be null and removed from the device representation to disable the consideration of the staticLocation section during processing.

Device‑published location

Those location data is directly provided by the device, and published into the device payload, two message formats are available:

  • unencoded datamessage contains a location section

  • encoded datamessage contains a location section but readable only after decoding.

Unencoded datamessage

Example of published payload
{
    "streamId": "urn:lo:nsid:test:my_device",
    "value": {
        "temperature" : 14.6,
        "battery" : 53,
        "messageAlert":"low battery"
    },
    "location": {           <-- Location data provided by device
        "lat": 48.86667,
        "lon": 2.33333,
        "alt": 35.2,
        "accuracy": 12.3,
        "provider": "My_embedded_GPS"
    },
    "tags": [ "production", "Orange Live Objects" ]
}
Stored datamessage after transformation
{
  "metadata": {
    "connector": "mqtt",
    "source": "urn:lo:nsid:my_device:test",
    "transformation": {
      "published": {
        "location": {
          "provider": "My_embedded_GPS",
          "alt": 35.2,
          "accuracy": 12.3,
          "lon": 2.33333,
          "lat": 48.86667
        }
      }
    },
    "group": {
      "path": "/",
      "id": "root"
    },
    "network": {
      "mqtt": {
        "clientId": "urn:lo:nsid:my_device:test"
      }
    }
  },
  "streamId": "urn:lo:nsid:test:my_device",
  "created": "2021-05-27T13:28:10.376Z",
  "extra": {},
  "location": {                                 <-- Assigned location data
    "provider": "My_embedded_GPS",
    "alt": 35.2,
    "accuracy": 12.3,
    "lon": 2.33333,
    "lat": 48.86667
  },
  "model": null,
  "id": "60af9e6a03b409370dbb1a24",
  "value": {
    "temperature": 14.6,
    "messageAlert": "low battery",
    "battery": 53
  },
  "timestamp": "2021-05-27T13:28:10.371Z",
  "tags": [
    "production",
    "Orange Live Objects"
  ]
}

Encoded datamessage

decoded datamessage
{
  "messageType": "TRACKER_POSITION",
  "triggerEvent": "TRACKER_MODE",
  "location": {                  <-- Location data provided by device after payload decoding
    "accuracy": 57,
    "lon": 164.7337728,
    "lat": 80.8596736
  },
  "battery": {
    "energyLevel": 51,
    "charging": false,
    "unmeasurable": false
  },
  "trackerMode": "CLASSIC",
  "status": {
    "wifiFailure": true,
    "bleFailure": true,
    "gpsFailure": false
  }
}
Output datamessage
{
  "metadata": {
    "connector": "mqtt",
    "source": "urn:lo:nsid:bike:test9",
    "encoding": "abeeway_microtracker_v1.0",
    "transformation": {
      "decoder": {
        "location": {
          "provider": "device",
          "accuracy": 57,
          "lon": 164.7337728,
          "lat": 80.8596736
        }
      }
    },
    "group": {
      "path": "/",
      "id": "root"
    },
    "network": {
      "mqtt": {
        "clientId": "urn:lo:nsid:bike:test9"
      }
    }
  },
  "streamId": "urn:lo:nsid:bike:test9",
  "created": "2021-05-29T15:12:49.577Z",
  "extra": {},
  "location": {                                 <-- Assigned location data
    "provider": "device",
    "alt": null,
    "accuracy": 57,
    "lon": 164.7337728,
    "lat": 80.8596736
  },
  "model": "model_abeeway_microtracker_v1",
  "id": "60b259f103b409370d05a98d",
  "value": {
    "messageType": "TRACKER_POSITION",
    "payload": "3333666530343065363937303962633561656361313435396330323836326530623063633139613831633437373061633638613337383730323562306163",
    "triggerEvent": "TRACKER_MODE",
    "location": {
      "accuracy": 57,
      "lon": 164.7337728,
      "lat": 80.8596736
    },
    "battery": {
      "energyLevel": 51,
      "charging": false,
      "unmeasurable": false
    },
    "trackerMode": "CLASSIC",
    "status": {
      "wifiFailure": true,
      "bleFailure": true,
      "gpsFailure": false
    }
  },
  "timestamp": "2021-05-29T15:12:49.543Z",
  "tags": []
}

Network‑derived location: LoRa®

The device’s location is determined using a triangulation algorithm that utilizes RSSI information from the gateways that received the last uplink.

For LoRa® devices and after enrichment process, the output data message has a network section which contains :

{
  "metadata": {
    "connector": "lora",
    "source": "myStream",
    "encoding": "myDecoder",
    "group": {
      "path": "/my_Sub_Group",
      "id": "O1WpwY"
    },
    "network": {
      "lora": {
        "rssi": -32,
        "esp": -32.54,
        "ack": false,
        "fcnt": 27657,
        "bestGatewayId": "FF020693",
        "devEUI": "70B03000B03GT5",
        "frequency": 867.9,
        "signalLevel": 5,
        "gatewayCnt": 5,
        "sf": 12,
        "messageType": "UNCONFIRMED_DATA_UP",
        "port": 3,
        "snr": 8.75,
        "location": {                 -->(Location data provided by network)
          "provider": "lora",
          "alt": 0,
          "accuracy": 10000,
          "lon": 2.295066,
          "lat": 48.798023
        },
        "missingFcnt": 0
      }
    }
  },
  "streamId": "myStream",
  "created": "2021-04-24T21:49:09.056Z",
  "extra": {},
  "location": {                       -->(Location data assigned after enrichment process)
    "provider": "lora",
    "alt": 0,
    "accuracy": 10000,
    "lon": 2.295066,
    "lat": 48.798023
  },
  "model": "myDecoder",
  "id": "608492558ea8f0470434318f",
  "value": {
    "payload": "039b86028e0801671a",
    "temperature": {
      "unit": "°C",
      "currentTemperatures": [
        {
          "value": 22.4375,
          "timestamp": "2021-04-24T21:36:18.758Z"
        }
      ]
    },
    "humidity": {
      "unit": "%",
      "currentHumidity": [
        {
          "value": 26,
          "timestamp": "2021-04-24T21:36:18.758Z"
        }
      ]
    },
    "battery": {
      "level": {
        "unit": "%",
        "value": 61
      }
    }
  },
  "timestamp": "2021-04-24T21:49:08.758Z",
  "tags": [
    "hygrometry",
    "temperature",
    "indoor"
  ]
}
Here is the datamessage value when the staticLocation is set in the device representation
{
  "metadata": {
    "connector": "lora",
    "source": "myStream",
    "encoding": "myDecoder",
    "device": {
      "location": {                 -->(Location data configured on device)
        "provider": "static",
        "lon": 3.545599,
        "lat": 48.82198
      }
    },
    "group": {
      "path": "/my_Sub_Group",
      "id": "O1WpwY"
    },
    "network": {
      "lora": {
        "rssi": -109,
        "esp": -110.19,
        "ack": false,
        "fcnt": 26316,
        "bestGatewayId": "FF020693",
        "devEUI": "70B03000B03GT5",
        "frequency": 867.9,
        "signalLevel": 5,
        "gatewayCnt": 3,
        "sf": 7,
        "messageType": "UNCONFIRMED_DATA_UP",
        "port": 10,
        "snr": 5,
        "location": {
          "provider": "lora",
          "alt": 0,
          "accuracy": 5000,
          "lon": 2.529708,
          "lat": 48.831375
        },
        "missingFcnt": 0
      }
    }
  },
  "streamId": "myStream",
  "created": "2021-04-24T21:49:09.056Z",
  "extra": {},
  "location": {
    "provider": "static",
    "alt": null,
    "accuracy": null,
    "lon": 3.545599,
    "lat": 48.82198
  },
  "model": "lora_v0",
  "id": "608492558ea8f0470434318f",
  "value": {
    "payload": "32a8"
  },
  "timestamp": "2021-05-26T13:13:53.760Z",
  "tags": []
}

Location provided by an external transformation

Custom pipeline can by used to perform an enrichment on location data. The behavior of this custom pipeline can perform a replacing location data by the location value contained in the response according the defined pipeline override rules.

Two type of steps are available can be used to resolve location coordinates from the input data published by the device or provided by other sources.

"Externaltransformation" step

Applied on location field, this external transformation, can be used to override the root location.

Depending on your location value override rule, this resolved value can override the last main location of a DataMessage assigned by previous processing. Also, It can be used to enrich the datamessage without override the main location previously assigned.

Priority location

Assigned location values

The assigned location of a DataMessage represents the location selected by Live Objects after the DataMessage has been processed by the data enrichment process, decoding, and custom pipelines. Then it will be assigned to the root of a DataMessage in the end.

As seen above, several sources can collect location values (staticLocation, device or network). Therefore, it becomes necessary to set the root "location" of a DataMessage according to a priority rule.

In output datamessage, the location infos are assigned in the location attribute, in the case of a lot of location providers, only one value is assigned in the location under the following priority rules :

  1. Custom infos manually set by an External Enricher

  2. staticLocation values (if present)

  3. location section values extracted after a message decoding (if the decoding service successfully decode message and the message contains a valid location section)

  4. Published location in the message by the device

  5. location section provided by the network

To retrieve the provided location values, here is the metadata section :

Field Description

location

The assigned location. This field (root location) indicates the location infos assigned by Live Objects.

metadata.device.location

optional. This field indicates the location provided by the device (the static location).

metadata.transformation.published.location

optional. This field, if present, contains the location infos published by the device.

metadata.transformation.decoder.location

optional. This field, if present, contains the infos published by the device after payload decoding.

metadata.network.lora.location

optional. This field, if present, contains the location infos provided by the network.
In the case where the datamessage contains a multiple location values, then the user can choose the "best" for its use case.

Location values processing

The datamessage journey includes the processing of location values step by step and involves several components. For each component, the location value is processed and then enriched in the datamessage:

Interactive
Figure 6. Assigned location by priority (viewing the position of the device on the map).

At the end and before the datamessage storage, the root location is assigned according to the rule specified and described above.

Location providers

Reserved providers

This providers are set in the output datamessage depending on the source: device or by the network.

Possible values : static, device, lora

Custom providers

When the device or an external transformation gives the location value, the provider becomes free: the device (or a customer) can set this value in the datamessage as need.

Location data retention

In the case of a multiple location data sources all the values are kept in the output datamessage, depending on the enrichment and transformation process rules, the root location is assigned by the prioriy location rule, the other values are retained in the datamessage and stored as metadata.

Input message published by the device
{
  "temperature": 14.6,
  "messageAlert": "low battery",
  "battery": 53,
  "location": {
          "provider": "My_embedded_GPS",
          "alt": 35.2,
          "accuracy": 12.3,
          "lon": 2.33333,
          "lat": 48.86667
        }
}
Stored datamessage
{
  "metadata": {
    "connector": "mqtt",
    "source": "urn:lo:nsid:my_stream",
    "transformation": {
      "pipeline": {
        "success": true,
        "id": "60af8cd2fb240421ed158b34"
      },
      "external": {
        "location": {
          "provider": "custom",
          "alt": null,
          "accuracy": 412,
          "lon": 2.2938888888888886,
          "lat": 48.80138888888889
        }
      },
      "published": {
        "location": {
          "provider": "My_embedded_GPS",
          "alt": 35.2,
          "accuracy": 12.3,
          "lon": 2.33333,
          "lat": 48.86667
        }
      },
    },
    "device": {
      "location": {
        "provider": "static",
        "alt": 12,
        "lon": 164.7337728,
        "lat": 80.8596736
      }
    },
    "group": {
      "path": "/",
      "id": "root"
    },
    "network": {
      "mqtt": {
        "clientId": "urn:lo:nsid:my_device"
      }
    }
  },
  "streamId": "urn:lo:nsid:my_stream",
  "created": "2021-05-31T14:09:18.750Z",
  "extra": {
    "_outdoor_source_alt_lat_lon": "appAndroid;48.8737361;2.3610431;83.42344672858451",
    "_indoor_source_building_floor_room": "how to save"
  },
  "location": {
    "provider": "custom",
    "alt": null,
    "accuracy": 412,
    "lon": 2.2938888888888886,
    "lat": 48.80138888888889
  },
  "model": null,
  "id": "60b4ee0e8f85ad1604e5c9d5",
  "value": {
    "temperature": 14.6,
    "messageAlert": "low battery",
    "battery": 53
  },
  "timestamp": "2021-05-31T14:09:17.911Z",
  "tags": [
    "production",
    "Orange Live Objects",
    "Location with external enricher"
  ]
}
field Content

location

To retrieve assigned data location (provider= custom according the priority rule)

metadata.device.location

To retrieve static location (provider=static).

metadata.transformation.device.location

To retrieve published location (provider=device).

metadata.transformation.external.location

To retrieve resolved location (provider=custom).

Using location information

  • Latest location by device

  • Geo circle/box queries

  • Provider-based filtering and accuracy thresholds

  • Tracking

Last known location

You can retrieve the last known location from the stored datamessages by using the inventory explorer, here is the example uses the RSQL notation :

.Query
POST /api/v1/data/search/hits
{
	"from":0,                               <-- defines the offset from the first result
	"size":1,                               <-- maximum amount of hits to be returned : last hit (only 1 hit is returned)
	"sort":[
	{
		"timestamp":"desc"                  <-- ordered from the last hit date to the first hit date
	}
	],
	"query":{
		"bool":{
			"must":[
			{
				"range":{
					"timestamp":
						{
							"lt":"now"    <-- time now (local time using the UTC timestamp)
						}
					}
				},
				{
				"exists":{
					 "field": "location"    <-- the datamessage must contain a location infos
					}
                }
			],
            "filter": [
                {
                    "term": {
                        "metadata.source": "urn:lo:nsid:mqtt:myTest"  <-- the datamessages are filtred by the deviceId
                    }
                }
            ],
			"must_not":[                          <-- you must exclude the device activity event from your aggregation
			{
				"term":{
				"model":"event:DeviceActivity"
				}
			}
			]
		}
	}
}
.Query response
[
    {
        "id": "60d2f5bb0dfe5f1e032db7ed",
        "streamId": "urn:lo:nsid:mqtt:myTest",
        "timestamp": "2021-06-23T08:50:03.562Z",  <--  the last datamessage which contains a location infos
        "location": {                             <-- the value of location
            "lat": 48.86667,
            "lon": 2.33333,
            "alt": 35.2,
            "accuracy": 12.3,
            "provider": "My_embedded_GPS"
        },
        "value": {
            "temperature": 14.6,
            "messageAlert": "low battery",
            "battery": 53
        },
        "tags": [],
        "extra": {},
        "metadata": {
            "connector": "mqtt",
            "source": "urn:lo:nsid:mqtt:myTest",
            "transformation": {
                "published": {
                    "location": {
                        "provider": "My_embedded_GPS",
                        "alt": 35.2,
                        "accuracy": 12.3,
                        "lon": 2.33333,
                        "lat": 48.86667
                    }
                }
            },
            "group": {
                "path": "/Devices MQTT test",
                "id": "G07y4D"
            },
            "network": {
                "mqtt": {
                    "clientId": "urn:lo:nsid:mqtt:myTest"
                }
            }
        },
        "created": "2021-06-23T08:50:03.576Z"
    }
]

Static sensor

Useful for devices without motion and without tracking use, use the static location during the device provisioning to save its location and retrieve it in your business application if needed.

Business use cases
- Possible measures and the trigger alarms: temperature, humdity (cold chain), fire detection (CO2/temperature), motion detection, pression,etc.
- Operations : monitoring, location of the intervention site, etc.
Advanced use case : industrial zone pollution monitoring

  • based on the example described in this use case, our use case uses the same devices spread over the area to be monitored, each device monitors an area and triggers an alert when something goes wrong.

  • devices are installed in different places located in the map with a static location.

  • alerts received in real time when the threshold pollution is reached.

  • the affected devices location is available on the map (site location).

  • you can inform the specialised early intervention teams to move to the affected site.

Geolocation and fleet management

Uses Live Objects inventory explorer API, useful to manage your fleet under location criteria (and the combination with others criterias).

  • You can supervise your device events by location criteria.

  • You can have a view of last activity of your fleet by location criteria.

  • You can have a coordinates of a problematic devices.

  • Then sent a maintenance team for operation.

Geolocation by boundary delimitation

Boundary delimitation is the drawing of boundaries on a map, in the context of fleet management, it can be used to monitor the devices operation, to collect their status and the network status in a target area by using a maps. Using inventory explorer API, you can also locate your devices on the map and manage easily your own fleet.

  • You can use the geobound filters

  • You can use the filters to refine your selection or your search by using a combinations of filters

  • You can plan the operations of the maintenance team on your devices fleet and optimize its progress over time and on the intervention pathways using the location map.

Geolocation aggregations

A bucket aggregation that works on geobound designation. The user can define a point of origin and a set of mean distance range of all its device fleet (or a sub set). The aggregation evaluate the distance of each device location from the centroid and determines the bucket it belongs to based on the ranges (a device belongs to a bucket if the distance between the device and the origin falls within the distance range of the bucket). Then depending on the needs, some operations can be applied on this set of the devices. To learn more, see.

Tracking

Based on the collection of location data, ordered over timestamp of each published datamessage, the user can use the geofencing approach :

  • The user can determine the moves of the device in time by collecting the successive positions ordered over a time. Here is the device tracking example using geofencing approach. Then you can receive alert when your device enter or leave a monitored zone.

  • In the other hand, the last collected datamessage which contains a last location data, can gives the last known position of the device.

Business use cases
- Location Data collect: tracking, last known position, alerts etc.
- Dynamic position provided by device, network or cellular infos (useful for devices without GPS).

Routed Data Message and data‑processing events

How it works

Data event detection is useful for monitoring business data collected by Live Objects to trigger alerts when needed.

Interactive
Figure 7. Routed Data Message flow

The routed Data Message is a JSON object. Please find below a description of its fields.

Field Description

type

dataMessage. This field is set by Live Objects in the routed Data message. In the store/search section, this field is not set.

version

Version number. See the existing versions in the summary. In the store/search section, this field is not set.

streamId

String identifying a timeseries /stream. Enriched by default if not set. Should not contain following characters: ' " \ ; { } ( ) and ' ' (space).

timestamp

Timestamp associated with the collected information. Generally set by the device, enriched by default if not set. Should follow ISO-8601 date time format.

created

Timestamp reflecting the date on which the data was collected by Live Objects.

location

Geo location (lat, lon, alt, accuracy, provider) associated with the collected info.

model

String used to indicate which schema is used for the value part of the message, more about model field. Can be empty, but can not contains ' ' (space) or '.' (dot) character.

value

Structured representation (JSON object) of the transported info. This field is usually filled with the useful payload (device measurements). Be a JSON object (not a primitive like number or string). Do not contains field name with '.' (dot) character. Size in bytes can not exceed 1 MiB (1024*1024 bytes).

tags

List of strings associated with the message. Used for extra-information.

extra

Enriched by Live Objects and can contains device inventory information like device’s properties.

metadata

Section enriched by Live Objects.

* source: unique identifier of the device, usually the URN (urn:lo:nsid:<namespace>:<id>) * group: group to which the device belongs, defined by its id and its path * connector: lora, mqtt, …​ * network: information from the network, depends on the connector

Standard Data message (MQTT example)

Data Message example : Original message sent by device or published by business application through MQTT interface

payload sent by device :

{
      "revmin":9992,
      "CO2":683,
      "doorOpen":false,
      "hygrometry":45,
      "temperature":139,
      "pressure":1367
}

stored data :

{
   "type":"dataMessage", <=== Message type
   "version":1,          <=== Message version
   "metadata":{
      "connector":"mqtt",
      "source":"urn:lo:nsid:mqtt:12345",
      "transformation": {
        "published": {
            "location": {
            "provider": "GPS",
            "lon": 2.30886,
            "lat": 48.81839
            }
        }
      },
      "group":{
         "path":"/",
         "id":"root"
      },
      "network":{
         "mqtt":{
            "clientId":"<my_mqtt_client_id>"
         }
      }
   },
   "streamId":"urn:lo:nsid:mqtt:12345",
   "created":"2019-09-26T08:03:09.394Z",
   "extra":{
      "propertyDevice1":"12:1b:2e"
   },
   "location":{
      "provider":"GPS",
      "alt":null,
      "accuracy":null,
      "lon":2.30886,
      "lat":48.81839
   },
   "model":"demoDevGuide",
   "id":"5d382598a1a7e8315ce82499",
   "value":{
      "revmin":9992,
      "CO2":683,
      "doorOpen":false,
      "hygrometry":45,
      "temperature":139,
      "pressure":1367
   },
   "timestamp":"2019-09-26T08:03:09.390Z",
   "tags":[
      "tag1",
      "tag2"
   ]
}

MatchingFired event

The Data Message flow goes through the Simple Event Processing service. This service can apply custom binary logics (written in jsonLogic syntax) on each message to detect specific events. These events will be sent as Live Objects MatchingFired event according to firing policies.

  • type field: matchingFired

  • version field: see summary for the available versions

  • This event can be consumed by a business application using Triggers and Actions feature. In this case, the event contains a type and a version. See first example below

  • Also, this event is stored in Live Objects database (if your commercial offer allows storage). In this case, the event is encapsulated in a Data message format. See second example below

  • More details about the feature, see Simple Event Processing section

MatchingFired event example - case: event retrieved by a business application (FIFO, httpPush)
{
   "type":"matchingFired",
   "version":1,
   "tenantId":"12345",
   "timestamp":"2019-09-05T08:51:06.691Z",
   "firingRule":{
      "id":"18d55812-22ae-4ff7-a632-6c4451069c26",
      "name":"firingTestDevGuide"
   },
   "matchingContext":{
      "tenantId":"12345",
      "timestamp":"2019-09-05T08:51:06.624Z",
      "matchingRule":{
         "id":"298502e0-4dc3-489b-ac21-08c98ad066d3",
         "name":"testEventProcessingDevGuide"
      },
      "data":{
         "type":"dataMessage",
         "version":1,
         "streamId":"urn:lo:nsid:mqtt:1234",
         "timestamp":"2019-09-05T08:51:06.583Z",
         "value":{
            "temp":100,
            "pressure":36575
         },
         "tags":[
         ],
         "extra":{
         },
         "metadata":{
            "source":"urn:lo:nsid:mqtt:1234",
            "group":{
               "id":"CdoJOs",
               "path":"/europe"
            },
            "connector":"mqtt",
            "network":{
               "mqtt":{
                  "clientId":"1234"
               }
            }
         }
      }
   }
}
MatchingFired event example - case: event encapsulated in a data message format and stored in Live Objects
{
   "metadata": null,
   "streamId": "event:urn:lo:nsid:mqtt:1234",
   "created": "2019-09-05T08:51:06.703Z",
   "extra": null,
   "location": null,
   "model": "event",
   "id": "5d70cc7aa1a7e85c6b9b587d",
   "value": {
      "matchingContext": {
         "matchingRule": {
            "dataPredicate": "{\">\":[{\"var\":\"value.temp\"},99]}",
            "name": "testEventProcessingDevGuide",
            "id": "298502e0-4dc3-489b-ac21-08c98ad066d3",
            "enabled": true
         },
         "data": {
            "metadata": {
               "connector": "mqtt",
               "source": "urn:lo:nsid:mqtt:1234",
               "group": {
                  "path": "/europe",
                  "id": "CdoJOs"
               },
               "network": {
                  "mqtt": {
                     "clientId": "1234"
                  }
               }
            },
            "streamId": "urn:lo:nsid:mqtt:1234",
            "extra": {},
            "value": {
               "temp": 100,
               "pressure": 36575
            },
            "timestamp": "2019-09-05T08:51:06.583Z",
            "tags": []
         },
         "tenantId": "12345",
         "timestamp": "2019-09-05T08:51:06.624Z"
      },
      "tenantId": "12345",
      "timestamp": "2019-09-05T08:51:06.691Z",
      "firingRule": {
         "name": "firingTestDevGuide",
         "matchingRuleIds": [
            "298502e0-4dc3-489b-ac21-08c98ad066d3"
         ],
         "id": "18d55812-22ae-4ff7-a632-6c4451069c26",
         "aggregationKeys": [
            "streamId"
         ],
         "firingType": "ALWAYS",
         "enabled": true
      }
   },
   "timestamp": "2019-09-05T08:51:06.691Z",
   "tags": [
      "event"
   ]
}

StateChange Event

The Data message flow goes through the StateChange Processing service. This service can detect changes in devices' states, for example geozone location changes. These events will be sent as Live Objects State Change event.

  • type field: stateChange

  • version field: see summary for the available versions

  • This event can be consumed by a business application using Triggers and Actions feature. In this case, the event contains a type and a version. See first example below

  • Also, this event is stored in Live Objects database (if your commercial offer allows storage). In this case, the event is encapsulated in a Data message format. See second example below

  • More details about the feature, see State Processing section

StateChange event example - case: event retrieved by a business application (FIFO, httpPush)
{
   "type":"stateChange",
   "version":1,
   "tenantId":"12345",
   "stateKey":"urn:lo:nsid:mqtt:1234",
   "previousState":"normal",
   "newState":"hot",
   "timestamp":"2019-09-05T08:51:06.616Z",
   "stateProcessingRuleId":"fa1ff947-7855-4249-a5fe-f5bafe53efe2",
   "stateProcessingRule":{
      "id":"fa1ff947-7855-4249-a5fe-f5bafe53efe2",
      "name":"temperature state rule"
   },
   "data":{
      "type":"dataMessage",
      "version":1,
      "streamId":"urn:lo:nsid:mqtt:1234",
      "timestamp":"2019-09-05T08:51:06.583Z",
      "value":{
         "temp":100,
         "pressure":36575
      },
      "tags":[

      ],
      "extra":{

      },
      "metadata":{
         "source":"urn:lo:nsid:mqtt:1234",
         "group":{
            "id":"CdoJOs",
            "path":"/europe"
         },
         "connector":"mqtt",
         "network":{
            "mqtt":{
               "clientId":"1234"
            }
         }
      }
   }
}
StateChange event example - case: event encapsulated in a data message format and stored in Live Objects
{
   "metadata": null,
   "streamId": "event:urn:lo:nsid:mqtt:1234",
   "created": "2019-09-05T08:51:06.621Z",
   "extra": null,
   "location": null,
   "model": "event",
   "id": "5d70cc7a5705d87bd1b66a8a",
   "value": {
      "stateProcessingRuleId": "fa1ff947-7855-4249-a5fe-f5bafe53efe2",
      "data": {
         "metadata": {
            "connector": "mqtt",
            "source": "urn:lo:nsid:mqtt:1234",
            "group": {
               "path": "/europe",
               "id": "CdoJOs"
            },
            "network": {
               "mqtt": {
                  "clientId": "1234"
               }
            }
         },
         "streamId": "urn:lo:nsid:mqtt:1234",
         "extra": {},
         "value": {
            "temp": 100,
            "pressure": 36575
         },
         "timestamp": "2019-09-05T08:51:06.583Z",
         "tags": []
      },
      "tenantId": "12345",
      "newState": "hot",
      "stateKey": "urn:lo:nsid:mqtt:1234",
      "previousState": "normal",
      "timestamp": "2019-09-05T08:51:06.616Z",
      "stateProcessingRule": {
         "stateKeyPath": "streamId",
         "name": "temperature state rule",
         "stateFunction": "{\"if\":[{\"<\":[{\"var\":\"value.temp\"},0]},\"cold\",{\"<\":[{\"var\":\"value.temp\"},100]},\"normal\",\"hot\"]}",
         "id": "fa1ff947-7855-4249-a5fe-f5bafe53efe2",
         "enabled": true,
         "filterPredicate": "null"
      }
   },
   "timestamp": "2019-09-05T08:51:06.616Z",
   "tags": [
      "event"
   ]
}

DeviceActivity event

The Activity processing feature aims to monitor device inactivity. When a device is "SILENT" or goes "ACTIVE" again, an event is generated. These events can be listened with a business application using FIFO or httpPush. In the web portal, these events are displayed as "notifications".

  • type field: deviceActivity

  • version field: see summary for the available versions

  • This event can be consumed by a business application using Triggers and Actions feature. In this case, the event contains a type and a version. See first example below

  • Also, this event is stored in Live Objects database (if your commercial offer allows storage). In this case, the event is encapsulated in a Data message format. See second example below

  • More details about the feature, see Activity Processing section

DeviceActivity event example - case: event retrieved by a business application (FIFO, httpPush)
{
	"type": "deviceActivity",
	"version": 1,
	"deviceId": "urn:lo:nsid:mqtt:1234",
	"deviceAdditionalInfo": {
		"deviceName": "sensor #12",
		"groupPath": "/europe"
	},
	"activityRule": {
		"id": "683bb813-495f-423a-87f6-d87656c8b02c",
		"name": "test 10 min"
	},
	"state": "SILENT",
	"previousState": "UNKNOWN",
	"timestamp": "2020-06-09T07:47:00.004Z",
	"numberOfAlarmReminders": 0
}
DeviceActivity event example - case: event encapsulated in a data message format and stored in Live Objects
{
   "metadata":null,
   "streamId":"event:urn:lo:nsid:mqtt:1234",
   "created":"2019-09-05T09:35:00.019Z",
   "extra":null,
   "location":null,
   "model":"event:DeviceActivity",
   "id":"5d70d6c4a1a7e85c6b9b58ab",
   "value":{
      "deviceAdditionalInfo":{
         "deviceName":"Auto-created device (mqtt / 1234)",
         "groupPath":"/europe"
      },
      "numberOfAlarmReminders":0,
      "state":"SILENT",
      "deviceId":"urn:lo:nsid:mqtt:1234",
      "activityRule":{
         "name":"test 10 min",
         "id":"683bb813-495f-423a-87f6-d87656c8b02c",
         "silentPolicy":{
            "duration":"PT10M",
            "repeatInterval":"PT10M"
         },
         "targets":{
            "deviceIds":[
               "urn:lo:nsid:mqtt:1234"
            ],
            "groupPaths":[
            ]
         },
         "enabled":true
      },
      "timestamp":"2020-06-09T07:47:00.004Z"
   },
   "timestamp":"2020-06-09T07:47:00.004Z",
   "tags":[
      "event"
   ]
}

Device events

Device events are reported when an event occurs on the device. The device manager reports this event as a message that will be collected by the routing service, which forwards it to the consumer. Business applications can use the listening channels (HTTP REST, MQTT client and Webhook) in order to have them.

Interactive
Figure 8. Message journey of routed event message.

Device created event

The deviceCreated events are generated by the Live Objects device manager when a device is provisioned.

These events are notifications and are not aimed at giving full provisioning details about the device. To retrieve the details about the device, you should use the Device Management Inventory REST API.

The deviceCreated notification is useful, for example, when devices are auto-provisioned in Live Objects (see MQTT devices and external connector mode).

The consumption of this event used with the Device Management REST API allow you to update your own business application database for example.

If you are not familiar with the device representation and device management in Live Objects, see Device inventory section.

The event is a JSON object. Please find below a description of its fields.

Field Description

type

deviceCreated. This field is set by Live Objects in the routed event.

version

Version number. See the existing versions in the summary.

deviceId

Device identifier.

timestamp

Timestamp for the routing event.
DeviceCreated event example
{
   "type":"deviceCreated",
   "version":1,
   "deviceId":"urn:lo:nsid:mqtt:1234",
   "timestamp":"2019-09-05T09:50:00.394Z"
}

Device deleted event

The deviceDeleted events are generated by the Live Objects device manager when a device is deleted.

These events are notifications and are not aimed at giving full provisioning details about the device. To retrieve the details about the device, you should use the Device Management Inventory REST API.

The consumption of this event used with the Device Management REST API allow you to update your own business application database for example.

If you are not familiar with the device representation and device management in Live Objects, see Device inventory section.

The event is a JSON object. Please find below a description of its fields.

Field Description

type

deviceDeleted. This field is set by Live Objects in the routed event.

version

Version number. See the existing versions in the summary.

deviceId

Device identifier.

timestamp

Timestamp for the routing event.
DeviceDeleted event example.
{
   "type":"deviceDeleted",
   "version":1,
   "deviceId":"urn:lo:nsid:mqtt:1234",
   "timestamp":"2019-09-05T09:55:00.004Z"
}

Device status event

This event is generated by Live Objects when a device interface’s status is changing. Examples :

  • When a LwM2M device recently created connects to Live Objects for the first time, a device status event is generated with the previous status : REGISTERED and the current status : ONLINE

  • When a MQTT device is disconnected, a device status event is generated with the previous status : ONLINE and the current status : OFFLINE

  • When the first JOIN REQUEST is received from a recently created LoRa device, a device status event is generated with the previous status : REGISTERED and the current status : INITIALIZING

This event is internally used by the device manager to update its connectors database. Also, it’s possible to route this event using Triggers and Actions feature. By doing this, a business application can listen and process this event.

Please refer to the Connectivity section for the description of device status state machines on each connectivity (LwM2M, MQTT, LoRa, …). And to the interface status section for a summary of the supported device status.

The device status event is a JSON object. Please find below a description of its fields.

Field Description

type

deviceStatus. This field is set by Live Objects in the routed event.

version

Version number. See the existing versions in the summary.

deviceId

Device identifier.

updatedInterface

Information about the interface. In status sub-section, information about the status of the interface with the previous and current state.

timestamp

Timestamp for the routing event.
DeviceStatus event example - case: event retrieved by a business application (FIFO, httpPush).
{
   "type":"deviceStatus",
   "version":1,
   "deviceId":"urn:lo:nsid:mqtt:1234",
   "updatedInterface":{
      "connector":"mqtt",
      "nodeId":"1234",
      "enabled":true,
      "status":{
         "current":"ONLINE",
         "previous":"OFFLINE"
      }
   },
   "timestamp":"2019-09-05T09:50:00.394Z"
}
Please refer to a global overview of supported event occurred on the interfaces of each connector, see Interface section.

Command status events

This event is generated by Live Objects platform when a device command status change occurs. For example, when a command is acknowledged by a MQTT device, a command status event is sent by the platform with the status PROCESSED.

The command status events are triggers than can be mapped to supported actions (HTTP push, fifo…​)

The command status event is a JSON object. Please find below a description of its fields.

Field Description

type

commandStatus. The type is set by Live Objects platform.

version

Version number. See the existing versions in the summary.

id

The id of the command.

targetDeviceId

The deviceId related to the command event.

status

The command status. Refers to command status chapter.

deliveryStatus

The delivery command status. Refers to command status chapter.

errorCode

The error code. Refers to command object model chapter.

request

The request associated to the command

request.connector

The connector used for the command (mqtt, lora…​)

request.value

The request JSON object

response

The device response associated to the command (depends on command status and ackMode used).

response.value

The response JSON object

created

Creation date of the command - string ISO 8601 format in UTC.

updated

Update date of the command (status change) - string ISO 8601 format in UTC.
Please refer to a global overview of supported command statuses of each connector, see Command status section.
CommandStatus event example: 
{
  "type" : "commandStatus",
  "version" : 1,
  "id" : "5d9ef867be84e3147f9db0a3",
  "targetDeviceId" : "urn:lo:nsid:mysensor:16503",
  "status" : "PROCESSED",
  "deliveryStatus" : "REPLIED",
  "request" : {
    "connector" : "mqtt",
    "value" : {
      "req" : "reboot",
      "arg" : {
        "delay" : 30000,
        "bootMode" : "safe"
      }
    }
  },
  "response" : {
    "value" : {
      "done" : true
    }
  },
  "created" : "2019-10-10T09:22:47.765Z",
  "updated" : "2019-10-10T09:23:53.318Z"
}

Network events

LoRa® network event

This event is generated by Live Objects platform when a LoRa® device or network perform an action. It is a specific event for LoRa® connectivity. If you don’t use this connectivity, you are not concern by this event.

For example, when a device sends a data without confirmation, a LoRa® network event is sent by the platform with the message type UNCONFIRMED_DATA_UP.

The LoRa® network event is a trigger type in Triggers and Actions feature. These events can be mapped to supported actions (HTTP push, fifo…​).

The LoRa® network event is a JSON object. Please find below a description of its fields.

Field Description

type

loraNetwork. The type is set by Live Objects platform.

version

Version number. See the existing versions in the summary.

timestamp

The time stamp when the event is emitted.

devEUI

The global end-device ID (for more information, see the chapter 6.2.1 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

appEUI

The global application ID (for more information, see the chapter 6.1.2 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

devNonce

Counter incremented to each emitted Join-request (for more information, see the chapter 6.2.4 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

messageType

Message type of message emitted by the LoRa® device (for more information, see the chapter 4.2.1 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf). List of message types: "UNCONFIRMED_DATA_UP", "CONFIRMED_DATA_UP", "UNCONFIRMED_DATA_DOWN", "CONFIRMED_DATA_DOWN", "JOIN_REQUEST", "JOIN_ACCEPT"

payload

Payload sent by the device

port

The value of FPort field (for more information, see the chapter 4.3.2 of https://lora-alliance.org/wp-content/uploads/2020/11/lorawan1.0.3.pdf).

signal

The description signal of the best Long Range Router (LRR). Ten field are defined in the standard:

  • rssi: its Received Signal Strength Indicator

  • snr: its Signal Noise Ratio

  • esp: its Estimated Signal Power

  • sf: its Spreading Factor

  • frequency: its frequency

  • signalLevel: signal quality indicator from 1 to 5. It is assessed from the spreading factor and from the signal noise ratio provided by the frame.

  • gatewayCnt: number of macro gateways that have received the message

  • bestGatewayId: ID of the best LoRa® gateway (optional)

  • gateways: list of gateway seen by the LoRa® device (optional)

  • id: id of the gateway

  • rssi: the Received Signal Strength Indicator of the described gateway

  • snr: the Signal Noise Ratio of the described gateway

  • esp: the Estimated Signal Power of the described gateway

result

Only available for JOIN_ACCEPT messages. Values : "success"

rawJoinAccept

Encoded message. This field is used only when the message type is "JOIN_ACCEPT"

frameHeader

The headers' description of the received frame

macCommands

The list of MAC commands emitted by the LoRa® device. Each MAC command is described in according to two fields:

This is an example:

LoRa® network example: 
{
   "type":"loraNetwork",
   "version":1,
   "timestamp":"2018-10-13T03:08:19.965Z",
   "devEUI":"0123456789ABCDEF",
   "messageType":"UNCONFIRMED_DATA_UP",
   "payload":"00000100000000000000000100000002000000030000000400000005000000060000000",
   "port":1,
   "signal": {
      "rssi":-114.0,
      "snr":-9.0,
      "esp":-123.51,
      "sf":12,
      "signalLevel":3,
      "gatewayCnt":3
    },
    "frameHeader":{
      "fcnt":13890,
      "adr":true,
      "ack":false,
      "adrAckRequest":false,
      "devAddr":"1000025A",
      "framePending" : true/false  <=== (1)
    },
    "macCommands":[
       {
         "type":"LinkADRAns",
         "rawValue":"0307"
       }
    ]
}
1 For downlinks only

LoRa® gateway status event

This event is generated by Live Objects when a LoRa® gateway status is changing.

The LoRa® gateway status event is a JSON object. Please find below a description of its fields.

Field Description

type

loraGatewayStatus. This field is set by Live Objects in the routed event.

version

Version number. See the existing versions in the summary.

gatewayId

Gateway identifier.

gatewayName

Gateway name.

status.current

Current status of the gateway. Either "ONLINE", "OFFLINE" or "UNKNOWN".

status.previous

Previous status of the gateway. Either "ONLINE", "OFFLINE" or "UNKNOWN".

timestamp

Timestamp for the routing event.


LoraGatewayStatus event example 
{
   "type":"loraGatewayStatus",
   "version":1,
   "gatewayId":"ABCD1234",
   "gatewayName":"Main site gateway",
   "status": {
      "current":"ONLINE",
      "previous":"OFFLINE"
   },
   "timestamp":"2020-09-11T09:50:00.394Z"
}

Connectivity Management Platform event

Connectivity Management Platforms can integrate with LiveObjects 'Message routing' capability to route their own events and messages.

Orange Connectivity Management Platforms events

Orange Connectivity Management Platforms is also known as 'Portail M2M', 'Conecta IoT', 'Simply IoT'…​

Here is the description of the Orange Connectivity Management Platforms events that can be routed through LiveObjects:

Field Description

type

connectivityManagementPlatformEvent. The type is set by Live Objects platform.

version

Version number. See the existing versions in the summary.

timestamp

The timestamp of the event (ISO-8601 format) provided by the CMP platform.

created

The date when the event has been routed to LiveObjects (ISO-8601 format).

id

The unique identifier for the event, useful for tracking and correlation.

issuer

Information regarding the trigger of the event.

issuer.cenId

Orange CMP account identifier.

issuer.subscriptionId

Orange CMP line identifier.

payload

The content of the event. Can include various fields depending on the event type : 'msisdn', 'country'…​

payloadType

Identify the event type. You can use this field as a filter into your action policy. Available types : 'prepaid_bucket'.

payloadVersion

Identify the schema version of the event.

Here is an example:

Connectivity Management Platform event example: 
{
  "type": "connectivityManagementPlatformEvent",
  "version": 1,
  "id": "evt-12345-abcde-67890",
  "timestamp": "2025-10-01T10:30:45Z",
  "issuer": {
    "subscriptionId": "sub-001-abc123",
    "cenId": "cen-456-def789"
  },
  "payloadType": "prepaid_bucket",
  "payloadVersion": "1.0.0",
  "payload": {
      "recordType": "Alerting",
      "msisdn": "337000007245112",
      "date": "2021-11-24T15:32:28Z",
      "bucketCapacity": 60,
      "thresholdValue": 48,
      "zone": "National UE SA",
      "country": "FRANCE",
      "levelAlerting": "80%"
  },
  "created": "2025-10-01T10:30:46Z"
}

Alarm event

Alarm events for account metrics monitoring are integrated with LiveObjects 'Message routing' capabilities.

Summary

Whenever Live Objects triggers an alarm related to account metrics monitoring, it generates an alarm event. This event is routed to the destination defined in the action policy. The alarm event is a JSON message that contains information about the alarm, such as its type, reason and timestamp.

Alarm event data model

Description of the alarm events that can be routed through LiveObjects.

Field Description

type

alarmEvent. The type of the event. Set by Live Objects platform.

version

Version number. See the existing versions in the summary. Default value is 1.

alarmRule

Information regarding the alarm rule that triggered the event.

alarmRule.type

The type of the alarm rule that triggered the event. You can filter the alarm events by this field. supported types are: messageDeliverySuccessRatio, actionSuspended Supported alarms full description is available in account alarming.

monitoredResource

Information regarding the resource being monitored. The format of this field depends on the type of resource being monitored. For example, if the monitored resource is an action, the field will contain information about the action, such as its ID, name and parent action policy.

triggerDetails

Details about the trigger that caused the alarm event.
alarm event example for "alarmRule.type" : "messageDeliverySuccessRatio"

Here is an example of an alarm event generated by the Live Objects platform when a "message delivery success ratio" alarm is triggered by a default alarm rule. The event contains information about the alarm rule, the monitored resource (an action), and the trigger details (the timestamp and value that caused the alarm to be triggered).

{
    "type": "alarmEvent",
    "version": 1,
    "alarmRule": {
        "id": "message-delivery-success-ratio-default",
        "type": "messageDeliverySuccessRatio",
        "name": "Delivered message degradation",
        "trigger": {
            "condition": {
                "comparisonOperator": "lessThanOrEqualTo",
                "threshold": 90.0,
                "evaluationWindow": "PT24H"
            }
        },
        "default": true
    },
    "monitoredResource": {
        "id": "http_push_action_id_with_alarm",
        "type": "action",
        "name": "HTTPPUSH",
        "parent": {
            "id": "action_policy_id_with_alarm",
            "type": "actionPolicy",
            "name": "my action policy"
        },
        "portalLink": "https://liveobjects.orange-business.com/#/redirect?id=A00Z%22%2C"
    },
    "triggerDetails": {
        "triggeredAt": "2026-06-25T10:00:00Z",
        "triggerValue": 90.0
    }
}
alarm event example for "alarmRule.type" : "actionSuspended"

Here is an example of an alarm event generated by the Live Objects platform when a action suspended alarm is triggered by a default alarm rule. The event contains information about the alarm rule, the monitored resource (an action), and the trigger details (the timestamp and value that caused the alarm to be triggered).

Note: The action suspended alarm is triggered automatically when an action is suspended due to a failure in its execution persisting for more than 7 days. See account alarming chapter.

{
    "tenantId": "f3062f39-f051-415a-ba35-48c0b6a03d48",
    "alarmRule": {
        "id": "6a3e7c2532a723ed77b5829d",
        "type": "actionSuspended",
        "name": "alarm_name",
        "default": true
    },
    "monitoredResource": {
        "id": "actionId",
        "type": "action",
        "name": "HTTPPUSH",
        "parent": {
            "id": "actionPolicyId",
            "type": "actionPolicy",
            "name": "my action policy"
        },
        "portalLink": "https://liveobjects.orange-business.com/#/redirect?id=A00Z%22%2C"
    },
    "triggerDetails": {
        "triggeredAt": "2026-06-26T13:18:29.647Z",
        "triggerReason": "Failure rate > 90% for more than 7 consecutive days"
    }
}
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC