Sorba AI Analytics Connector

Run SORBA SDE machine learning models on Unified Namespace data over MQTT.

Name: SorbaAI
Version: 1.0.0.0
Protocol: MQTT
Interface: TCP/IP
Runtime: .NET 2.0 (Multiplatform)
Configuration:
- UNS / TagProviders

Download SorbaAI solution template: SORBA.dbsln (version 10.1.5.2020)

Overview

The SorbaAI connector links the Unified Namespace to SORBA SDE, an industrial machine learning platform. It exposes a SORBA model as a TagProvider namespace: live tag values go to SORBA for training and inference, and SORBA sends back predictions, model-quality metrics and anomaly indicators as tags you can use in displays, alarms and scripts.

Supported model types: Regression, Classification, Clustering, Forecasting, Digital Twin and Optimization.

Architecture

Input tags (UNS) --+
                   +--> SorbaAI TagProvider (Runtime) <--> MQTT broker <--> SORBA SDE
Historian ---------+

The MQTT broker is external to both products: usually the broker that comes with SORBA SDE, but any MQTT 3.1.1 broker reachable from both sides works.
The connector publishes the model structure and the live input values. SORBA trains the model and publishes predictions and diagnostics back.
When SORBA asks for training history, the connector reads it from the Historian module, whatever storage location the solution uses. The connector keeps no history of its own.
The station's Instance ID identifies the gateway to SORBA and must match an Integration record in SORBA SDE.

Designer and Runtime

Both the Designer and the Runtime load the station, but only the Runtime acts as the SORBA gateway: it publishes the structure and values, and answers SORBA's history requests.

The Designer connects as a read-only mirror. It shows the model tree, the SORBA outputs, output_message and the values the Runtime sends. It never sends anything to SORBA, and it refuses writes to SorbaAI tags: write values from the Runtime. With only the Designer open, SORBA receives nothing from the gateway.

MQTT topics

All topics are under sorba_framework_x/<Instance ID>/.

Topic	Direction	Content
`tags/structures`	To SORBA	Model structure, every 10 s.
`udt_definitions`	To SORBA	UDT definitions, every 10 s.
`tags/inputs/realtime`	To SORBA	Current values of all model tags except OUTPUTS, every 1 s.
`tags/inputs/historical/request`	From SORBA	Request for training history.
`tags/inputs/historical`	To SORBA	Historian samples of each input for the requested window.
`tags/outputs/realtime`	From SORBA	Predictions and diagnostics.
`tags/outputs/structure`	From SORBA	Structure of the OUTPUTS folder.

Prerequisites

SORBA SDE running and reachable on the network.
An MQTT broker reachable from SORBA SDE and from the Runtime computer: the broker included with SORBA SDE (default port 1883), the built-in MQTT broker, or any MQTT 3.1.1 broker.
An Integration record in SORBA SDE whose Name matches the station's Instance ID (see Setup).
The Runtime running. Only the Runtime exchanges data with SORBA.
For training: active historization of every input tag in the Historian module, with data covering the training window.

The connector is installed with the product. There is no separate installation step.

Setup

The configuration has two sides that must match: an Integration record in SORBA SDE and a SorbaAI TagProvider in the solution. Without the matching Integration record, SORBA ignores the gateway's MQTT traffic.

SORBA SDE side

In the SORBA SDE web UI, go to Edit Device > Services > Integrations and add an Integration with these values:

Field	Value
Integration	`ExternalTool`
Name	The Instance ID you will use in the station, for example `frameworx_gateway` (the station default).
Server Name	MQTT broker host, for example `localhost` when using the SORBA SDE broker.
Port	MQTT broker port (default `1883`).
UserName	MQTT broker username.
Password	MQTT broker password.
Secure communication	Off. The connector does not use TLS.

Save the record. SORBA SDE then exchanges messages with the gateway under sorba_framework_x/<Instance ID>/.

TagProvider in the solution

In the Designer, go to Unified Namespace > TagProvider Services and create a new TagProvider.
In the dialog, set Service to Extension Module, set Provider to SorbaAI Connector, and enter a Name.
Fill in the connection in the station editor (see Station Configuration). Add the model inputs with Add Tag... under Input Sources.
In Unified Namespace > Asset Tree, link the new TagProvider to a folder.
Save the solution and start the Runtime.

When the Runtime starts, the station connects to the broker and starts publishing to SORBA. The linked folder shows the model tree under the Model Name: INPUTS, OUTPUTS, CONFIG and, for most algorithms, TARGET.

The dialog has no Test button for this connector. To check the connection, watch the topics with an MQTT viewer (see Monitoring Traffic).

The connector does not reconnect to the MQTT broker automatically. Start the broker and SORBA SDE before the Runtime. If the broker restarts, restart the Runtime or the station.

Station Configuration

The station editor stores the connection as a semicolon-separated string of 13 positional fields. The defaults work for a local SORBA SDE with its own broker.

#	Field	Default	Description
1	Broker Host	`localhost`	Hostname or IP of the MQTT broker.
2	Port	`1883`	MQTT broker port.
3	Instance ID	`frameworx_gateway`	Identifies this gateway to SORBA and forms the topic root `sorba_framework_x/<Instance ID>/`. Must match the Name of the Integration record in SORBA SDE. Characters other than letters, digits and underscore are replaced by `_`, and `sbr_` is added in front if the result is empty, a single character, or starts with a digit. Use letters, digits and underscores, starting with a letter, so the ID is used exactly as typed.
4	Algorithm	`Regression`	Model type: `Regression`, `Classification`, `Clustering`, `Forecasting`, `DigitalTwin` or `Optimization`. Defines the TARGET folder (see Algorithms).
5	Model Name	`MODEL`	Root of the model tree, for example `MODEL/CONFIG/...`. SORBA also uses it as the model name in its messages.
6	Username	empty	MQTT broker username. Leave empty for anonymous brokers.
7	Password	empty	MQTT broker password.
8-10	TLS CA PEM, TLS Client Cert PEM, TLS Client Key PEM	empty	Reserved. These fields appear in the editor but the current connector does not use them: the connection is plain MQTT, without TLS. Leave them empty.
11	Output TTL Seconds	`30`	Shown as Output TTL (s) in the editor. An output that SORBA stops refreshing for longer than this is removed from the model tree.
12	Reserved	empty	Leave empty.
13	Input Sources	empty	Comma-separated tag paths, for example `Tag.Machine.Power`. Managed with the tag picker in the station editor (see below).

Input Sources

Input Sources lists the tags streamed to SORBA as model inputs. Manage the list in the station editor: Add Tag... opens a tag picker and Remove deletes the selected rows. The list shows each Source Tag and the Input Name it gets in the model. Inputs are added only through the picker.

Each source becomes <Model Name>/INPUTS/<Input Name>. The Input Name is the tag path with the Tag. prefix removed and dots and other separators replaced by _. Duplicate names get a suffix: _2, _3 and so on.

Source Tag	Input Name	Model tag
`Tag.Boiler1.Temperature`	`Boiler1_Temperature`	`<Model Name>/INPUTS/Boiler1_Temperature`
`Tag.Machine.Power`	`Machine_Power`	`<Model Name>/INPUTS/Machine_Power`

Input values are read every second and sent to SORBA.

Use the Input Name, not the source path, wherever SORBA expects an input, such as TARGET/response_variable and the optimization lists. For example, Machine_Power, not Tag.Machine.Power.

Example

Scenario	Configuration string
Local broker, Regression model with three inputs	`localhost;1883;frameworx_gateway;Regression;MODEL;;;;;;30;;Tag.Boiler1.Temperature,Tag.Boiler1.Pressure,Tag.Pump1.FlowRate`

Algorithms

The Algorithm setting selects the model type and the content of the TARGET folder.

Algorithm	Use case	`TARGET` folder
Regression	Predict a continuous variable from other inputs, for example Temperature from Pressure and Flow.	`response_variable` (Text)
Classification	Predict a discrete class from inputs, for example normal or fault.	`response_variable` (Text)
Clustering	Group similar samples without labels.	No TARGET folder
Forecasting	Predict future values of a time series.	`response_variable` (TextArray), plus `lag_steps`, `future_steps` and `window_length` under `CONFIG/TRAINING`
DigitalTwin	Multi-output predictive model of a physical asset.	`response_variable` (TextArray)
Optimization	Recommend control-variable settings that minimize or maximize an objective.	`control_variables`, `independent_variables`, `optimization_goals`, `optimization_variables` (TextArray)

Model Structure

The model tree appears under the Model Name. Layout for a Regression model named MODEL:

MODEL/
+-- CONFIG/
|   +-- RUNTIME/
|   |   +-- autolearning_status
|   |   +-- autolearning_time_range(min)
|   |   +-- autolearning_trigger
|   +-- TRAINING/
|       +-- DATASET/
|       |   +-- discard_nulls
|       |   +-- replace_with_last_value
|       |   +-- replace_with_value
|       +-- SYNTHETIC_TAGS/
|       +-- algorithm_type
|       +-- end_date
|       +-- history_storage_provider
|       +-- initialize_training
|       +-- output_message
|       +-- start_date
|       +-- time_zone
+-- INPUTS/             <- one tag per Input Source
+-- OUTPUTS/            <- created as SORBA sends results
+-- TARGET/
    +-- response_variable

TARGET

Algorithm	Tag	Type	Value
Regression, Classification	`response_variable`	Text	Input Name of the variable to predict, for example `Machine_Power`.
Forecasting, DigitalTwin	`response_variable`	TextArray	Input Names of the variables to predict. Enter them comma-separated, for example `Temperature, Pressure`.
Optimization	`optimization_variables`	TextArray	Variables SORBA tries to minimize or maximize.
Optimization	`optimization_goals`	TextArray	Optimization direction: `minimum` or `maximum`.
Optimization	`control_variables`	TextArray	Variables SORBA may recommend changes to.
Optimization	`independent_variables`	TextArray	Context variables SORBA reads but does not adjust.

For Optimization, use each input in only one of optimization_variables, control_variables and independent_variables.

CONFIG/TRAINING

Tag	Type	Default	Description
`time_zone`	Text	`UTC`	Time zone SORBA assumes for the gateway. Keep `UTC`: the connector sends dates and timestamps in UTC.
`algorithm_type`	Text	From Algorithm	Set by the connector from the station's Algorithm.
`output_message`	Text	empty	Status and error messages from SORBA (see Training a Model).
`initialize_training`	Digital	`false`	Set to `true`, after the other fields, to start training.
`start_date`	DateTime	empty	Start of the training window, in local time.
`end_date`	DateTime	empty	End of the training window, in local time.
`history_storage_provider`	Text	`[default]`	Reserved. Keep `[default]`.
`lag_steps`, `future_steps`, `window_length`	Integer	`6`, `3`, `18`	Forecasting only: number of past samples used for each prediction, number of steps ahead to predict, and length of the analysis window.

CONFIG/TRAINING/DATASET

How SORBA handles null samples during training.

Tag	Type	Default	Description
`discard_nulls`	Digital	`false`	Discard samples with null values.
`replace_with_last_value`	Digital	`false`	Replace null samples with the last good value of the same tag.
`replace_with_value`	Float	`0.0`	Constant used to replace null samples.

CONFIG/TRAINING/SYNTHETIC_TAGS

Folder for derived features. Not covered by this page; contact Tatsoft Support before using it.

CONFIG/RUNTIME

Tag	Type	Default	Description
`autolearning_status`	Text	`Standby`	Autolearning state.
`autolearning_trigger`	Digital	`true`	Autolearning trigger.
`autolearning_time_range(min)`	Integer	`10`	Autolearning time range, in minutes.

These settings are sent to SORBA with the rest of the model.

Training a Model

Train from the Runtime, for example from a display. The Runtime answers SORBA's history request, and the Designer refuses writes to SorbaAI tags.

Check that the Historian has data for every input tag over the window you want to use.
Set TARGET/response_variable to the Input Name of one of the model inputs, for example Machine_Power. For other algorithms, fill the TARGET tags listed in Model Structure.
Set CONFIG/TRAINING/start_date and end_date in local time. The connector sends them to SORBA in UTC. Keep CONFIG/TRAINING/time_zone = UTC.
Optionally, set the CONFIG/TRAINING/DATASET options.
Set CONFIG/TRAINING/initialize_training = true. Do this last.

SORBA validates the fields and reports progress in CONFIG/TRAINING/output_message. After initialize_training is set, SORBA requests the training history within a couple of seconds, the Runtime answers with the Historian samples of each input for the window, and the outputs appear under OUTPUTS after a few minutes.

Status messages

Messages seen in output_message while setting up a training run, in the order they usually appear:

Message	Meaning and action
`Target response variable "" was not found in the inputs in instance <InstanceId> and asset <Model>`	`response_variable` is empty or is not an Input Name. Set it to one of the inputs.
`Training start date is not in the correct format in instance <InstanceId> and asset <Model>`	The training dates are not set or not valid. Set `start_date` and `end_date`.
`Waiting for training confirmation in instance <InstanceId> and asset <Model>`	The fields are valid. Set `initialize_training` = `true`.
`Model <Model> is already trained`	SORBA already trained this model and does nothing. See Training again.

Dates and times

start_date and end_date take local time. Text values are accepted in the formats below. A value with an offset, such as -03:00, uses that offset. Day and month without leading zeros (d/M/yyyy) also work, and DateTime values written from a display or a script are accepted as well.

Format	Example
`dd/MM/yyyy HH:mm:ss.fff`	`15/05/2026 16:30:00.000`
`dd/MM/yyyy HH:mm:ss`	`15/05/2026 16:30:00`
`dd/MM/yyyy HH:mm`	`15/05/2026 16:30`
`dd/MM/yyyy`	`15/05/2026`
With offset	`15/05/2026 16:30:00 -03:00`
ISO	`2026-05-15 16:30:00`, `2026-05-15T16:30:00`

For example, 15/05/2026 16:30:00 entered on a computer at UTC-3 reaches SORBA as May 15, 2026, 7:30:00 PM (UTC).

Training again

SORBA trains a model once. If a trained model receives initialize_training again, output_message shows Model <Model> is already trained and nothing happens. To train again, either:

set a new Model Name in the station, and update the displays bound to the old model paths, or
reset the model on the SORBA side.

Outputs

The OUTPUTS folder is empty until SORBA sends results. Each output is created the first time SORBA sends it, as a numeric (Double) or Digital tag, and is removed if SORBA stops refreshing it for longer than Output TTL Seconds (default 30).

Predictions update about every 10 seconds and are timestamped when they arrive. In a trend, the prediction curve therefore appears shifted to the right (later) relative to the inputs. To compare prediction and actual value, use a trend window of several minutes, or inputs that vary slowly.

The set of outputs depends on the algorithm. For Regression, expect the outputs below, where <Target> is the value of TARGET/response_variable and <Input> stands for each of the other inputs.

Output	Meaning
`<Target>_Prediction`	Predicted value of the response variable.
`<Target>_Prediction_Error`	Difference between predicted and actual value.
`<Target>_Prediction_Upper_Band`, `<Target>_Prediction_Lower_Band`	Upper and lower bounds of the confidence band.
`<Target>_Prediction_Drift`, `<Target>_Prediction_Drift_Score`	Prediction drift flag and score.
`<Target>_Target_Drift`, `<Target>_Target_Drift_Score`	Drift flag and score of the response variable.
`<Input>_Tag_Ranking_Percent`	Contribution of the input to the prediction (feature importance).
`<Input>_Tag_Ranking_p_value`	Statistical significance of that contribution.
`<Input>_outlier`	Set when the input is currently an outlier.
`<Input>_Data_Drift`, `<Input>_Data_Drift_Score`	Drift flag and score of the input.
`Dataset_Drift`	Drift flag for the whole dataset.
`Best_Score_Training`, `Best_Score_Realtime`	Model quality score on training data and on live data.
`Model_Status_1_ok_2_error_3_warning`	Model status: 1 OK, 2 error, 3 warning.
`Data_Status_1_ok_2x_error_3x_warning`	Data status: 1 OK, 2x error, 3x warning.
`Anomaly_Score_Percent`	Current anomaly score, in percent.
`Anomaly_Detection_Analog`	Analog anomaly signal.
`Anomaly_Detection_Boolean`	Anomaly flag.
`Anomaly_Detection_High_Limit_Threshold`, `Anomaly_Detection_Low_Limit_Threshold`	Thresholds that set the anomaly flag.
`Anomaly_Detection_Notification_Warning`, `Anomaly_Detection_Notification_Critical`	Warning and critical notification flags.

Start with <Target>_Prediction (the predicted value), <Target>_Prediction_Error (how far it is from the actual value) and Model_Status_1_ok_2_error_3_warning (model health). Plot the prediction together with the Upper and Lower Band outputs to show the confidence band.

Multiple Stations

A solution can have several SorbaAI stations, each managing its own SORBA model.

Setting	Between stations
Broker Host, Port	Same broker or different brokers.
Instance ID	Must be unique. It defines the MQTT topic namespace of the station.
Algorithm	Independent per station.

Each station needs its own Integration record in SORBA SDE, with the station's Instance ID as Name.

Monitoring Traffic

Keep an MQTT viewer connected to the same broker as the station, during setup and in operation. It shows the exchange between the gateway and SORBA as it happens.

MQTT Explorer: free, cross-platform, tree view.
mosquitto_sub, the command-line client that ships with Mosquitto: mosquitto_sub -h <broker host> -t "sorba_framework_x/<Instance ID>/#" -v

Subscribe to sorba_framework_x/<Instance ID>/# to see every topic listed under MQTT topics. The viewer tells you whether SORBA is answering at all, which separates a SORBA-side problem from a gateway-side one.

Troubleshooting

Symptom	Likely cause	Fix
The model tree appears, but SORBA receives nothing. The trace shows `MQTT broker not reachable`.	Wrong Broker Host or Port, broker not running, or a firewall blocking the port.	Check host and port, start the broker, and test it with `mosquitto_sub` from the Runtime computer. Then restart the Runtime or the station.
Only the Designer is open and SORBA receives nothing.	Only the Runtime acts as the gateway.	Start the Runtime.
Writing a SorbaAI tag in the Designer fails.	The Designer is a read-only mirror.	Write the value from the Runtime, for example from a display.
Traffic stopped after the broker restarted.	The connector does not reconnect automatically.	Restart the Runtime or the station.
The station runs but SORBA never responds.	No matching Integration record in SORBA SDE.	Add an Integration whose Name equals the station's Instance ID.
`output_message`: `Target response variable "" was not found ...`	`response_variable` is empty or is not an Input Name.	Set it to an Input Name such as `Boiler1_Temperature`, not `Tag.Boiler1.Temperature`.
`output_message`: `Training start date is not in the correct format ...`	`start_date` or `end_date` not set or not valid.	Set both dates. See Dates and times.
`output_message`: `Model <Model> is already trained`	SORBA trains a model once.	Use a new Model Name, or reset the model on the SORBA side.
Training was started but no outputs appear.	Training still running, or no Historian data for one or more inputs in the window.	Allow a few minutes. Check that every input tag is historized and that the Historian covers the window. Check `output_message` and the MQTT viewer.
Outputs appear, then disappear after about 30 s.	SORBA stopped refreshing them and the Output TTL expired.	Check why SORBA stopped publishing, or raise Output TTL Seconds.
In a trend, the prediction lags the actual value.	Predictions arrive about every 10 s and are timestamped on arrival.	Use a trend window of several minutes, or slowly varying inputs.
An OUTPUTS value read with `TK.Asset()` in the Runtime returns empty.	No client uses the tag yet.	Use the tag in a display, script or alarm. Values flow after the first subscription.

For more detail, the driver writes a diagnostic trace to C:\Temp\SorbaAI_Trace.log.

In this section...

Page tree