barnacles-opcua

barnacles-opcua is an OPC UA server of IoT data from ambient wireless sensors. reelyActive is an OPC UA logo member.

barnacles-opcua ingests a real-time stream of dynamb objects from barnacles, converting their properties into standard OPC UA format. It couples seamlessly with reelyActive's Pareto Anywhere open source IoT middleware.

barnacles-opcua is a lightweight Node.js package that can run on resource-constrained edge devices as well as on powerful cloud servers and anything in between.

Pareto Anywhere integration

A common application of barnacles-opcua is to publish IoT data from pareto-anywhere via an OPC UA server. Simply follow our Create a Pareto Anywhere startup script tutorial using the script below:

#!/usr/bin/env node

const ParetoAnywhere = require('../lib/paretoanywhere.js');

// Edit the options to customise the server
const BARNACLES_OPCUA_OPTIONS = {};

// ----- Exit gracefully if the optional dependency is not found -----
let BarnaclesOPCUA;
try {
  BarnaclesOPCUA = require('barnacles-opcua');
}
catch(err) {
  console.log('This script requires barnacles-opcua.  Install with:');
  console.log('\r\n    "npm install barnacles-opcua"\r\n');
  return console.log('and then run this script again.');
}
// -------------------------------------------------------------------

let pa = new ParetoAnywhere();
pa.barnacles.addInterface(BarnaclesOPCUA, BARNACLES_OPCUA_OPTIONS);

Supported Properties

barnacles-opcua currently supports the following properties:

| OPC UA browseName | OPC UA dataType | dynamb property | |:------------------------|:----------------|:-----------------------| | Temperature | AnalogDataItem | temperature | | AccelerationTimeSeriesX | YArrayItem | accelerationTimeSeries | | AccelerationTimeSeriesY | YArrayItem | accelerationTimeSeries | | AccelerationTimeSeriesZ | YArrayItem | accelerationTimeSeries |

Additional dynamb properties will be added in future. Helpful node-opcua API documentation references for adding items:

• AddAnalogDataItemOptions
• AddYArrayItemOptions

Quick Start

Clone this repository, then from its root folder, install dependencies with npm install. Start the OPC-UA server with the following command:

npm start

and connect an OPC-UA client (see examples below) on port 4840 and resource path /UA/ParetoAnywhere. Note that no device data will be available without a source of dynamb data, for example from Pareto Anywhere open source IoT middleware.

To validate secure communication, simply provide a certificate and private key as config files.

Simulated Data

The following simulated devices/sensors are supported for interface testing.

Sensor-Works BluVib

To simulate a Sensor-Works BluVib industrial vibration sensor, start barnacles-opcua with the following command:

npm run sensorworks-bluvib

Simulated sensor browseName = "5e4504b1071b/3" will expose the following variables:

| OPC UA browseName | OPC UA dataType | |:------------------------|:----------------| | Temperature | AnalogDataItem | | AccelerationTimeSeriesX | YArrayItem | | AccelerationTimeSeriesY | YArrayItem | | AccelerationTimeSeriesZ | YArrayItem |

Observing Data with opcua-commander

The opcua-commander CLI, based on the same node-opcua open source package used by barnacles-opcua, provides a simple means of browsing and monitoring the OPC-UA data.

After installing opcua-commander, open a terminal and browse to the barnacles-opcua server with the following command:

opcua-commander -e opc.tcp://localhost:4840

Use the arrow keys and the t / l / i / c / u / s / a keys to navigate through the CLI interface, and use the x key to close.

Observing Data with UaExpert

Unified Automation offers UaExpert, a full-featured Windows/Linux OPC UA client, for free download, with registration.

Config Files

The /config folder accepts the following run-time configuration files:

• certificate.pem (security certificate)
• key.pem (private key)

Alternatively, these can be specified in the Options.

Security Certificate

barnacles-opcua does not, by default, implement a secure OPC-UA server. This facilitates testing in a local sandbox environment. In any other environment, the use of an Application Instance Certificate is essential for secure operation.

When creating the security certificate, for example using OpenSSL, ensure that the following properties are included and correctly entered for compliance with the OPC UA specification.

| Property | Example | Description | |:---------------------|:-----------------------------|:-----------------------| | subjectAltName | urn:machine:NodeOPCUA-Server | Application URI | | commonName (CN) | Pareto Anywhere | Name of the product | | organizationName (O) | Your organisation | Operator of server |

The Node-OPCUA server will output warnings when a certificate is present but not compliant, for example:

"The certificate subjectAltName uniformResourceIdentifier is missing."
"Please regenerate a specific certificate with a uniformResourceIdentifier that matches your server applicationUri"
"applicationUri  = urn:machine:NodeOPCUA-Server"

It is up to the user to generate and validate compliant security certificates.

Creating a Self-Signed Certificate for OPC-UA using OpenSSL

In a development environment, it is common for barnacles-opcua to run on the same local network as OPC UA client. A self-signed server certificate (for barnacles-opcua) and the CA certificate can be generated with OpenSSL using the following procedure:

Create a server.cnf file

[req]
default_bits  = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
countryName = CA
stateOrProvinceName = QC
localityName = Montreal
organizationName = reelyActive
commonName = Pareto Anywhere
domainComponent = machine

[req_ext]
subjectAltName = @alt_names
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth

[v3_req]
subjectAltName = @alt_names

[alt_names]
URI.1 = urn:machine:NodeOPCUA-Server

Update the domainComponent and URI.1 fields, replacing "machine" with the network name of the machine running barnacles-opcua. Optionally update the other fields of the distinguished name to reflect the organisation/software using barnacles-opcua.

Create a CA.cnf file

[ req ]
prompt = no
distinguished_name = req_distinguished_name

[ req_distinguished_name ]
C = CA
ST = QC
L = Montreal
O = reelyActive
OU = Develop
CN = Pareto Anywhere

Optionally update the fields of the distinguished name to reflect the organisation/software using barnacles-opcua.

Create the .pem files using OpenSSL

First, generate a CA private key & certificate:

openssl req -nodes -new -x509 -keyout CA_key.pem -out CA_certificate.pem -days 1825 -config CA.cnf

Second, generate the web server's secret key & CSR:

openssl req -sha256 -nodes -newkey rsa:2048 -keyout key.pem -out server.csr -config server.cnf

Third, create the web server's certificate, signing it with its own certificate authority:

openssl x509 -req -days 398 -in server.csr -CA CA_certificate.pem -CAkey CA_key.pem -CAcreateserial -out certificate.pem -extensions req_ext -extfile server.cnf

Assign the certificates

Configure barnacles-opcua by copying the certificate.pem and key.pem files to the /config folder, as described in the Config Files section above.

Options

barnacles-opcua supports the following options:

| Property | Default | Description | |:----------------|:---------------------------|:------------------------------| | port | 4840 | OPC UA Server port | | certificateFile | config/certificate.pem | Path to optional certificate | | privateKeyFile | config/key.pem | Path to optional key |

Acknowledgements

barnacles-opcua is based on the Node-OPCUA open source project, maintained by Sterfive, which we invite you to consider sponsoring at opencollective.com/node-opcua.

Contributing

Discover how to contribute to this open source project which upholds a standard code of conduct.

Security

Consult our security policy for best practices using this open source software and to report vulnerabilities.

License

MIT License

Copyright (c) 2024 reelyActive

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.