Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added option to turn shared subscription off or change the group identifier #754

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Added option to turn shared subscription off or change the group identifier #754

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c5c256
Twin PR for iotagent-ul
fbuedding Sep 26, 2023
46d46c6
update MQTTBindings.js
fbuedding Sep 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,4 @@
npm-debug.log
.eslintcache

pnpm-lock.yaml
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ library's GitHub repository.
This project is part of [FIWARE](https://www.fiware.org/). For more information check the FIWARE Catalogue entry for the
[IoT Agents](https://github.com/Fiware/catalogue/tree/master/iot-agents).

| :books: [Documentation](https://fiware-iotagent-json.readthedocs.io) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | <img style="height:1em" src="https://quay.io/static/img/quay_favicon.png"/> [quay.io](https://quay.io/repository/fiware/iotagent-json) | :whale: [Docker Hub](https://hub.docker.com/r/telefonicaiot/iotagent-json/) | :dart: [Roadmap](https://github.com/telefonicaid/iotagent-json/blob/master/docs/roadmap.md) |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --- |
| :books: [Documentation](https://fiware-iotagent-json.readthedocs.io) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | <img style="height:1em" src="https://quay.io/static/img/quay_favicon.png"/> [quay.io](https://quay.io/repository/fiware/iotagent-json) | :whale: [Docker Hub](https://hub.docker.com/r/telefonicaiot/iotagent-json/) | :dart: [Roadmap](https://github.com/telefonicaid/iotagent-json/blob/master/docs/roadmap.md) |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |


## Contents
Expand Down
2 changes: 1 addition & 1 deletion config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,7 @@ config.iota = {

/**
* map {name: function} of extra transformations avaliable at JEXL plugin
* see https://github.com/telefonicaid/iotagent-node-lib/tree/master/doc/expressionLanguage.md#available-functions
* see https://github.com/telefonicaid/iotagent-node-lib/tree/master/doc/expressionLanguage.md#available-functions
*/

config.jexlTransformations = {};
Expand Down
54 changes: 33 additions & 21 deletions docs/contribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,24 @@

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-json/issues) and
[pull requests](https://github.com/telefonicaid/iotagent-json/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-json/issues) and
[pull requests](https://github.com/telefonicaid/iotagent-json/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:

Expand All @@ -28,18 +31,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 <commit hash>` in case the discussion involves a fix in the PR branch (which commit hash is included as reference)
- `Fixed in <commit hash>` 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
Expand All @@ -48,16 +55,21 @@ 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-json/issues) and [Pull Requests](https://github.com/telefonicaid/iotagent-json/pulls)
and also in the IoT Agent Node Lib repository ([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-json/issues) and
[Pull Requests](https://github.com/telefonicaid/iotagent-json/pulls) and also in the IoT Agent Node Lib repository
([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.

Expand Down
14 changes: 7 additions & 7 deletions docs/deprecated.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,10 @@ in the case you want to use old versions:

The following table provides information about the last iotagent-json version supporting currently removed features:

| **Removed feature** | **Last iotagent-json version supporting feature** | **That version release date** |
| ---------------------- | --------------------------------------------------- | ----------------------------- |
| NGSIv1 API | 1.17.0 | February 18th, 2021 |
| Support to Node.js v4 | 1.9.0 | December 19th, 2018 |
| Support to Node.js v6 | 1.10.0 | May 22nd, 2019 |
| Support to Node.js v8 | 1.14.0 | April 7th, 2020 |
| Support to Node.js v10 | 1.17.0 | February 18th, 2021 |
| **Removed feature** | **Last iotagent-json version supporting feature** | **That version release date** |
| ---------------------- | ------------------------------------------------- | ----------------------------- |
| NGSIv1 API | 1.17.0 | February 18th, 2021 |
| Support to Node.js v4 | 1.9.0 | December 19th, 2018 |
| Support to Node.js v6 | 1.10.0 | May 22nd, 2019 |
| Support to Node.js v8 | 1.14.0 | April 7th, 2020 |
| Support to Node.js v10 | 1.17.0 | February 18th, 2021 |
80 changes: 43 additions & 37 deletions docs/installationguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,8 +136,12 @@ These are the currently available MQTT configuration options:
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
`iotajson_` and a random suffix, i.e. `iotajson_43bf8a3a`.
- **clientId**: string ID which identifies client in mqtt broker. By default is using a string composed by a fixed
prefix `iotajson_` and a random suffix, i.e. `iotajson_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

TLS options (i.e. **ca**, **cert**, **key**, **rejectUnauthorized**) are directly linked with the ones supported by the
[tls module of Node.js](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options).
Expand Down Expand Up @@ -183,41 +187,43 @@ The ones relating global configuration described in the following table.

The ones relating specific JSON 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_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 |

(HTTP-related environment variables will be used in the upcoming HTTP binding)

Expand Down
4 changes: 2 additions & 2 deletions docs/roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
11 changes: 8 additions & 3 deletions docs/usermanual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,9 +236,14 @@ ID of the device involved in the interaction; i.e.: there is a different set of
`/json/FF957A98/MyDeviceId/attrs`). The API Key is a secret identifier shared among all the devices of a service, and
the DeviceID is an ID that uniquely identifies the device in a service. API Keys can be configured with the IoTA
Configuration API or the public default API Key of the IoT Agent can be used in its stead. The Device ID must be
provisioned in advance in the IoT Agent before information is sent. All topis 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 '/json', just include
apikey and deviceid (e.g: `/FF957A98/MyDeviceId/cmd` and `/FF957A98/MyDeviceId/configuration/values` ).
provisioned in advance in the IoT Agent before information is sent.

> **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 '/json', just include apikey and deviceid (e.g: `/FF957A98/MyDeviceId/cmd` and
`/FF957A98/MyDeviceId/configuration/values` ).

> **Note** Measures and commands are sent over different MQTT topics:
>
Expand Down
Loading