diff --git a/doc/admin.md b/doc/admin.md index 41758343b..b82c27f88 100644 --- a/doc/admin.md +++ b/doc/admin.md @@ -125,7 +125,7 @@ allowing the computer to interpret the rest of the data with more clarity and de ``` Under mixed mode, **NGSI v2** payloads are used for context broker communications by default, but this payload may also -be switched to **NGSI LD** at service group or device provisioning time using the `ngsiVersion` field in the +be switched to **NGSI LD** at group or device provisioning time using the `ngsiVersion` field in the provisioning API. The `ngsiVersion` field switch may be added at either group or device level, with the device level overriding the group setting. @@ -306,7 +306,7 @@ added `agentPath`: #### `types` -See **Type Configuration** in the [Configuration API](#configurationapi) section below. +This parameter includes additional groups configuration as described into the [Config group API](api.md#config-group-api) section. #### `service` @@ -344,7 +344,7 @@ if this flag is activated: #### `defaultResource` -default string to use as resource for the registration of new Configurations (if no resource is provided). +default string to use as resource for the registration of new config groups (if no resource is provided). #### `defaultKey` diff --git a/doc/api.md b/doc/api.md index 29e5fdf84..41f38f375 100644 --- a/doc/api.md +++ b/doc/api.md @@ -135,7 +135,7 @@ 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 information, security information and other +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. @@ -163,7 +163,7 @@ parameters defined at device level in database, the parameters are inherit from ### Uniqueness of groups and devices -Group service uniqueness is defined by the combination of: service, subservice and apikey +Group uniqueness is defined by the combination of: service, subservice and apikey Device uniqueness is defined by the combination of: service, subservice, device_id and apikey. Note that several devices with the same device_id are allowed in the same service and subservice as long as their apikeys are different. @@ -602,8 +602,8 @@ 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 -- `subservice`: device subservice +- `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 diff --git a/doc/devel/architecture.md b/doc/devel/architecture.md index f5c688fc4..75b3dd1c4 100644 --- a/doc/devel/architecture.md +++ b/doc/devel/architecture.md @@ -13,7 +13,7 @@ Be aware that the IoT Agents are only required to support NGSI10 operations `upd standard formats (currently in JSON format; XML deprecated) but will not answer to NGSI9 operations (or NGSI convenience operations of any kind). -#### Configurations and Device provisioning information +#### Config groups and Device provisioning information In order for a device to connect to the IoT Agent, the device should be provisioned (although there may be occasions where this registration is not needed). The provision process is meant to provide the IoT Agent with the following @@ -33,13 +33,13 @@ information: In order to provide this information, the IoT Agent Northbound API provides two resources: Device and Configuration provisioning. -**Configurations** may be used when a set of similar devices will be connected to the IoT Agent, to avoid provisioning -the same set of information for every device. Custom APIKeys can be only provided with the use of Configurations for +**Config groups** may be used when a set of similar devices will be connected to the IoT Agent, to avoid provisioning +the same set of information for every device. Custom APIKeys can be only provided with the use of config group for device groups. When a device is provisioned, it is assigned to a configuration _if there is one that matches its type, its service and its subservice_. In that case, all the default information in the Configuration is merged with the device information to create the definitive Device object that will be stored in the system. -Particular IoT Agents _may_ support autoregistration of devices into configurations, if enough information is given from +Particular IoT Agents _may_ support autoregistration of devices into config groups, if enough information is given from the Southbound. #### Registration diff --git a/doc/devel/development.md b/doc/devel/development.md index 92ee51344..0c1d2243e 100644 --- a/doc/devel/development.md +++ b/doc/devel/development.md @@ -24,7 +24,7 @@ - [Function reference](#function-reference) - [Generic middlewares](#generic-middlewares) - [DB Models from API document](#db-models-from-api-document) - - [Service group model](#service-group-model) + - [Config group model](#config-group-model) - [Device model](#device-model) - [Developing a new IoT Agent](#developing-a-new-iot-agent) - [Protocol](#protocol) @@ -756,9 +756,9 @@ The `newConfiguration` parameter will contain the newly created configuration. T callback with no parameters (this handler should only be used for reconfiguration purposes of the IoT Agent). For the cases of multiple updates (a single Device Configuration POST that will create several device groups), the -handler will be called once for each of the configurations (both in the case of the creations and the updates). +handler will be called once for each of the config groups (both in the case of the creations and the updates). -The handler will be also called in the case of updates related to configurations. In that situation, the +The handler will be also called in the case of updates related to config groups. In that situation, the `newConfiguration` parameter contains also the fields needed to identify the configuration to be updated, i.e., `service`, `subservice`, `resource` and `apikey`. @@ -1333,7 +1333,7 @@ The IoT Agent is now ready to be used. Execute it with the following command: node index.js ``` -The North Port interface should now be fully functional, i.e.: management of device registrations and configurations. +The North Port interface should now be fully functional, i.e.: management of device registrations and config groups. ### IoT Agent With Active attributes @@ -1831,7 +1831,7 @@ iotAgentLib.startServer(config, iotAgent, function (error) { ### Configuration management -For some IoT Agents, it will be useful to know what devices or configurations were registered in the Agent, or to do +For some IoT Agents, it will be useful to know what devices or config groups were registered in the Agent, or to do some actions whenever a new device is registered. All this configuration and provisioning actions can be performed using two mechanisms: the provisioning handlers and the provisioning API. @@ -2078,14 +2078,14 @@ addProtocols migrate - Migrate all the devices and services for the selected service and subservice into the + Migrate all the devices and groups for the selected service and subservice into the specified Mongo database. To perform the migration for all the services or all the subservices, use the "*" value. ``` The agent session stores transient configuration data about the target Context Broker and the target IoT Agent. This configuration is independent, and can be checked with the `showConfigCb` and `showConfigIot` commands, respectively. -Their values can be changed with the `configCb` and `configIot` commands respectively. The new configurations will be +Their values can be changed with the `configCb` and `configIot` commands respectively. The new config group will be deleted upon startup. --- diff --git a/doc/getting-started.md b/doc/getting-started.md index e253b88e0..35ce29cad 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -40,11 +40,11 @@ at the URL `http://iot-agent:4041`. All configuration settings can also updated using Docker environment variables. -### Provisioning a Service Group +### Provisioning a Config Group -Settings which are common to a group of devices can be passed to the IoT Agent using the Service API. The -`fiware-service` and `fiware-service-path` to be used to access the API are defined within the `config.js`. Each service -may override values previously defined in the configuration if necessary. +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. ```bash curl -iX POST \ @@ -66,7 +66,7 @@ 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 service group would usual hold additional attribute mappings, commands and common static attributes as +`type=Thing`. The config group would usual hold additional attribute mappings, commands and common static attributes as well. ### Provisioning an Individual Device @@ -97,7 +97,7 @@ curl -iX POST \ ' ``` -This information is combined with the common service group information whenever a request is received at the South port +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. #### Receiving a measure from a known Device @@ -111,9 +111,9 @@ curl -iX POST \ -d 'c|1' ``` -The IoT Agent South port is listening to the path defined in the service group, and the API key is recognized to match. +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 service group. A mapping has been found to rename the `c` measurement to `count` - the following context entity +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: ```json @@ -137,8 +137,8 @@ curl -iX POST \ -d 't|1' ``` -The IoT Agent South port is listen to the path defined in the service group, and the API key is recognized to match, so -the Service group configuration will be used. No mappings will be made for the Entity `id` or the attribute names and +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: ```json