Tentacle-edge NPM

Tentacle

Travis (.com)

A nodejs industrial automation edge gateway with a GraphQL API.

Installation

The best way to get a full featured tentacle install (which includes tentacle-ui and exposes everything on port 80) is using LXD and applying the tentacle-docker profile.

To install tentacle as a global module with all of it's dependencies:

sudo npm install -g --unsafe-perm tentacle-edge

Once installed you can run them command tentacle to start the server. You can use Ctrl-C to stop the server.

The graphql api will then be available at http://localhost:4000. You can also access Graphql Playground, a powerful GraphQL IDE, at that at that address.

Starting Tentacle on Boot

The easiest way is to use PM2.

Install PM2
```
sudo npm install -g pm2
```
Determine the exact location of the tentacle command
if you have installed tentacle globally, then on linux/OS X the tentacle command will probably be either: /usr/bin/tentacle or /usr/local/bin/tentacle. The command which tentacle can be used to confirm the location.
Tell pm2 to run Tentacle
The following command tells PM2 to run tentacle, assuming /usr/bin/tentacle as the location of the tentacle command.
The -- argument must appear before any arguments you want to pass to tentacle.
```
pm2 start /usr/bin/tentacle -- -v
```
This will start tentacle in the background. You can view information about the process and access the log output using the commands:
```
pm2 info tentacle
pm2 logs tentacle
```
More information about managing processes under PM2 is available here.
Tell PM2 to run on boot
```
pm2 save
pm2 startup
```
This will generate a command that you must copy/paste and run to add the pm2 process to your services.
Reboot
Reboot and verify everything is working as expected.

Protocols

Services

MQTT (Sparkplug B)

GraphQL API

GraphQL

Query

Read only queries

Gets user based on authentication header and returns relevant data

Requires a valid authorization token. List of all tags configured in this gateway

Requires a valid authorization token. ist of all scan classes configured in this gateway

Requires a valid authorization token. List of all devices configured in this gateway

Requires a valid authorization token. List of all services configured in this gateway

Mutation

Read/Write queries

If a valid username and password is provided, this will return an auth payload with a java web token to be used for future requests and information about the user that successfully logged in.

Allows the user to change their password

Requires a valid authorization token. Creates a new scan class

Requires a valid authorization token. Updates an existing scan class

Requires a valid authorization token. Deletes a scan class. Will not be successfully if there are tags currently assigned to this scan class.

Requires a valid authorization token. Creates a new tag

Requires a valid authorization token. Updates an existing tag

Requires a valid authorization token. Deletes a tag. Will delete any source assigned to this tag, and tag will no longer be scanned.

Requires a valid authorization token. Creates a opcua device, and automatically starts a connection.

Requires a valid authorization token. Updates an existing opcua device and refreshes the connection.

Requires a valid authorization token. Deletes a opcua device. All sources assigned to this device are deleted and tags using this device as a source will have their sources set to null, making their values static.

Requires a valid authorization token. Creates a OPC UA source. The tag value will then be updated to the value at the source register per the scan class

Requires a valid authorization token. Updates a OPC UA source register. The tag value will then update per the new register at the rate of the scan class.

Requires a valid authorization token. Deletes a OPC UA source. The tag value will then be static.

Requires a valid authorization token. Creates an Modbus TCP/IP device, and automatically starts a connection.

Requires a valid authorization token. Updates an existing modbus device and refreshes the connection.

Requires a valid authorization token. Deletes a modbus device. All sources assigned to this device are deleted and tags using this device as a source will have their sources set to null, making their values static.

Requires a valid authorization token. Creates a modbus source. The tag value will then be updated to the value at the source register per the scan class

Requires a valid authorization token. Updates a modbus source register. The tag value will then update per the new register at the rate of the scan class.

Requires a valid authorization token. Deletes a modbus source. The tag value will then be static.

Requires a valid authorization token. Creates an Ethernet/IP device, and automatically starts a connection.

Requires a valid authorization token. Updates an existing Ethernet/IP device and refreshes the connection.

Requires a valid authorization token. Deletes an Ethernet/IP device. All sources assigned to this device are deleted and tags using this device as a source will have their sources set to null, making their values static.

Requires a valid authorization token. Creates an Ethernet/IP source. The tag value will then be updated to the value at the source register per the scan class

Requires a valid authorization token. Updates an Ethernet/IP source tagname. The tag value will then update per the new tagname at the rate of the scan class.

Requires a valid authorization token. Deletes an Ethernet/IP source. The tag value will then be static.

Requires a valid authorization token. Creates an MQTT Sparkplug B service (tied to a single MQTT broker).

Requires a valid authorization token. Updates an MQTT Sparkplug B service and restarts the connection.

Requires a valid authorization token. Adds a device to an MQTT service. All the tags with sources from that device will be published at the rate of the MQTT service configuration.

Requires a valid authorization token. Deletes a device from an MQTT service. The tags for the removed device will no longer be published to the broker (but the device and tags will still exist).

Requires a valid authorization token. Adds a primary host id to monitor (for store & forward)

Requires a valid authorization token. Deletes a primary host id to monitor (for store & forward)

Requires a valid authorization token. Deletes an MQTT Service. All devices assigned to this service will no longer have their tags published.

Objects

AuthPayload

The data returned after a successful login attempt.

Bearer token to be added to the Authorization header for future requests.

User that successfully logged in.

Device

A Device is a something that can serve data to be used for updating tag values, such as a modbus TCP or Ethernet/IP server.

Identifier for the device that will be also used for external services, such as MQTT Sparkplug B.

Description to allow for users to give the device more context.

Configuration is specific to the protocol used by the device, such as modbus or Ethernet/IP

User who created the tag.

Date/time the tag was created.

EthernetIP

Ethernet/IP is a device config allowing for access to data for updating tag values per the ODVA Ethernet/IP specification.

Device for this Ethernet/IP configuration.

Host or IP address of the Ethernet/IP device. Port is fixed at 44818.

Slot of the PLC. It is typically zero for devices that do no have slots or where the PLC is fixed.

List of sources (tag/register) pairs that are using this Ethernet/IP device.

Status of the Ethernet/IP device connection. Will be connected if connection is successful or an error message if connection failed.

EthernetIPSource

An Ethernet/IP source reads an tag from an Ethernet/IP device and updates a tag value per the tags scan class.

The ethernet/IP device this source uses to get the register values.

The tag to update.

The tagname of the tag in the Ethernet/IP device (not to be confused with the name of the tag in this gateway)

Modbus

Modbus is a device config allowing for access to data for updating tag values per the Modbus TCP specification.

Device for this modbus configuration.

Host or IP address of the modbus device.

Port of the modbus device.

Whether registers are stored as Big Endian (false) or Little Endian (true).

Whether multiregister sources should use the lowest register first (false) or the highest register first (true).

How long to wait to for connection with the device to complete before throwing an error.

List of sources (tag/register) pairs that are using this modbus device.

Status of the modbus device connection. Will be connected if connection is successful or an error message if connection failed.

Whether registers start from zero or one. Can be used to make sure device addresses and those configured in the gateway match (and are not one off from eachother)

Milliseconds between retries when connection is interrupted.

ModbusSource

A Mobus source reads a register from a modbus TCP device and updates a tag value per the tags scan class.

The modbus device this source uses to get the register values.

The tag to update.

The starting register to read from the modbus device.

The register type per the modbus specification. Can be HOLDING_REGISTER, INPUT_REGISTER, DISCRETE_INPUT, or COIL.

Mqtt

MQTT is a service that allows for publishing tag values to an MQTT broker using the sparkplug B specification, which will server data to other subscribing nodes. One broker per service.

Hostname or IP address of the MQTT broker

Port for the service on the MQTT broker

Identifies a logical grouping of edge devices.

Identifies the edge device pushing data to the MQTT broker.

MQTT Broker username.

MQTT Broker password.

List of MQTT source devices that will be publishing to this broker.

Publishing rate in milliseconds

True if ssl:// is to be used, otherwise tcp:// will be used.

Maximum number of records to publish at one time while forwarding historical data.

Primary host IDs. This is used for store and forward to detect if the consumers are online. The gateway will store data if any consumer is offline.

MqttPrimaryHost

MQTT is a service that allows for publishing tag values to an MQTT broker using the sparkplug B specification, which will server data to other subscribing nodes. One broker per service.

Primary Host ID, used to verify primary host state for store and forward

UKNOWN before STATE has been received from broker, ONLINE/OFFLINE otherwise, indicating status

Number of historical records stored, awaiting forwarding

MqttSource

An MQTT source publishes data from all tags with the same device source. The device name will be used as the Device field in sparkplug B.

MQTT service (broker)

Source device. All tags updating their values from this device will be published at the MQTT services configured scan rate.

Number of historical records stored, awaiting forwarding

Opcua

Opcua is a device config allowing for access to data for updating tag values per the Opcua specification.

Device for this Opcua configuration.

Host or IP address of the modbus device.

Port of the modbus device.

Status of the modbus device connection. Will be connected if connection is successful or an error message if connection failed.

Milliseconds between retries when connection is interrupted.

Nodes

Non-heirarchical list

List of sources (tag/nodeId) pairs that are using this opcua device.

OpcuaNode

OpcuaSource

An OPC UA source reads an tag from an OPC UA device and updates a tag value per the tags scan class.

The OPC UA device this source uses to get the register values.

The tag to update.

The node id of the tag in the OPC UA device

ScanClass

A scan class allows for groups of tags to be updated at the same pre-defined rate.

Identifier for the scan class, used as a brief descriptor

Description to allow for users to give the scan class more context.

Rate at which to update that tags assigned to this scan class from their device source.

List of tags assigned to this scan class

The number of times this scan class has been scanned since the scan class scan started. This values clears to zero when the periodic scan is stopped.

Service

A service makes data available to external services by acting as a server or publishing the data as is done with MQTT.

Identifier for the service.

Description to allow for users to give the service more context.

Configuration is specific to the protocol used by the service, such as MQTT

User who created the service.

Date/time the service was created.

Subscription

Tag

A Tag stores data point values. It's value can be updated from a device source per it's scan class, and it's value can be made available to external services like MQTT.

Identifier for the tag that will be also used for external services, such as MQTT Sparkplug B.

Description to allow for users to give the tag more context.

Tag value, which is updated at the scan class rate from the assigned source and also delivered to services that use this tag as a source.

Format of that tag value, allowing clients to parse the value appropriately.

Assigned scan class which determines the rate at which the tag is updated from it's assigned source.

User who created the tag.

Date/time the tag was created.

Source from which this tag value is updated.

Maximum tag value (meant for use if the tag is numeric). Can be used to generate out of range indication and for graphical displays

Minimum tag value (meant for use if the tag is numeric). Can be used to generate out of range indication and for graphical displays

Deadband, used to determine whether to publish a change or write to history. If the change in value is less than the deadband, the update is ignored. If this value is zero, all changes are published and write to history.

Engineering units of the tag. Meant to be used for user displays to give context to a numerical value.

User

Credentials used to identify who is logging into the gateway.

Enums

Datatype

Tag datatypes allowing for clients to properly parse tag values.

ModbusRegisterType

Modbus register types for use with modbus sources per the modbus specification.

Scalars

Boolean

The Boolean scalar type represents true or false.

DateTime

Used to deliver timestamp values.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.