From 90a1245d015874305c2463a541d723ea5bedaf69 Mon Sep 17 00:00:00 2001 From: mapedraza Date: Wed, 20 Sep 2023 17:52:10 +0200 Subject: [PATCH 01/11] rework README.md files --- README.md | 335 ++++++++++---------------------------------------- doc/README.md | 2 +- 2 files changed, 68 insertions(+), 269 deletions(-) diff --git a/README.md b/README.md index 49e006401..b1613add4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# FIWARE IoT Agent Node.js Library +# FIWARE IoT Agent Node Library [![FIWARE IoT Agents](https://nexus.lab.fiware.org/static/badges/chapters/iot-agents.svg)](https://www.fiware.org/developers/catalogue/) [![License: APGL](https://img.shields.io/github/license/telefonicaid/iotagent-node-lib.svg)](https://opensource.org/licenses/AGPL-3.0) @@ -10,296 +10,95 @@ ![Status](https://nexus.lab.fiware.org/static/badges/statuses/iot-node-lib.svg) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4671/badge)](https://bestpractices.coreinfrastructure.org/projects/4671) -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](https://github.com/telefonicaid/fiware-orion)). +An IoT Agent is a component that lets groups of IoT devices send their data to a NGSI Context Broker (such as +[Orion Context Broker](https://github.com/telefonicaid/fiware-orion)) using their own native protocols and translating +them into NGSI. -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. +The **IoT Agent Node Lib** provides simple standardized REST API for registering, provisioning, discovering and managing +devices and groups of devices. It also 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 -This project is part of [FIWARE](https://www.fiware.org/). For more information check the FIWARE Catalogue entry for the -[IoT Agents](https://github.com/Fiware/catalogue/tree/master/iot-agents). - -| :books: [Documentation](https://iotagent-node-lib.rtfd.io) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | :dart: [Roadmap](https://github.com/telefonicaid/iotagent-node-lib/blob/master/doc/roadmap.md) | -| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | - -## Index - -- [Background](#background) -- [Install](#install) -- [API](#api) -- [Usage](#usage) -- [Testing](#testing) - - [Agent Console](#agent-console) - - [Agent tester](#agent-tester) -- [Licence](#licence) +It also provides a common configuration framework driven by a `config.js` configuration file and a series of common ENV +variables, configuring some flags for common functionality provided by the **IoT Agent node lib** (e.g. for contecting +to a Conext Broker or for authenticating with an Identity Manager).Some of common utility functions provided by the +**IoT Agent node lib** include: -## 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. +- For the device communication (southbound), the library listens to changes in context entities and raises callbacks + for the IoT Agent to process. It also handles the commands sent by the Context Broker to the devices. +- For the context broker communications (northbound), the library offers an interface which persists data from the + device in the Context Broker and accepts NGSI data from the Context Broker to be sent to the device. - 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. -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 - -```json -... -"dependencies": { - "iotagent-node-lib": "*", -} -``` - -In order to use the library within your own IoT Agent, you must first you require it before use: - -```javascript -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](doc/admin.md). - -## Usage - -This library has no packaging or build processes. The [Getting Started](./doc/getting-started.md) is a good place to -start. You can also review the [API documentation](./doc/api.md) for a full list of the available functions. - -If you plan to use the library in your own IoT Agent, you should read the [Developer Guide](./doc/devel/development.md). -You can also review the [Architecture](./doc/devel/architecture.md) documentation and -[Northbound API](./doc/devel/northbound-api.md). - -The following features are listed as [deprecated](doc/deprecated.md). - -## API - -The **IoT Agent node library** offers a simple REST API which provides common functionality to access, provision and -decommission devices. [API](doc/api.md). - -## Testing - -Contributions to development can be found [here](doc/devel/development.md) - 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: - -```console -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: - -```text -stressInit - - Start recording a stress batch. - -stressCommit - - 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 - - Register a new device in the IoT Agent. The attributes to register will be extracted from the - type configuration - -unregister - - Unregister the selected device - -showConfig - - Show the current configuration file - -config - - Change the configuration file to a new one - -updatevalue - - 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: - -```console -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: - -```text -stressInit - - Start recording a stress batch. - -stressCommit - - 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 - - Update the values of the defined set of attributes, using the following format: name#type=value(|name#type=value)* - -append - - Append a new Entity with the defined set of attributes, using the following format: name:type=value(,name:type=value)* - -query - - Get all the information on the selected object. - -queryAttr - - Get information on the selected object for the selected attributes. - -discover - - Get all the context providers for a entity and type. - -configCb - - Config a new host and port for the remote Context Broker. - -showConfigCb - - Show the current configuration of the client for the Context Broker. - -configIot - - Config a new host and port for the remote IoT Agent. - -showConfigIot - - Show the current configuration of the client for the IoT Agent. - -provision - - Provision a new device using the Device Provisioning API. The device configuration is - read from the file specified in the "filename" parameter. - -provisionGroup