Skip to content

Commit

Permalink
align docs
Browse files Browse the repository at this point in the history
  • Loading branch information
walterwootz committed Mar 25, 2024
1 parent ea25197 commit f5fd0b4
Show file tree
Hide file tree
Showing 7 changed files with 65 additions and 42 deletions.
28 changes: 12 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,7 @@
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4612/badge)](https://bestpractices.coreinfrastructure.org/projects/4612)
![Status](https://nexus.lab.fiware.org/static/badges/statuses/full.svg)
[![Join the chat at https://gitter.im/iotagent-opcua/community](https://badges.gitter.im/iotagent-opcua/community.svg)](https://gitter.im/iotagent-opcua/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
<br/>
<img align="right" width="200" src="/docs/images/iotagent-logo.png" />

<br/> <img align="right" width="200" src="/docs/images/iotagent-logo.png" />

An Internet of Things Agent accepting data from OPC UA devices. This IoT Agent is designed to be a bridge between the
OPC Unified Architecture protocol and the
Expand All @@ -31,8 +29,8 @@ library's GitHub repository.
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-opcua.rtfd.io) | <img style="height:1em" src="https://quay.io/static/img/quay_favicon.png"/> [quay.io](https://quay.io/repository/fiware/iotagent-opcua) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | :dart: [Roadmap](https://github.com/Engineering-Research-and-Development/iotagent-opcua/blob/master/roadmap.md) |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| :books: [Documentation](https://iotagent-opcua.rtfd.io) | <img style="height:1em" src="https://quay.io/static/img/quay_favicon.png"/> [quay.io](https://quay.io/repository/fiware/iotagent-opcua) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/iot-agents/idas) | :dart: [Roadmap](https://github.com/Engineering-Research-and-Development/iotagent-opcua/blob/master/roadmap.md) |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |


## Contents
Expand Down Expand Up @@ -77,7 +75,7 @@ A step-by-step tutorial is available

Before launching the Agent you must install Orion Context Broker (Be aware to choose the correct version, please use
_orion_ if it's needed to test the Agent with NGSI v2 otherwise use _orion-ld_ in case of NGSI-ld test.) and a OPC UA
Server. After that you must tell the Agent how to interact with these components by using config.properties file. Once
Server. After that you must tell the Agent how to interact with these components by using config.js file. Once
configuration is complete you can execute these commands to run the Agent.

```console
Expand All @@ -103,10 +101,10 @@ Administration services are reachable at port specified by api-port property (co

### Poll commands

Poll commands can be enabled switching polling property to true (config.properties). Once enabled poll command, you can
customize the polling Daemon Frequency and Expiration time still in the (config.properties). The polling-commands-timer
is referred to the feature developed, that consist in the execution of the older polling command periodically (if
exists) ed delete it in case of success.
Poll commands can be enabled switching polling property to true (config.js). Once enabled poll command, you can
customize the polling Daemon Frequency and Expiration time still in the (config.js). The polling-commands-timer is
referred to the feature developed, that consist in the execution of the older polling command periodically (if exists)
ed delete it in case of success.

## API

Expand All @@ -119,14 +117,12 @@ their APIs can be found in the IoT Agent Library [documentation](https://iotagen
For test purpose can create an OPC UA server using the code in the following
[GitHub repository](https://github.com/Engineering-Research-and-Development/opc-ua-car-server/)

Firstly edit the
[properties](https://github.com/Engineering-Research-and-Development/iotagent-opcua/blob/master/conf/config.properties)
in order to set Northbound (NGSI) and Southbound (OPC UA) settings.
Firstly edit the [config.js](conf/config.js) in order to set Northbound (NGSI) and Southbound (OPC UA) settings.

Further information about configuration properties can be found [here](docs/howto.md)

For checking current status of the Agent, send a request to /status service
(`http://{agent-ip-address}:api-port/status`)
For checking current status of the Agent, send a request to /version service
(`http://{agent-ip-address}:api-port/version`)

### Secure connection with an OPC UA Server

Expand All @@ -135,7 +131,7 @@ establish a secure connection to the OPC UA Server.

### How to get access to the advanced API and Documentation topics

Documentation about the OPC UA Administration API can be found [here](https://opcuaiotagent.docs.apiary.io)
Documentation about the OPC UA Administration API can be found [here](https://iotagentopcua.docs.apiary.io/)

## Quality Assurance

Expand Down
1 change: 1 addition & 0 deletions docker/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ services:
- "IOTA_OPCUA_SUBSCRIPTION_REQ_MAX_KEEP_ALIVE_COUNT=10"
- "IOTA_OPCUA_SUBSCRIPTION_REQ_PUBLISHING_INTERVAL=1000"
- "IOTA_OPCUA_SUBSCRIPTION_PRIORITY=128"
- "IOTA_OPCUA_MT_ENABLED=false"
- "IOTA_OPCUA_MT_POLLING=false"
- "IOTA_OPCUA_MT_AGENT_ID=age01_"
- "IOTA_OPCUA_MT_ENTITY_ID=age01_Car"
Expand Down
43 changes: 34 additions & 9 deletions docs/howto.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ npm install

### Configure

IotAgent-opcua comes with MappingTool, an automated tool that goes in discovery for all the nodes belonging to an OPC UA
Server. You can chose configure the config.js file yourself ( in particular the three objects: _types_, _contexts_,
_contextSubscriptions_) or let MappingTool configure the config.js file itself.
IotAgent OPC UA comes with MappingTool, an automated tool that goes in discovery for all the nodes belonging to an OPC
UA Server. You can chose configure the config.js file yourself (in particular the three objects: _types_, _contexts_,
_contextSubscriptions_, _events_) or let MappingTool configure the config.js file itself.

```js
/*
Expand All @@ -36,7 +36,7 @@ _contextSubscriptions_) or let MappingTool configure the config.js file itself.
* please contact with::[[email protected], [email protected], [email protected], [email protected]]
*/

var config = {};
const config = {};

config.iota = {
/**
Expand Down Expand Up @@ -175,6 +175,7 @@ config.iota = {
types: {},
contexts: [],
contextSubscriptions: [],
events: [],
/**
* Default service, for IoT Agent installations that won't require preregistration.
*/
Expand Down Expand Up @@ -205,9 +206,29 @@ config.iota = {
* flag indicating whether the incoming measures to the IoTAgent should be processed as per the "attributes" field.
*/
explicitAttrs: false,
/**
* List of characters to be filtered before forwarding any request to Orion.
* Default Orion forbidden characters are filtered by default, see (https://github.com/telefonicaid/fiware-orion/blob/74aaae0c98fb24f082e3b258aa642461eb285e39/doc/manuals/orion-api.md#general-syntax-restrictions)
*/
extendedForbiddenCharacters: [],
/**
* Flag indicating whether to provision the Group and Device automatically
*/
autoprovision: true,
};

config.opcua = {
/**
* Subscription options for OPC UA connection.
*/
subscription: {
maxNotificationsPerPublish: 1000,
publishingEnabled: true,
requestedLifetimeCount: 100,
requestedMaxKeepAliveCount: 10,
requestedPublishingInterval: 1000,
priority: 128,
},
/**
* Endpoint where the IoT Agent will listen for an active OPC UA Server.
*/
Expand Down Expand Up @@ -236,7 +257,11 @@ config.opcua = {

config.mappingTool = {
/**
* Boolean property to assess whether enable polling in MappingTool or not
* Boolean property to assess whether enabling MappingTool or not
*/
enabled: false,
/**
* Boolean property to assess whether enabling polling in MappingTool or not
*/
polling: false,
/**
Expand All @@ -255,6 +280,10 @@ config.mappingTool = {
* entityType to be assigned to the newly generated entity from MappingTool execution
*/
entityType: "Device",
/**
* boolean flag to determine whether to store the output of the mapping tool execution or not
*/
storeOutput: true,
};

/**
Expand Down Expand Up @@ -282,10 +311,6 @@ config.defaultTransport = "OPCUA";
* single-thread one (false).
*/
//config.multiCore = false;
/**
* flag indicating whether or not to provision the Group and Device automatically
*/
config.autoprovision = true;

module.exports = config;
```
Expand Down
10 changes: 5 additions & 5 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
[![FIWARE IoT Agents](https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/iot-agents.svg)](https://www.fiware.org/developers/catalogue/)
[![](https://nexus.lab.fiware.org/repository/raw/public/badges/stackoverflow/iot-agents.svg)](https://stackoverflow.com/questions/tagged/fiware+iot)

The F4I IDAS OPC UA Agent is an Open Source component intended to enable capturing data from OPC UA devices on the
shopfloor and provide them to the upper levels of a FIWARE-based system. Therefore, the main focus of this component is
on the communication from field devices implementing an OPC UA server to FIWARE, allowing the communication to the
FIWARE Orion Context Broker.
The F4I OPC UA Agent is an Open Source component intended to enable capturing data from OPC UA devices on the shopfloor
and provide them to the upper levels of a FIWARE-based system. Therefore, the main focus of this component is on the
communication from field devices implementing an OPC UA server to FIWARE, allowing the communication to the FIWARE Orion
Context Broker.

# Getting Started

As first step we suggest you to follow the instructions available in the
[Tutorial](https://iotagent-opcua.readthedocs.io/en/latest/opc_ua_agent_tutorial/index.html) section.
[Tutorial](https://iotagent-opcua.readthedocs.io/en/latest/index.html) section.

In this way you will soon be able to install and run a testbed containing the OPC UA IoTAgent. Then read the "What's
next" section to know how the IoTAgent can be used with your own OPC UA Server
14 changes: 7 additions & 7 deletions docs/installation_and_administration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,32 +24,32 @@ cd iotagent-opcua

##### Step 2 - Configure the environment

Open the `conf/config.js` and make your changes (see how to do this
[here](https://iotagent-opcua.readthedocs.io/en/latest/user_and_programmers_manual/index.html)).
Open the `conf/config.js` and make your changes (see how to do this [here](howto.md)).

##### Step 3 - Configure device

The downloaded repository comes with a `config.js` (conf/config.js) in which an empty Device is preloaded.

At this point, you have two options:
At this point, you have three options:

- Use the mapping tool to automatically generate a `config.js`
- Define your own context mappings in properties `types`, `contexts`, `contextSubscriptions` in `config.js`
- Provision the new Device (mapping between OPC UA Server and OPC UA Agent) via REST interface
- Define your own context mappings in fields `types`, `contexts`, `contextSubscriptions`, `events` in `config.js`
- Dynamically provision the new Device (mapping between OPC UA Server and OPC UA Agent) via REST interface

If you want to use the mapping tool simply set as empty the following properties in the config.js:

- `types: {}`
- `contexts: []`
- `contextSubscriptions: []`
- `events: []`

When you launch the Agent, the mapping tool will automatically be triggered and will extract the above properties of the
`config.js` you need using the information contained on the rest of the file. Be sure the addresses contained inside the
`config.js` are the correct ones.

If you want to use the REST interface have a look at Step 4
[here](https://iotagent-opcua.readthedocs.io/en/latest/opc_ua_agent_tutorial/index.html#step-by-step-tutorial) to see
how to provision a new device.
[here](https://iotagent-opcua.readthedocs.io/en/latest/opc_ua_agent_tutorial.html#step-by-step-tutorial) to see how to
provision a new device.

##### Step 4 - Install the npm packages

Expand Down
9 changes: 5 additions & 4 deletions docs/opc_ua_agent_tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ It represents a car with the following structure:
IoT Agent can be configured as described in the
[user guide](https://github.com/Engineering-Research-and-Development/iotagent-opcua/blob/master/docs/user_and_programmers_manual.md).
In order to start playing with the above mentioned OPC UA server, configuration files have been already edited and
available in *conf* folder.
available in _conf_ folder.

#### Orion Context Broker

Expand Down Expand Up @@ -142,12 +142,13 @@ configuration file (config.js) or through the REST API
Three different initialization modalities are available:

- Use a preloaded config.js
- Invoke a mapping tool responsible of automatically building the config.js (**NOTE:** **_Before using the
MappingTool, erase the three objects: *types*, *contexts*, *contextSubscriptions* within the existing config.js_**)
- Invoke a mapping tool responsible of automatically building the mapping between OPC UA and NGSI (**NOTE:** **_Before
using the MappingTool, erase the three objects: *types*, *contexts*, *contextSubscriptions* within the existing
config.js_**)
- Use the REST API

Since in the following parts of this tutorial we are going to use the REST API you have not to worry about the
initialization.
initialization.

#### Step 4 - Provision a new Device

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "iotagent-opcua",
"license": "AGPL-3.0-only",
"description": "IoT Agent for OPC UA protocol",
"version": "2.0.7",
"version": "2.2.5",
"homepage": "https://github.com/Engineering-Research-and-Development/iotagent-opcua",
"author": {
"name": "Manfredi Giuseppe Pistone",
Expand Down

0 comments on commit f5fd0b4

Please sign in to comment.