TagProvider Services with MQTT Skill

—
title: "MQTT TagProvider Integration"
tags: [mqtt, tagprovider, uns, iiot, asset-navigation, dynamic-tags]
description: "Connect to an MQTT broker via TagProvider, explore its namespace, link selected nodes into the UNS AssetTree, and build an asset-navigation UI with DataGrid, TrendChart, and AlarmViewer — all driven by dynamic Asset() bindings."
version: "0.1-draft"
author: "Tatsoft"
—

1. MQTT TagProvider Integration

1. 1. What This Skill Does

This skill connects FrameworX to an external MQTT broker using a TagProvider — the dynamic, zero-local-tags approach. Instead of creating individual UnsTags and mapping them with Device Points, the TagProvider auto-discovers the broker's topic tree and extends the UNS namespace directly. The skill then builds a complete asset-navigation UI: a Layout with an AssetTree on the left, a header with commands, and a content area that reacts to the user's tree selection using `Asset()` bindings and `Client.Context` properties. The result is a fully dynamic application where the UI adapts to whatever data the MQTT broker publishes — no tag-by-tag engineering required.

1. 1. When to Use This Skill

Use this skill when:

• The user wants to connect to an *external MQTT broker* (not create local simulated data)
• The data structure is *dynamic or unknown upfront* — the broker defines what exists
• The user mentions *TagProvider, **MQTT, **IIoT, **UNS integration, or **auto-discovery*
• The user wants an *asset-navigation UI* where selecting a tree node changes the displayed data
• The application is monitoring/visualization focused (not tight SCADA control)

Do NOT use this skill when:

• The user wants *explicit point-by-point control* over specific MQTT topics ? use Device Module approach instead (Channel ? Node ? Points)
• The user needs *local tags with alarms and historian on individual points* with strict validation ? use Device Module
• The data source is *not MQTT* (for OPC UA TagProviders, similar patterns apply but connection details differ)
• The user just needs a *simple dashboard with simulated data* ? use ValueSimulator with standard Tags

*Decision guide:*

1. 1. Prerequisites

• Solution must be open (`open_solution` or `create_solution` completed)
• An MQTT broker must be accessible from the machine (local or remote)
• For testing without an external broker: FrameworX has a *built-in MQTT broker* and a *SparkplugB simulator* that can be started from Data Explorer ? MQTT Tools

1. 1. MCP Tools and Tables Involved

1. 1. Implementation Steps

1. 1. 1. Step 0: Discover the MQTT Broker Data (Interactive)

Before creating any configuration, you need to see what data the broker has. This step is interactive — it involves the user.

*If using the built-in broker for testing:*

```text
designer_action('start_mqtt_broker')
designer_action('start_mqtt_simulator')
```

This starts a local MQTT broker and a SparkplugB simulator that publishes sample data (solar panels, cities, sensors).

*Navigate to MQTT Tools:*

```text
designer_action('navigate', 'DataExplorer.MQTTTools')
```

*Connect to the broker:*

```text
designer_action('connect_mqtt_explorer', '<PrimaryStation string>')
```

The PrimaryStation format for MQTT is a semicolon-delimited string:
```

;

;

;

;

;

;

;

;

;

;

;

;

;

;
```

Common examples:

• Local built-in broker: `localhost;1883;FrameworX-Explorer;;;;;None;False;;AtLeastOnce;10;False;False;`
• Remote broker: `mqtt.factory.local;1883;FrameworX-001;;;;;None;False;;AtLeastOnce;10;False;False;`
• With authentication: `broker.cloud.io;8883;MyClient;admin;password123;;;TLS 1.2;False;;AtLeastOnce;30;False;False;`

*Ask the user to explore and select:*

At this point, tell the user:
> "The MQTT browser is now connected. Please navigate the tree to explore the available data. When you've identified the nodes you want to integrate into the Unified Namespace, select them and let me know — or I can read your current selection."

*Read the user's selection:*

```text
get_designer_state()
```

This returns the current MQTT Tools state including which nodes the user has selected (or browsed to). Use this information to determine the initial tree nodes for the TagProvider link.

*AI-driven alternative:* If the user says "just connect everything" or "pick reasonable defaults," the AI can read the top-level structure from `get_designer_state()` and propose a reasonable default selection, then create the configuration. Verify with the user afterward — it's easier to modify an existing object than to wait for the user to manually select before creating anything.

1. 1. 1. Step 1: Create the TagProvider Connection

Fetch the schema and protocol details:

```text
get_table_schema('UnsTagProviders')
list_protocols('mqtt')
```

Write the TagProvider object:

```json
{
"table_type": "UnsTagProviders",
"data": [

]
}
```

*Key decisions:*

• *Name: This becomes the root of the dynamic namespace — `Tag.MQTT.`. Choose a meaningful name (e.g., `ProductionMQTT`, `FactoryBroker`).
• *Separators*: `BranchSeparator=/;AttributeSeparator=/;` maps MQTT topic hierarchy (`plant/line1/temp`) to UNS path hierarchy. This is almost always the correct default for MQTT.
• *PrimaryStation*: Must match the connection details confirmed in Step 0.

After creation, the TagProvider immediately starts discovering topics when runtime starts. Topics appear as dynamic tags under `Tag.<ProviderName>.<topic.path>`.

1. 1. 1. Step 2: Create the Linked Folder in AssetTree

The AssetTree folder is what makes the TagProvider data visible and navigable in the UI. A *Linked Folder* connects an AssetTree node to a TagProvider and specifies which initial nodes from the provider's namespace to display.

<!-- TODO: UnsAssetTree schema needs to be updated to include TagProviderLink parameters.
Current schema shows readOnly=true. The write mechanism requires:

• TagProviderLink: name of the TagProvider (e.g., "MQTT")
• InitialPath: the starting node(s) from the provider tree (e.g., "spBv1.0/GroupID")
  These fields connect the folder to the TagProvider's auto-discovered namespace.
  The exact field names and write_objects format need confirmation from Tatsoft.
  -->

```json
{
"table_type": "UnsAssetTree",
"data": [

]
}
```

*Key decisions:*

• *Name*: The folder name in the AssetTree — what operators see in the navigation tree.
• *TagProviderLink*: Must match the TagProvider Name from Step 1 exactly.
• *InitialPath*: The starting node(s) selected by the user in Step 0. Everything below this path in the broker automatically expands into the folder.

From this point down, the AssetTree is dynamic — the platform auto-expands the tree based on whatever the MQTT broker publishes. No further tag creation needed.

1. 1. 1. Step 3: Build the Layout (Header + AssetTree + Content)

The standard pattern for asset-navigation applications is a Layout with three regions:

```text
get_table_schema('DisplaysLayouts')
list_elements('Layout')
```

Write the Layout:

```json
{
"table_type": "DisplaysLayouts",
"data": [

]
}
```

The Layout `Startup` (ID 0) is the predefined startup layout — modifying it changes what loads on application launch.

*Regions:*

• *Header*: Top bar — title, navigation buttons, status indicators
• *Menu* (left side): The AssetTree control — users click here to navigate assets
• *Content* (main area): The display that reacts to the selected asset

1. 1. 1. Step 4: Create the Header Display

A simple Canvas display with the application title and optional navigation controls:

```text
get_table_schema('DisplaysList')
list_elements('TextBlock,Button')
```

```json
{
"table_type": "DisplaysList",
"data": [
{
"Name": "Header",
"PanelType": "Canvas",
"Width": 1200,
"Height": 60,
"Description": "Application header bar",
"Objects": [

]
}
]
}
```

1. 1. 1. Step 5: Create the AssetTree Menu Display

A Canvas display containing the AssetTree control that drives navigation:

```text
list_elements('AssetsTree')
```

```json
{
"table_type": "DisplaysList",
"data": [
{
"Name": "AssetTreeMenu",
"PanelType": "Canvas",
"Width": 300,
"Height": 700,
"Description": "Asset tree navigation panel",
"Objects": [

]
}
]
}
```

When the user clicks a node in the AssetsTree, the platform automatically updates:

• `Client.Context.AssetPath` — full path (e.g., `"MQTT/spBv1.0/GroupID/Barcelona/Panel1"`)
• `Client.Context.AssetName` — name (e.g., `"Panel1"`)
• `Client.Context.AssetNodeName` — leaf name
• `Client.Context.SelectedTag` — full tag path of the selected tag

These properties drive the content display reactively.

1. 1. 1. Step 6: Create the MainPage (Dynamic Content)

The MainPage uses `Asset()` bindings to react to the user's tree selection. This is the key pattern — all content is driven by `Client.Context.AssetPath`.

```text
list_elements('DataGrid,TrendChart,TextBlock,AlarmViewer')
```

*Dashboard layout approach (recommended for MainPage):*

```json
{
"table_type": "DisplaysList",
"data": [
{
"Name": "MainPage",
"PanelType": "Dashboard",
"Columns": 2,
"Rows": 3,
"Description": "Dynamic content — reacts to AssetTree selection",
"Objects": [

,

,

,

]
}
]
}
```

*Key pattern — the DataGrid LinkedValue:*
When you set the DataGrid's `LinkedValue` to `@Tag` and provide a `LinkedContext` pointing to `@Client.Context.AssetPath`, the DataGrid automatically shows all children (sub-tags and attributes) of whatever the user selected in the AssetTree. This is the heart of the dynamic pattern — one display serves the entire asset hierarchy.

*The Asset() syntax for code and expressions:*
```csharp
// In scripts or CodeBehind:
double value = Asset(@Client.Context.AssetPath + "/Temperature");

// In display element LinkedValue fields:
// Static: @Tag.MQTT.plant.line1.temperature
// Dynamic: Asset(Client.Context.AssetPath + "/Temperature")
```

1. 1. 1. Step 7: Start Runtime and Verify

```text
designer_action('start_runtime')
```

After starting:
1. The TagProvider connects to the MQTT broker and discovers topics
2. The AssetTree populates with the linked folder structure
3. Clicking any node in the tree updates `Client.Context` properties
4. The DataGrid, TrendChart, and other elements on MainPage react to the selection

Take a single screenshot to verify the layout renders correctly:

```text
get_screenshot('runtime')
```

1. 1. Code Examples

1. 1. 1. Asset() in CodeBehind (Display Events)

```csharp
// Opening event — set initial context
void Opening()
{
// Optionally set a default branch to expand
@Client.Context.TreeInitialBranch = "MQTT/spBv1.0/GroupID";
}
```

1. 1. 1. Asset() in Scripts

```csharp
// Read a dynamic value based on context
public static double GetTemperature(string assetPath)
{
return TK.ToDouble(Asset(assetPath + "/Temperature"));
}
```

1. 1. 1. Data Type Handling for HTML5/Portable Clients

```csharp
// WPF (.NET Framework 4.8) — automatic type resolution
var value = Asset("/MQTT/plant/line1/temperature");

// HTML5/Portable (NetStandard 2.0) — explicit conversion required
int intValue = TK.ToInt(Asset("/MQTT/plant/line1/count"));
double dblValue = TK.ToDouble(Asset("/MQTT/plant/line1/temperature"));
string strValue = TK.ToString(Asset("/MQTT/plant/line1/status"));
bool boolValue = TK.ToDigital(Asset("/MQTT/plant/line1/running"));
```

1. 1. Verification

1. `get_objects('UnsTagProviders')` — verify the TagProvider was created with correct PrimaryStation
2. `designer_action('navigate', 'Uns.AssetTree')` ? `get_designer_state()` — confirm the linked folder appears with the TagProvider reference
3. `designer_action('start_runtime')` ? `get_runtime_state()` — confirm the TagProvider connection is active
4. `get_screenshot('runtime')` — verify the AssetTree populates and the Layout renders correctly
5. Ask the user to click different nodes in the AssetTree and confirm the DataGrid updates dynamically

1. 1. Common Pitfalls

1. 1. Variations

*Variation A: Mixed Approach (TagProvider + Device Module)*

• Use TagProvider for browsing and monitoring the full MQTT namespace
• Use Device Module for specific critical tags that need alarms, historian, and strict validation
• Both can connect to the same MQTT broker in the same solution
• Useful when: 90% of data is for monitoring, but 10% needs SCADA-grade control

*Variation B: SparkplugB-Specific*

• Use `MQTTspB` protocol instead of `MQTT` in the TagProvider
• SparkplugB provides richer metadata (data types, birth/death certificates)
• Change `Separators` to match SparkplugB topic structure
• Useful when: The MQTT broker uses Sparkplug B specification

*Variation C: Multiple Brokers*

• Create multiple TagProviders, each with a different Name and PrimaryStation
• Create separate AssetTree linked folders for each provider
• The same Layout and MainPage pattern works — `Client.Context` handles any source
• Useful when: Aggregating data from multiple factories or edge gateways

*Variation D: Add Historian to Dynamic Tags*

• For specific TagProvider paths that need historical trending, create a Historian TagProvider connection
• TrendCharts can use `Asset()` syntax to automatically query historical data from historian TagProviders
• Useful when: You need long-term trending on external data without creating local tags

1. 1. Related Skills

• `skill-device-mqtt` — Explicit MQTT integration using Device Module (Channel ? Node ? Points)
• `skill-asset-navigation` — Generic asset-navigation UI patterns (not MQTT-specific)
• `skill-sparkplugb-collector` — SparkplugB Collector setup with Device Module

1. 1. Documentation References

• TagProvider Services(https://docs.tatsoft.com/display/FX/TagProvider+Services) — Concept overview
• TagProvider Services How-to(https://docs.tatsoft.com/display/FX/TagProvider+Services+How-to) — Step-by-step procedures
• UNS TagProvider Services Reference(https://docs.tatsoft.com/display/FX/UNS+TagProvider+Services+Reference) — All properties and settings
• TagProvider Services Technology(https://docs.tatsoft.com/display/FX/TagProvider+Services+Technology) — Architecture deep dive
• MQTT Tools Reference(https://docs.tatsoft.com/display/FX/MQTT+Tools+Reference) — Data Explorer MQTT browser
• MQTT Integration Reference(https://docs.tatsoft.com/display/FX/MQTT+Integration+Reference) — TagProvider vs Device comparison with JSON examples

1. 1. Open Items (Draft Notes)

> *?? This is a DRAFT (v0.1). The following items need resolution before publishing:*
>
> 1. *`connect_mqtt_explorer` designer_action*: New action needed — navigates to DataExplorer.MQTTTools and initiates connection with a PrimaryStation string. Not yet implemented.
>
> 2. *`get_designer_state()` for MQTT Tools*: Must return the user's selected nodes in the MQTT browser tree. This is how the AI reads which nodes the user wants to integrate.
>
> 3. *`UnsAssetTree` write support*: Currently `get_table_schema('UnsAssetTree')` returns `readOnly: true`. Need writable schema with fields:
> - `Name` (String) — folder name
> - `TagProviderLink` (String) — name of the TagProvider to link
> - `InitialPath` (String) — initial node path(s) from the provider tree
> - `Description` (String) — folder description
> - Exact field names TBD — may be `LinkedTo`, `Path`, or encoded in `Children` field.
>
> 4. *DataGrid `LinkedContext` property*: Verify exact property name and behavior — does the DataGrid have `LinkedContext` as a separate field, or is the asset-driven behavior configured differently?
>
> 5. *TrendChart Asset() binding*: How does a TrendChart dynamically bind its pens to the currently selected asset's children? Does it use `LinkedContext` similar to DataGrid?
>
> 6. *Layout field names*: Verify exact field names for `DisplaysLayouts` — is it `Header`, `Menu`, `Content` or different property names? Need `get_table_schema('DisplaysLayouts')` confirmation.
>
> 7. *Template integration*: The skill currently builds the Layout from scratch. If solution templates with built-in Header+AssetTree+Content are available, reference them as a shortcut.