Skip to content

Commit

Permalink
Fix DOC
Browse files Browse the repository at this point in the history
  • Loading branch information
@mapedraza
mapedraza committed Aug 26, 2024
1 parent 517cdb7 commit b94b414
Show file tree
Hide file tree
Showing 4 changed files with 80 additions and 70 deletions.
71 changes: 37 additions & 34 deletions doc/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,10 @@
- [Config group API](#config-group-api)
- [Config group datamodel](#config-group-datamodel)
- [Config group operations](#config-group-operations)
- [Retrieve config groups `GET /iot/services`](#retrieve-config-groups-get-iotservices)
- [Create config group `POST /iot/services`](#create-config-group-post-iotservices)
- [Modify config group `PUT /iot/services`](#modify-config-group-put-iotservices)
- [Remove config group `DELETE /iot/services`](#remove-config-group-delete-iotservices)
- [Retrieve config groups `GET /iot/groups`](#retrieve-config-groups-get-iotgroups)
- [Create config group `POST /iot/groups`](#create-config-group-post-iotgroups)
- [Modify config group `PUT /iot/groups`](#modify-config-group-put-iotgroups)
- [Remove config group `DELETE /iot/groups`](#remove-config-group-delete-iotgroups)
- [Device API](#device-api)
- [Device datamodel](#device-datamodel)
- [Device operations](#device-operations)
Expand Down Expand Up @@ -136,9 +136,9 @@ For every config group, the pair (resource, apikey) _must_ be unique (as it is u
which device). Those operations of the API targeting specific resources will need the use of the `resource` and `apikey`
parameters to select the appropriate instance.

Config groups can be created with preconfigured sets of attributes, service and subservice information, security information and other
parameters. The specific parameters that can be configured for a given config group are described in the
[Config group datamodel](#config-group-datamodel) section.
Config groups can be created with preconfigured sets of attributes, service and subservice information, security
information and other parameters. The specific parameters that can be configured for a given config group are described
in the [Config group datamodel](#config-group-datamodel) section.

### Devices

Expand Down Expand Up @@ -218,7 +218,7 @@ device preprovisioning). Device measures can have four different behaviors:
an attribute in the device's entity, for which the IoT Agent will be regitered as Context Provider. The IoT Agent
will return an immediate response to the Context Broker, and will be held responsible of contacting the device to
perform the command itself using the device specific protocol. Special `status` and `info` attributes should be
update. For each command, its `name` and `type` must be provided. For further information, please refer to
update. For each command, its `name` and `type` must be provided. For further information, please refer to
[Command execution](#command-execution) section.

All of them have the same syntax, a list of objects with the following attributes:
Expand Down Expand Up @@ -565,17 +565,18 @@ expression. In all cases the following data is available to all expressions:
- `id`: device ID
- `entity_name`: NGSI entity Name (principal)
- `type`: NGSI entity type (principal)
- `service`: device service (`Fiware-Service`)
- `service`: device service (`Fiware-Service`)
- `subservice`: device subservice (`Fiware-ServicePath`)
- `staticAttributes`: static attributes defined in the device or config group

Additionally, for attribute expressions (`expression`, `entity_name`), `entityNameExp` and metadata expressions
(`expression`) the following is available in the **context** used to evalute:

- measures, as `<AttributeName>`
- metadata (both for attribute measurement in the case of NGSI-v2 measurements and static attribute) are available in the **context** under the following convention:
`metadata.<AttributeName>.<MetadataName>` or `metadata.<StaticAttributeName>.<MetadataName>` in a similar way of defined
for [Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support)
- measures, as `<AttributeName>`
- metadata (both for attribute measurement in the case of NGSI-v2 measurements and static attribute) are available in
the **context** under the following convention: `metadata.<AttributeName>.<MetadataName>` or
`metadata.<StaticAttributeName>.<MetadataName>` in a similar way of defined for
[Context Broker](https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#metadata-support)

### Examples of JEXL expressions

Expand Down Expand Up @@ -736,7 +737,8 @@ e.g.:
}
```

Note that there is no order into metadata structure and there is no warranty about which metadata attribute expression will be evaluated first.
Note that there is no order into metadata structure and there is no warranty about which metadata attribute expression
will be evaluated first.

## Measurement transformation

Expand Down Expand Up @@ -1070,21 +1072,21 @@ As part of the device to entity mapping process, the IoT Agent creates and updat
attribute called `TimeInstant`. This timestamp is represented as two different properties of the mapped entity:

- An attribute `TimeInstant` is added to updated entities in the case of NGSI-v2, which captures as an ISO8601
timestamp when the associated measurement was observed. With NGSI-LD, the Standard
`observedAt` property is used instead
timestamp when the associated measurement was observed. With NGSI-LD, the Standard `observedAt` property is used
instead

- With NGSI-v2, an attribute metadata named `TimeInstant` per active or lazy attribute mapped, which captures as an ISO8601
timestamp when the associated measurement (represented as attribute value) was observed. With NGSI-LD, the Standard
`observedAt` property-of-a-property is used instead.
- With NGSI-v2, an attribute metadata named `TimeInstant` per active or lazy attribute mapped, which captures as an
ISO8601 timestamp when the associated measurement (represented as attribute value) was observed. With NGSI-LD, the
Standard `observedAt` property-of-a-property is used instead.

If timestamp is not explicily defined when sending the measures through the IoT Agent (for further details on how to
attach timestamp information to the measures, please refer to the particular IoT Agent implementation documentation),
the arrival time on the server when receiving the measurement will be used to generate a `TimeInstant` for both the
entity attribute and the attribute metadata.

This functionality can be turned on and off globaly through the use of the `timestamp` configuration flag or `IOTA_TIMESTAMP`
variable as well as `timestamp` flag in device or group provision (in this case, the device or group level flag takes
precedence over the global one). The default value is `true`.
This functionality can be turned on and off globaly through the use of the `timestamp` configuration flag or
`IOTA_TIMESTAMP` variable as well as `timestamp` flag in device or group provision (in this case, the device or group
level flag takes precedence over the global one). The default value is `true`.

The `timestamp` configuration value used, according to the priority:

Expand All @@ -1104,6 +1106,7 @@ the IoTA behaviour is described in the following table:
| false | No | TimeInstant and metadata updated with server timestamp |
| Not defined | Yes | TimeInstant and metadata updated with measure value |
| Not defined | No | TimeInstant and metadata updated with server timestamp |

Some additional considerations to take into account:

- If there is an attribute which maps a measure to `TimeInstant` attribute (after
Expand Down Expand Up @@ -1724,7 +1727,7 @@ Config group is represented by a JSON object with the following fields:

The following actions are available under the config group endpoint:

#### Retrieve config groups `GET /iot/services`
#### Retrieve config groups `GET /iot/groups`

List all the config groups for the given `fiware-service` and `fiware-servicepath`. The config groups that match the
`fiware-servicepath` are returned in any other case.
Expand All @@ -1748,14 +1751,14 @@ Successful operations return `Content-Type` header with `application/json` value

_**Response payload**_

A JSON object with a services field that contains an array of services that match the request. See the
[config group datamodel](#service-group-datamodel) for more information.
A JSON object with a `groups` field that contains an array of groups that match the request. See the
[config group datamodel](#config-group-datamodel) for more information.

Example:

```json
{
"services": [
"groups": [
{
"resource": "/deviceTest",
"apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
Expand Down Expand Up @@ -1792,7 +1795,7 @@ Example:
}
```

#### Create config group `POST /iot/services`
#### Create config group `POST /iot/groups`

Creates a set of config groups for the given service and service path. The service and subservice information will taken
from the headers, overwritting any preexisting values.
Expand All @@ -1806,14 +1809,14 @@ _**Request headers**_

_**Request payload**_

A JSON object with a `services` field. The value is an array of config groups objects to create. See the
[config group datamodel](#service-group-datamodel) for more information.
A JSON object with a `groups` field. The value is an array of config groups objects to create. See the
[config group datamodel](#config-group-datamodel) for more information.

Example:

```json
{
"services": [
"groups": [
{
"resource": "/deviceTest",
"apikey": "801230BJKL23Y9090DSFL123HJK09H324HV8732",
Expand Down Expand Up @@ -1847,7 +1850,7 @@ _**Response headers**_

Successful operations return `Content-Type` header with `application/json` value.

#### Modify config group `PUT /iot/services`
#### Modify config group `PUT /iot/groups`

Modifies the information of a config group, identified by the `resource` and `apikey` query parameters. Takes a service
group body as the payload. The body does not have to be complete: for incomplete bodies, just the attributes included in
Expand All @@ -1869,8 +1872,8 @@ _**Request headers**_

_**Request payload**_

A JSON object with the config group information to be modified. See the
[config group datamodel](#service-group-datamodel) for more information.
A JSON object with the config group information to be modified. See the [config group datamodel](config-group-datamodel)
for more information.

Example:

Expand All @@ -1887,7 +1890,7 @@ _**Response code**_
- 400 MISSING_HEADERS if any of the mandatory headers is not present.
- 500 SERVER ERROR if there was any error not contemplated above.:

#### Remove config group `DELETE /iot/services`
#### Remove config group `DELETE /iot/groups`

Removes a config group, identified by the `resource` and `apikey` query parameters.

Expand Down
2 changes: 2 additions & 0 deletions doc/deprecated.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ A list of deprecated features and the version in which they were deprecated foll
- Bidirectinal pluging (finally removed in 3.4.0)
- appendMode configuration (`IOTA_APPEND_MODE` env var) (finally removed in 3.4.0)
- `config.stats` section, and push-mode statistics.
- Services API routes (`/iot/services`) in favor of the `/iot/groups`. Both are still supported, but the former is
deprecated.

The use of Node.js v14 is highly recommended.

Expand Down
38 changes: 19 additions & 19 deletions doc/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@

## Introduction

In this guide we will be using the IoT Agent JSON (which is the reference IoTAgent using the IoTAgent Library) as an example to demonstrate how to provision config groups, devices
and how to receive measures from devices.
In this guide we will be using the IoT Agent JSON (which is the reference IoTAgent using the IoTAgent Library) as an
example to demonstrate how to provision config groups, devices and how to receive measures from devices.

Be aware that every IoT Agent which uses the library is different, but the concepts for provisioning IoT devices remain
the same regardless of protocol.
Expand Down Expand Up @@ -52,8 +52,9 @@ config = {
```

In this case the context broker hostname is `orion` and is listening on port `1026`, the IoT Agent can be provisioned by
sending requests to port `4041` which is also the port used to receive NGSI requests. The IoT Agent is using the `iotagent`
database from a MongoDB instance at `localhost:27017` to store needed information (provisioned groups and devices, etc.).
sending requests to port `4041` which is also the port used to receive NGSI requests. The IoT Agent is using the
`iotagent` database from a MongoDB instance at `localhost:27017` to store needed information (provisioned groups and
devices, etc.).

The remaining settings help to define the NGSI interactions - the IoT Agent will be using the `fiware-service=openiot`
and `fiware-service-path=/`. The default `type`for each created entity is `Thing`, although this can be overridden as
Expand All @@ -73,12 +74,12 @@ config group is shown below:

```bash
curl -iX POST \
'http://localhost:4041/iot/services' \
'http://localhost:4041/iot/groups' \
-H 'Content-Type: application/json' \
-H 'fiware-service: openiot' \
-H 'fiware-servicepath: /' \
-d '{
"services": [
"groups": [
{
"apikey": "4jggokgpepnvsb2uv4s40d59ov",
"entity_type": "Device",
Expand All @@ -95,8 +96,8 @@ In this case an `apiKey` for identifying devices has been created and all intera
present this `apiKey` will be created as entities of `type=Device` rather than using the configuration default of
`type=Thing`.

Additionally, the group has defined an attribute mapping for a measurement `t` to be mapped to `temperature` attribute when
receiving data from devices.
Additionally, the group has defined an attribute mapping for a measurement `t` to be mapped to `temperature` attribute
when receiving data from devices.

The config group would usual hold additional attribute mappings, commands and common static attributes as well.

Expand Down Expand Up @@ -132,12 +133,12 @@ curl -iX POST \

The device `motion001` has been provisioned to persist data to the Context Broker as an entity of `type=Motion` (instead
of the default `type=Thing`). The destination entity is identified by the `entity_name` field, which is set to
`urn:ngsi-ld:Motion:001`. The device has a single attribute mapping for a measurement `c` to be mapped to `count` attribute,
additionally to one defined in the group mapping (`temperature`). The device also has a static attribute `refStore`
which is a relationship to the entity `urn:ngsi-ld:Store:001`.
`urn:ngsi-ld:Motion:001`. The device has a single attribute mapping for a measurement `c` to be mapped to `count`
attribute, additionally to one defined in the group mapping (`temperature`). The device also has a static attribute
`refStore` which is a relationship to the entity `urn:ngsi-ld:Store:001`.

This information is combined with the common config group information whenever a measurement is received at the IoT Agent
and used to create or update the relevant entity in the Context Broker.
This information is combined with the common config group information whenever a measurement is received at the IoT
Agent and used to create or update the relevant entity in the Context Broker.

## Receiving measures from devices

Expand All @@ -163,8 +164,8 @@ The IoT Agent South port is listening to the path defined in the config group, a
Because the `device_id` is also recognized, the provisioned device configuration is used and its settings are combined
with the config group.

Mapping has been found to use the `c` measurement as `count` and the `t` measurement as `temperature` attributes values. The following
context entity is created in the context broker:
Mapping has been found to use the `c` measurement as `count` and the `t` measurement as `temperature` attributes values.
The following context entity is created in the context broker:

```json
{
Expand All @@ -179,10 +180,9 @@ context entity is created in the context broker:
### Receiving a measure from an anonymous Device

When receiving a measure, it is not necessary to have the device provisioned. In this case, the IoT Agent will use the
config group configuration to create the device and the entity. This process is called "autoprovision" and it is enabled
by default in provisioned groups (for further information, review the [Autoprovision](api.md#autoprovision-configuration-autoprovision)
section in the API documentation).

config group configuration to create the device and the entity. This process is called "autoprovision" and it is enabled
by default in provisioned groups (for further information, review the
[Autoprovision](api.md#autoprovision-configuration-autoprovision) section in the API documentation).

Take as an example the following request from an anonymous device:

Expand Down
Loading

0 comments on commit b94b414

Please sign in to comment.