diff --git a/docs/contribution.md b/docs/contribution.md index 544f5630..c2f22b3a 100644 --- a/docs/contribution.md +++ b/docs/contribution.md @@ -4,21 +4,23 @@ Before we get started, here are a few things we expect from you (and that you should expect from others): -* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and +- Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct. -* Please ensure that your contribution passes all tests. If there are test failures, you will need to address them +- Please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution. -* When adding content, please consider if it is widely valuable. Please don't add references or links to things you or +- When adding content, please consider if it is widely valuable. Please don't add references or links to things you or your employer have created as others will do so if they appreciate it. -* When reporting a vulnerability on the software, please, put in contact with IoT Agent Node Lib repository maintainers in order to discuss it - in a private way. +- When reporting a vulnerability on the software, please, put in contact with IoT Agent Node Lib repository + maintainers in order to discuss it in a private way. ## How to contribute -If you'd like to contribute, start by searching through the [issues](https://github.com/telefonicaid/iotagent-ul/issues) and -[pull requests](https://github.com/telefonicaid/iotagent-ul/pulls) to see whether someone else has raised a similar idea or -question. In adition, you can also check in the IoTAgent Node Lib framework repository for [issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and [pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) across all the IoT-Agents +If you'd like to contribute, start by searching through the [issues](https://github.com/telefonicaid/iotagent-ul/issues) +and [pull requests](https://github.com/telefonicaid/iotagent-ul/pulls) to see whether someone else has raised a similar +idea or question. In adition, you can also check in the IoTAgent Node Lib framework repository for +[issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and +[pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) across all the IoT-Agents If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following: @@ -28,18 +30,22 @@ If you don't see your idea listed, and you think it fits into the goals of this ### Pull Request protocol -As explained in ([FIWARE Contribution Requirements](https://fiware-requirements.readthedocs.io/en/latest/)) +As explained in ([FIWARE Contribution Requirements](https://fiware-requirements.readthedocs.io/en/latest/)) contributions are done using a pull request (PR). The detailed "protocol" used in such PR is described below: -- Direct commits to master branch (even single-line modifications) are not allowed. Every modification has to come as a PR -- In case the PR is implementing/fixing a numbered issue, the issue number has to be referenced in the body of the PR at creation time -- Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by Github) -- Use *code line comments* instead of *general comments*, for traceability reasons (see comments lifecycle below) +- Direct commits to master branch (even single-line modifications) are not allowed. Every modification has to come as + a PR +- In case the PR is implementing/fixing a numbered issue, the issue number has to be referenced in the body of the PR + at creation time +- Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by + Github) +- Use _code line comments_ instead of _general comments_, for traceability reasons (see comments lifecycle below) - Comments lifecycle - - Comment is created, initiating a *comment thread* + - Comment is created, initiating a _comment thread_ - New comments can be added as responses to the original one, starting a discussion - After discussion, the comment thread ends in one of the following ways: - - `Fixed in ` in case the discussion involves a fix in the PR branch (which commit hash is included as reference) + - `Fixed in ` in case the discussion involves a fix in the PR branch (which commit hash is + included as reference) - `NTC`, if finally nothing needs to be done (NTC = Nothing To Change) - PR can be merged when the following conditions are met: - All comment threads are closed @@ -48,15 +54,19 @@ contributions are done using a pull request (PR). The detailed "protocol" used i Some additional remarks to take into account when contributing with new PRs: -* PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications to existing one) and tests -* PR modifications must pass full regression based on existing test (unit, functional, memory, e2e) in addition to whichever new test added due to the new functionality -* PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please, redo the work in smaller pieces" without any further discussing +- PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications + to existing one) and tests +- PR modifications must pass full regression based on existing test (unit, functional, memory, e2e) in addition to + whichever new test added due to the new functionality +- PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please, + redo the work in smaller pieces" without any further discussing ## Community Discussions about the Open Source Guides take place on this repository's -[Issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and [Pull Requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) -sections. Anybody is welcome to join these conversations. +[Issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and +[Pull Requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) sections. Anybody is welcome to join these +conversations. Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. @@ -78,8 +88,8 @@ In order to start contributing: git clone https://github.com/your-github-username/iotagent-ul.git ``` -3. Add the main iotagent-ul repository as a remote to your forked repository (use any name for your remote - repository, it does not have to be iotagent-ul, although we will use it in the next steps): +3. Add the main iotagent-ul repository as a remote to your forked repository (use any name for your remote repository, + it does not have to be iotagent-ul, although we will use it in the next steps): ```bash git remote add iotagent-ul https://github.com/telefonicaid/iotagent-ul.git diff --git a/docs/deprecated.md b/docs/deprecated.md index 810c0322..999f0d57 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -39,10 +39,10 @@ the case you want to use old versions: The following table provides information about the last iotagent-ul version supporting currently removed features: -| **Removed feature** | **Last iotagent-ul version supporting feature** | **That version release date** | -| ---------------------- | ------------------------------------------------- | ----------------------------- | -| NGSIv1 API | 1.17.0 | June 18th, 2021 | -| Support to Node.js v4 | 1.8.0 | December 19th, 2018 | -| Support to Node.js v6 | 1.9.0 | May 22nd, 2019 | -| Support to Node.js v8 | 1.13.0 | April 7th, 2020 | -| Support to Node.js v10 | 1.16.0 | February 18th, 2021 | +| **Removed feature** | **Last iotagent-ul version supporting feature** | **That version release date** | +| ---------------------- | ----------------------------------------------- | ----------------------------- | +| NGSIv1 API | 1.17.0 | June 18th, 2021 | +| Support to Node.js v4 | 1.8.0 | December 19th, 2018 | +| Support to Node.js v6 | 1.9.0 | May 22nd, 2019 | +| Support to Node.js v8 | 1.13.0 | April 7th, 2020 | +| Support to Node.js v10 | 1.16.0 | February 18th, 2021 | diff --git a/docs/installationguide.md b/docs/installationguide.md index fa04e0ef..8a68da3e 100644 --- a/docs/installationguide.md +++ b/docs/installationguide.md @@ -193,10 +193,12 @@ IoT Agent. The following attributes are accepted: order versions) or without the slash. See [discussion](https://github.com/telefonicaid/iotagent-node-lib/issues/866). - **clean**: this flag is by default true, set to false to receive QoS 1 and 2 messages while offline. -- **clientId**: string ID which identifies client in mqtt broker. By default is using a string composed by a fixed prefix - `iotaul_` and a random suffix, i.e. `iotaul_43bf8a3a`. -- **sharedSubscriptionsDisabled**: this flag is by default undefined and shared subscriptions are enabled, to disable shared subscriptions set to true -- **groupIdSufix**: defaults to undefined and is not set, when set to a value the value is appended to the groupId of the mqtt subscriptions +- **clientId**: string ID which identifies client in mqtt broker. By default is using a string composed by a fixed + prefix `iotaul_` and a random suffix, i.e. `iotaul_43bf8a3a`. +- **sharedSubscriptionsDisabled**: this flag is by default undefined and shared subscriptions are enabled, to disable + shared subscriptions set to true +- **groupIdSufix**: defaults to undefined and is not set, when set to a value the value is appended to the groupId of + the mqtt subscriptions #### AMQP Binding configuration @@ -239,44 +241,43 @@ The ones relating global configuration described in the following table. The ones relating specific Ultralight 2.0 bindings are described in the following table. -| Environment variable | Configuration attribute | -| :---------------------------- | :---------------------- | -| IOTA_MQTT_PROTOCOL | mqtt.protocol | -| IOTA_MQTT_HOST | mqtt.host | -| IOTA_MQTT_PORT | mqtt.port | -| IOTA_MQTT_CA | mqtt.ca | -| IOTA_MQTT_CERT | mqtt.cert | -| IOTA_MQTT_KEY | mqtt.key | -| IOTA_MQTT_REJECT_UNAUTHORIZED | mqtt.rejectUnauthorized | -| IOTA_MQTT_USERNAME | mqtt.username | -| IOTA_MQTT_PASSWORD | mqtt.password | -| IOTA_MQTT_QOS | mqtt.qos | -| IOTA_MQTT_RETAIN | mqtt.retain | -| IOTA_MQTT_RETRIES | mqtt.retries | -| IOTA_MQTT_RETRY_TIME | mqtt.retryTime | -| IOTA_MQTT_KEEPALIVE | mqtt.keepalive | -| IOTA_MQTT_AVOID_LEADING_SLASH | mqtt.avoidLeadingSlash | -| IOTA_MQTT_CLEAN | mqtt.clean | -| IOTA_MQTT_CLIENT_ID | mqtt.clientId | -| IOTA_MQTT_DISABLED | mqtt.disabled | -| IOTA_MQTT_DISABLE_SHARED_SUBSCRIPTIONS | mqtt.sharedSubscriptionsDisabled| -| IOTA_MQTT_GROUP_ID_SUFIX | mqtt.groupIdSufix | -| IOTA_AMQP_HOST | amqp.host | -| IOTA_AMQP_PORT | amqp.port | -| IOTA_AMQP_USERNAME | amqp.username | -| IOTA_AMQP_PASSWORD | amqp.password | -| IOTA_AMQP_EXCHANGE | amqp.exchange | -| IOTA_AMQP_QUEUE | amqp.queue | -| IOTA_AMQP_DURABLE | amqp.durable | -| IOTA_AMQP_RETRIES | amqp.retries | -| IOTA_AMQP_RETRY_TIME | amqp.retryTime | -| IOTA_AMQP_DISABLED | amqp.disabled | -| IOTA_HTTP_HOST | http.host | -| IOTA_HTTP_PORT | http.port | -| IOTA_HTTP_TIMEOUT | http.timeout | -| IOTA_HTTP_KEY | http.key | -| IOTA_HTTP_CERT | http.cert | - +| Environment variable | Configuration attribute | +| :------------------------------------- | :------------------------------- | +| IOTA_MQTT_PROTOCOL | mqtt.protocol | +| IOTA_MQTT_HOST | mqtt.host | +| IOTA_MQTT_PORT | mqtt.port | +| IOTA_MQTT_CA | mqtt.ca | +| IOTA_MQTT_CERT | mqtt.cert | +| IOTA_MQTT_KEY | mqtt.key | +| IOTA_MQTT_REJECT_UNAUTHORIZED | mqtt.rejectUnauthorized | +| IOTA_MQTT_USERNAME | mqtt.username | +| IOTA_MQTT_PASSWORD | mqtt.password | +| IOTA_MQTT_QOS | mqtt.qos | +| IOTA_MQTT_RETAIN | mqtt.retain | +| IOTA_MQTT_RETRIES | mqtt.retries | +| IOTA_MQTT_RETRY_TIME | mqtt.retryTime | +| IOTA_MQTT_KEEPALIVE | mqtt.keepalive | +| IOTA_MQTT_AVOID_LEADING_SLASH | mqtt.avoidLeadingSlash | +| IOTA_MQTT_CLEAN | mqtt.clean | +| IOTA_MQTT_CLIENT_ID | mqtt.clientId | +| IOTA_MQTT_DISABLED | mqtt.disabled | +| IOTA_MQTT_DISABLE_SHARED_SUBSCRIPTIONS | mqtt.sharedSubscriptionsDisabled | +| IOTA_MQTT_GROUP_ID_SUFIX | mqtt.groupIdSufix | +| IOTA_AMQP_HOST | amqp.host | +| IOTA_AMQP_PORT | amqp.port | +| IOTA_AMQP_USERNAME | amqp.username | +| IOTA_AMQP_PASSWORD | amqp.password | +| IOTA_AMQP_EXCHANGE | amqp.exchange | +| IOTA_AMQP_QUEUE | amqp.queue | +| IOTA_AMQP_DURABLE | amqp.durable | +| IOTA_AMQP_RETRIES | amqp.retries | +| IOTA_AMQP_RETRY_TIME | amqp.retryTime | +| IOTA_AMQP_DISABLED | amqp.disabled | +| IOTA_HTTP_HOST | http.host | +| IOTA_HTTP_PORT | http.port | +| IOTA_HTTP_TIMEOUT | http.timeout | +| IOTA_HTTP_KEY | http.key | +| IOTA_HTTP_CERT | http.cert | #### High performance configuration diff --git a/docs/roadmap.md b/docs/roadmap.md index 7803fffd..a8d83877 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -5,8 +5,8 @@ This product is a FIWARE Generic Enabler. If you would like to learn about the o ### Introduction -This IoT Agent uses the [FIWARE IoT Agent Node.js Library](https://github.com/telefonicaid/iotagent-node-lib) framework. -This is why most of the functionalities of this component depend on the new features of the library itself. +This IoT Agent uses the [FIWARE IoT Agent Node.js Library](https://github.com/telefonicaid/iotagent-node-lib) framework. +This is why most of the functionalities of this component depend on the new features of the library itself. For this reason, the roadmap of this component would be defined by the IoT Agent Node Library Roadmap that you can check [here](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/roadmap.md) diff --git a/docs/usermanual.md b/docs/usermanual.md index fa39c4cd..9b79f408 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -149,65 +149,64 @@ then the NGSI v2 update uses `10`(number), `true` (boolean) and `78.8` (number) (string) and "78.8" (string). This functionality relies on string measures casting feature implemented in the iotagent library. This functionality -uses native JavaScript [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) -function to cast data coming from measures (as text) to JSON native types. +uses native JavaScript +[`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) function +to cast data coming from measures (as text) to JSON native types. In order to use it, the `autocast` configuration parameter has to be set to true. Please see [configuration section of iotagent library](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/installationguide.md#global-configuration) for further information. This functionality does not change the attribute type, using the type specified in the config group or device provision. - + As an example, for a given measure: - + ``` -a|1|b|1.01|c|true|d|null|e|[1,2,3]|f|['a','b','c']|g|{a:1,b:2,c:3}|h|I'm a string +a|1|b|1.01|c|true|d|null|e|[1,2,3]|f|['a','b','c']|g|{a:1,b:2,c:3}|h|I'm a string ``` The resulting entity would be something like: ```json { - "id": "entityid:001", - "type": "entitytype", - "a": { - "type": "provisionedType", - "value": 1 - }, - "b": { - "type": "provisionedType", - "value": 1.01 - }, - "c": { - "type": "provisionedType", - "value": true - }, - "d": { - "type": "provisionedType", - "value": null - }, - "e": { - "type": "provisionedType", - "value": [1,2,3] - }, - "f": { - "type": "provisionedType", - "value": ["a","b","c"] - }, - "g": { - "type": "provisionedType", - "value": {"a":1,"b":2,"c":3} - }, - "h": { - "type": "provisionedType", - "value": "I'm a string" - } + "id": "entityid:001", + "type": "entitytype", + "a": { + "type": "provisionedType", + "value": 1 + }, + "b": { + "type": "provisionedType", + "value": 1.01 + }, + "c": { + "type": "provisionedType", + "value": true + }, + "d": { + "type": "provisionedType", + "value": null + }, + "e": { + "type": "provisionedType", + "value": [1, 2, 3] + }, + "f": { + "type": "provisionedType", + "value": ["a", "b", "c"] + }, + "g": { + "type": "provisionedType", + "value": { "a": 1, "b": 2, "c": 3 } + }, + "h": { + "type": "provisionedType", + "value": "I'm a string" + } } ``` -Note that `provisionedType` is the type included in the device provision or config group, and it is not changed. - - +Note that `provisionedType` is the type included in the device provision or config group, and it is not changed. ### Transport Protocol @@ -314,8 +313,8 @@ are prefixed with the agent procotol: where `` is the API Key assigned to the service and `` is the ID of the device. -> **Note** By default the IoT Agent uses shared subscriptions with the group ID 'ul': -> To changes this behaviour either set the IOTA_MQTT_DISABLE_SHARED_SUBSCRIPTIONS or IOTA_MQTT_GROUP_ID_SUFIX environment variable. +> **Note** By default the IoT Agent uses shared subscriptions with the group ID 'ul': To changes this behaviour either +> set the IOTA_MQTT_DISABLE_SHARED_SUBSCRIPTIONS or IOTA_MQTT_GROUP_ID_SUFIX environment variable. All topics published by the agent (to send a comamnd or to send configuration information) to a device are not prefixed by the protocol, in this case '/ul', just include apikey and deviceid (e.g: `/FF957A98/MydeviceId/cmd` and @@ -323,19 +322,16 @@ by the protocol, in this case '/ul', just include apikey and deviceid (e.g: `/FF > **Note** Measures and commands are sent over different MQTT topics: > -> * _Measures_ are sent on the `////attrs` topic, -> * _Commands_ are sent on the `///cmd` topic, +> - _Measures_ are sent on the `////attrs` topic, +> - _Commands_ are sent on the `///cmd` topic, > -> The reasoning behind this is that when sending measures northbound from device to IoT Agent, -> it is necessary to explicitly identify which IoT Agent is needed to parse the data. This -> is done by prefixing the relevant MQTT topic with a protocol, otherwise there is no way to -> define which agent is processing the measure. This mechanism allows smart systems to connect -> different devices to different IoT Agents according to need. +> The reasoning behind this is that when sending measures northbound from device to IoT Agent, it is necessary to +> explicitly identify which IoT Agent is needed to parse the data. This is done by prefixing the relevant MQTT topic +> with a protocol, otherwise there is no way to define which agent is processing the measure. This mechanism allows +> smart systems to connect different devices to different IoT Agents according to need. > -> For southbound commands, this distinction is unnecessary since the correct IoT Agent has already -> registered itself for the command during the device provisioning step and the device will always -> receive commands in an appropriate format. - +> For southbound commands, this distinction is unnecessary since the correct IoT Agent has already registered itself for +> the command during the device provisioning step and the device will always receive commands in an appropriate format. This transport protocol binding is still under development.