{% hint style="success" %}
If you haven't installed ObX collector go over [here](/obx-r3-manual/installation/installation.md#installing-obx-collector-component).
{% endhint %}
## How ObX Collector works
The system interfaces with diverse sources like OPCUA servers, MQTT brokers, and Modbus devices (TCP and Serial). It incorporates data buffering functionality, which autonomously caches data during network disruptions between the ObX collector and ObX Historian, or in the event of historian server downtime. Subsequently, it automatically transfers the buffered data to the ObX historian upon network restoration or server availability.
### Supported Protocol
Currently the ObX Collector supports the following protocol. In the future release, it will soon support Bacnet and EthernetIP.
* OPCUA (Polling and Subscribe)
* MQTT (Pub and Sub)
* Modbus (TCP and RTU)
### What if my current system doesn't have the supported protocol of the ObX collector?
We prioritize the utilization of diverse communication protocols, with a particular emphasis on those widely adopted across various industries. OPC UA and Modbus are prevalent in small, medium, and large-scale Industrial Automation settings, whereas MQTT is commonly employed in the Internet of Things (IoT) domain. One advantageous aspect of these protocols is their widespread device support. However, in instances where existing systems or devices lack compatibility with these protocols, we recommend the use of protocol gateways readily available in the market as a straightforward solution.
There are multiple gateways that can convert multiple communication protocol to OPCUA protocol. Here are some.
* [Ignition Gateway](https://inductiveautomation.com/downloads/)
* [Cogent DataHub](https://cogentdatahub.com/products/cogent-datahub/)
* [Matrikon OPC Gateway](https://www.matrikonopc.com/)
* [Haiwell PLCs (with built-in opcua server) and Cloud SCADA](https://en.haiwell.com/)
* [Kepware Server](https://www.ptc.com/en/products/thingworx/thingworx-kepware-server/demo-download)
These are just a few of the many gateways that you can use, most of them are cheap and have a FREE trial. You may use them to convert almost any protocols into a protocol supported by ObX collector.
{% hint style="info" %}
You can access the ObX Collector UI by opening your browser and typing in [http://localhost:188](http://localhost:1880)[1](http://localhost:1881/)
{% endhint %}
Accessing ObX Collector UI
## Accessing ObX Collector UI
1. Open your browser and typing in
2. From the top-left side, click on the `hamburger` menu and click `Go to Settings`.
3. A login dialog will open. Type in the following credentials:
`username: admin`\
`password: admin`
Accessing ObX Collector UI
{% hint style="warning" %}
In the production environment, it is recommended to change the default password of the admin. You can change it anytime.
{% endhint %}
## Collector Historian Settings
Prior to incorporating any devices and adding tags into the ObX collector, it is imperative to configure the historian settings within the collector. These settings dictate the destination where the collector will transmit data for historization, typically the computer hosting the ObX historian software.
1. Open a browser and go to
2. Go to Settings and Login your credentials (see [here](#accessing-obx-collector-ui))
3. On the upper left side menu, click on the `settings` button with :gear: icon, this will open the collector settings window.
4. Click on the `Settings`, this will open the `Historian Settings`
5. Configure the Historian settings with the following:
| Field | Description | Value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Historian Type | Only ObX Historian available | N/A |
| IP Address | The IP address of computer where ObX historian component installed |
IP address (xxx.xxx.xxx.xxx)
FQDN (server.example.com)
localhost
|
| Datasource | The datasource name in the ObX historian as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). This will override the datasource field indicated in the Collector historian settings [here.](#collector-historian-settings) | Selection - a list of datasources created in the ObX Admin tool as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). |
| Collector Username | The username of the ObX Collector user. Make sure the user is existing as discussed [here.](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#create-obx-collector-user) | String and Case-senstive |
| Collector Password | The password of the ObX Collector user. Make sure the user is existing as discussed [here.](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#create-obx-collector-user) | String and Case-sensitive |
6. Click `OK`
Setting the Collector Historian
{% hint style="warning" %}
Make sure to input the correct ObX Collector username and password created in the ObX Admin tool as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#create-obx-collector-user).
{% endhint %}
## Adding OPCUA Device
Adding a device in ObX collector is pretty straightforward.
1. Open a browser and go to
2. From the upper right menu, click on the hamburger icon -> `Go To Settings` and Login your credentials (see [here](#accessing-obx-collector-ui))
3. On your lower right corner, click on the :heavy\_plus\_sign: button, this will open a `Device Property` window.
4. In the `name` field, type your preferred name of the device and from the type select `OPCUA`.
5. Fill all the required fields with valid values:
Field Name
Description
Values
Name
The name of the device (String)
String (any)
Type
The type of communication protocol.
OPCUA
Polling
How fast this device (client) polls data from the OPCUA server. Omitting it will default to (1000ms)
500ms
1 sec
5 sec
10 sec
30 sec
1 min
5 min
Enable
Wether this device is enabled (means polling data from the opcua server) or not (not polling data)
Toggled Boolean (True or False)
Address
The URL connection address of the OPCUA server in UA TCP protocol.
opc.tcp://server:port/
ObX Datasource Name
The datasource name in the ObX historian as discussed here. This will override the datasource field indicated in the Collector historian settings here.
Selection - a list of datasources created in the ObX Admin tool as discussed here.
Security
List of all available security settings in the specified OPCUA server URL.
Basic123Rsa15 - Sign
Aes128_Sha256_RsaOaep - Sign
Basic256Sha256 - Sign
None - None
Aes256_Sha256_RsaPss - Sign & Encrypt
Basic256 - Sign
Basic256 - Sign & Encrypt
Aes256_Sha256_RsaPss - Sign
Basic256Sha256 - Sign & Encrypt
Basic128Rsa15 - Sign & Encrypt
Aes128_Sha256_RsaOaep - Sign & Encrypt
Security (Username and Password) -Optional
If there is a credential indicated in the OPCUA server, you must supply the username and password.
5. Click `OK`
6. Repeat the steps if you want to add more.
Adding OPCUA Device
{% hint style="info" %}
A color green status of the device indicates that you are successfully connected to the OPCUA server. Otherwise it is color red indicating that there is a fault in the connection.
{% endhint %}
{% hint style="info" %}
There is no limitation of the number of OPCUA device to add in the ObX collector. However, make sure that there is enough resource capacity of the server where ObX collector is installed, the more data your are polling, the more resources is needed.
{% endhint %}
### Adding OPCUA Tags
{% hint style="warning" %}
Make sure you have successfully connected to the OPCUA server and you have enabled the OPCUA device first. You cannot add opcua tags when either of the conditions is met.
{% endhint %}
From the Device Settings of ObX Collector:
1. Click the `edit device tag` :link: icon of the specific device you want configure. This will open the List of tags already added in that device.
2. From lower right, click on the :heavy\_plus\_sign:icon. This will open the `Browse Tags in Server` window. This windows will allow you view and select existing tags in the opcua server.
3. Browse and Select all the Tags you want to add in the ObX Collector. Then click `OK`.
Adding OPCUA Tags
{% hint style="info" %}
By default, the Tag Options for every new tag added was set to the following:\
Historian - enable\
Polling Type - polled\
Save value interval - 1sec\
ObX Tagname - the Tagname of the tag selected\
Unit - Empty string\
Description - Empty string \
Engineering Max - 0\
Engineering Min - 0 \
Format - Empty\
Scale Mode - Empty\
\
To learn more about Tag Options, go [here](#tag-options).
{% endhint %}
## Adding Modbus Device
1. Open a browser and go to
2. From the upper right menu, click on the hamburger icon -> `Go To Settings` and Login your credentials (see [here](#accessing-obx-collector-ui))
3. On your lower right corner, click on the :heavy\_plus\_sign: button, this will open a `Device Property` window.
4. In the `name` field, type your preferred name of the device and from the type select `ModbusTCP or ModbusRTU`.
5. Fill all required fields with valid values:
#### For ModbusTCP Options:
| Field Name | Description | Values |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | The name of the device (String) | String (any) |
| Type | The type of communication protocol | ModbusTCP |
| Polling | How fast this device (Modbus Master) polls data from modbus slave device. Omitting it will default to (1sec) |
500ms
1 sec
5 sec
10 sec
30 sec
1 min
5 min
|
| Enable | Wether this device is enabled (means requesting data from Modbus slave) or not (not requesting data) | Toggled Boolean (True or False) |
| Connection Options | Type of connection on how this device will connect to the modbus slave. |
TcpPort - using tcp as protocol
UdpPort - using udp as protocol
TcpRTUBufferedPort
TelnetPort
|
| Slave IP and Port | The IP address of the modbus slave device. |
IP address:port xxx.xxx.xxx.xxx:\[port] e.g. (127.0.0.1:502)
|
| Slave ID | The slave ID of the modbus slave | 1-255 |
| ObX Datasource Name | The datasource name in the ObX historian as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). This will override the datasource field indicated in the Collector historian settings [here.](#collector-historian-settings) | Selection - a list of datasources created in the ObX Admin tool as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). |
| Fragmented | No effect | N/A |
#### For ModbusRTU
| Field Name | Description | Values |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | The name of the device (String) | String (any) |
| Type | The type of communication protocol | ModbusRTU |
| Polling | How fast this device (Modbus Master) polls data from modbus slave device. Omitting it will default to (1sec) |
500ms
1 sec
5 sec
10 sec
30 sec
1 min
5 min
|
| Enable | Wether this device is enabled (means requesting data from Modbus slave) or not (not requesting data) | Toggled Boolean (True or False) |
| Connection Options | Type of connection on how this device will connect to the modbus slave. |
SerialPort
RTUBufferedPort
AsciiPort
|
| ObX Datasource Name | The datasource name in the ObX historian as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). This will override the datasource field indicated in the Collector historian settings [here.](#collector-historian-settings) | Selection - a list of datasources created in the ObX Admin tool as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). |
| Serial Port | The serial port name where the modbus slave device is connected. | e.g. COM1 |
| Slave ID | The slave ID of the modbus slave device. | 1-255 |
| Baudrate | Baudrate of the communication. | Select from the options. |
| Data bits | Data bits of the communication. | Select from the options. |
| Stop bits | Stop bits of the communication. | Select from the options. |
| Parity | The parity of the communication. |
Odd
Even
None (default)
|
| Fragmented | No effect | N/A |
Adding Modbus TCP Device
Adding Modbus RTU
{% hint style="info" %}
A color green status of the device indicates that you are successfully connected to the Modbus slave device. Otherwise it is color red indicating that there is a fault in the connection.
{% endhint %}
{% hint style="info" %}
There is no limitation of the number of Modbus slave device to add in the ObX collector. However, make sure that there is enough resource capacity of the server where ObX collector is installed, the more data your are polling, the more resources is needed.
{% endhint %}
### Adding Modbus Tags
{% hint style="info" %}
When adding Modbus tag, take note that you have to know the list of Modbus addresses on the specific Modbus slave device. Contact the device supplier for the modbus table.
{% endhint %}
{% hint style="info" %}
Other thing to note is, the modbus address could be based zero or + 1, you can try to use other tool first like [ModbusPoll](https://www.modbustools.com/download.html) so you can easily identify its behavior.
{% endhint %}
When you already know specific modbus address:
1. Click the `edit device tag` :link: icon of the specific device you want configure. This will open the List of tags already added in that device.
2. From lower right, click on the :heavy\_plus\_sign:icon. This will open the `Tag Property` window.
3. Configure necessary field related to modbus.
| Field | Description | Values |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Tagname | The name of the Tag. | String (any) - case sensitive |
| Register | The type of register |
Coil Status
Digital Input
Holding Registers
Input Registers
|
| Type | The type of the modbus value. | Selection |
| Address offset | The modbus address of the tag. | 1-655536 |
| Divisor | Automatically divide the raw value of data to specific number. Suppose your recieve integer value of 100, and you set the Divisor = 10, then your value will become 100 / 10 = 10. | Number |
4. Click `OK` button.
Adding Modbus Tag
{% hint style="info" %}
By default, the Tag Options for every new tag added was set to the following:\
Historian - enable\
Polling Type - monitor\
Save value interval - 1sec\
ObX Tagname - the Tagname of the tag selected\
Unit - Empty string\
Description - Empty string \
Engineering Max - 0\
Engineering Min - 0 \
Format - Empty\
Scale Mode - Empty\
\
To learn more about Tag Options, go [here](#tag-options).
{% endhint %}
## Adding MQTT Device
1. Open a browser and go to
2. From the upper right menu, click on the hamburger icon -> `Go To Settings` and Login your credentials (see [here](#accessing-obx-collector-ui))
3. In your lower right corner, click on the :heavy\_plus\_sign: button, this will open a `Device Property` window.
4. In the `name` field, type your preferred name of the device and from the type select `MQTTClient`.
5. Fill all the required fields with valid values:
| Field Name | Description | Values |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | The name of device. | String (any) |
| Type | The type of connection | MQTTClient |
| Polling | How fast this device (client) polls data from the OPCUA server. Omitting it will default to (1000ms) |
500ms
1 sec
5 sec
10 sec
15 sec
30 sec
1 min
5 min
|
| Enable | Wether this device is enabled (means actively subscribing to a topic from the MQTT broker) or not (inactive). | Toggled Boolean (True or False) |
| Address | The mqtt broker address. | mqtt://server:port |
| ObX Datasource Name | The datasource name in the ObX historian as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). This will override the datasource field indicated in the Collector historian settings [here.](#collector-historian-settings) | Selection - a list of datasources created in the ObX Admin tool as discussed [here](/obx-r3-manual/backend-engineering/obx-backend-engineering.md#adding-datasource). |
| Security | If with Username and Password credentials |
Client-ID - define your custom clientID. Username - the username when connecting to MQTT broker. Password - the password when connection to MQTT broker.
|
| TLS Certificate | When connecting via TLS certificate, you have to upload the certificate given by the MQTT Broker. |
Certificate
Private Key
CA Certificate
|
6. Click `OK`
Adding MQTT Device
{% hint style="info" %}
A color green status of the device indicates that you are successfully connected to the MQTT Broker . Otherwise it is color red indicating that there is a fault in the connection.
{% endhint %}
{% hint style="info" %}
There is no limitation of the number of MQTT broker to add in the ObX collector. However, make sure that there is enough resource capacity of the server wher ObX collector is installed, the more data your are polling, the more resources is needed.
{% endhint %}
### Adding MQTT tags (subscribe)
{% hint style="info" %}
Before adding any MQTT tags, make sure that you have successfully connected to the broker and that the device is enabled.
{% endhint %}
1. Click the `edit device tag` :link: icon of the specific device you want configure. This will open the List of tags already added in that device.
2. From lower right, click on the :heavy\_plus\_sign:icon. This will open the `Broker Topics to subscribe and publish` window.
3. In the window, there are two tabs (Subscribe and Publish). Make sure you are in the `Subscribe` tab.
4. In the `Browser Topics in broker`, input the topic you want to subscribe. Then press the `Search` ๐icon.
{% hint style="info" %}
In the step 4, this will list multiple topics or a single topic depends on how to define the topic. If you use wildcards e.g. ("topic1/#"), then it should look to all topics under the "topic1".
{% endhint %}
5. From the list, click on the topic you want to add.
6. Select wether the payload format of the topic value is RAW or JSON. (You should select according to the actual value)
7. In the below configuration, specifically the "`Name`", you may input the name of the Tag you want for this Tag.
{% hint style="info" %}
In step 7, make sure you define a `Name` for the specific tag, otherwise it will be "undefined" and may cause error.
{% endhint %}
5. Click the `Subscribe` button.
Adding MQTT Tags
{% hint style="info" %}
By default, the Tag Options for every new tag added was set to the following:\
Historian - enable\
Polling Type - monitor\
Save value interval - 1sec\
ObX Tagname - the Tagname of the tag selected\
Unit - Empty string\
Description - Empty string \
Engineering Max - 0\
Engineering Min - 0 \
Format - Empty\
Scale Mode - Empty\
\
To learn more about Tag Options, go [here](#tag-options).
{% endhint %}
## Tag Options
Tag options defines the characteristic of the Tag on how are they historized in the ObX Historian. Such characteristics will be based on the following configuration.
| Field Name | Description | Values |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Historian | Wether this tag will be historized or not in the ObX historian. |
Toggled switch Boolean True - means it will historized to ObX historian False - nothing
|
| Polling type | The type of polling, wether to poll at every specific seconds (based on the settings of `Save value interval`) or Monitored. |
Polled - will read the data and save it regardless if its value changed or not. Use this if you want to historized specific parameters that very seldom to change its value. Monitored - will read and save the data if there is only a change in the value of the tag. Use this if your data changes frequently. Monitored items are only applicable for OPCUA device.
|
| Save value interval (sec) |
The value in seconds to how frequent this tag to be historized in ObX historian. Note: This will not override the polling interval settings in the Device level. Basic rule of ๐ is always make the polling interval in the Device level to be faster than the settings you will configure in a Tag level.
|
1 - 1 sec 5 - 5 sec 10 - 10sec 15 - 15sec and so on.. Note: Make sure that you will only input number that is when divided by 60 (1 minute), will not give you remainder.
|
| ObX Tagname | The name of the Tag in the ObX historian. |
String (Optional) default to the name of Tag itself.
|
| Unit | The unit of the Tag | String (Optional) |
| Description | The description of the Tag | String (Optional) |
| Engineering Max | The maximum value of the Tag |
Number (Optional) default to 0
|
| Engineering Min | The minumum value of the Tag |
Number (Optiona) defaul to 0
|
| Format digits | The number of decimal number points. |
Number (Optional) default to Nothing, automatically gets all the decimal number. Specifying 2 will only get the first 2 decimal number in the floating value.
|
| Scaling | Setting if you want to Scale Up or Down the raw value of the specific Tag. |
Options (default to No Scaling) No Scaling - No scaling of the value Linear - Linear scaling of up or down of the value
|
1. Click the `edit device tag` :link: icon of the specific device you want configure. This will open the List of tags already added in that device.
2. From the table of list of Tags, each row of Tag contains an ellipsis  icon (on their right-side). Click on this icon and select -> `Tag Options`.
3. Configure the `Tag Options` based on your requirements.
4. and Click `OK`.
5. To take effect all the Tag Options settings, click on the save icon ๐พ
Note: There are 2 save icon buttons in the collector, please click the save icon (right-side of the Timestamp column)
6. A confirmation dialog will open, simply click `OK`.
Tag Options
## Deleting / Removing a Tag
Deleting a tag in any devices is pretty straight-forward.
From the Device setting in ObX Collector:
* Click the `edit device tag` :link: icon of the specific device you want configure. This will open the List of tags already added in that device.
* From the list of Tags, you can see that for every tag, it has an option :heavy\_multiplication\_x: (at right side). Click the X mark of the Tag you want to delete. You can also delete multiple tags.
* Once you have deleted all the tags you want to delete. Click on the Save (At the top left corner) button to take effect.
{% hint style="info" %}
Make sure you hit that `Save` button (at the top left corner) to take effect the deletion.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://obx-organization.gitbook.io/obx-r3-manual/backend-engineering/obx-collector.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.