iotagent-node-lib 2.18.0 → 2.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/ci.yml +1 -2
- package/doc/advanced-topics.md +122 -53
- package/doc/api.md +52 -52
- package/doc/development.md +8 -9
- package/doc/expressionLanguage.md +514 -316
- package/doc/installationguide.md +66 -64
- package/doc/usermanual.md +48 -16
- package/docker/Mosquitto/Dockerfile +1 -0
- package/docker/Mosquitto/README.md +1 -0
- package/docker/Mosquitto/startMosquitto.sh +6 -4
- package/lib/command/commandLine.js +1 -1
- package/lib/fiware-iotagent-lib.js +3 -0
- package/lib/jexlTranformsMap.js +9 -1
- package/lib/model/Device.js +4 -1
- package/lib/model/Group.js +19 -1
- package/lib/plugins/expressionParser.js +6 -4
- package/lib/plugins/expressionPlugin.js +8 -1
- package/lib/plugins/jexlParser.js +3 -1
- package/lib/request-shim.js +111 -0
- package/lib/services/common/genericMiddleware.js +6 -2
- package/lib/services/common/iotManagerService.js +1 -1
- package/lib/services/common/securityServiceKeystone.js +1 -1
- package/lib/services/common/securityServiceOAuth2.js +3 -2
- package/lib/services/devices/deviceRegistryMongoDB.js +1 -0
- package/lib/services/devices/devices-NGSI-LD.js +1 -1
- package/lib/services/devices/devices-NGSI-v2.js +2 -6
- package/lib/services/devices/registrationUtils.js +0 -2
- package/lib/services/ngsi/entities-NGSI-LD.js +95 -11
- package/lib/services/ngsi/entities-NGSI-v2.js +93 -8
- package/lib/services/ngsi/ngsiService.js +3 -2
- package/lib/services/northBound/contextServer-NGSI-LD.js +3 -2
- package/lib/services/northBound/deviceProvisioningServer.js +29 -6
- package/lib/services/northBound/northboundServer.js +2 -0
- package/lib/services/northBound/restUtils.js +1 -1
- package/package.json +4 -4
- package/test/tools/utils.js +2 -0
- package/test/unit/expressions/jexlExpression-test.js +5 -5
- package/test/unit/general/contextBrokerKeystoneSecurityAccess-test.js +1 -1
- package/test/unit/general/deviceService-test.js +2 -5
- package/test/unit/general/loglevel-api_test.js +6 -11
- package/test/unit/general/migration-test.js +1 -0
- package/test/unit/general/startup-test.js +1 -0
- package/test/unit/memoryRegistry/deviceRegistryMemory_test.js +1 -0
- package/test/unit/mongodb/mongodb-group-registry-test.js +1 -1
- package/test/unit/mongodb/mongodb-registry-test.js +2 -1
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin12a.json +7 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin13.json +13 -13
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin1a.json +18 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin29.json +18 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin31.json +15 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin32.json +17 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin33.json +18 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin34.json +17 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin4a.json +36 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin7.json +16 -16
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin8a.json +18 -0
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextMultientityPlugin15.json +25 -0
- package/test/unit/ngsi-ld/expressions/jexlBasedTransformations-test.js +1018 -0
- package/test/unit/ngsi-ld/general/contextBrokerOAuthSecurityAccess-test.js +2 -2
- package/test/unit/ngsi-ld/general/deviceService-test.js +1 -1
- package/test/unit/ngsi-ld/general/https-support-test.js +2 -1
- package/test/unit/ngsi-ld/general/iotam-autoregistration-test.js +2 -1
- package/test/unit/ngsi-ld/general/startup-test.js +1 -0
- package/test/unit/ngsi-ld/lazyAndCommands/active-devices-attribute-update-test.js +3 -1
- package/test/unit/ngsi-ld/lazyAndCommands/command-test.js +2 -1
- package/test/unit/ngsi-ld/lazyAndCommands/lazy-devices-test.js +2 -6
- package/test/unit/ngsi-ld/lazyAndCommands/polling-commands-test.js +2 -1
- package/test/unit/ngsi-ld/ngsiService/active-devices-test.js +1 -0
- package/test/unit/ngsi-ld/ngsiService/autocast-test.js +1 -0
- package/test/unit/ngsi-ld/ngsiService/geoproperties-test.js +1 -0
- package/test/unit/ngsi-ld/ngsiService/subscriptions-test.js +4 -3
- package/test/unit/ngsi-ld/plugins/alias-plugin_test.js +1 -0
- package/test/unit/ngsi-ld/plugins/bidirectional-plugin_test.js +3 -2
- package/test/unit/ngsi-ld/plugins/multientity-plugin_test.js +61 -0
- package/test/unit/ngsi-ld/provisioning/device-provisioning-api_test.js +2 -1
- package/test/unit/ngsi-ld/provisioning/device-registration_test.js +3 -2
- package/test/unit/ngsi-ld/provisioning/device-update-registration_test.js +1 -0
- package/test/unit/ngsi-ld/provisioning/listProvisionedDevices-test.js +42 -54
- package/test/unit/ngsi-ld/provisioning/provisionDeviceMultientity-test.js +2 -1
- package/test/unit/ngsi-ld/provisioning/removeProvisionedDevice-test.js +4 -4
- package/test/unit/ngsi-ld/provisioning/singleConfigurationMode-test.js +3 -5
- package/test/unit/ngsi-ld/provisioning/updateProvisionedDevices-test.js +12 -18
- package/test/unit/ngsi-mixed/provisioning/ngsi-versioning-test.js +3 -1
- package/test/unit/ngsiv2/examples/contextRequests/updateContextExpressionPlugin17.json +1 -1
- package/test/unit/ngsiv2/examples/contextRequests/updateContextExpressionPlugin32.json +16 -0
- package/test/unit/ngsiv2/examples/contextRequests/updateContextExpressionPlugin33.json +22 -0
- package/test/unit/ngsiv2/examples/contextRequests/updateContextExpressionPlugin34.json +12 -0
- package/test/unit/ngsiv2/examples/contextRequests/updateContextMultientityPlugin15.json +25 -0
- package/test/unit/ngsiv2/examples/contextRequests/updateContextMultientityPlugin16.json +25 -0
- package/test/unit/ngsiv2/expressions/expressionBasedTransformations-test.js +4 -4
- package/test/unit/ngsiv2/expressions/jexlBasedTransformations-test.js +500 -0
- package/test/unit/ngsiv2/general/contextBrokerOAuthSecurityAccess-test.js +3 -2
- package/test/unit/ngsiv2/general/deviceService-test.js +9 -8
- package/test/unit/ngsiv2/general/https-support-test.js +2 -1
- package/test/unit/ngsiv2/general/iotam-autoregistration-test.js +2 -1
- package/test/unit/ngsiv2/general/startup-test.js +1 -0
- package/test/unit/ngsiv2/lazyAndCommands/active-devices-attribute-update-test.js +3 -1
- package/test/unit/ngsiv2/lazyAndCommands/command-test.js +2 -1
- package/test/unit/ngsiv2/lazyAndCommands/lazy-devices-test.js +14 -18
- package/test/unit/ngsiv2/lazyAndCommands/polling-commands-test.js +3 -1
- package/test/unit/ngsiv2/ngsiService/active-devices-test.js +1 -0
- package/test/unit/ngsiv2/ngsiService/queryDeviceInformationInCb-test.js +0 -1
- package/test/unit/ngsiv2/ngsiService/subscriptions-test.js +4 -3
- package/test/unit/ngsiv2/plugins/bidirectional-plugin_test.js +3 -2
- package/test/unit/ngsiv2/plugins/multientity-plugin_test.js +210 -0
- package/test/unit/ngsiv2/plugins/translation-inPlugins_test.js +1 -1
- package/test/unit/ngsiv2/provisioning/device-group-api-test.js +3 -2
- package/test/unit/ngsiv2/provisioning/device-group-utils-test.js +2 -1
- package/test/unit/ngsiv2/provisioning/device-provisioning-api_test.js +2 -1
- package/test/unit/ngsiv2/provisioning/device-registration_test.js +3 -2
- package/test/unit/ngsiv2/provisioning/device-update-registration_test.js +4 -3
- package/test/unit/ngsiv2/provisioning/listProvisionedDevices-test.js +42 -53
- package/test/unit/ngsiv2/provisioning/provisionDeviceMultientity-test.js +2 -1
- package/test/unit/ngsiv2/provisioning/removeProvisionedDevice-test.js +4 -4
- package/test/unit/ngsiv2/provisioning/singleConfigurationMode-test.js +3 -4
- package/test/unit/ngsiv2/provisioning/updateProvisionedDevices-test.js +13 -19
- package/test/unit/plugins/capture-configuration-inPlugins_test.js +3 -1
- package/test/unit/plugins/capture-provision-inPlugins_test.js +2 -1
- package/test/unit/ngsi-ld/examples/contextRequests/updateContextExpressionPlugin20.json +0 -25
package/.github/workflows/ci.yml
CHANGED
package/doc/advanced-topics.md
CHANGED
|
@@ -1,37 +1,36 @@
|
|
|
1
1
|
## Advanced Topics
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
3
|
+
- [Secured access to the Context Broker](#secured-access-to-the-context-broker)
|
|
4
|
+
- [NGSI-LD `GeoProperty` support](#ngsi-ld-geoproperty-support)
|
|
5
|
+
- [Metadata support](#metadata-support)
|
|
6
|
+
- [NGSI LD data and metadata considerations](#ngsi-ld-data-and-metadata-considerations)
|
|
7
|
+
- [NGSI-LD Linked Data support](#ngsi-ld-linked-data-support)
|
|
8
|
+
- [Autoprovision configuration (autoprovision)](#autoprovision-configuration-autoprovision)
|
|
9
|
+
- [Explicitly defined attributes (explicitAttrs)](#explicitly-defined-attributes-explicitattrs)
|
|
10
|
+
- [Configuring operation to persist the data in Context Broker (appendMode)](#configuring-operation-to-persist-the-data-in-context-broker-appendmode)
|
|
11
|
+
- [Data mapping plugins](#data-mapping-plugins)
|
|
12
|
+
- [Development](#development)
|
|
13
|
+
- [Provided plugins](#provided-plugins)
|
|
14
|
+
- [Timestamp Compression plugin (compressTimestamp)](#timestamp-compression-plugin-compresstimestamp)
|
|
15
|
+
- [Attribute Alias plugin (attributeAlias)](#attribute-alias-plugin-attributealias)
|
|
16
|
+
- [Event plugin (addEvents)](#event-plugin-addevents)
|
|
17
|
+
- [Timestamp Processing Plugin (timestampProcess)](#timestamp-processing-plugin-timestampprocess)
|
|
18
|
+
- [Expression Translation plugin (expressionTransformation)](#expression-translation-plugin-expressiontransformation)
|
|
19
|
+
- [Multientity plugin (multiEntity)](#multientity-plugin-multientity)
|
|
20
|
+
- [Bidirectionality plugin (bidirectional)](#bidirectionality-plugin-bidirectional)
|
|
21
|
+
- [Autoprovision configuration (autoprovision)](#autoprovision-configuration-autoprovision)
|
|
22
|
+
- [Explicitly defined attributes (explicitAttrs)](#explicitly-defined-attributes-explicitattrs)
|
|
23
|
+
- [Configuring operation to persist the data in Context Broker (appendMode)](#configuring-operation-to-persist-the-data-in-context-broker-appendmode)
|
|
24
|
+
- [Old IoTAgent data migration](#old-iotagent-data-migration)
|
|
26
25
|
|
|
27
26
|
### Secured access to the Context Broker
|
|
28
27
|
|
|
29
28
|
For access to instances of the Context Broker secured with a
|
|
30
29
|
[PEP Proxy](https://github.com/telefonicaid/fiware-orion-pep), an authentication mechanism based in Keystone Trust
|
|
31
|
-
tokens is provided. A trust token is a way of Keystone to allow an user delegates a role to another user for a
|
|
32
|
-
It is a long-term token that can be issued by any user to give another user permissions
|
|
33
|
-
|
|
34
|
-
|
|
30
|
+
tokens is provided. A trust token is a way of Keystone to allow an user delegates a role to another user for a
|
|
31
|
+
subservice. It is a long-term token that can be issued by any user to give another user permissions to impersonate him
|
|
32
|
+
with a given role in a given project (subservice). Such impersonation itself is in turn based on a short-term access
|
|
33
|
+
token.
|
|
35
34
|
|
|
36
35
|
For the authentication mechanisms to work, the `authentication` attribute in the configuration has to be fully
|
|
37
36
|
configured, and the `authentication.enabled` subattribute should have the value `true`.
|
|
@@ -73,15 +72,18 @@ Agent.
|
|
|
73
72
|
|
|
74
73
|
Complete info on Keystone trust tokens could be found at:
|
|
75
74
|
|
|
76
|
-
-
|
|
77
|
-
-
|
|
75
|
+
- [Trusts concept](https://docs.openstack.org/keystone/stein/user/trusts)
|
|
76
|
+
- [Trusts API](https://docs.openstack.org/keystone/stein/api_curl_examples.html#post-v3-os-trust-trusts)
|
|
77
|
+
|
|
78
|
+
### NGSI-LD `GeoProperty` support
|
|
78
79
|
|
|
79
|
-
|
|
80
|
+
For NGSI-LD only, the defined `type` of any GeoJSON attribute can be any set using any of the standard NGSI-v2 GeoJSON
|
|
81
|
+
types - (e.g. `geo:json`, `geo:point`). NGSI-LD formats such as `GeoProperty`, `Point` and `LineString` are also
|
|
82
|
+
accepted `type` values. If the latitude and longitude are received as separate measures, the JEXL or legacy
|
|
83
|
+
[expression language](expressionLanguage.md) can be used to concatenate them into GeoJSON objects an array of tuples or
|
|
84
|
+
a string as shown
|
|
80
85
|
|
|
81
|
-
|
|
82
|
-
`geo:json`, `geo:point`). NGSI-LD formats such as `GeoProperty`, `Point` and `LineString` are also accepted `type`
|
|
83
|
-
values. If the latitude and longitude are received as separate measures, the
|
|
84
|
-
[expression language](expressionLanguage.md) can be used to concatenate them.
|
|
86
|
+
#### Legacy - encode as String
|
|
85
87
|
|
|
86
88
|
```json
|
|
87
89
|
{
|
|
@@ -99,8 +101,30 @@ values. If the latitude and longitude are received as separate measures, the
|
|
|
99
101
|
}
|
|
100
102
|
```
|
|
101
103
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
+
#### JEXL - encode as GeoJSON
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"entity_type": "GPS",
|
|
109
|
+
"resource": "/iot/d",
|
|
110
|
+
"protocol": "PDI-IoTA-JSON",
|
|
111
|
+
"expressionLanguage": "jexl",
|
|
112
|
+
..etc
|
|
113
|
+
"attributes": [
|
|
114
|
+
{
|
|
115
|
+
"name": "location",
|
|
116
|
+
"type": "geo:json",
|
|
117
|
+
"expression": "{coordinates: [longitude,latitude], type: 'Point'}"
|
|
118
|
+
}
|
|
119
|
+
]
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
JEXL can be used to create GeoJSON objects directly. The Legacy expression language does not support GeoJSON. However,
|
|
124
|
+
there is a workaround specifically for NGSI-LD Entities which always require `location` to be encoded as GeoJSON. For
|
|
125
|
+
`attributes` and `static_attributes` which need to be formatted as GeoJSON values, three separate input formats are
|
|
126
|
+
currently accepted. Provided the `type` is provisioned correctly, the `value` may be defined using any of the following
|
|
127
|
+
formats:
|
|
104
128
|
|
|
105
129
|
- a comma delimited string
|
|
106
130
|
|
|
@@ -269,26 +293,70 @@ updated as shown:
|
|
|
269
293
|
|
|
270
294
|
### Autoprovision configuration (autoprovision)
|
|
271
295
|
|
|
272
|
-
By default, when a measure arrives to the IoTAgent, if the `device_id` does not match with an existing one, then, the
|
|
273
|
-
creates a new device and a new entity according to the group config. Defining the field `autoprovision` to `false`
|
|
274
|
-
when provisioning the device group, the IoTA to reject the measure at the southbound, allowing only to persist the
|
|
275
|
-
|
|
276
|
-
|
|
296
|
+
By default, when a measure arrives to the IoTAgent, if the `device_id` does not match with an existing one, then, the
|
|
297
|
+
IoTA creates a new device and a new entity according to the group config. Defining the field `autoprovision` to `false`
|
|
298
|
+
when provisioning the device group, the IoTA to reject the measure at the southbound, allowing only to persist the data
|
|
299
|
+
to devices that are already provisioned. It makes no sense to use this field in device provisioning since it is intended
|
|
300
|
+
to avoid provisioning devices (and for it to be effective, it would have to be provisional).
|
|
277
301
|
|
|
278
302
|
### Explicitly defined attributes (explicitAttrs)
|
|
279
303
|
|
|
280
|
-
If a given measure element (object_id) is not defined in the mappings of the device or group provision, the measure is
|
|
281
|
-
in the Context Broker by adding a new attribute to the entity with the same name of the undefined measure
|
|
282
|
-
field `explicitAttrs` with `true` value to device or group provision, the IoTAgent rejects the
|
|
283
|
-
in the mappings of device or group provision, persisting only the one defined in
|
|
284
|
-
is provided both at device and group level, the device level takes
|
|
304
|
+
If a given measure element (object_id) is not defined in the mappings of the device or group provision, the measure is
|
|
305
|
+
stored in the Context Broker by adding a new attribute to the entity with the same name of the undefined measure
|
|
306
|
+
element. By adding the field `explicitAttrs` with `true` value to device or group provision, the IoTAgent rejects the
|
|
307
|
+
measure elements that are not defined in the mappings of device or group provision, persisting only the one defined in
|
|
308
|
+
the mappings of the provision. If `explicitAttrs` is provided both at device and group level, the device level takes
|
|
309
|
+
precedence. Additionally `explicitAttrs` can be used to define which meassures defined in JSON/JEXL array will be
|
|
310
|
+
propagated to NGSI interface.
|
|
311
|
+
|
|
312
|
+
The different possibilities are summarized below:
|
|
313
|
+
|
|
314
|
+
Case 1 (default):
|
|
315
|
+
|
|
316
|
+
```
|
|
317
|
+
"explicitAttrs": false
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
every measure will be propagated to NGSI interface.
|
|
321
|
+
|
|
322
|
+
Case 2:
|
|
323
|
+
|
|
324
|
+
```
|
|
325
|
+
"explicitAttrs": true
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
just measures defined in active, static (plus conditionally TimeInstant) will be propagated to NGSI interface.
|
|
329
|
+
|
|
330
|
+
Case 3:
|
|
331
|
+
|
|
332
|
+
```
|
|
333
|
+
"explicitAttrs": "['attr1','atrr2']"
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
just measures defined in the array will be will be propagated to NGSI interface (note that in this case the value of
|
|
337
|
+
`explicitAttrs` is not a JSON but a string that looks likes a JSON).
|
|
338
|
+
|
|
339
|
+
Case 4:
|
|
340
|
+
|
|
341
|
+
```
|
|
342
|
+
"explicitAtttr": "<JEXL expression resulting in bool or array>"
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
depending on the JEXL expression evaluation:
|
|
346
|
+
|
|
347
|
+
- If it evaluates to `true` every measure will be propagated to NGSI interface (as in case 1)
|
|
348
|
+
- If it evaluates to `false` just measures defined in active, static (plus conditionally TimeInstant) will be
|
|
349
|
+
propagated to NGSI interface (as in case 2)
|
|
350
|
+
- If it evaluates to an array just measures defined in the array will be will be propagated to NGSI interface (as in
|
|
351
|
+
case 3)
|
|
285
352
|
|
|
286
353
|
### Configuring operation to persist the data in Context Broker (appendMode)
|
|
287
354
|
|
|
288
|
-
This is a flag that can be enabled by activating the parameter `appendMode` in the configuration file or by using the
|
|
289
|
-
environment variable (more info
|
|
290
|
-
If this flag is
|
|
291
|
-
|
|
355
|
+
This is a flag that can be enabled by activating the parameter `appendMode` in the configuration file or by using the
|
|
356
|
+
`IOTA_APPEND_MODE` environment variable (more info
|
|
357
|
+
[here](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/installationguide.md)). If this flag is
|
|
358
|
+
activated, the update requests to the Context Broker will be performed always with APPEND type, instead of the default
|
|
359
|
+
UPDATE. This have implications in the use of attributes with Context Providers, so this flag should be used with care.
|
|
292
360
|
|
|
293
361
|
### Data mapping plugins
|
|
294
362
|
|
|
@@ -373,8 +441,8 @@ events in the IoT Agent with the configured type name will be marked as events.
|
|
|
373
441
|
|
|
374
442
|
##### Timestamp Processing Plugin (timestampProcess)
|
|
375
443
|
|
|
376
|
-
This plugin processes the entity attributes looking for a `TimeInstant` attribute. If one is found, for NGSIv2,
|
|
377
|
-
|
|
444
|
+
This plugin processes the entity attributes looking for a `TimeInstant` attribute. If one is found, for NGSIv2, the
|
|
445
|
+
plugin adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the
|
|
378
446
|
Standard `observedAt` property-of-a-property is used instead.
|
|
379
447
|
|
|
380
448
|
##### Expression Translation plugin (expressionTransformation)
|
|
@@ -438,7 +506,8 @@ When a device is provisioned with bidirectional attributes, the IoTAgent subscri
|
|
|
438
506
|
change notification for that attribute arrives to the IoTA, it applies the transformation defined in the device
|
|
439
507
|
provisioning payload to the notification, and calls the underlying notification handler with the transformed entity.
|
|
440
508
|
|
|
441
|
-
The following `attributes` section shows an example of the plugin configuration (using IOTA_AUTOCAST=false to avoid
|
|
509
|
+
The following `attributes` section shows an example of the plugin configuration (using IOTA_AUTOCAST=false to avoid
|
|
510
|
+
translation from geo:point to geo:json)
|
|
442
511
|
|
|
443
512
|
```json
|
|
444
513
|
"attributes": [
|
package/doc/api.md
CHANGED
|
@@ -75,26 +75,26 @@ information configured:
|
|
|
75
75
|
The table below shows the information held in the service group provisioning resource. The table also contains the
|
|
76
76
|
correspondence between the API resource fields and the same fields in the database model.
|
|
77
77
|
|
|
78
|
-
| Payload Field | DB Field | Definition
|
|
79
|
-
| ------------------------------ | ------------------------------ |
|
|
80
|
-
| `service` | `service` | Service of the devices of this type
|
|
81
|
-
| `subservice` | `subservice` | Subservice of the devices of this type.
|
|
82
|
-
| `resource` | `resource` | string representing the Southbound resource that will be used to assign a type to a device (e.g.: pathname in the southbound port).
|
|
83
|
-
| `apikey` | `apikey` | API Key string.
|
|
84
|
-
| `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.
|
|
85
|
-
| `entity_type` | `entity_type` | name of the Entity `type` to assign to the group.
|
|
86
|
-
| `trust` | `trust` | trust token to use for secured access to the Context Broker for this type of devices (optional; only needed for secured scenarios).
|
|
87
|
-
| `cbHost` | `cbHost` | Context Broker connection information. This options can be used to override the global ones for specific types of devices.
|
|
88
|
-
| `lazy` | `lazy` | list of common lazy attributes of the device. For each attribute, its `name` and `type` must be provided.
|
|
89
|
-
| `commands` | `commands` | list of common commands attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.
|
|
90
|
-
| `attributes` | `attributes` | list of common active attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional.
|
|
91
|
-
| `static_attributes` | `staticAttributes` | this attributes will be added to all the entities of this group 'as is', additional `metadata` is optional.
|
|
92
|
-
| `internal_attributes` | `internalAttributes` | optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry.
|
|
93
|
-
| `expressionLanguage` | `expresionLanguage` | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, `legacy` is used as default value.
|
|
94
|
-
| `explicitAttrs` | `explicitAttrs` | optional
|
|
95
|
-
| `ngsiVersion` | `ngsiVersion` | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. Possible values are: `v2` or `ld`. The default is `v2`. When not running in mixed mode, this field is ignored.
|
|
96
|
-
| `defaultEntityNameConjunction` | `defaultEntityNameConjunction` | optional string value to set default conjunction string used to compose a default `entity_name` when is not provided at device provisioning time.
|
|
97
|
-
| `autoprovision` | `autoprovision` | optional boolean: If `false`, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is `true`.
|
|
78
|
+
| Payload Field | DB Field | Definition |
|
|
79
|
+
| ------------------------------ | ------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
80
|
+
| `service` | `service` | Service of the devices of this type |
|
|
81
|
+
| `subservice` | `subservice` | Subservice of the devices of this type. |
|
|
82
|
+
| `resource` | `resource` | string representing the Southbound resource that will be used to assign a type to a device (e.g.: pathname in the southbound port). |
|
|
83
|
+
| `apikey` | `apikey` | API Key string. |
|
|
84
|
+
| `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 |
|
|
85
|
+
| `entity_type` | `entity_type` | name of the Entity `type` to assign to the group. |
|
|
86
|
+
| `trust` | `trust` | trust token to use for secured access to the Context Broker for this type of devices (optional; only needed for secured scenarios). |
|
|
87
|
+
| `cbHost` | `cbHost` | Context Broker connection information. This options can be used to override the global ones for specific types of devices. |
|
|
88
|
+
| `lazy` | `lazy` | list of common lazy attributes of the device. For each attribute, its `name` and `type` must be provided. |
|
|
89
|
+
| `commands` | `commands` | list of common commands attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional. |
|
|
90
|
+
| `attributes` | `attributes` | list of common active attributes of the device. For each attribute, its `name` and `type` must be provided, additional `metadata` is optional. |
|
|
91
|
+
| `static_attributes` | `staticAttributes` | this attributes will be added to all the entities of this group 'as is', additional `metadata` is optional. |
|
|
92
|
+
| `internal_attributes` | `internalAttributes` | optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry. |
|
|
93
|
+
| `expressionLanguage` | `expresionLanguage` | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, `legacy` is used as default value. |
|
|
94
|
+
| `explicitAttrs` | `explicitAttrs` | optional field to support selective ignore of measures so that IOTA doesn’t progress. See details in [specific section](advanced-topics.md#explicitly-defined-attributes-explicitattrs) |
|
|
95
|
+
| `ngsiVersion` | `ngsiVersion` | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. Possible values are: `v2` or `ld`. The default is `v2`. When not running in mixed mode, this field is ignored. |
|
|
96
|
+
| `defaultEntityNameConjunction` | `defaultEntityNameConjunction` | optional string value to set default conjunction string used to compose a default `entity_name` when is not provided at device provisioning time. |
|
|
97
|
+
| `autoprovision` | `autoprovision` | optional boolean: If `false`, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is `true`. |
|
|
98
98
|
|
|
99
99
|
### Service Group Endpoint
|
|
100
100
|
|
|
@@ -205,45 +205,45 @@ Note that there is a 1:1 correspondence between payload fields and DB fields (bu
|
|
|
205
205
|
|
|
206
206
|
### Relationship between service groups and devices
|
|
207
207
|
|
|
208
|
-
Devices may be associated to exisiting service groups (or not) based in `apiKey` matching or `type` matching (in the
|
|
209
|
-
matching fails). For instance, let's consider a situation in which a service group has been provisioned
|
|
210
|
-
and no other service group has been provisioned.
|
|
208
|
+
Devices may be associated to exisiting service groups (or not) based in `apiKey` matching or `type` matching (in the
|
|
209
|
+
case `apiKey` matching fails). For instance, let's consider a situation in which a service group has been provisioned
|
|
210
|
+
with `type=X`/`apiKey=111` and no other service group has been provisioned.
|
|
211
211
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
212
|
+
- IoT Agent receives an anonymous measure with `apiKey=111`. The matching `apiKey` means the entity inherits from
|
|
213
|
+
service group. Device entity has `type=X` and `apiKey=111`
|
|
214
|
+
- IoT Agent receives a provisioning request for an explicit device of `type=Y`/`apiKey=111`. The matching `apiKey`
|
|
215
|
+
means the entity inherits from service group but type is overridden. Device entity has `type=Y` and `apiKey=111`
|
|
216
|
+
- IoT Agent receives a provisioning request for an explicit device of `type=X`/`apiKey=222`. The matching `type` means
|
|
217
|
+
the entity inherits from service group but `apiKey` is overridden. Device entity has `type=X` and `apiKey=222`.
|
|
218
|
+
- IoT Agent receives a provisioning request for an explicit device of `type=Y`/`apiKey=222`. No matching. Device
|
|
219
|
+
entity has `type=Y` and `apiKey=222` and no service group.
|
|
220
220
|
|
|
221
221
|
### Device model
|
|
222
222
|
|
|
223
223
|
The table below shows the information held in the Device resource. The table also contains the correspondence between
|
|
224
224
|
the API resource fields and the same fields in the database model.
|
|
225
225
|
|
|
226
|
-
| Payload Field | DB Field | Definition
|
|
227
|
-
| --------------------- | -------------------- |
|
|
228
|
-
| `device_id` | `id` | Device ID that will be used to identify the device.
|
|
229
|
-
| `service` | `service` | Name of the service the device belongs to (will be used in the fiware-service header).
|
|
230
|
-
| `service_path` | `subservice` | Name of the subservice the device belongs to (used in the fiware-servicepath header).
|
|
231
|
-
| `entity_name` | `name` | Name of the entity representing the device in the Context Broker
|
|
232
|
-
| `entity_type` | `type` | Type of the entity in the Context Broker
|
|
233
|
-
| `timezone` | `timezone` | Time zone of the sensor if it has any
|
|
234
|
-
| `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.
|
|
235
|
-
| `apikey` | `apikey` | Optional Apikey key string to use instead of group apikey
|
|
236
|
-
| `endpoint` | `endpoint` | Endpoint where the device is going to receive commands, if any.
|
|
237
|
-
| `protocol` | `protocol` | Name of the device protocol, for its use with an IoT Manager.
|
|
238
|
-
| `transport` | `transport` | Name of the device transport protocol, for the IoT Agents with multiple transport protocols.
|
|
239
|
-
| `attributes` | `active` | List of active attributes of the device
|
|
240
|
-
| `lazy` | `lazy` | List of lazy attributes of the device
|
|
241
|
-
| `commands` | `commands` | List of commands of the device
|
|
242
|
-
| `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration
|
|
243
|
-
| `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.
|
|
244
|
-
| `expressionLanguage` | `expresionLanguage` | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, legacy is used as default value.
|
|
245
|
-
| `explicitAttrs` | `explicitAttrs` |
|
|
246
|
-
| `ngsiVersion` | `ngsiVersion` | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. The default is `v2`. When not running in mixed mode, this field is ignored.
|
|
226
|
+
| Payload Field | DB Field | Definition | Example of value |
|
|
227
|
+
| --------------------- | -------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------- |
|
|
228
|
+
| `device_id` | `id` | Device ID that will be used to identify the device. | UO834IO |
|
|
229
|
+
| `service` | `service` | Name of the service the device belongs to (will be used in the fiware-service header). | smartGondor |
|
|
230
|
+
| `service_path` | `subservice` | Name of the subservice the device belongs to (used in the fiware-servicepath header). | /gardens |
|
|
231
|
+
| `entity_name` | `name` | Name of the entity representing the device in the Context Broker | ParkLamplight12 |
|
|
232
|
+
| `entity_type` | `type` | Type of the entity in the Context Broker | Lamplights |
|
|
233
|
+
| `timezone` | `timezone` | Time zone of the sensor if it has any | America/Santiago |
|
|
234
|
+
| `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 |
|
|
235
|
+
| `apikey` | `apikey` | Optional Apikey key string to use instead of group apikey | 9n4hb1vpwbjozzmw9f0flf9c2 |
|
|
236
|
+
| `endpoint` | `endpoint` | Endpoint where the device is going to receive commands, if any. | http://theDeviceUrl:1234/commands |
|
|
237
|
+
| `protocol` | `protocol` | Name of the device protocol, for its use with an IoT Manager. | IoTA-UL |
|
|
238
|
+
| `transport` | `transport` | Name of the device transport protocol, for the IoT Agents with multiple transport protocols. | MQTT |
|
|
239
|
+
| `attributes` | `active` | List of active attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
|
|
240
|
+
| `lazy` | `lazy` | List of lazy attributes of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
|
|
241
|
+
| `commands` | `commands` | List of commands of the device | `[ { "name": "attr_name", "type": "Text" } ]` |
|
|
242
|
+
| `internal_attributes` | `internalAttributes` | List of internal attributes with free format for specific IoT Agent configuration | LWM2M mappings from object URIs to attributes |
|
|
243
|
+
| `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" } ]` |
|
|
244
|
+
| `expressionLanguage` | `expresionLanguage` | optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl. When not set or wrongly set, legacy is used as default value. |
|
|
245
|
+
| `explicitAttrs` | `explicitAttrs` | optional field to support selective ignore of measures so that IOTA doesn’t progress. See details in [specific section](advanced-topics.md#explicitly-defined-attributes-explicitattrs) | (see details in specific section) |
|
|
246
|
+
| `ngsiVersion` | `ngsiVersion` | optional string value used in mixed mode to switch between **NGSI-v2** and **NGSI-LD** payloads. The default is `v2`. When not running in mixed mode, this field is ignored. | `v2/ld` |
|
|
247
247
|
|
|
248
248
|
#### Attribute lists
|
|
249
249
|
|
package/doc/development.md
CHANGED
|
@@ -27,15 +27,15 @@ The following sections show the available options in detail.
|
|
|
27
27
|
|
|
28
28
|
### Environment requirements
|
|
29
29
|
|
|
30
|
-
A [MongoDB](https://www.mongodb.com/) 3.2+ instance is required to run tests.
|
|
31
|
-
|
|
30
|
+
A [MongoDB](https://www.mongodb.com/) 3.2+ instance is required to run tests. You can deploy one by using the commodity
|
|
31
|
+
`docker-compose-dev.yml`:
|
|
32
32
|
|
|
33
33
|
```
|
|
34
34
|
docker-compose -f docker-compose-dev.yml up -d
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
To run docker compose you will need [docker](https://docs.docker.com/get-docker/)
|
|
38
|
-
|
|
37
|
+
To run docker compose you will need [docker](https://docs.docker.com/get-docker/) and
|
|
38
|
+
[docker-compose](https://docs.docker.com/compose/install/).
|
|
39
39
|
|
|
40
40
|
### Testing
|
|
41
41
|
|
|
@@ -51,14 +51,13 @@ To run tests, type
|
|
|
51
51
|
npm test
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
There are additional targets starting with `test:` prefix to run specific test subsets isolatedly. For instance,
|
|
55
|
-
|
|
54
|
+
There are additional targets starting with `test:` prefix to run specific test subsets isolatedly. For instance, the
|
|
55
|
+
`test:expressions` target runs the subset of tests related with expression language feature:
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
npm run test:expressions
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
-
|
|
62
61
|
### Debug Test
|
|
63
62
|
|
|
64
63
|
To debug the code while running run tests, type
|
|
@@ -67,8 +66,8 @@ To debug the code while running run tests, type
|
|
|
67
66
|
npm run test:debug
|
|
68
67
|
```
|
|
69
68
|
|
|
70
|
-
In the console the link to the debugger will be provided. You can connect
|
|
71
|
-
|
|
69
|
+
In the console the link to the debugger will be provided. You can connect to it via Chrome, for example, by opening the
|
|
70
|
+
following url: `chrome://inspect`.
|
|
72
71
|
|
|
73
72
|
Additional debug clients are listed on [node.js](https://nodejs.org/en/docs/guides/debugging-getting-started/).
|
|
74
73
|
|