Page History

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

:

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 (the Object Class), UI Navigation, and Runtime Namespace are linked.

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

• 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	Example Objects	Use Cases
Server	Synchronized to ALL connected clients	Tag.*, Alarm.*, Device.*, Script.*, Historian.*, Dataset.*	Process data, shared state
Client	Local to each client only	@Client.Username, tags with Domain='Client'	User-specific UI state, report parameters

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
Aspect
Script Tasks
Script Expressions
Complexity
Full methods, multi-line code
One-liners
Languages
C#, VB, Python
Expression syntax
Compilation
Compiled to .NET method
Interpreted
Trigger
Events, schedules, tag changes
OnChange, intervals
Use Case
Complex logic, API calls
Simple calculations
Performance
Equivalent
Equivalent
Configuration
More setup required
Quick and simple
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
Context
Syntax
Example
Script Tasks/Classes
@ prefix required
@Tag.Temperature.Value
Script Expressions
No prefix
Tag.Temperature + Tag.Offset
Display Bindings
@ prefix + .Value
@Tag.Temperature.Value
StringWithObjects
Curly braces
"Value: {Tag.Temperature}"
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
Type
Positioning
Use Case
Canvas
Absolute X,Y (Left, Top)
Process graphics, P&IDs
Dashboard
Grid cells
KPI screens, responsive layouts
5.2 Layout Regions
Displays run inside Layout regions. The layout (DisplaysLayouts) defines which display appears in each region.
Region
Position
Typical Size
Purpose
Header
Top
1366 x 40
Application header, logo, user info
Menu
Left
Variable
Navigation menu
SubMenu
Right
Variable
Secondary navigation or details
Footer
Bottom
Variable
Status bar, messages
Content
Center
1366 x 728
Main working area (fills remaining space)
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

:

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

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

String with embedded tags

:

{ "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.
Wizard Type
Description
BLOWER
Industrial blower/fan
MOTOR
Electric motor
PUMP
Various pump styles
TANK
Storage tank
VALVE
Various valve styles
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
Layer
Table
Purpose
Example
1. Tags
UnsTags
Process variables
Tag.Pump1/Flow
2. Points
DevicesPoints
Address mapping
Address: HR100
3. Nodes
DevicesNodes
Device address
IP: 192.168.1.100
4. Channels
DevicesChannels
Protocol config
Protocol: Modbus
5. Physical

Creation Order: Channels

→ Nodes

→ Points

6.2 Protocol-Dependent Fields

These fields vary by protocol

— use get_protocol_schema(protocol) to get valid values.

6.3 Protocol Selection

Workflow

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

For: AI training,

API development, advanced users