Add ROC Connection - How To
You can add an Emerson Operations Controller (ROC) connection through the Kelvin UI, Kelvin SDK and Kelvin API.
Only available for x86_64 devices. arm64 version coming soon.
Connections was formerly called Bridges. You will find the Kelvin SDK and Kelvin API commands still refer to Connections as Bridges.
To start click on the Connections menu option from the left side bar menu.
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 ROC 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/Write (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.
curl -X "POST" \
"https://<url.kelvin.ai>/api/v4/bridges/deploy" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "demo-well-roc",
"title": "Demo Well ROC",
"cluster_name": "demo-cluster",
"app_name": "kelvin-bridge-roc-client",
"app_version": "3.0.2",
"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": "pcp_50",
"configuration": {
"address": "000.3838.388",
"polling_rate": 1,
"protocol_type": "INT8",
"scale_multiplier": null
},
"data_type": "raw.float64",
"name": "accelerometer_data"
}
]
}
}'
The response will look something like this;
{"name":"demo-well-roc","title":"Demo Well ROC","cluster_name":"demo-cluster","workload_name":"demo-well-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":"pcp_50","configuration":{"address":"000.3838.388","polling_rate":1,"protocol_type":"INT8","scale_multiplier":null},"data_type":"raw.float64","name":"accelerometer_data"}]},"enabled":true,"node_name":"sales-01-cluster","app_name":"kelvin-bridge-roc-client","app_version":"3.0.2","status":{"state":"pending_deploy","message":"Pending for deploy","last_seen":"2024-06-01T05:47:02.140680176Z","warnings":null},"created":"2024-06-01T05:41:34.75806Z","updated":"2024-06-01T05:47:01.342726Z"}
Then in Kelvin UI under Connections you will see your Connection deployed and running.
If you have any issues in the deployment and the /bridges/deploy fails to run, then you can check its logs.
from kelvin.api.client import Client
# Login
client = Client(config={"url": "https://<url.kelvin.ai>", "username": "<your_username>"})
client.login(password="<your_password>")
# Create Connection (Bridge)
response = client.bridge.deploy_bridge(data={
"name": "demo-well-roc",
"title": "Demo Well ROC",
"cluster_name": "demo-cluster",
"app_name": "kelvin-bridge-roc-client",
"app_version": "3.0.2",
"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": "pcp_50",
"configuration": {
"address": "000.3838.388",
"polling_rate": 1,
"protocol_type": "INT8",
"scale_multiplier": None
},
"data_type": "raw.float64",
"name": "accelerometer_data"
}
]
}
})
print(response)
You will get a response similar to this;
cluster_name='demo-cluster' created=datetime.datetime(2024, 6, 1, 6, 23, 19, 24631, tzinfo=datetime.timezone.utc) enabled=True name='demo-well-roc' node_name=None payload=AppYaml(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}, metrics_map=[{'access': 'RO', 'asset_name': 'pcp_50', 'configuration': {'address': '000.3838.388', 'polling_rate': 1, 'protocol_type': 'INT8', 'scale_multiplier': None}, 'data_type': 'raw.float64', 'name': 'accelerometer_data'}], logging_level='INFO') status=WorkloadStatus(last_seen=datetime.datetime(2024, 6, 1, 6, 23, 20, 33055, tzinfo=datetime.timezone.utc), message='Received', state=<WorkloadStatus.received: 'received'>, warnings=None) title='Demo Well ROC' updated=datetime.datetime(2024, 6, 1, 6, 23, 19, 24631, tzinfo=datetime.timezone.utc) workload_name='demo-well-roc' app_name='kelvin-bridge-roc-client' app_version='3.0.2'