Skip to content

Commit 82e1d30

Browse files
fgalanfgalan
authored
Merge pull request #843 from jason-fox/feature/time-and-geo
Add GeoJSON and DateTime, unitCode and observedAt NGSI-LD support
2 parents 3cc3064 + 3d72455 commit 82e1d30

File tree

48 files changed

+956
-260
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+956
-260
lines changed

‎CHANGES_NEXT_RELEASE‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,8 @@ Add NGSIv2 metadata support to device provisioned attributes
33
Fix: Error message when sending measures with unknown/undefined attribute
44
Add Null check within executeWithSecurity() to avoid crash (#829)
55
Basic NGSI-LD active measures support (#841)
6+
Add GeoJSON and DateTime, unitCode and observedAt NGSI-LD support (#843)
7+
- The NGSI v2 `TimeInstant` element has been mapped onto the NGSI-LD `observedAt` property
8+
- The NGSI v2 `metadata.unitCode` attribute has been mapped onto the NGSI-LD `unitCode` property
69
Add NGSIv2 metadata support to attributeAlias plugin.
710
Add mongodb authentication: IOTA_MONGO_USER, IOTA_MONGO_PASSWORD and IOTA_MONGO_AUTH_SOURCE (#844)

‎doc/advanced-topics.md‎

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,50 @@ e.g.:
8383
}
8484
```
8585

86+
#### NGSI-LD data and metadata considerations
87+
88+
When provisioning devices for an NGSI-LD Context Broker, `type` values should typically correspond to one of the
89+
following:
90+
91+
- `Property`, `Relationship`, `Geoproperty`
92+
- Native JSON types (e.g. `String`, `Boolean`, `Float` , `Integer` `Number`)
93+
- Temporal Properties (e.g. `Datetime`, `Date` , `Time`)
94+
- GeoJSON types (e.g `Point`, `LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`)
95+
96+
Most NGSI-LD attributes are sent to the Context Broker as _properties_. If a GeoJSON type or native JSON type is
97+
defined, the data will be converted to the appropriate type. Temporal properties should always be expressed in UTC,
98+
using ISO 8601. This ISO 8601 conversion is applied automatically for the `observedAt` _property-of-a-property_ metadata
99+
where present.
100+
101+
Data for any attribute defined as a _relationship_ must be a valid URN.
102+
103+
Note that when the `unitCode` metadata attribute is supplied in the provisioning data under NGSI-LD, the standard
104+
`unitCode` _property-of-a-property_ `String` attribute is created.
105+
106+
Other unrecognised `type` attributes will be passed as NGSI-LD data using the following JSON-LD format:
107+
108+
```json
109+
"<property_name>": {
110+
"type" : "Property",
111+
"value": {
112+
"@type": "<property_type>",
113+
"@value": { string or object}
114+
}
115+
}
116+
```
117+
118+
`null` values will be passed in the following format:
119+
120+
```json
121+
"<property_name>": {
122+
"type" : "Property",
123+
"value": {
124+
"@type": "Intangible",
125+
"@value": null
126+
}
127+
}
128+
```
129+
86130
### Data mapping plugins
87131

88132
The IoT Agent Library provides a plugin mechanism in order to facilitate reusing code that makes small transformations
@@ -138,7 +182,7 @@ The library provides some plugins out of the box, in the `dataPlugins` collectio
138182
use the `addQueryMiddleware` and `addUpdateMiddleware` functions with the selected plugin, as in the example:
139183

140184
```javascript
141-
var iotaLib = require('iotagent-node-lib');
185+
var iotaLib = require("iotagent-node-lib");
142186

143187
iotaLib.addUpdateMiddleware(iotaLib.dataPlugins.compressTimestamp.update);
144188
iotaLib.addQueryMiddleware(iotaLib.dataPlugins.compressTimestamp.query);
@@ -166,8 +210,9 @@ events in the IoT Agent with the configured type name will be marked as events.
166210

167211
##### Timestamp Processing Plugin (timestampProcess)
168212

169-
This plugin processes the entity attributes looking for a TimeInstant attribute. If one is found, the plugin add a
170-
TimeInstant attribute as metadata for every other attribute in the same request.
213+
This plugin processes the entity attributes looking for a `TimeInstant` attribute. If one is found, for NGSI-v1/NGSIv2,
214+
the plugin adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the
215+
Standard `observedAt` property-of-a-property is used instead.
171216

172217
##### Expression Translation plugin (expressionTransformation)
173218

‎doc/api.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -203,25 +203,25 @@ Note that there is a 1:1 correspondence between payload fields and DB fields (bu
203203
The table below shows the information held in the Device resource. The table also contains the correspondence between
204204
the API resource fields and the same fields in the database model.
205205

206-
| Payload Field | DB Field | Definition | Example of value |
207-
| ------------------------- | -------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
208-
| `device_id` | `id` | Device ID that will be used to identify the device. | UO834IO |
209-
| `service` | `service` | Name of the service the device belongs to (will be used in the fiware-service header). | smartGondor |
210-
| `service_path` | `subservice` | Name of the subservice the device belongs to (used in the fiware-servicepath header). | /gardens |
211-
| `entity_name` | `name` | Name of the entity representing the device in the Context Broker | ParkLamplight12 |
212-
| `entity_type` | `type` | Type of the entity in the Context Broker | Lamplights |
213-
| `timezone` | `timezone` | Time zone of the sensor if it has any | America/Santiago |
214-
| `timestamp` | `timestamp` | Optional flag about whether or not to addthe TimeInstant attribute to the device entity created, as well as a TimeInstant metadata to each attribute, with the current timestamp | true |
215-
| `apikey` | `apikey` | Optional Apikey key string to use instead of group apikey |
206+
| Payload Field | DB Field | Definition | Example of value |
207+
| ------------------------- | -------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
208+
| `device_id` | `id` | Device ID that will be used to identify the device. | UO834IO |
209+
| `service` | `service` | Name of the service the device belongs to (will be used in the fiware-service header). | smartGondor |
210+
| `service_path` | `subservice` | Name of the subservice the device belongs to (used in the fiware-servicepath header). | /gardens |
211+
| `entity_name` | `name` | Name of the entity representing the device in the Context Broker | ParkLamplight12 |
212+
| `entity_type` | `type` | Type of the entity in the Context Broker | Lamplights |
213+
| `timezone` | `timezone` | Time zone of the sensor if it has any | America/Santiago |
214+
| `timestamp` | `timestamp` | Optional flag about whether or not to add the `TimeInstant` attribute to the device entity created, as well as a `TimeInstant` metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard `observedAt` property-of-a-property is created instead. | true |
215+
| `apikey` | `apikey` | Optional Apikey key string to use instead of group apikey |
216216
| 9n4hb1vpwbjozzmw9f0flf9c2 |
217-
| `endpoint` | `endpoint` | Endpoint where the device is going to receive commands, if any. | http://theDeviceUrl:1234/commands |
218-
| `protocol` | `protocol` | Name of the device protocol, for its use with an IoT Manager. | IoTA-UL |
219-
| `transport` | `transport` | Name of the device transport protocol, for the IoT Agents with multiple transport protocols. | MQTT |
220-
| `attributes` | `active` | List of active attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
221-
| `lazy` | `lazy` | List of lazy attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
222-
| `commands` | `commands` | List of commands of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
223-
| `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration | LWM2M mappings from object URIs to attributes |
224-
| `static_attributes` | `staticAttributes` | List of static attributes to append to the entity. All the updateContext requests to the CB will have this set of attributes appended. | `[ { "name": "attr_name", "type": "Text" } ]` |
217+
| `endpoint` | `endpoint` | Endpoint where the device is going to receive commands, if any. | http://theDeviceUrl:1234/commands |
218+
| `protocol` | `protocol` | Name of the device protocol, for its use with an IoT Manager. | IoTA-UL |
219+
| `transport` | `transport` | Name of the device transport protocol, for the IoT Agents with multiple transport protocols. | MQTT |
220+
| `attributes` | `active` | List of active attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
221+
| `lazy` | `lazy` | List of lazy attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
222+
| `commands` | `commands` | List of commands of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
223+
| `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration | LWM2M mappings from object URIs to attributes |
224+
| `static_attributes` | `staticAttributes` | List of static attributes to append to the entity. All the updateContext requests to the CB will have this set of attributes appended. | `[ { "name": "attr_name", "type": "Text" } ]` |
225225

226226
#### Attribute lists
227227

‎doc/architecture.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ basis preprovisioning the devices). Device measures can have three different beh
3232
The following sequence diagram shows the different NGSI interactions an IoT Agent makes with the Context Broker,
3333
explained in the following subsections (using the example of a OMA Lightweight M2M device).
3434

35-
![General ](./img/ngsiInteractions.png 'NGSI Interactions')
35+
![General ](./img/ngsiInteractions.png "NGSI Interactions")
3636

3737
Be aware that the IoT Agents are only required to support NGSI10 operations `updateContext` and `queryContext` in their
3838
standard formats (currently in JSON format; XML deprecated) but will not answer to NGSI9 operations (or NGSI convenience
@@ -207,21 +207,22 @@ the concrete IoT Agent implementations will be to map between the native device
207207
The following figure offers a graphical example of how a COAP IoT Agent work, ordered from the registration of the
208208
device to a command update to the device.
209209

210-
![General ](./img/iotAgentLib.png 'Architecture Overview')
210+
![General ](./img/iotAgentLib.png "Architecture Overview")
211211

212212
### The `TimeInstant` element
213213

214214
As part of the device to entity mapping process the IoT Agent creates and updates automatically a special timestamp.
215215
This timestamp is represented as two different properties of the mapped entity::
216216

217-
- An attribute metadata named `TimeInstant` per dynamic attribute mapped, which captures as an ISO8601 timestamp when
218-
the associated measurement (represented as attribute value) was observed.
217+
- With NGSIv1/NGSI-v2, an attribute metadata named `TimeInstant` (per dynamic attribute mapped, which captures as an
218+
ISO8601 timestamp when the associated measurement (represented as attribute value) was observed. With NGSI-LD, the
219+
Standard `observedAt` property-of-a-property is used instead.
219220

220-
- An entity attribute named `TimeInstant` which captures as an ISO8601 timestamp when the last measurement received
221-
from the device was observed.
221+
- For NGSIv1/NGSI-v2 only, an additional attribute `TimeInstant` is added to the entity which captures as an
222+
ISO8601 timestamp when the last measurement received from the device was observed.
222223

223224
If no information about the measurement timestamp is received by the IoT Agent, the arrival time of the measurement will
224-
be used to generate a `TimeInstant` for both the entity and the attribute's metadata.
225+
be used to generate a `TimeInstant` for both the entity attribute and the attribute metadata.
225226

226227
Take into account that:
227228

‎doc/installationguide.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,9 @@ used for the same purpose. For instance:
149149

150150
- **mongodb**: configures the MongoDB driver for those repositories with 'mongodb' type. If the `host` parameter is a
151151
list of comma-separated IPs, they will be considered to be part of a Replica Set. In that case, the optional
152-
property `replicaSet` should contain the Replica Set name. If the database requires authentication, username
153-
(`username`), password (`password`) and authSource (`authSource`) can be set. For The MongoBD driver will retry the
154-
connection at startup time `retries` times, waiting `retryTime` seconds between attempts, if those attributes are
152+
property `replicaSet` should contain the Replica Set name. If the database requires authentication, username
153+
(`username`), password (`password`) and authSource (`authSource`) can be set. For The MongoBD driver will retry the
154+
connection at startup time `retries` times, waiting `retryTime` seconds between attempts, if those attributes are
155155
present (default values are 5 and 5 respectively). E.g.:
156156

157157
```javascript
@@ -206,9 +206,10 @@ used for the same purpose. For instance:
206206
any unexpected error.
207207
- **singleConfigurationMode**: enables the Single Configuration mode for backwards compatibility (see description in
208208
the Overview). Default to false.
209-
- **timestamp**: if this flag is activated, the IoT Agent will add a 'TimeInstant' metadata attribute to all the
210-
attributes updated from device information. This flag is overwritten by `timestamp` flag in group or device
209+
- **timestamp**: if this flag is activated:
210+
- For NGSIv1/NGSIv2, the IoT Agent will add a `TimeInstant` metadata attribute to all the attributes updated from device information. This flag is overwritten by `timestamp` flag in group or device
211211
provision.
212+
- With NGSI-LD, the standard `observedAt` property-of-a-property is created instead.
212213
- **defaultResource**: default string to use as resource for the registration of new Configurations (if no resource is
213214
provided).
214215
- **defaultKey**: default string to use as API Key for devices that do not belong to a particular Configuration.

0 commit comments

Comments
 (0)