# Devices¶

Device commissioning describes the process of integrating hardware of the shop-floor into the Cybus Connectware ecosystem.

Central to this process is the creation and installation of a so-called commissioning file. The commission file consists of 3 main parts:

• Source Protocol
• Target Protocol
• Data-endpoint mappings

A single commissioning file expresses a variable number of data-endpoint mappings for a specific source protocol to a target protocol (currently always MQTT).

Important

A single commissioning files works with exactly one source and one target protocol, but can express any number of data-point mappings between those.

Different device/protocol types hence require separate commissioning files. Separate commissioning files are also needed if the same protocol is used but is connected to different source instances (connections).

A single Connectware instance can cope with an arbitrary number of loaded commissioning files, only limited by physical computing resources.

## Commissioning file structure¶

The commissioning file uses the .yaml format.

Below a fully valid, but simple commissioning file is shown as an example:

Example 1
  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 # ----------------------------------------------------------------------------# # General Information # ----------------------------------------------------------------------------# general: name: HBM Device 1 # ----------------------------------------------------------------------------# # Source Protocol Definition - HBM DAQ Streaming # ----------------------------------------------------------------------------# source: driver: hbmdaq connection: protocol: hbmdaq host: {{IP address}} defaults: operation: subscribe # ----------------------------------------------------------------------------# # Target Interface Definition - MQTT (Cybus Connectware Broker) # ----------------------------------------------------------------------------# target: driver: mqtt defaults: operation: write topicPrefix: io/cybus/hbm # ----------------------------------------------------------------------------# # Mappings: The HBM Box has a set of default signals for each connector # and may additionally have user-defined signals # ----------------------------------------------------------------------------# mappings: - source: signal: AnalogIn_Connector1.Signal1 target: topic: analog1/signal1 - source: signal: AnalogIn_Connector2.Signal1 target: topic: analog2/signal1 

From the file you quickly see some important syntax rules:

• Comments always start with #
• Keys are separated from values using a :
• Indentation is used to express nesting
• A - sign indicates a list of key:value instructions
• The {{...}} acts as a template, which can be configured later at installation time

Moreover, you see the structuring into the three parts (highlighted in yellow) mentioned above:

### General Information¶

The section general contains meta data for this device mapping. The following keys are currently supported:

name
Name of the device to display in the overview (defaults to connection string)
image
avatar image of the device to show in the overview

### Source Protocol¶

Starting with the key source this section describes the connection parameters for the device going to be connected. It contains the protocol identifier driver and all connection parameters for this protocol under connection.

Depending on the protocol type this information may need to contain more or less sub-information, such as port, protocol, user, password, etc. See the individual protocol documentations for detailed information.

Note

It is recommended to make installation specific parameters configurable using the {{...}} template syntax (as is done in the example file in line 8). This allows using a single file to configure different installations. The Connectware’s web interface will automatically generate a form allowing to fill this template variables.

### Target Protocol¶

Currently, only the MQTT protocol is supported as target. In future other protocols such as REST will be available here. For the MQTT broker we recommend a configuration as shown in the example file, or even with a flexible topicPrefix: {{TopicPrefix}}.

### Mapping¶

This section describes the mappings of source protocol data-endpoints into a MQTT topic names. Consequently, each mapping entry defines one data-endpoint name in the source and one in the target protocol’s namespace. To this end the source and target keys as defined in the above sections of the commissioning file are reused of to refer to the respective protocols.

Important

source and target always refer to the protocol as defined in the respective section of the commission file independent of the direction of the data flow.

Besides identifying the data-endpoint’s name, the operation to be done on a given data-endpoint needs to be fixed.

#### Operation¶

In principle, three operations are possible for a given data-endpoint.

• subscribe
• write
• read

subscribe starts a listener and reacts on each update of the data-endpoint’s value. write issues a write operation on the given data-endpoint and read triggers a read-request.

Let’s look at an example to understand this better:

Example 2
 1 2 3 4 5 6 7  mappings: - source: signal: AnalogIn_Connector1.Signal1 operation: subscribe target: topic: analog1/signal1 operation: write 

This example shows a valid mapping for a single data-endpoint from a HBM protocol as source to a MQTT protocol as target.

The operation on the source is subscribe (line 4). Any value update on the data-endpoint AnalogIn_Connector1.Signal1 will trigger a write operation (line 7) on the data-endpoint <topic-prefix>/analog1/signal1. This way the data flows from source to target. In other words: we read from the HBM device.

An inversion of the operation would result in a data flow from target to source. We would hence write to the HBM device.

A read operation on the source combined with a subscribe operation on the target would expresses a read-request into the source that typically needs another mapping (subscribe/write) to reflect forwarding of the read response.

Note

As different protocols have different requirements for identifying a distinct data-endpoint, the keys are specific to the respective protocol (like signal and topic in the above example).

Please refer to the individual protocol’s documentation for the specific key names.

## Installing a commissioning file¶

Commissioning files are installed using the web-based interface of the Connectware. Once you have opened the entry screen of the Connectware interface:

1. If the navigation panel is not displayed on the left side click the menu icon in the upper left corner.
1. On the navigation panel click on Devices.
1. Press the + Button in the bottom right corner to add a mapping.

2. In the popped up dialog click Choose File and select the commissioning file in the file browser.

3. Afterwards click on Location and choose the host on which the device mapping should be running. If you have just one Cybus running you typically select local (localhost).

4. Click Install.

5. If you have custom parameters in your commissioning file now the Configure Device dialog shows up. Enter the needed information and click Install to continue.

1. In case everything was configured correctly, you should see the mapping becoming connected in the next screen.

Once you see a successfully connected device mapping data can flow from the source protocol to the broker.

Important

Your data however, is still safe, in order to access the data one or more users with appropriate authorizations have to be created (see user/granteeManagement how).

Unless actively deleted, this mapping will be alive and persisted even over eventual restarts of the entire Cybus Connectware.