iotagent-node-lib
IoT Agent library to interface with NGSI Context Broker
Last updated 2 months ago by fgalan .
Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install iotagent-node-lib 
SYNC missed versions from official npm registry.

FIWARE IoT Agent Node.js Library

FIWARE IoT Agents License: APGL Support badge
Documentation badge Build badge Coverage Status Status

This project aims to provide a Node.js module to enable IoT Agent developers to build custom agents for their devices that can easily connect to NGSI Context Brokers (such as Orion).

An IoT Agent is a component that lets groups of devices send their data to and be managed from a FIWARE NGSI Context Broker using their own native protocols. IoT Agents should also be able to deal with security aspects of the FIWARE platform (authentication and authorization of the channel) and provide other common services to the device programmer.

This project is part of FIWARE. For more information check the FIWARE Catalogue entry for the IoT Agents.

:books: Documentation :mortar_board: Academy :dart: Roadmap

Index

Background

The main concept of the IoT Agent node library is to provide a common framework for provisioning IoT devices, allowing each individual IoT Agent to access standardized mapping data for devices and to offer a series common utility functions.

  • For southbound communications, the library listens to changes in context entities and raises callbacks for the IoT Agent to process.
  • For northbound communications, the library offers an interface which accepts structured input data so that all NGSI communications are left to the library.
  • Standardized OAuth2-based security is available to enable each IoT Agent to connect to several common Identity Managers (e.g. Keystone and Keyrock) so that communications can be restricted to trusted components.
  • A series of additional plugins are offered where necessary to allow for expression parsing, attribute aliasing and the processing of timestamp metadata.

Each individual IoT Agent offers is driven by a config.js configuration file contains explicit custom settings based on the protocol and payload the IoT Agent is translating. It will also contain some common flags for common functionality provided by the IoT Agent node lin (e.g. for contecting to a conext broker or for authentication). The IoT Agent node library offers a standard API for provisioning devices and ensures that each IoT Agent can configure its device communications using a common vocabulary regardless of the payload, syntax or transport protocol used by the device itself.

Install

The IoT Agent node library is not a standalone product and should be added as a dependency to package.json of the IoT Agent

...
"dependencies": {
    "iotagent-node-lib": "*",
}

In order to use the library within your own IoT Agent, you must first you require it before use:

const iotagentLib = require("iotagent-node-lib");

Information about how to configure the Library can be found at the corresponding section of the Installation & Administration Guide.

Usage

This library has no packaging or build processes. The Getting Started is a good place to start. Usage of the library is explained in the User & Programmers Manual.

  • Details of the architecture of an IoT Agent be found here.
  • Further Advanced topics can be found here.
  • The following features are listed as deprecated.

API

The IoT Agent node library offers a simple REST API which provides common functionality to access, provision and decommission devices. API.

Testing

Contribitions to development can be found here - additional contributions are welcome.

Agent Console

A command-line client to experiment with the library is packed with it. The command-line client can be started using the following command:

bin/agentConsole.js

The client offers an API similar to the one offered by the library: it can start and stop an IoT agent, register and unregister devices, send measures mimicking the device and receive updates of the device data. Take into account that, by default, the console uses the same config.js file than the IoT Agent.

The command-line client creates a console that offers the following options:

stressInit

	Start recording a stress batch.

stressCommit <delay> <times> <threads> <initTime>

	Executes the recorded batch as many times as requested, with delay (ms) between commands.
	The "threads" parameter indicates how many agents will repeat that same sequence. The "initTime" (ms)
	parameter indicates the mean of the random initial waiting times for each agent.

exit

	Exit from the command-line.

start

	Start the IoT Agent

stop

	Stop the IoT Agent

register <id> <type>

	Register a new device in the IoT Agent. The attributes to register will be extracted from the
	type configuration

unregister <id> <type>

	Unregister the selected device

showConfig

	Show the current configuration file

config <newConfig>

	Change the configuration file to a new one

updatevalue <deviceId> <deviceType> <attributes>

	Update a device value in the Context Broker. The attributes should be triads with the following
	format: "name/type/value" sepparated by commas.

listdevices

	List all the devices that have been registered in this IoT Agent session

Agent tester

Command-line testing

The library also offers a Context Broker and IoT Agent client that can be used to:

  • Simulate operations to the Context Broker used by the IoT Agent, triggering Context Provider forwardings for lazy attributes and checking the appropriate values for active ones.
  • Simulate operations to the Device Provisioning API and Configuration API of the IoT Agent.

The tester can be started with the following command, from the root folder of the project:

bin/iotAgentTester.js

From the command-line, the help command can be used to show a description of the currently supported features. These are the following:

stressInit

	Start recording a stress batch.

stressCommit <delay> <times> <threads> <initTime>

	Executes the recorded batch as many times as requested, with delay (ms) between commands.
	The "threads" parameter indicates how many agents will repeat that same sequence. The "initTime" (ms)
	parameter indicates the mean of the random initial waiting times for each agent.

exit

	Exit from the command-line.

update <entity> <type> <attributes>

	Update the values of the defined set of attributes, using the following format: name#type=value(|name#type=value)*

append <entity> <type> <attributes>

	Append a new Entity with the defined set of attributes, using the following format: name:type=value(,name:type=value)*

query <entity> <type>

	Get all the information on the selected object.

queryAttr <entity> <type> <attributes>

	Get information on the selected object for the selected attributes.

discover <entity> <type>

	Get all the context providers for a entity and type.

configCb <host> <port> <service> <subservice>

	Config a new host and port for the remote Context Broker.

showConfigCb

	Show the current configuration of the client for the Context Broker.

configIot <host> <port> <service> <subservice>

	Config a new host and port for the remote IoT Agent.

showConfigIot

	Show the current configuration of the client for the IoT Agent.

provision <filename>

	Provision a new device using the Device Provisioning API. The device configuration is
	read from the file specified in the "filename" parameter.

provisionGroup <template> <data> <type>

	Provision a group of devices with the selected template, taking the information needed to
	fill the template from a CSV with two columns, DEVICE_ID and DEVICE_NAME. The third parameter, type
	will be used to replace the DEVICE_TYPE field in the template. All the devices will be provisioned
	to the same IoT Agent, once the templates have been fulfilled.

listProvisioned

	List all the provisioned devices in an IoT Agent.

removeProvisioned <deviceId>

	Remove the selected provisioned device from the IoT Agent, specified by its Device ID.

addGroup <filename>

	Add a new device group to the specified IoT Agent through the Configuration API. The
	body is taken from the file specified in the "filename" parameter.

listGroups

	List all the device groups created in the selected IoT Agent for the configured service

removeGroup <apiKey> <resource>

	Remove the device group corresponding to the current configured subservice.

authenticate <host> <port> <user> <password> <service>

	Authenticates to the given authentication server, and use the token in subsequent requests.

setProtocol <protocol>

	Sets the protocol to use in the requests (http or https). Defaults to http.

configMigration <host> <port> <originDb>

	Sets the configuration for a migration between a C++ IoTA and a Node.js one.

showConfigMigration

	Shows the current migration configuration.

addProtocols <protocols>

	Add a protocol translation table, in the following format:
		protocolOrigin1=protocolTarget1;protocolOrigin2=protocolTarget2...


migrate <targetDb> <service> <subservice>

	Migrate all the devices and services 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 deleted upon startup.

Creating specialized testers

The command-line testing tools make use of the command-node Node.js library for command-line utils. In order to help creating testing tools for IoTAgents of specific protocols, all the commands of the library tester are offered as a array that can be directly imported into other Command-Line tools, using the following steps:

  • Require the iotagent-node-lib command-line module in your command-line tool:
  var iotaCommands = require('iotagent-node-lib').commandLine;
  • Initialize the command-line utils (the initialization function takes two arguments, that will be explained in detail below:
iotaCommands.init(configCb, configIot);
  • Add the IOTA Lib commands to your array of commands
commands = commands.concat(commands, iotaCommands.commands);
  • Execute the command-line interpreter as usual:
clUtils.initialize(commandLine.commands, 'IoT Agent tester> ');

The command-line module makes use of two configuration objects. Both can be shown and edited in the command-line using the provided commands, but a default value must be present.

The Context Broker configuration object holds all the information about the Context Broker where the IoT Agent to be tested is connected. It MUST contain the following attributes:

  • host: host where the Context Broker instance is located.
  • port: port where the Context Broker instance is listening.
  • service: service that will be used in all the NGSI operations.
  • subservice: service that will be used in all the NGSI operations.

The IoT Agent configuration object holds information about the IoT Agent that is being tested. It MUST contain the following attributes:

  • host: host where the IoT Agent instance is located.
  • port: port where the IoT Agent instance is listening.
  • service: service that will be used to group devices and device information.
  • subservice: subservice that will be used to group devices and device information.

Licence

The IoT Agent Node Library is licensed under Affero General Public License (GPL) version 3.

© 2019 Telefonica Investigación y Desarrollo, S.A.U

Are there any legal issues with AGPL 3.0? Is it safe for me to use?

There is absolutely no problem in using a product licensed under AGPL 3.0. Issues with GPL (or AGPL) licenses are mostly related with the fact that different people assign different interpretations on the meaning of the term “derivate work” used in these licenses. Due to this, some people believe that there is a risk in just using software under GPL or AGPL licenses (even without modifying it).

For the avoidance of doubt, the owners of this software licensed under an AGPL-3.0 license
wish to make a clarifying public statement as follows:

Please note that software derived as a result of modifying the source code of this software in order to fix a bug or incorporate enhancements is considered a derivative work of the product. Software that merely uses or aggregates (i.e. links to) an otherwise unmodified version of existing software is not considered a derivative work, and therefore it does not need to be released as under the same license, or even released as open source.

Current Tags

  • 2.12.0                                ...           latest (2 months ago)

48 Versions

  • 2.12.0                                ...           2 months ago
  • 2.11.0                                ...           7 months ago
  • 2.10.0                                ...           10 months ago
  • 2.9.0                                ...           a year ago
  • 2.7.50                                ...           a year ago
  • 2.8.1                                ...           a year ago
  • 2.7.0                                ...           2 years ago
  • 2.6.0                                ...           2 years ago
  • 2.5.1                                ...           3 years ago
  • 2.5.0                                ...           3 years ago
  • 2.4.1                                ...           4 years ago
  • 2.4.0                                ...           4 years ago
  • 2.3.0                                ...           4 years ago
  • 2.2.0                                ...           4 years ago
  • 2.1.4                                ...           4 years ago
  • 2.1.3                                ...           4 years ago
  • 2.1.2                                ...           4 years ago
  • 2.1.1                                ...           4 years ago
  • 2.1.0                                ...           4 years ago
  • 2.0.0                                ...           4 years ago
  • 1.0.0                                ...           4 years ago
  • 0.10.0                                ...           4 years ago
  • 0.9.8                                ...           4 years ago
  • 0.9.7                                ...           4 years ago
  • 0.9.6                                ...           4 years ago
  • 0.9.5                                ...           4 years ago
  • 0.9.4                                ...           4 years ago
  • 0.9.3                                ...           4 years ago
  • 0.9.2                                ...           4 years ago
  • 0.9.1                                ...           4 years ago
  • 0.9.0                                ...           4 years ago
  • 0.8.4                                ...           5 years ago
  • 0.8.3                                ...           5 years ago
  • 0.8.2                                ...           5 years ago
  • 0.8.1                                ...           5 years ago
  • 0.8.0                                ...           5 years ago
  • 0.7.0                                ...           5 years ago
  • 0.6.1                                ...           5 years ago
  • 0.6.0                                ...           5 years ago
  • 0.5.5                                ...           5 years ago
  • 0.5.4                                ...           5 years ago
  • 0.5.3                                ...           5 years ago
  • 0.5.2                                ...           5 years ago
  • 0.5.1                                ...           5 years ago
  • 0.5.0                                ...           5 years ago
  • 0.4.0                                ...           5 years ago
  • 0.3.0                                ...           5 years ago
  • 0.2.0                                ...           5 years ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (16)

Copyright 2014 - 2017 © taobao.org |