Device Basics

Jari Krützfeldt 2018-09-24

Prerequisites

Introduction

This lesson will focus on the question of how are we actually getting data into the Connectware, i.e. to the MQTT data broker. If you followed along in the previous lesson on the technical overview of the Connectware, the following image will be familiar to you.

Connectware Architecture Device Mapper

Here we will focus on the Device Mapper and its connections to the shopfloor - the devices. We will first learn what a device is and then explain how we are able to connect and use the device.

What is a device

A device is any data endpoint which can be connected to by using a specific communication protocol (MQTT, OPC UA, Modbus, etc) and usually represents one shopfloor connection (e.g. a machine, sensor, signal analyzer, etc). Below are different examples to clarify what a device is.

Simple device

Think of a simple arm gripping machine in the physical world. It has a PLC that controls it and a few sensors that read back temperature, power consumption, etc. Lets then say all of these data points all use the same protocol such as OPC UA and all these endpoints are connected to the same network. This could then be represented in the Connectware as a single arm gripper device. By this logic any data endpoint can then be considered a simple device.

Complex device

Think of a machine that contains a few arm gripping machines like the simple device example above. It uses these different arm gripping machines to complete a single task. They all use the same protocol such as OPC UA and all endpoints are connected to the same network. This could then be represented in the Connectware as a complex device.

Even more complex device

Think of a complex arm gripping machine. This machine has multiple controlling PLCs and many sensors. In fact the PLCs and sensors use different protocols such as Modbus and OPC UA. They may also be connected to different networks. That means that even though it is one physical machine we would need multiple devices in the Connectware to represent this single machine. Such as upper arm gripper device, lower arm gripper device, etc. But that's okay since a single Connectware instance can cope with any number of devices. The only limit is the physical computing resources on the host machine.

How to install a device

Now that we know what a device is, let's install a device on the Connectware. For this example we are going to go with a simple machine device. We will also be using the YAML format based Device Commissioning File which tells the Device Mapper the type of device that we want to connect, its connection configuration and specifies the datapoints that should be accessed. Device Commissioning File details can be found in the protocol specific device lessons and in the Reference docs. For now lets focus on the three main sections of the Commissioning file, which are

  • Source protocol
  • Target protocol
  • Data endpoint mappings

See the following schematic:

Device Mapper

In the following sections we will go through the three parts of a Device Commissioning File and create an example Device Commissioning File which we will use to connect to an OPC UA device and enable read access to a data endpoint. If you want to connect to a specific device afterwards, you can continue with the protocol specific device lessons which contain detailed information on how to configure the Device Mapper for different protocols.

Source protocol

The source protocol section of the device commissioning describes the device we want to connect to and its connection parameters, i.e. it defines what kind of device we are using and which protocol the Connectware should use to talk to it. The configuration needs to include the Connectware driver and connection parameters. Our source section looks like the following:

# ----------------------------------------------------------------------------#
# Source Interface Definition - OPC UA Protocol
# ----------------------------------------------------------------------------#
source:
  driver: opcua
  connection:
    protocol: opc.tcp
    host: <source host>
    port: <source port>
  defaults:
    operation: subscribe
    samplingInterval: <sampling interval msec>

We define that we want to use the opcua Connectware driver, which tells the Connectware that the device will be an OPC UA device. In order to be able to establish a connection to the device, we need to specify the connection settings as well. Here we want to use the opc.tcp protocol to connect to our device on the given host IP and port. Do not worry about the username and password for now.

Furthermore, we specified that the default operation (see mappings below) for the source should be subscribe, i.e. usually we want to read data from our OPC UA device. The default sampling interval specifies the interval in milliseconds in which we want to sample the OPC UA server.

Target protocol

The target protocol section describes the other side of the Device Mapper, the protocol to which the source data (here OPC UA) should be mapped to. Our preferred target protocol is MQTT, because the Connectware MQTT Broker is our main data hub. We want to map the OPC UA protocol of our device onto the Connectware MQTT Broker and thus get access to the data via MQTT. Similar to the source section of the commissioning file, we define the target section:

# ----------------------------------------------------------------------------#
# Target Interface Definition - MQTT (Connectware Data Broker)
# ----------------------------------------------------------------------------#
target:
  driver: mqtt
  defaults:
    operation: write
    topicPrefix: <topic-prefix>

We define that we are using MQTT as target driver and that the default operation is write (corresponding to the subscribe operation in the source section). Further, we can define a path which will be prefixed to all MQTT topics defined in the mappings below. As you may have noticed, the connection parameters are missing in the target section - this is due to the fact that the Connectware MQTT Broker is the default target. It is however possible to connect to any other MQTT broker by specifying its connection parameters.

Mappings

Mappings are a collection of data endpoints, each defined by the source and target address as well as the operation on the data.

mappings:
- source:
    typeAddress: <opcua-source-address>
    operation: <subscribe or write>
  target:
    topic: <MQTT-topic>
    operation: <subscribe or write>

This can be viewed as:

             _________ _______________ __________
            |         |               |          |
 Device ----| Source  | DEVICE MAPPER |  Target  |---- MQTT Broker
            |_________|_______________|__________|

Operation:  Subscribe |     ---->     | Write      (Read each value update from device)
Operation:  Write     |     <----     | Subscribe  (Write to the device)

This means we are mapping a datapoint from source to target by translating the source protocol to the target protocol. The operation defines the direction of this specific mapping. Here is an example OPC UA mapping:

mappings:
- source:
    nodeId: "ns=3;s=AirConditioner_1.Temperature"
  target:
    topic: "sensor/temperature"

Our example mapping transfers data from the source (OPC UA, source-default-operation = subscribe) on OPC UA nodeId ns=3;s=AirConditioner_1.Temperature to the target (MQTT, target-default-operation = write) on topic sensor/temperature. In our case we do not need to define the operations again, since we are using the default operations as defined in the source respectively target section.

In order to use our OPC UA device we need to find out which paths we want to use and how to define those paths in the Commissioning File, as mentioned above see the protocol specific lessons for more information afterwards.

Making the Device Commissioning File configurable

Imagine that we do not want to commission only one OPC UA device, but ten similar devices. In this case we would need to write ten different device commissioning files because the IP address and port might differ. For this case we can make our device commissioning file configurable by adding variables. Here we want to access the same datapoints at different devices, thus we can add a variable for the IP address and use an identifier for each device. Variables are used with the Mustache {{<variable name>}} notation. We need to add following to the source and target section:

# ----------------------------------------------------------------------------#
# Source Interface Definition - OPC UA Protocol
# ----------------------------------------------------------------------------#
source:
  driver: opcua
  connection:
    protocol: opc.tcp
    host: {{Source IP address}}
    port: {{Source Port}}
  defaults:
    operation: subscribe
    samplingInterval: 2000

Now we can use the same Device Commissioning File to connect multiple OPC UA devices. Upon installation, the Connectware will go through the variables and we are able to customize the Commissioning File before actually installing each device.

Putting it all together

Now that we know how to write a basic Device Commissioning File, let's analyze it in total once again. Here is our Commissioning File:

# ----------------------------------------------------------------------------#
# Source Interface Definition - OPC UA Protocol
# ----------------------------------------------------------------------------#
source:
  driver: opcua
  connection:
    protocol: opc.tcp
    host: {{Source Host}}
    port: {{Source Port}}
  defaults:
    operation: subscribe
    samplingInterval: 2000
# ----------------------------------------------------------------------------#
# Target Interface Definition - MQTT (Connectware Data Broker)
# ----------------------------------------------------------------------------#
target:
  driver: mqtt
  defaults:
    operation: write
    topicPrefix: cybus/learn/{{Device ID}}
# ----------------------------------------------------------------------------#
# Mappings
# ----------------------------------------------------------------------------#
mappings:
- source:
    nodeId: {{OPC UA Node Id}}
  target:
    topic: {{MQTT Topic}}

Let's go through it again. We have three sections source, target and mappings. In our example we are using an OPC UA device, thus we are using a suitable source configuration. We use a variable as source host and port to be able to reuse our file for multiple similar devices and we are specifying that the default source operation is subscribe.

We then specify our target, the MQTT data broker. Here we are using the default operation write and the the MQTT topic prefix cybus/learn/<device-id>. The default target configuration is the Connectware MQTT Broker, thus we do not specify any target connection settings.

In the mappings section, we define that we want to map the OPC UA path <opc ua browse path> to the MQTT topic <mqtt-topic> using the default operations as specified in the source respectively target sections.

After commissioning the device, the Device Mapper will publish an MQTT message with JSON payload with data from the OPC UA path to the MQTT topic cybus/learn/<device-id>/<mqtt-topic>. To use more mappings, we simply add more source/target definitions to the mappings section.

How to use a device

Our OPC UA Device Commissioning is ready, it is time to use the device. Therefore, let's commission it on the Connectware and see if we can generate data.

Commission the Device

We are finally ready to connect to our OPC-UA device and use it!

Go to the devices tab in the Connectware. Device tab

Click on the menu button in the lower right. Device menu

Click add on the menu. Device add

Select the Device Commissioning File that we just created and choose localhost as location (we can also commission the device at a Device Mapper Agent which can be placed e.g. directly at the device. This will however be covert in a separate lesson). Device select

Since we used variables in the commissioning, we are prompted here to fill those in. We will use opcuaserver.com as an example here and choose a suitable data endpoint. Commission the device

Press Install and the device will be installed. A new row with the installed device will appear. The row displays some useful information about our device.

Commission the device

Click on that row and we will go to the device details page. Here we can see that it is an OPC-UA device, the host and port that we used. We can also see the status section. This section indicates if the connection to the OPC-UA device and to the MQTT Broker could be established. If everything went well, both connection states should change to connected. Further we can see the execution location (here: localhost) and the data endpoint mappings and corresponding operations that we defined in the device commissioning file.

Device connected

The device is installed, now let's check if we can see incoming data.

Explore the device

To see the incoming data, go to the Explorer Tab in the Connectware and see the MQTT topic we specified in the Device Commissioning Files.

Connectware MQTT Explorer

By clicking the eye icon on the right of the topic the Explorer will subscribe to the specific topic. The current value will be shown in the monitor pane. The history view shows the topic history, as we can see the Device Mapper samples the OPC UA server every 2 seconds as defined in the source default section.

Summary

In this lesson we learned what a device is and how to connect to a basic OPC UA device. Furthermore we discussed how to make sure that our device is connected correctly by checking incoming data in the Connectware Explorer and how we can start using the device.

Going further

A good point to go further from here is to read the soon to come Service Basics Lesson, it will cover how to use the data from your devices.

Further, if you want to commission your own devices, first check out the different lessons on device commissioning available here at Cybus Learn (e.g. OPC UA or S7)!