[Doc Rework] Devel files

README.md

@@ -21,8 +21,7 @@ This project is part of [FIWARE](https://www.fiware.org/). For more information
 [IoT Agents](https://github.com/Fiware/catalogue/tree/master/iot-agents).
 
 | :books: [Documentation](https://iotagent-node-lib.rtfd.io) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | :dart: [Roadmap](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/roadmap.md) |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 
 ## Index
 
@@ -76,16 +75,18 @@ const iotagentLib = require('iotagent-node-lib');
 ```
 
 Information about how to configure the Library can be found at the corresponding section of the
-[Installation & Administration Guide](doc/installationguide.md).
+[Installation & Administration Guide](doc/admin.md).
 
 ## Usage
 
-This library has no packaging or build processes. The [Getting Started](doc/getting-started.md) is a good place to
-start. Usage of the library is explained in the [User & Programmers Manual](doc/usermanual.md).
+This library has no packaging or build processes. The [Getting Started](./doc/getting-started.md) is a good place to
+start. You can also review the [API documentation](./doc/api.md) for a full list of the available functions.
+
+If you plan to use the library in your own IoT Agent, you should read the [Developer Guide](./doc/devel/development.md).
+You can also review the [Architecture](./doc/devel/architecture.md) documentation and
+[Northbound API](./doc/devel/northbound-api.md).
 
--   Details of the architecture of an IoT Agent be found [here](doc/architecture.md).
--   Further Advanced topics can be found [here](doc/advanced-topics.md).
--   The following features are listed as [deprecated](doc/deprecated.md).
+The following features are listed as [deprecated](doc/deprecated.md).
 
 ## API
 
@@ -94,7 +95,7 @@ decommission devices. [API](doc/api.md).
 
 ## Testing
 
-Contributions to development can be found [here](doc/development.md) - additional contributions are welcome.
+Contributions to development can be found [here](doc/devel/development.md) - additional contributions are welcome.
 
 ### Agent Console
 

doc/admin.md

@@ -50,7 +50,9 @@ adding the following line to the `package.json` file:
 
 wher `x.y.z` is an actual version number.
 
-As alternative, you can use the master branch as dependency. In this case, you will be using the latest version of the code but note that some instability could exist (as the code in master is work in progress until the next version is closed).
+As alternative, you can use the master branch as dependency. In this case, you will be using the latest version of the
+code but note that some instability could exist (as the code in master is work in progress until the next version is
+closed).
 
 ```json
 ...
@@ -403,7 +405,7 @@ When enabled, the IoT Agents runs in multi-thread environment to take advantage
 values `true` or `false`. This attribute is optional with default to false, which means that the IoTAgent runs in a
 single thread. For more details about multi-core functionality, please refer to the
 [Cluster](https://nodejs.org/api/cluster.html) module in Node.js and
-[this section](howto.md#iot-agent-in-multi-thread-mode) of the library documentation.
+[this section](devel/development.md#iot-agent-in-multi-thread-mode) of the library documentation.
 
 #### `fallbackTenant`
 

doc/api.md

@@ -31,7 +31,6 @@
         -   [Multientity measurement transformation support (`object_id`)](#multientity-measurement-transformation-support-object_id)
     -   [Timestamp Compression](#timestamp-compression)
     -   [Timestamp Processing](#timestamp-processing)
-    -   [Bidirectionality plugin (bidirectional)](#bidirectionality-plugin-bidirectional)
     -   [Overriding global Context Broker host](#overriding-global-context-broker-host)
     -   [Multitenancy, FIWARE Service and FIWARE ServicePath](#multitenancy-fiware-service-and-fiware-servicepath)
     -   [Secured access to the Context Broker](#secured-access-to-the-context-broker)
@@ -185,8 +184,6 @@ Some transformation plugins also allow the use of the following optional fields:
     with the `entity_type` attribute. If no type is configured, the device entity type is used instead. Entity names can
     be defined as expressions, using the [Expression Language definition](#expression-language-support).
 -   **entity_type**: configures the type of an alternative entity.
--   **reverse**: add bidirectionality expressions to the attribute. See the **bidirectionality** transformation plugin
-    in the [Data Mapping Plugins section](development.md#bidirectionality-plugin-bidirectional) for details.
 
 Additionally for commands (which are attributes of type `command`) the following fields are optional:
 
@@ -439,10 +436,9 @@ depending on the JEXL expression evaluation:
 ### Configuring operation to persist the data in Context Broker (appendMode)
 
 This is a flag that can be enabled by activating the parameter `appendMode` in the configuration file or by using the
-`IOTA_APPEND_MODE` environment variable (more info
-[here](admin.md)). If this flag is activated, the
-update requests to the Context Broker will be performed always with APPEND type, instead of the default UPDATE. This
-have implications in the use of attributes with Context Providers, so this flag should be used with care.
+`IOTA_APPEND_MODE` environment variable (more info [here](admin.md)). If this flag is activated, the update requests to
+the Context Broker will be performed always with APPEND type, instead of the default UPDATE. This have implications in
+the use of attributes with Context Providers, so this flag should be used with care.
 
 ### Differences between `autoprovision`, `explicitAttrs` and `appendMode`
 
@@ -853,54 +849,6 @@ The IOTA processes the entity attributes looking for a `TimeInstant` attribute.
 adds a `TimeInstant` attribute as metadata for every other attribute in the same request. With NGSI-LD, the Standard
 `observedAt` property-of-a-property is used instead.
 
-## Bidirectionality plugin (bidirectional)
-
-This plugin allows the devices with composite values an expression to update the original values in the devices when the
-composite expressions are updated in the Context Broker. This behavior is achieved through the use of subscriptions.
-
-IoTAs using this plugins should also define a notification handler to handle incoming values. This handler will be
-intercepted by the plugin, so the mapped values are included in the updated notification.
-
-When a device is provisioned with bidirectional attributes, the IoTAgent subscribes to changes in that attribute. When a
-change notification for that attribute arrives to the IoTA, it applies the transformation defined in the device
-provisioning payload to the notification, and calls the underlying notification handler with the transformed entity
-including the `value` along with any `metadata`, and in the case of an NGSI-LD bidirectional attribute a `datasetId` if
-provided.
-
-The following `attributes` section shows an example of the plugin configuration (using `IOTA_AUTOCAST=false` to avoid
-translation from geo:point to geo:json)
-
-```json
-      "attributes": [
-        {
-          "name":"location",
-          "type":"geo:point",
-          "expression": "latitude, longitude",
-          "reverse": [
-            {
-              "object_id":"longitude",
-              "type": "Number",
-              "expression": "location | split(', ')[0] | parsefloat()"
-            },
-            {
-              "object_id":"latitude",
-              "type": "Number",
-              "expression": "location | split(', ')[1] | parsefloat()"
-            }
-          ]
-        }
-      ],
-```
-
-For each attribute that would have bidirectionality, a new field `reverse` must be configured. This field will contain
-an array of fields that will be created based on the notifications content. The expression notification can contain any
-attribute of the same entity as the bidirectional attribute; declaring them in the expressions will add them to the
-subscription payload.
-
-For each attribute in the `reverse` array, an expression must be defined to calculate its value based on the
-notification attributes. This value will be passed to the underlying protocol with the `object_id` name. Details about
-how the value is then progressed to the device are protocol-specific.
-
 ## Overriding global Context Broker host
 
 **cbHost**: Context Broker host URL. This option can be used to override the global CB configuration for specific types

doc/architecture.md → doc/devel/architecture.md

@@ -1,6 +1,6 @@
 ## Architecture
 
-The following section defines the archtecture and message flow which is common to all IoT Agents which use the library.
+The following section defines the architecture and message flow which is common to all IoT Agents which use the library.
 
 ### Device to NGSI Mapping
 
@@ -32,7 +32,7 @@ basis preprovisioning the devices). Device measures can have three different beh
 The following sequence diagram shows the different NGSI interactions an IoT Agent makes with the Context Broker,
 explained in the following subsections (using the example of a OMA Lightweight M2M device).
 
-![General ](./img/ngsiInteractions.png "NGSI Interactions")
+![General ](../img/ngsiInteractions.png 'NGSI Interactions')
 
 Be aware that the IoT Agents are only required to support NGSI10 operations `updateContext` and `queryContext` in their
 standard formats (currently in JSON format; XML deprecated) but will not answer to NGSI9 operations (or NGSI convenience
@@ -254,7 +254,7 @@ the concrete IoT Agent implementations will be to map between the native device
 The following figure offers a graphical example of how a COAP IoT Agent work, ordered from the registration of the
 device to a command update to the device.
 
-![General ](./img/iotAgentLib.png "Architecture Overview")
+![General ](../img/iotAgentLib.png 'Architecture Overview')
 
 ### The `TimeInstant` element
 

doc/Contribution.md → doc/devel/contribution-guidelines.md

@@ -4,21 +4,22 @@
 
 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
-  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
-  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
-  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.
+-   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
+    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
+    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.
 
 ## How to contribute
 
-If you'd like to contribute, start by searching through the [issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and
-[pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) to see whether someone else has raised a similar idea or
-question.
+If you'd like to contribute, start by searching through the
+[issues](https://github.com/telefonicaid/iotagent-node-lib/issues) and
+[pull requests](https://github.com/telefonicaid/iotagent-node-lib/pulls) to see whether someone else has raised a
+similar idea or question.
 
 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,36 +29,43 @@ 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)) 
-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)
-* Comments lifecycle
-  * 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)
-    * `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
-    * All the participants in the discussion have provided a `LGTM` general comment (LGTM = Looks good to me)
- * Self-merging is not allowed (except in rare and justified circumstances)
+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)
+-   Comments lifecycle
+    -   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)
+        -   `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
+    -   All the participants in the discussion have provided a `LGTM` general comment (LGTM = Looks good to me)
+-   Self-merging is not allowed (except in rare and justified circumstances)
 
 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.