Add ROC Connection - How To¶
You can add an Emerson Operations Controller (ROC) connection through the Kelvin UI, Kelvin SDK and Kelvin API.
Kelvin UI¶
To start go to Connections and click on the Create Connection button.
Step 1¶
Select the ROC option and click Next.
Step 2¶
Type in a memorable name in the Connection Display Name text input. You can use any letters, numbers and special characters.
The Connection Name text input will be automatically converted and filled in as you type in the Connection Display Name section. The conversion ensures the Connection Name only contains lowercase alphanumeric characters and ., _ or - characters.
Then select which Cluster to deploy the new Connector to.
It is important that the asset is reachable from the selected Cluster.
Step 3¶
Configure the ROC connection to the asset. There are a number of optional and mandatory parameters to fill in.
For the optional parameters, if you do not fill in any values, the default values will be used.
| Parameter | Options | Description | Default | Mandatory |
|---|---|---|---|---|
| ROC Plus Protocol | Boolean (True/False) | Indicates whether the ROC Plus protocol is used for communication. | False | No |
| Host Unit | Numeric value | Identifies the unit number of the host in the ROC network. | Yes | |
| Host Group | Numeric value | Specifies the group number the host belongs to in the ROC network. | Yes | |
| Dead Poll | Boolean (True/False) | Enables or disables the detection of non-responsive polls, marking a poll as 'dead' if not answered. | False | Yes |
| Optimize Read Requests | Boolean (True/False) | Enables or disables optimization of read requests to reduce network traffic. | False | Yes |
| Optimize Write Requests | Boolean (True/False) | Enables or disables optimization of write requests to reduce network traffic. | False | Yes |
| Number of Socket Connections | Numeric value | Defines the number of socket connections to be maintained with the ROC device. | 1 | No |
| Socket Connections Timeout (In Seconds) | Numeric value | The maximum duration to wait for a response on a socket connection before timing out. | 2 | No |
| Connection | Serial, Ethernet | Specifies the type of connection used to communicate with the ROC device. | Yes | |
| IP | String (IP address format) | The IP address used for Ethernet communication with the ROC device. | Yes | |
| Port | Numeric value (port number) | The network port number used for Ethernet communication with the ROC device. | Yes | |
| Device | String value | Identifies the specific ROC device for Serial Connections. | Yes | |
| Baud Rate | Numeric value (in baud) | The communication speed for Serial connections, measured in baud (e.g., 9600, 19200). | 9600 | Yes |
Step 4¶
Download, complete, and upload the available template to define the mapping connections between the Modbus address and the Asset/Data Stream.
You can only upload one file. Multiple file uploads is not allowed and only the latest selected file will be used.
Do not modify the header in the downloaded template file. In the next step the header will be checked to ensure the csv structure is correct. Start adding your data from row 2 onwards.
| Header | Description | Example | Mandatory |
|---|---|---|---|
| DataStream Name | The Kelvin Data Stream name (must be lowercase alphanumeric with no spaces) | water-flow | Yes |
| Asset Name | The Kelvin Asset name (must be lowercase alphanumeric with no spaces) | well-01 | Yes |
| DataStream Type | The type of data (boolean, number, object and string) | number | No |
| Access | Read/Wrtie (RW) or Read Only (RO) | RO | Yes |
| Storage | Location of the storage; "none", "node", "node-and-cloud" | node-and-cloud | No |
| Polling Rate (in seconds) | How often to pull the data from the asset | 30 | Yes |
| TLP | A three-component address system used to identify specific data points (Type, Logical, Parameters) in the ROC800’s database | Yes | |
| Protocol Type | Supports various protocols including ROC Plus protocol and Modbus master and slave protocol | Yes | |
| Device Series | Specific series or version of the ROC800 controller | Yes | |
| ROC Unit | Identifier for the specific ROC800 unit in use | Yes | |
| ROC Group | Defines the group setting or configuration within the ROC network | Yes | |
| Operator ID | User identifier for system access and operations | Yes | |
| Password | Security feature for accessing and operating the ROC800 system | Yes | |
| Access Level | Defines the level of access or permissions granted to a user or operator ID | Yes |
Step 5¶
The file will now be validated before you can initiate the connection with the following checks;
- Structure
- All required columns are present
- Columns naming is correct
- File has content below the header
- Content
- Required Fields (Data Stream Name, Asset Name and Access fields are properly filled)
- Content Matches the patterns and is valid content
- No duplicate content has been detected
- System
- All Assets exist on the system
- All Data Stream exist on the system
If there are any errors, you can view the details by clicking on the Show Errors button.
After looking at the error list, you will need to correct your csv file and then return to Step 4 to re-upload. The new file will then be checked and validated again.
When everything is validated, then you can click on Connect button to deploy the Connector to the Cluster. It will start automatically, connect to the asset and start collecting data.
Then in Kelvin UI under Connections you will see your Connection deployed and running.
If you have any issues in the deployment and the Add Connection fails to run, then you can check its logs.
Kelvin SDK¶
You can add a new ROC Connection (Bridge) using the following command;
$ kelvin bridge deploy --help
Usage: kelvin bridge deploy [OPTIONS]
Deploy a bridge with specified parameters. e.g. kelvin bridge deploy
--bridge-name "test-bridge" --cluster-name "my-node" --protocol "opc-ua"
--bridge-config "/path/to/app.yaml"
Options:
--cluster-name TEXT The name of the cluster (or node) to deploy the bridge
to. [required]
--bridge-name TEXT The friendly name of the bridge. [required]
--protocol TEXT The protocol to be used by the bridge. May be one of:
[opc-ua, mqtt, modbus, roc] [required]
--bridge-title TEXT The title of the bridge.
--bridge-config PATH The configuration file (e.g. app.yaml) to be used by
the bridge. [required]
-v, --verbose Display all executed steps to the screen.
--help Show this message and exit.
| Option | Description |
|---|---|
| cluster-name | This is the name of the Kelvin Cluster where you want to deploy the Connection (Bridge). (Note: This is not the Title but the name which can not include spaced). |
| bridge-name | This is the name for the Connection. It must be all lowercase and cannot include spaces and any special characters except "-" and "_". It also must start with a alphabet letter. |
| protocol | This will be roc |
| bridge-title | This is a friendly name for the Connection. It can include special characters and spaces. If using spaces, make sure to wrap your title with quotation marks. |
| bridge-config | This is a file with all the Kelvin Asset / Kelvin Data Stream information and their links to the asset addresses. |
Create a yaml file called roc.yaml and put the following information inside;
app:
bridge:
configuration:
asset_configurations:
tank-farm:
device_series: '32'
roc_group: 18
roc_unit: 24
connection:
ethernet:
ip: 192.168.0.100
mode: client
port: 8080
protocol: tcp
type: ethernet
dead_poll_enabled: false
host_group: 24
host_unit: 32
optimize_read_requests: false
optimize_write_requests: false
language:
cpp:
dso: kelvin_bridge_roc_client/kelvin_bridge_roc_client.so
type: cpp
logging_level: INFO
metrics_map:
- access: RO
asset_name: docs-demo-bridge
configuration:
address: 000.3838.388
polling_rate: 1
protocol_type: INT8
scale_multiplier:
data_type: raw.float64
name: docs-demo-bridge-roc
protocol: ROC
type: bridge
info:
description: Demo Well ROC
name: demo-well-roc
title: Demo Well ROC
version: 2.5.0
spec_version: 4.10.0
Then run the command in the terminal;
kelvin bridge deploy --cluster-name docs-demo-cluster-k3s --bridge-name demo-well-roc --protocol roc --bridge-title "Demo Well ROC" --bridge-config roc.yaml --verbose
You should see a response similar to this;
[kelvin.sdk][2023-09-08 16:19:11][R]
Bridge "kelvin-bridge-roc-client" successfully deployed.
Then you can check the status with kelvin bridge list command.
It will only show here when it is running on the edge. If it is pending deploy, it will not show here. You can see the actual status of the Connections in the Kelvin UI.
[kelvin.sdk][2023-12-07 20:08:26][I] Retrieving bridges..
[kelvin.sdk][2023-12-07 20:08:28][I] *************************** Bridges ***************************
+-------------------------------+-------------------------------------+------------------------+-------------------------------+------------+----------------------------------+----------------------------------+
| Name | Title | Node name | Workload name | Protocol | Created | Updated |
|-------------------------------+-------------------------------------+------------------------+-------------------------------+------------+----------------------------------+----------------------------------|
| demo-well-roc | Demo Well ROC | docs-demo-cluster-k3s | demo-well-modbus | roc | 2023-12-07 12:38:39.045767+00:00 | 2023-12-07 12:38:39.045767+00:00 |
+-------------------------------+-------------------------------------+------------------------+-------------------------------+------------+----------------------------------+----------------------------------+
Or in Kelvin UI under Connections you will see your Connection deployed and running.
If you have any issues in the deployment and the kelvin bridge deploy fails to run, then you can check its logs.
Kelvin API¶
/bridges/deploy
The API request POST for adding a new ROC Connection (Bridge) can be done with the /bridge/deploy request POST.
You can easily make a new ROC Connection by using the Request Body like this;
{
"name": "docs-demo-bridge-roc",
"title": "Docs Demo Bridge ROC",
"cluster_name": "docs-demo-cluster-k3s",
"workload_name": "docs-demo-bridge-roc",
"protocol": "roc",
"payload": {
"configuration": {
"asset_configurations": {
"tank-farm": {
"device_series": "32",
"roc_group": 18,
"roc_unit": 24
}
},
"connection": {
"ethernet": {
"ip": "192.168.0.100",
"mode": "client",
"port": 8080,
"protocol": "tcp"
},
"type": "ethernet"
},
"dead_poll_enabled": false,
"host_group": 24,
"host_unit": 32,
"optimize_read_requests": false,
"optimize_write_requests": false
},
"logging_level": "INFO",
"metrics_map": [
{
"access": "RO",
"asset_name": "docs-demo-bridge",
"configuration": {
"address": "000.3838.388",
"polling_rate": 1,
"protocol_type": "INT8",
"scale_multiplier": null
},
"data_type": "raw.float64",
"name": "docs-demo-bridge-roc"
}
]
}
}
If you have any issues in the deployment and the kelvin bridge deploy fails to run, then you can check its logs.