<commit_before># User & Programmers Manual

## Index

* [API Overview](#apioverview)
  * [Ultralight 2.0 Protocol](#ultralight-20-protocol)
  * [Transport Protocol](#transport-protocol)
* [Developing new transports](#developing-new-transports)
* [Development documentation](#development-documentation)

## <a name="apioverview"></a> API Overview
This section describes the specific South-bound API implemented by this IoTAgent. For the Configuration API and other
APIs concerning general IoTAgents, check the [API Reference section](#apireference);

### Ultralight 2.0 Protocol
#### Description
Ultralight 2.0 is a lightweight text based protocol aimed to constrained devices and communications where the
bandwidth and device memory may be limited resources.

#### Measure Payload Syntax
The payload for information update requests is composed of a list of key-value pairs separated by the '|' character. E.g.:
```
t|15|k|abc
```
In this example, two attributes, one named "t" with value "15" and another named "k" with value "abc" are transmitted.
Values in Ultralight 2.0 are not typed (everything is treated as a string).

Multiple groups of measures can be combined into a single request, using the '#' character. In that case, a different
NGSI request will be generated for each group of measures. E.g.:
```
gps|1.2/3.4#t|10
```
This will generate two NGSI requests for the same entity, one for each one of the values. Each one of those requests
can contain any number of attributes.

Measure groups can additionaly have an optional timestamp, with the following syntax:
```
2016-06-13T00:35:30Z|lle|100
```
The timestamp will be added as a prefix of the measures themselves, separated by a '|'. The attribute will be translated
to a `TimeInstant` attribute in the final entity.T

#### Active versus passive attributes
Current version of the agent only supports active attributes, i.e. those attributes actively reported
+by the device to the agent. Passive or lazy attributes, i.e. those attributes whose value is only given upon explicit
+request from the agent, are not implemented. Please check the issue
+[#23](https://github.com/telefonicaid/iotagent-ul/issues/23) for more details and updates regarding its implementation.

#### Commands Syntax
Commands are messages sent to the device from the IoT Agent. A command has the following format:
```
<device name>@<command name>|<command value>
```
This indicates that the device (named 'device_name' in the Context Broker) has to execute the command 'command_name', with
the given value. E.g.:
```
Robot1@turn|left
```
This example will tell the Robot 1 to turn to left.

In the case of complex commands requiring parameters, the `command_value` could be used to implement parameter passing. E.g:
```
weatherStation167@ping|param1:1|param2:2
```
This example will tell the Weather Station 167 to reply to a ping message with the provided params. Note that `=` cannot be used instead of `:` given that `=` is [a forbidden character for Context Broker](https://fiware-orion.readthedocs.io/en/master/user/forbidden_characters/index.html), so the update at CB triggering the command would be never progressed.

Once the command has finished its execution in the device, the reply to the server must adhere to the following format:
```
<device name>@<command name>|result
```
Where `device_name` and `command_name` must be the same ones used in the command execution, and the result is the
final result of the command. E.g.:
```
weatherStation167@ping|Ping ok
```
In this case, the Weather station replies with a String value indicating everything has worked fine.

#### Bidirectionality Syntax
The latest versions of the Provisioning API allow for the definition of reverse expressions to keep data shared between
the Context Broker and the device in sync (regardless of whether the data originated in plain data from the device or
in a transformation expression in the IoTAgent). In this cases, when a reverse expression is defined, whenever the
bidirectional attribute is modified, the IoTAgent sends a command to the original device, with the name defined in the
reverse expression attribute and the ID of the device (see Commands Syntax, just above).


#### Casting to Json native format
Ultralight 2.0 defines a method that allows to use native JSON types in the NGSIv2. For example:
The IotAgent receives this UL measure:
```
t|10|s|true|l|78.8
```
then the NGSIv2 update uses ```10```(number), ```true``` (boolean) and ```78.8``` (number) instead of "10" (string), "true" (string) and "78.8" (string).

This functionality relies on string measures casting feature implemented in the iotagent library. In order to use it, the `autocast` configuration parameter has to be set to true. Please see [https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/installationguide.md#global-configuration] for more detail.

### Transport Protocol
Ultralight 2.0 defines a payload describing measures and commands to share between devices and servers but, does not
specify a single transport protocol. Instead, different transport protocol bindings can be established for different
scenarios.
<commit_msg>Address comments of PR#242<commit_after># User & Programmers Manual

## Index

* [API Overview](#apioverview)
  * [Ultralight 2.0 Protocol](#ultralight-20-protocol)
  * [Transport Protocol](#transport-protocol)
* [Developing new transports](#developing-new-transports)
* [Development documentation](#development-documentation)

## <a name="apioverview"></a> API Overview
This section describes the specific South-bound API implemented by this IoTAgent. For the Configuration API and other
APIs concerning general IoTAgents, check the [API Reference section](#apireference);

### Ultralight 2.0 Protocol
#### Description
Ultralight 2.0 is a lightweight text based protocol aimed to constrained devices and communications where the
bandwidth and device memory may be limited resources.

#### Measure Payload Syntax
The payload for information update requests is composed of a list of key-value pairs separated by the '|' character. E.g.:
```
t|15|k|abc
```
In this example, two attributes, one named "t" with value "15" and another named "k" with value "abc" are transmitted.
Values in Ultralight 2.0 are not typed (everything is treated as a string).

Multiple groups of measures can be combined into a single request, using the '#' character. In that case, a different
NGSI request will be generated for each group of measures. E.g.:
```
gps|1.2/3.4#t|10
```
This will generate two NGSI requests for the same entity, one for each one of the values. Each one of those requests
can contain any number of attributes.

Measure groups can additionaly have an optional timestamp, with the following syntax:
```
2016-06-13T00:35:30Z|lle|100
```
The timestamp will be added as a prefix of the measures themselves, separated by a '|'. The attribute will be translated
to a `TimeInstant` attribute in the final entity.T

#### Active versus passive attributes
Current version of the agent only supports active attributes, i.e. those attributes actively reported
+by the device to the agent. Passive or lazy attributes, i.e. those attributes whose value is only given upon explicit
+request from the agent, are not implemented. Please check the issue
+[#23](https://github.com/telefonicaid/iotagent-ul/issues/23) for more details and updates regarding its implementation.

#### Commands Syntax
Commands are messages sent to the device from the IoT Agent. A command has the following format:
```
<device name>@<command name>|<command value>
```
This indicates that the device (named 'device_name' in the Context Broker) has to execute the command 'command_name', with
the given value. E.g.:
```
Robot1@turn|left
```
This example will tell the Robot 1 to turn to left.

In the case of complex commands requiring parameters, the `command_value` could be used to implement parameter passing. E.g:
```
weatherStation167@ping|param1:1|param2:2
```
This example will tell the Weather Station 167 to reply to a ping message with the provided params. Note that `=` cannot be used instead of `:` given that `=` is [a forbidden character for Context Broker](https://fiware-orion.readthedocs.io/en/master/user/forbidden_characters/index.html), so the update at CB triggering the command would be never progressed.

Once the command has finished its execution in the device, the reply to the server must adhere to the following format:
```
<device name>@<command name>|result
```
Where `device_name` and `command_name` must be the same ones used in the command execution, and the result is the
final result of the command. E.g.:
```
weatherStation167@ping|Ping ok
```
In this case, the Weather station replies with a String value indicating everything has worked fine.

#### Bidirectionality Syntax
The latest versions of the Provisioning API allow for the definition of reverse expressions to keep data shared between
the Context Broker and the device in sync (regardless of whether the data originated in plain data from the device or
in a transformation expression in the IoTAgent). In this cases, when a reverse expression is defined, whenever the
bidirectional attribute is modified, the IoTAgent sends a command to the original device, with the name defined in the
reverse expression attribute and the ID of the device (see Commands Syntax, just above).


#### Casting to Json native format
Ultralight 2.0 defines a method that allows to use native JSON types in the NGSIv2. For example:
The IotAgent receives this UL measure:
```
t|10|s|true|l|78.8
```
then the NGSIv2 update uses ```10```(number), ```true``` (boolean) and ```78.8``` (number) instead of "10" (string), "true" (string) and "78.8" (string).

This functionality relies on string measures casting feature implemented in the iotagent library. 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.

### Transport Protocol
Ultralight 2.0 defines a payload describing measures and commands to share between devices and servers but, does not
specify a single transport protocol. Instead, different transport protocol bindings can be established for different
scenarios.

{'fraction_non_alphanumeric': 0.07958044649730563, 'fraction_numerical': 0.015107775211701308, 'mean_word_length': 5.092028135990621, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1829863', 'n_tokens_mistral': 2858, 'n_tokens_neox': 2647, 'n_words': 1389}