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.
Static device location (provisioned)
The static location can be added in the device representation. Cf. device representation with the staticLocation section.
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.
{
"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" ]
}{
"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"
]
}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
{
"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" ]
}{
"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
{
"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
}
}{
"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"
]
}{
"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 :
-
Custom infos manually set by an External Enricher
-
staticLocation values (if present)
-
location section values extracted after a message decoding (if the decoding service successfully decode message and the message contains a valid location section)
-
Published location in the message by the device
-
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:
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 |
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.
{
"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
}
}{
"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 :
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"
}
}
]
}
}
}[
{
"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.
- 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.
-
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.
- Location Data collect: tracking, last known position, alerts etc. - Dynamic position provided by device, network or cellular infos (useful for devices without GPS).