iotagent-node-lib

# Getting Started - [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) ## 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. The following is an example of a typical `config.js` file: ```javascript config = { logLevel: 'DEBUG', contextBroker: { host: 'orion', port: '1026' }, server: { port: 4041, host: '0.0.0.0' }, deviceRegistry: { type: 'mongodb' }, mongodb: { host: 'localhost', port: '27017', db: 'iotagent' }, service: 'openiot', subservice: '/', providerUrl: 'http://iot-agent:4041', defaultType: 'Thing' }; ``` 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. You can find more information about the available configuration parameters and environment variables in the [Administration Guide](admin.md). ## 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. 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 \ 'http://localhost:4041/iot/groups' \ -H 'Content-Type: application/json' \ -H 'fiware-service: openiot' \ -H 'fiware-servicepath: /' \ -d '{ "groups": [ { "apikey": "4jggokgpepnvsb2uv4s40d59ov", "entity_type": "Device", "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`. 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. ## 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 \ 'http://localhost:4041/iot/devices' \ -H 'Content-Type: application/json' \ -H 'fiware-service: openiot' \ -H 'fiware-servicepath: /' \ -d '{ "devices": [ { "device_id": "motion001", "entity_name": "urn:ngsi-ld:Motion:001", "entity_type": "Motion", "attributes": [ { "object_id": "c", "name": "count", "type": "Number" } ], "static_attributes": [ { "name":"refStore", "type": "Relationship", "value": "urn:ngsi-ld:Store:001"} ] } ] } ' ``` 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 measures from devices 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/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. 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", "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 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/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 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": "Device:dev001", "type": "Device", "temperature": { "value": 13, "type": "Number" }, "c": { "value": 4, "type": "Number" } } ```