Twin Types with Twin Designer

A piece of equipment such as a chiller, pump, air handling unit, or UPS needs dozens of points, several alarms, and a protocol mapping. Instead of defining these repeatedly for every device, a "twin type" is defined once, and every device of that model follows it. This work happens in ARG Twin Designer: a separate engineering application, with an English interface, that runs on the engineering workstation and is not part of the product's menu. In this lesson you learn this tool's layout and the process of defining, testing, and releasing a type.

Get to know the screen

The first screen is the کتابخانهٔ نوع‌ها (Type Library), with the note: "Each twin type is defined once; code, docs, and tests are generated from it."

Opening a type opens its workspace. At the top are the ذخیره (Save) button (Ctrl+S), undo and redo, draft and published version chips, a validity button (معتبر (Valid) or "n issues"), and انتشار نسخه (Publish Version). Beside them sit the ساختار مدل (Model Structure) tree and the مشخصات (Specifications) panel. The workspace has eight tabs:

Step by step

1. Create the type from a template. In the کتابخانهٔ نوع‌ها click از قالب دستگاه. In the تعریف نوع جدید (Define New Type) dialog, pick one from the templates table and review the رجیسترهای قالب (Template Registers) preview (key, English label, address, data type, scale, unit, and whether it is writable). About 25 ready-made Modbus templates exist, including an energy meter, chiller, CRAC, UPS, variable-frequency drive, generator, and weather station. For equipment with no template, use the نوع خالی tab.
2. Enter the type's identity. Fill in برچسب فارسی (Local Label), برچسب انگلیسی (English Label), برچسب موجودیت (Entity Label), فضای نام (Namespace), and کلید (Key). For equipment that is only monitored, leave فقط‌خواندنی (Read-only) on. Then click ایجاد (Create). The نقاط داده tab opens; an "Online" point, an offline event, a Modbus source, and a 120-second staleness timeout are generated automatically.
3. Complete the points. In نقاط داده, translate each point's local label; it is initially filled from the template's English description. Check the واحد (Unit), ضریب (scale) (Scale) (e.g. ×0.1 so a raw value of 72 becomes 7.2), and, if needed, the minimum and maximum. Every cell is edited with a double-click or Enter. افزودن ویژگی (Add Property) creates a new point. The data type is one of number, integer, boolean, string, or enum, and دسترسی is either "read-only" or "write with policy".
4. Define events and alarms. In the رویدادها و هشدارها tab, click افزودن رویداد (Add Event) and set the نقطه (Point), عملگر (Operator) (=, ≠, >, ≥, <, ≤), مقدار (Value), and شدت (Severity) (اطلاع (Info), هشدار (Warning), آلارم (Alarm), بحرانی (Critical)). Example: discharge pressure greater than 20 bar → Alarm. Review the "if … → …" sentence in the specifications panel.
5. Complete the protocol mapping. In نگاشت پروتکل, give each point an address. The address format depends on the protocol: in Modbus, for example IR:100 or HR:210; in BACnet, for example AI:1; in SNMP an OID; and in MQTT a topic. Rows without an address show "not mapped". The goal is to bring the coverage bar to full.
6. Configure the source. In منبع و هویت, set کهنه‌شدن پس از (Stale after) (between 5 and 1800 seconds) and the فیلدهای هویت (Identity fields). If no data arrives within this period, its quality is reported as stale.
7. Save and validate. Click ذخیره. The validity button should read معتبر. If it shows "n issues", click it and fix them. Validation messages are in English, for example a duplicate key, a minimum greater than a maximum, or a writable point in a read-only type.
8. Test in the simulator. In شبیه‌ساز زنده click اجرا (Run). Change the سناریو (Scenario) from عملکرد عادی (Normal operation) to شرایط آلارم (Alarm condition) and watch the event fire in the رویدادنگار (Event Log). Then try قطع ارتباط (Disconnected), خرابی سنسور (Sensor fault), and خطای دریافت داده (Data receive error), and follow the data-quality change (GOOD, STALE, UNKNOWN, BAD). Up to six points can be shown on the chart at once, and سرعت (Speed) can be set to ×0.5, ×1, or ×2.5.

   

9. Publish a version. In نسخه و انتشار, read the سازگاری با آخرین انتشار (Compatibility with Latest Release) panel; it states what kind of version bump is required (MAJOR, MINOR, PATCH, or NONE). Set نسخه (Version) accordingly, or click استفاده از پیشنهاد (Use suggestion), enter the منتشرکننده (Publisher) name, and click انتشار نسخه. A published version is immutable and carries a checksum.
10. Retrieve the code. In کد تولیدی, get the files with دانلود (Download) or نوشتن در پوشهٔ out (Write to out folder). Adding these files to the product is a manual step for the development team; there is no automatic installation.

Once deployed, devices of that type appear inside the product itself, on pages such as «مدیریت انرژی» ← «مدیریت UPS» ← «دوقلوی دیجیتال» (Energy Management → UPS Management → Digital Twin). Each instance shows its هویت دوقلو (Twin Identity), نسخه نوع Twin (Twin Type Version), source, and data class.

Tips and common mistakes

• The "Publish Version" button is enabled only once changes are saved, the type is valid, "Publisher" is filled in, and the version has been bumped enough.
• The "Generated Code" tab stays disabled while an unsaved change exists.
• The operators >, ≥, <, and ≤ are valid only for numeric points.
• A read-only type cannot contain a writable point.
• In the current version, Twin Designer has no tab for defining commands, and generated types do not send commands; configure equipment control from dashboards (lessons B9 and B10).
• Sub-components (such as a UPS's batteries) are edited from the "Model Structure" tree, not with an add button.

Summary

• Twin Designer is a separate engineering application that defines each equipment type once.
• A type definition includes data points, events and alarms, protocol mapping, and source and identity.
• The Live Simulator runs normal, alarm, disconnected, sensor-fault, and receive-error scenarios.
• A published version is immutable, and the tool itself determines whether a MAJOR, MINOR, or PATCH bump is required.
• The development team adds the generated code to the product; the result appears on pages such as the UPS "Digital Twin".