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.

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

Modify getting started to use IoTA JSON #1646

Merged
merged 7 commits into from
Aug 23, 2024
Merged
Changes from 6 commits
Commits
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
159 changes: 110 additions & 49 deletions doc/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,50 +1,75 @@
## Getting Started
# Getting Started

Every IoT Agent which uses the library is different, but the concepts for provisioning IoT devices remain the same
regardless of protocol.
- [Introduction](#introduction)
- [IoT Agent settings - `config.js`](#iot-agent-settings---configjs)
- [Provisioning a Config Group](#provisioning-a-config-group)
- [Provisioning an Individual Device](#provisioning-an-individual-device)
- [Receiving measures from devices](#receiving-measures-from-devices)
- [Receiving a measure from a known Device](#receiving-a-measure-from-a-known-device)
- [Receiving a measure from an anonymous Device](#receiving-a-measure-from-an-anonymous-device)

### `config.js` - IoT Agent settings
## 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.

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.

The IoT Agent JSON is a simple IoT Agent which uses JSON payloads to send and receive data. It is a good starting point
for understanding how an IoT Agent works since it uses JSON payloads to send and receive data.

## IoT Agent settings - `config.js`

The `config.js` holds common information about the interactions between the Agent and the Context Broker. Additional
custom settings may also be required dependent upon the actual IoT Agent used.
custom settings may also be required dependent upon the actual IoT Agent used. The following is an example of a typical
`config.js` file:

```javascript
config = {
logLevel: "DEBUG",
logLevel: 'DEBUG',
contextBroker: {
host: "orion",
port: "1026",
host: 'orion',
port: '1026'
},
server: {
port: 4041,
host: "0.0.0.0",
host: '0.0.0.0'
},
deviceRegistry: {
type: "memory",
type: 'mongodb'
},
mongodb: {
host: 'localhost',
port: '27017',
db: 'iotagent'
},
service: "openiot",
subservice: "/",
providerUrl: "http://iot-agent:4041",
defaultType: "Thing",
service: 'openiot',
subservice: '/',
providerUrl: 'http://iot-agent:4041',
defaultType: 'Thing'
};
```

In this case the context broker is called `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 holding the
device mappings in memory.
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`
collection from a MongoDB instance at `localhost:27017` to the device mappings.

mapedraza marked this conversation as resolved.
Show resolved Hide resolved
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
shown below. Devices will be registered for a period of one month and the IoT Agent will receive registration callbacks
at the URL `http://iot-agent:4041`.

All configuration settings can also updated using Docker environment variables.
All configuration settings can also updated using Docker environment variables. You can find more information about the
available configuration parameters and environment variables in the [Administration Guide](admin.md).

### Provisioning a Config Group
## Provisioning a Config Group

Settings which are common to a group of devices can be passed to the IoT Agent using the Config Group API. The
`fiware-service` and `fiware-service-path` to be used to access the API are defined within the `config.js`. Each config group
may override values previously defined in the global configuration if necessary.
Settings which are common to a group of devices can be passed to the IoT Agent using the Config Group API. Each config
group may override values previously defined in the global configuration if necessary. When using the config group API,
the `fiware-service` and `fiware-servicepath` headers will define the service and subservice to which the configuration
will be applied. Additionally, the `apikey` field is used to identify the configuration group. An example of a basic
config group is shown below:

```bash
curl -iX POST \
Expand All @@ -56,22 +81,30 @@ curl -iX POST \
"services": [
{
"apikey": "4jggokgpepnvsb2uv4s40d59ov",
"cbHost": "http://orion:1026",
"entity_type": "Device",
"resource": "/iot/d",
"resource": "/iot/json",
"attributes": [
{ "object_id": "t", "name": "temperature", "type": "Number" }
]
}
]
}'
```

In this case an `apiKey` for identifying devices has been created and all interactions to the path `/iot/d` which
present this `apiKey` will be created as entities of `type=Device` rather than using the configuration default of
`type=Thing`. The config group would usual hold additional attribute mappings, commands and common static attributes as
well.
`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.

### Provisioning an Individual Device
The config group would usual hold additional attribute mappings, commands and common static attributes as well.

Settings which are specific to an individual device can be passed to the IoT Agent using the Device API
## Provisioning an Individual Device

Settings which are specific to an individual device can be passed to the IoT Agent using the Device API. The
configuration provided in the Device API will override any settings defined in the Config Group API and the global
configuration as well. An example of a basic device configuration is shown below:

```bash
curl -iX POST \
Expand All @@ -86,7 +119,7 @@ curl -iX POST \
"entity_name": "urn:ngsi-ld:Motion:001",
"entity_type": "Motion",
"attributes": [
{ "object_id": "c", "name": "count", "type": "Integer" }
{ "object_id": "c", "name": "count", "type": "Number" }
],
"static_attributes": [
{ "name":"refStore", "type": "Relationship", "value": "urn:ngsi-ld:Store:001"}
Expand All @@ -97,54 +130,82 @@ curl -iX POST \
'
```

This information is combined with the common config group information whenever a request is received at the South port
of the IoT Agent and used to create or update the relevant entity in the Context Broker.
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`.

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 a measure from a known Device
## Receiving measures from devices

For example, imagine we are using the Ultralight IoT Agent and the following request is sent to the South port:
In order to see the complete process from provisioning the groups and devices to receiving measures, we will show how a
device can send a measure to the IoT Agent. In this case, we will use the IoTA JSON as an example, using the HTTP
transport protocol. To reproduce the measure sending, you can use the following `curl` commands.

The device measures are sent to the South port of the IoT Agent which is listening in the port `7896`.

### Receiving a measure from a known Device

In this case, the device has been provisioned previously. We will use the `motion001` device defined in the previous
example. To simulate the device sending a measure, the following request is sent to the South port:

```bash
curl -iX POST \
'http://localhost:7896/iot/d?k=4jggokgpepnvsb2uv4s40d59ov&i=motion001' \
-H 'Content-Type: text/plain' \
-d 'c|1'
'http://localhost:7896/iot/json?k=4jggokgpepnvsb2uv4s40d59ov&i=motion001' \
-H 'Content-Type: application/json' \
-d '{"t":23,"c":1}'
```

The IoT Agent South port is listening to the path defined in the config group, and the API key is recognized to match.
Because the `device_id` is also recognized, the provisioned device configuration is used and its settings are combined
with the config group. A mapping has been found to rename the `c` measurement to `count` - the following context entity
is created in the context broker:
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:

```json
{
"id": "urn:ngsi-ld:Motion:001",
"type": "Motion",
"count": { "value": "1", "type": "Integer" },
"temperature": { "value": 23, "type": "Number" },
"count": { "value": 1, "type": "Number" },
"refStore": { "value": "urn:ngsi-ld:Store:001", "type": "Relationship" }
}
```

#### Receiving a measure from an anonymous Device
### Receiving a measure from an anonymous Device

For example, imagine we are using the Ultralight IoT Agent and a request from an anonymous, unprovisioned device is sent
to the South port:
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).


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

```bash
curl -iX POST \
'http://localhost:7896/iot/d?k=4jggokgpepnvsb2uv4s40d59ov&i=temp001' \
-H 'Content-Type: text/plain' \
-d 't|1'
'http://localhost:7896/iot/json?k=4jggokgpepnvsb2uv4s40d59ov&i=dev001' \
-H 'Content-Type: application/json' \
-d '{"t":13,"c":4}'
```

The IoT Agent South port is listen to the path defined in the config group, and the API key is recognized to match, so
the config group configuration will be used. No mappings will be made for the Entity `id` or the attribute names and
the following entity will be created:
the config group configuration will be used. No device has been provisioned with the `device_id=dev001`, so the IoT
Agent will only use the config group configuration.

A new entity will be created in the Context Broker with the `id` `Device:dev001` and the `type` `Device`. Only the `t`
measurement will be mapped to the `temperature` attribute, as defined in the config group. The remaining measurements
will be created as attributes with the same name. The following context entity will be created in the context broker:

```json
{
"id": "temp001",
"id": "Device:dev001",
"type": "Device",
"t": { "value": "1", "type": "Number" }
"temperature": { "value": 13, "type": "Number" },
"c": { "value": 4, "type": "Number" }
}
```
Loading