Architecture Reference 

Purpose: Deep understanding of FrameworX for AI tools and API programmers

1. System Architecture

1.1 Design-Time vs Runtime Separation

FrameworX has a clear separation between configuration (design-time) and execution (runtime).

Design-Time Components:

• Designer.exe - Human UI for configuration
• .DBSLN file - Solution file (encrypted SQLite) containing all configuration
• MCP Tools - AI control interface for configuration

Runtime Components:

• TStartup.exe - Loader that reads .DBSLN and launches processes
• TServer.exe - Main UNS process, opens port (default 3101)
• Runtime MCP Tools - AI monitoring interface (separate from Designer tools)
• Clients - WPF, Web, or Mobile displays connecting to TServer

Architecture Flow Table:

Key Points:

• Designer MCP tools ONLY affect the .DBSLN file (design-time configuration)
• Designer can START runtime but should NOT stop it (separate responsibility)
• Runtime MCP tools connect to running TServer.exe for monitoring/interaction
• All code is compiled incrementally during editing - solution is always ready to run

1.2 Solution File (.DBSLN)

1.3 Build and Publish

2. The Unified Object Model

2.1 The Three-Way Mapping (Critical Concept)

FrameworX has a unified structure where TableType, UI Navigation, and Runtime Namespace are linked.

Mapping Table:

Implication: Objects in a table (e.g., AlarmsGroups has "Critical", "Warning") become runtime namespace objects (Alarm.Group.Critical, Alarm.Group.Warning).

2.2 Runtime Objects Concept

ALL objects in FrameworX are "runtime objects" - they have properties that can be read (and sometimes written) at runtime.

Runtime Object Categories:

• User-created Tags - Tag.*
• Module Objects
  • Alarm.Group.{name}, Alarm.Item.{name}
  • Device.Channel.{name}, Device.Node.{name}
  • Script.Task.{name}, Script.Class.{name}
  • Historian.Table.{name}
  • Dataset.Query.{name}
  • Display.{name}
• System Namespaces
  • @Server.* (server info, date/time)
  • @Client.* (client info, logged user)
  • @Info.* (system information)

Example: Device.Node.MyNode has properties like .Error, .Status that can be read at runtime for diagnostics.

3. Tags and Data Model

3.1 Tag Hierarchy and Folders

Tag Path Syntax: Tag.Folder1/Folder2/TagName

Structure:

• Folders exist as AssetFolder objects in UnsAssetTree
• Listed via list_objects('UnsAssetTree')
• Auto-created when importing tags with folder paths
• Tags reference their folder via path syntax

3.2 User Defined Types (UDT)

When creating a tag with a UDT type, member tags are automatically created.

Example UDT Definition (UnsUserTypes):

Tag Instance Creation:

Resulting Runtime Objects:

• Tag.Controller1 (parent - can be used for bulk operations)
• Tag.Controller1.SP (Double tag with all tag properties)
• Tag.Controller1.PV (Double tag with all tag properties)
• Tag.Controller1.Output (Double tag with all tag properties)
• Tag.Controller1.Auto (Digital tag with all tag properties)

UDT Advantages:

• Communication mapping: map parent tag to get all members
• Display binding: reference parent for all members
• Historian: log parent to capture all members
• Alarms: configure on parent applies to members

3.3 Server vs Client Domain

Domain Scope Table:

Server Domain Behavior:

• Value changes on server propagate to all clients
• Value changes from any client propagate to server and all other clients
• Used for: Process data, alarms, shared state

Client Domain Behavior:

• Each client has its own independent value
• Operator A's value does NOT affect Operator B
• Used for: Logged username, report date parameters, UI preferences

Creating Client Domain Tags:

{ "Name": "ReportStartDate", "Domain": "Client", "Type": "DateTime" }

4. Scripting Model

4.1 Script Tasks vs Expressions

When to use Expressions:

• Tag.Output = Tag.Input1 + Tag.Input2 * 0.5
• Tag.Status = Tag.Value > 100 ? "High" : "Normal"

When to use Tasks:

• Complex logic with multiple steps
• Database access
• External API calls
• Error handling requirements

4.2 Code Syntax by Context

StringWithObjects Usage: Used in text fields, SQL queries, alarm messages:

• TextBlock.Text = "Current temp: {Tag.Temperature} C"
• AlarmItem.Message = "Tank {Tag.TankID} level is {Tag.Level}%"
• SQL Query = "SELECT * FROM logs WHERE batch = '{Tag.BatchID}'"

5. Display System

5.1 Display Types

5.2 Layout Regions

Displays run inside Layout regions. The layout (DisplaysLayouts) defines which display appears in each region.

Key Points:

• A display is just a display - Layout decides where and when to use it
• Most AI-created displays are Content displays (shown via navigation)
• Size is aspect ratio, not absolute pixels (responsive)
• Query DisplaysLayouts to discover current sizes for other regions

5.3 Data Binding

Direct binding (most properties):

{ "ElementType": "TextBox", "LinkedValue": "@Tag.Temperature.Value" }

Expression binding:

{ "ElementType": "TextBox", "LinkedValue": "@Tag.Value1 + @Tag.Value2" }

String with embedded tags (where supported):

{ "ElementType": "TextBlock", "Text": "Temperature: {Tag.Temperature} C" }

5.4 Symbol Labels (Parameterization)

Creating a Symbol (hashtag syntax in original element):

• TextBox.LinkedValue = #FlowRate:Tag.DefaultTag
• #FlowRate = Label name (Key)
• Tag.DefaultTag = Default value

Using Symbol Instance:

{
  "ElementType": "Symbol",
  "SymbolName": "HMI/Pumps/CentrifugalPump",
  "SymbolLabels": [
    { "Key": "FlowRate", "Value": "Tag.Pump1/Flow" },
    { "Key": "Status", "Value": "Tag.Pump1/Running" }
  ]
}

5.5 Wizard Symbols

Pre-built industrial symbols with configurable appearance.

Usage:

{
  "Type": "Symbol",
  "WizardType": "VALVE",
  "Left": 100,
  "Top": 200,
  "Width": 65,
  "Height": 65,
  "SymbolLabels": [
    { "Key": "State", "LabelValue": "@Tag.ValveState.Value" }
  ]
}

Note: Created with default appearance. User can customize in Designer dialogs.

6. Device Communication

6.1 Communication Stack

Creation Order: Channels, then Nodes, then Points

6.2 Protocol-Dependent Fields

These fields vary by protocol - use get_protocol_schema(protocol) to get valid values.

6.3 Protocol Selection

AI workflow for helping users connect equipment:

1. User specifies equipment (e.g., "Siemens S7-1500 PLC")
2. AI calls list_protocols()
3. Match against protocol names and descriptions
4. Suggest appropriate protocol (e.g., "S7" or "OPC UA")
5. Get connection parameters with get_protocol_schema('S7')

7. Execution Profiles

7.1 Purpose

Allow same solution to run in different environments with different connection settings.

7.2 What Changes Per Profile

• Database connection strings
• Device IP addresses / network settings
• Some port configurations

7.3 AI Capabilities

8. Runtime Startup Process

Startup Sequence:

1. Designer or MCP: START clicked or designer_action('start_runtime')
2. TStartup.exe launches:
   • Reads .DBSLN file
   • Reads RuntimeStartup table (modules, ports, settings)
3. TServer.exe starts:
   • Loads all tags (UNS)
   • Opens port (default 3101)
   • Starts communication channels
   • Executes startup scripts
4. Other modules launch as configured
5. Ready for client connections

Note: Code is already compiled during design-time saves. START just launches the runtime processes.

9. MCP Tools Separation

9.1 Designer MCP Tools (Configuration)

9.2 Runtime MCP Tools (Monitoring - Separate Implementation)

10. Glossary

11. Common Patterns

Tag Path Syntax

Object Reference Syntax

Creation Order (Dependencies)

1. UnsUserTypes (if using UDTs)
2. UnsTags (may reference UDTs)
3. DevicesChannels
4. DevicesNodes (references Channels)
5. DevicesPoints (references Nodes and Tags)
6. AlarmsGroups (or use predefined)
7. AlarmsItems (references Tags and Groups)
8. HistorianTables (or use predefined Table1)
9. HistorianTags (references Tags and Tables)
10. DisplaysList (references Tags for bindings)

Document Version: 1.1 (Confluence-compatible formatting) Based on: FrameworX MCP Tools Code Review Session For: AI training, documentation enhancement, search_docs content