diff --git a/doc/getting-started.md b/doc/getting-started.md index 35ce29cad..689ea189d 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -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` +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 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 \ @@ -56,9 +81,11 @@ 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" } + ] } ] }' @@ -66,12 +93,18 @@ curl -iX POST \ 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 \ @@ -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"} @@ -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" } } ```