Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
57 lines
7.2 KiB
Markdown
57 lines
7.2 KiB
Markdown
# Object Design Considerations
|
||
|
||
Before you start defining your object, you should plan its features and structure. You should:
|
||
|
||
- Decide how to design the object’s structure by using primitives.
|
||
- Make a list of the attributes that your object and any of its primitives will need, and develop a naming structure.
|
||
|
||
## Guidelines for Designing the Structure of Control-Oriented Objects
|
||
|
||
This section describes basic guidelines for developing objects that perform feedback control actions at the supervisory level. The AnalogDevice, configured as an AnalogRegulator, and the DiscreteDevice objects that are provided with Wonderware Application Server provide good working examples of how to design such objects.
|
||
|
||
Developing objects in accordance with these guidelines ensures that objects are structured in a manner that fits well within the overall architecture of ArchestrA, and that they offer a consistent structure to end users.
|
||
|
||
In general, you should separate control objects into three primary blocks: Feedback processing, Control processing, and one or more Alarm processing blocks.
|
||
|
||
- The **Feedback** processing block includes the attributes and logic for reading field inputs and processing them to derive a primary calculated result that is placed into an attribute called the “PV” (process value). The feedback processing should also include a “PVMode” attribute that determines whether the PV is calculated automatically or set manually.
|
||
- The **Control** processing block includes the attributes and logic for receiving setpoints or commands that result in output control actions. The control processing should also include a “CtrlMode” (control mode) attribute that determines whether the control actions are commanded manually or cascaded from another object. The run time set handler for the control attributes can then reject set requests coming from disallowed sources.
|
||
- The **Alarm** processing block(s) includes the attributes and logic for alarm detection for the feedback and control blocks. The feedback alarming determines whether the input(s) are abnormal or unexpected. The control alarming determines whether control actions are failing or have had unexpected results. You can implement these blocks of logic as part of the Feedback or Control processing blocks or separately, depending on what makes sense for your object.
|
||
|
||
By using primitives, you can model these multiple blocks in a clean and easy way. The ArchestrA Object Toolkit also allows you to develop “virtual” primitives that allow you to add primitive instances as required at config time. For more information, see Working with Virtual Primitives.
|
||
|
||
In many objects, it will be most appropriate to separate the object into a top-level primitive that brings in an optional child Control virtual primitive. When the user enables Control functionality, then the config time logic adds the Control primitive dynamically. Since alarms are commonly optional, it also makes sense to use virtual primitives for one or more blocks of alarm detection functionality. The $AnalogDevice object that is provided with Application Server provides a good example of these concepts.
|
||
|
||
> **Note**
|
||
> When you arrange local primitives in a hierarchy (that is, embed primitives within other primitives, and so on), there is a limit to the number of levels the hierarchy can have. For more information, see Limitations to the Complexity of Primitive Hierarchies.
|
||
|
||
### Limitations to the Complexity of Primitive Hierarchies
|
||
|
||
When you arrange local primitives in a hierarchy (that is, embed primitives within other primitives, and so on), there is a limit to the number of levels the hierarchy can have.
|
||
|
||
When you add a local primitive to an ApplicationObject, the ArchestrA Object Toolkit adds a subfolder to the solution folder that contains the code files for that primitive. When you add another primitive to that primitive, it creates a subfolder in the primitive subfolder, and so on. Each level in the primitive hierarchy corresponds to another level of folders in the ArchestrA Object Toolkit solution folder. (For more information on the content of the solution folder, see Working with Projects.)
|
||
|
||
However, the Windows operating system imposes a limit on the maximum length of a file path. On current Windows versions, this limit is 260 characters for the complete path including all formatting characters. No path to any code file in any ArchestrA Object Toolkit project folder may exceed this limitation. Therefore, there is a limit to how many levels of primitives you can use.
|
||
|
||
The exact number of levels depends on the path length of the base ArchestrA Object Toolkit solution folder and on the length of the primitive names. The shorter the primitive names, the shorter the folder names, and the more levels you can use.
|
||
|
||
## Planning Attribute Usage
|
||
|
||
Attributes are the data items of an object or primitive. By reading from and writing to attributes, objects can exchange data with each other. In addition, your objects can also have Inputs and Outputs to communicate with other attributes in the ArchestrA environment.
|
||
|
||
Before you start developing your object, you should determine the following:
|
||
|
||
- **Which attributes do you need?** As a guideline, only expose those data items as attributes that your users actually need to see and/or change. For data items that you’ll only need locally or temporarily in the object’s code, simply use local C# variables. Those attributes that you do expose should be organized and named in a way that is intuitive to your users. Also determine whether your attributes will require I/O capabilities.
|
||
- **What level of access should users have to these** **attributes?** There might be attributes that are only relevant at config time, but not at run time. For other attributes, you might want to allow run time write access only to users with certain privileges.
|
||
|
||
In the ArchestrA Object Toolkit, you can use three strategies to control attribute structure and access:
|
||
|
||
- **Developing a logical naming hierarchy.** You can use named and unnamed primitives as well as structured attribute names to organize attributes logically and only expose those attributes that the user really needs. For more information, see Creating a Logical Attribute Hierarchy.
|
||
- **Security classifications.** By specifying different security classifications for individual attributes, you can restrict attribute access to users with the right privileges. For more information, see ArchestrA Security Classifications.
|
||
- **Attribute categories.** By using different attribute categories, you can specify whether or not an attribute should be available and readable/writable at config time and/or run time. For more information, see ArchestrA Attribute Categories.
|
||
|
||
## Performance Considerations
|
||
|
||
There is no arbitrary limit to the number of primitives, attributes, and inputs/outputs that you can add to your ApplicationObject. As with all software, the more complex your object gets, the more resources it will need. Depending on your system resources, there will eventually be a practical limit where performance becomes unacceptable. However, under normal circumstances, this should not be an issue except for very large and complex ApplicationObjects.
|
||
|
||
For additional restrictions on the complexity of primitive hierarchies, see Limitations to the Complexity of Primitive Hierarchies.
|