مرجع فنی و نقشهٔ راه
راهنمای یکپارچه‌سازی با سامانه‌های دیگر، مرجع رویدادها، تنظیمات و مدل داده، راهنمای گام‌به‌گام کارهای روزمره، پرسش‌های متداول و نقشهٔ راه.
راهنمای یکپارچه‌سازی و مرجع API
هر چهار سرویس، رابط برنامه‌نویسی REST با مستند OpenAPI (Swagger) دارند. سامانهٔ همزاد دیجیتال با ۱٬۰۶۶ عملیات در دو فضای نام عمومی (/api، با کلید پروژه) و مدیریتی (/internal/api، با نشست مدیر) گسترده‌ترین سطح را دارد؛ WebSocket برای دادهٔ زنده و فرمان، Webhook برای رویدادهای خروجی.
خانواده‌های API سامانهٔ همزاد دیجیتال (گزیده)
| خانواده | عملیات | کاربرد |
|---|---|---|
| مدیریت SNMP | ۶۴ | تجهیزات، نگاشت OID، قالب‌ها، MIB، نظرسنجی اجباری، Trap |
| مدیریت منطق | ۴۷ + ۱۹ | قوانین، حدود، اسکریپت‌ها، ماشین‌های حالت، سناریوها، اجرای آزمایشی، اعتبارسنجی عبارت |
| مدیریت Redfish | ۴۶ + ۹ | سرورها/BMC، نگاشت منابع، قالب‌ها، مرور درخت، نوشتن |
| مدیریت Modbus | ۴۲ + ۲۱ | تجهیزات، رجیسترها، قالب‌ها، اسکن، خواندن/نوشتن coil و رجیستر |
| کاتالوگ تجهیزات (داخل سامانه) | ۳۱ + ۲۹ + ۱۴ | مدل‌ها، برندها، دسته‌ها، ساخت تجهیز از مدل، همگام‌سازی با سرویس کاتالوگ |
| PLC | ۳۰ + ۱۰ | تجهیزات PLC، تگ‌ها، پروتکل‌ها، خواندن/نوشتن |
| تجهیزات و گروه‌ها | ۳۰ + ۱۲ + ۱۴ | CRUD تجهیز، سریال، گروه‌بندی، تبدیل به تجهیز پروتکلی |
| دارایی و نگهداشت | ۳۰ + ۱۰ | دارایی، هزینه، نگهداشت، روابط، انتقال، گزارش |
| نقاط (ACV) | ۲۷ + ۸ + ۹ | CRUD نقطه، مقادیر بلادرنگ، نقاط هشداردار، تجزیهٔ شناسه، بارگذاری مجدد |
| اعلان | ۲۷ + ۱۰ | کانال‌ها، گروه‌ها، گیرنده‌ها، قالب‌ها، لاگ، تست کانال، سیاست تشدید |
| باتری و UPS | ۲۸ + ۱۹ + ۱۳ + ۹ + ۱۱ | وضعیت UPS، گره‌های باتری، تاریخچه، فرمان‌های کنترلی (ریبوت گره…) |
| Tuya · MQTT · OPC UA · KNX · BACnet · M‑Bus | ۲۴ · ۲۸ · ۳۲ · ۱۹ · ۳۴ · ۱۵ | تجهیزات، نگاشت‌ها، کشف، خواندن/نوشتن هر پروتکل |
| ساختار پروژه | ۲۰ + ۹ + ۹ + ۱۱ + ۱۰ + ۱۴ | پروژه، سازمان، ساختمان، طبقه، فضا؛ تکثیر طبقه |
| رسانه | ۲۰ + ۱۲ | بارگذاری/سرو فایل، تصاویر داشبورد، مدل‌های سه‌بعدی |
| افراد، کاربران، نقش‌ها، مجوزها، کلیدها | ۲۰ + ۱۹ + ۹ + ۱۶ + ۹ | هویت، نقش‌ها، انتساب مجوز، کلیدهای پروژه |
| تیکت | ۱۸ | تیکت، نظرات، وضعیت، SLA |
| نگاشت پروتکل و رجیستری | ۱۸ + ۱۳ | نگاشت دوطرفهٔ شناسه ↔ OID/رجیستر، نوشتن با شناسه |
| دستیار هوشمند | ۱۷ | چت، گفت‌وگوها، حافظه‌ها، دانش، تأیید/لغو اقدام |
| داشبوردها | ۱۴ | CRUD داشبورد، المان‌ها، کلون، صادرات |
| انرژی | ۱۱ + ۹ + … | کنتورها، تعرفه‌ها، هزینه، تقاضا، بلادرنگ |
| تنظیمات، لاگ، پایش، صف‌ها، سیستم | ۱۵ + ۱۸ + ۱۰ + ۸ + ۸ | ۳۳۵ تنظیم، سطح لاگ هر دسته، GC، راه‌اندازی مجدد، آمار صف |
| شبیه‌ساز، SMPP، سرویس‌های داخلی | ۱۵ + ۱۴ + ۱۲ | کنترل شبیه‌ساز، اتصال SMPP، شروع/توقف سرویس‌ها |
سرویس‌های همراه
| سرویس | عملیات | خانواده‌ها |
|---|---|---|
| کاتالوگ تجهیزات | ۶۹ | مدل‌ها (۱۱)، دسته‌ها (۱۱)، برندها (۸)، تگ‌ها (۸)، مشخصهٔ پروتکل (۶)، پورت‌ها (۶)، لوازم (۶)، اسناد (۶)، تصاویر (۴)، کشف (۵)، عامل غنی‌سازی (۵)، مرجع (۵)، همگام‌سازی (۲)، ورود/خروج (۲)، جست‌وجو، آمار |
| ARG AI | ۱۴۵ | تحلیل ML (۶۸)، چت (۸)، هشدار (۸)، چندسایتی (۷)، ارائه‌دهنده‌ها (۷)، اصلاح خودکار (۷)، پرامپت (۶)، ورود داده (۶)، گزارش ML (۵)، انطباق (۵)، تنظیمات و سلامت (۵)، گزارش (۴)، توئین (۴)، داشبورد (۴)، موبایل (۴)، Webhook (۴)، تحلیل (۴)، احراز (۳)، صادرات (۲)، CSV (۱) |
| نقشهٔ آفلاین | ۱۸ | مناطق (۱۱)، دانلود (۷)، سرویس کاشی z/x/y (۲) |
| Twin Designer | ۱۴ | تایپ‌ها، پیش‌نویس‌ها، اعتبارسنجی، سازگاری، انتشار، چرخهٔ عمر، قالب‌های Modbus، تولید کد |
الگوهای یکپارچه‌سازی
خواندن دادهٔ زنده
اتصال WebSocket با کلید پروژه → authenticate → enid_subscribe برای نقاط دلخواه → دریافت بسته‌های batch هر ۷۵ میلی‌ثانیه. برای سامانه‌هایی که WebSocket ندارند: رابط REST مقادیر لحظه‌ای به‌صورت دوره‌ای.
ارسال فرمان
set_enid_value روی WebSocket یا فراخوانی REST فرمان با کلید دارای مجوز کنترل و کلید یکتای فرمان؛ رسید اجرا با COMMAND_RECEIPT_UPDATE برمی‌گردد.
دریافت رویداد
Webhook از قوانین و اعلان‌ها (JSON با شناسهٔ نقطه، مقدار، شدت، زمان)؛ یا پرس‌وجوی رابط REST رویدادها و گزارش اعلان‌ها.
ورود ساختار و تجهیزات
API ساختار (پروژه → … → فضا) و تجهیزات، یا فایل اکسل ورود گروهی؛ ساخت نقاط از کاتالوگ با یک فراخوانی؛ همگام‌سازی کاتالوگ مرکزی با full-snapshot و changes.
مرجع‌ها: رویدادها، تنظیمات، توابع، المان‌ها
انواع رویداد و شدت
| رویداد | چه زمانی ثبت می‌شود |
|---|---|
| RULE_FIRED · STATE_CHANGED · SCRIPT_EXECUTED | اجرای قانون، گذار ماشین حالت، پایان اسکریپت (با نتیجه) |
| ACV_ALARM · ACV_LIMIT_EXCEEDED · ACV_VALUE_CHANGED | ورود نقطه به وضعیت هشدار، عبور از حد، تغییر مقدار (اختیاری برای نقاط مهم) |
| DEVICE_CONNECTED · DEVICE_DISCONNECTED | تغییر وضعیت آنلاین تجهیز روی هر کانال |
| SERVICE_STARTED · SERVICE_STOPPED | شروع/توقف سرویس‌های پروتکل و اعلان |
| USER_LOGIN · USER_LOGOUT · SETTINGS_CHANGED · MANUAL_COMMAND · CUSTOM | ورود/خروج، تغییر تنظیمات، فرمان دستی اپراتور، رویداد سفارشی از اسکریپت |
| شدت | INFO · WARNING · CRITICAL · ERROR — قابل فیلتر در دفتر رویداد و قابل استفاده در سیاست تشدید |
دسته‌های تنظیمات سرور (۳۳۵ تنظیم)
هر تنظیم نوع داده و اعتبارسنجی دارد، در فایل ذخیره و در جدول تنظیمات آینه می‌شود؛ بازه‌های زمان‌بندی (دسته‌ای، تاریخچه، انرژی) از همین‌جا خوانده می‌شوند. برون‌برد/درون‌برد برای انتقال پیکربندی بین محیط‌ها.
توابع زبان عبارت
| تابع | معنا |
|---|---|
ACV['enid'] | مقدار جاری نقطه |
HOUR() MINUTE() SECOND() | زمان جاری سرور |
DAY_OF_WEEK() DAY_OF_MONTH() MONTH() YEAR() | اجزای تاریخ |
TIME_IN_RANGE(h1,m1,h2,m2) | درست اگر زمان جاری در بازه باشد (بازهٔ شبانه هم پشتیبانی می‌شود) |
IS_WEEKDAY() IS_WEEKEND() | روز کاری / تعطیل |
TIMESTAMP() | زمان یونیکس |
AVG(enid,n) MIN(enid,n) MAX(enid,n) | آمار n مقدار اخیر نقطه |
LAST_N(enid,n) | n مقدار اخیر |
CHANGED(enid) RISING(enid) FALLING(enid) | تغییر / روند صعودی / نزولی در بافر اخیر |
HISTORY_SIZE(enid) | تعداد مقادیر در بافر |
ویژگی‌های مشترک المان‌های دوبعدی
موقعیت و اندازه، چرخش، لایه (z)، قفل، پنهان، رنگ پس‌زمینه/حاشیه/متن، فونت و اندازه، شعاع گوشه، سایه، شفافیت، شرط نمایش، پیوند به داشبورد دیگر، اتصال نقطه (تک یا چند نقطه با تجمیع)، نگاشت مقدار (گسسته/بازه‌ای)، واحد و دقت اعشار، فرمان (نوع، مقدار، تأیید).
دسته‌های انیمیشن BMS (۱۵۳)
حوزه‌های مجوز (۱۲ × ۷ عمل)
حوزه‌ها: داشبورد، ساختار، تجهیزات، نقاط، منطق، هشدار، انرژی، دارایی، کاربران، تنظیمات، رسانه، گزارش. عمل‌ها: مشاهده، ایجاد، ویرایش، حذف، کنترل، صادرات، مدیریت. نقش‌های پیش‌فرض: مدیر سیستم، مدیر پروژه، اپراتور، تکنسین، مدیر انرژی، امنیت، بازدیدکننده.
پرسش‌های متداول و واژه‌نامه
پرسش‌های متداول
آیا سامانه بدون اینترنت کار می‌کند؟
بله. همهٔ اجزا داخل شبکهٔ مشتری اجرا می‌شوند؛ نقشه از سرور نقشهٔ آفلاین و مدل زبانی دستیار می‌تواند محلی باشد. فقط اعلان تلگرام و برخی ارائه‌دهنده‌های مدل زبانی به اینترنت نیاز دارند.
اگر تجهیزی در کاتالوگ نباشد؟
از رابط «درخواست افزودن تجهیز» یا مستقیم با نگاشت دستی OID/رجیستر/تگ در همان پروژه ساخته می‌شود؛ سپس می‌تواند به کاتالوگ اضافه شود تا در پروژه‌های بعدی آماده باشد.
چند نقطه را پشتیبانی می‌کند؟
نمونهٔ مرجع این سند ۴۲۷ تجهیز و ۳٬۹۶۴ نقطه در سه پروژه است. موتور انتشار روی یک سرور معمولی ۶۹ هزار به‌روزرسانی در ثانیه را بدون از دست رفتن تحویل داد (فصل ۳۱)؛ هر پروژه پایگاه تاریخچهٔ مستقل دارد و سایت‌های بسیار بزرگ به واحدهای مستقل تقسیم می‌شوند.
فرمان اشتباه یا تکراری چه می‌شود؟
فرمان به مجوز کنترل و تأیید رمز نیاز دارد، با کلید یکتا فقط یک‌بار اجرا می‌شود و رسید تجهیز ثبت می‌شود. اقدام‌های دستیار هوشمند هرگز بدون تأیید اجرا نمی‌شوند.
داده‌ها کجا ذخیره می‌شوند؟
در PostgreSQL روی سرور مشتری (یا نمونهٔ ابری اختصاصی)؛ پشتیبان روزانه؛ هیچ داده‌ای به سرویس بیرونی ارسال نمی‌شود مگر ارائه‌دهندهٔ مدل زبانی که مشتری انتخاب می‌کند.
می‌توان سامانهٔ فعلی مشتری را نگه داشت؟
بله. از طریق OPC UA، Modbus، MQTT یا WebSocket به سامانهٔ موجود متصل می‌شود و می‌تواند به‌عنوان لایهٔ نمایش/تحلیل روی آن بنشیند؛ فریم‌های SCADA نسل قبل ARG هم پذیرفته می‌شود.
واژه‌نامه
| واژه | معنا در این سامانه |
|---|---|
| همزاد دیجیتال | همتای دیجیتال یک تجهیز یا سایت که مقادیر زنده، وضعیت، تاریخچه، حدود و رفتار آن را حمل می‌کند |
| نقطه (ACV) | متغیر کنترلی فعال؛ یک سیگنال ورودی یا خروجی با واحد، مقیاس و حدود |
| ENID | شناسهٔ یکتای ۱۶ عددی هر نقطه در کل سامانه |
| تایپ توئین | تعریف داده‌محور یک نوع تجهیز (نقاط، رویدادها، فرمان‌ها، نگاشت پروتکل) که کد اجرایی از آن تولید می‌شود |
| حد با هیسترزیس | آستانه‌ای که خروج از آن به عبور از آستانه ± فاصلهٔ ایمنی نیاز دارد تا هشدار نوسانی نسازد |
| سناریو | مجموعه‌عمل‌های فعال/غیرفعال‌شونده با راه‌انداز و شرط خاموشی |
| ماشین حالت | مدل رفتاری با حالت‌ها و گذارها که حالت جاری‌اش ماندگار است |
| پروفایل محصول | برش منوها و ماژول‌ها برای یک نوع مشتری (BMS، DCIM، IoT…) |
| کاتالوگ تجهیزات | پایگاه دانش مرکزی مدل‌های تجهیز با نقاط و مشخصهٔ پروتکل آماده |
| MBTiles | بستهٔ استاندارد کاشی‌های نقشه برای استفادهٔ آفلاین |
| DCIM · PUE | مدیریت زیرساخت مرکز داده · نسبت توان کل به توان IT |
راهنمای گام‌به‌گام — کارهای روزمره در سامانه
هفت روال پرتکرار، همان‌طور که یک کاربر در رابط سامانه انجام می‌دهد. هر روال با صفحه‌های واقعی همراه است.
الف · افزودن یک تجهیز جدید از کاتالوگ
ب · تعریف یک نقطهٔ محاسباتی یا دستی
پ · ساخت یک داشبورد دوبعدی
ت · ساخت یک صحنهٔ سه‌بعدی
ث · نوشتن یک قانون و آزمودن آن
ج · راه‌اندازی اعلان پیامکی و تشدید
چ · گفت‌وگو با دستیار برای انجام کار
مرجع مدل داده — انواع، دسته‌ها و وضعیت‌ها
نوع داده و جهت نقطه
نوع داده: بولی، عدد صحیح، اعشاری، شمارشی، رشته. جهت: ورودی (خواندنی) یا خروجی (فرمان‌پذیر). نقاط خروجی از طریق درایور پروتکل (SET، رجیستر، گره، تاپیک، datapoint) نوشته می‌شوند.
وضعیت نقطه
غیرفعال · عادی · احتیاط · خطر · خطا. احتیاط/خطر از حدود دوسطحی هر سو (Low/LowLow، High/HighHigh) محاسبه می‌شود؛ خطا برای مقدار خارج از محدودهٔ معتبر یا خواندن ناموفق.
انواع نقطه (۵۵)
ورودی/خروجی دیجیتال و آنالوگ، شمارنده، تایمر، متغیر، زمان، وضعیت سیستم، پیامک، ایمیل، و انواع تخصصی تجهیزات (UPS، ژنراتور، ATS، PDU، HVAC، دسترسی…).
دسته‌های سیگنال (~۵۰۰)
سنسورها (دما، رطوبت، CO₂، فشار، دبی، سطح، لرزش، نور، حضور…)، ژنراتور (GEN_*)، تهویه (AC_*)، مخابرات (GSM_*)، انرژی (ENERGY_*)، اصلی/شبکه (MAIN_*)، وضعیت‌ها و فرمان‌ها.
پایه‌های شناسه (نمونه)
| پایه | معنا |
|---|---|
| 2000–2005 | متغیر، تاریخ/زمان، تایمر، وضعیت سیستم، پیامک، ایمیل |
| 4000 · 5000 | شخص، گروه اشخاص (دسترسی فیزیکی) |
| 6000–6800 | خانوادهٔ تجهیزات: UPS، ژنراتور، ATS، PDU، AHU، FCU، چیلر، بویلر، آسانسور، کنترلر دسترسی، کنترلر پارکینگ، دوربین LPR، VFD… |
| 9000–9011 | AC، SNMP (9004)، Modbus (9005)، KNX (9006)، BACnet (9007)، LonWorks (9008)، M‑Bus (9009)، PLC (9010)، Redfish (9011) |
| 9024–9027 · 9065 | S7، FINS، MC، ADS · Tuya |
سلسله‌مراتب و موجودیت‌های همراه
پروژه (کلیدها، تنظیمات، پروفایل) → سازمان → ساختمان → طبقه → فضا → تجهیز (گروه، سریال، مدل کاتالوگ، پروتکل) → نقطه. موجودیت‌های همراه: داشبوردها (دوبعدی/سه‌بعدی/لیستی/نقشه، مالک، اشتراک)، رسانه، قوانین/حدود/اسکریپت‌ها/ماشین‌های حالت/سناریوها، کانال‌ها/گروه‌ها/قالب‌های اعلان، سیاست‌های تشدید، رویدادها، دارایی‌ها، تیکت‌ها، کنتورها/تعرفه‌ها، UPS/گره‌های باتری، افراد/نقش‌ها/مجوزها، توئین‌ها و رویدادهای توئین.
نقشهٔ راه
مواردی که در این سند به‌عنوان قابلیت ادعا نشده‌اند و در برنامهٔ توسعه قرار دارند.
| مورد | وضعیت |
|---|---|
| کلاستر فعال‑فعال لایهٔ کاربردی و گره‌های جمع‌آوری افقی | در برنامه امروز: HA پایگاه داده، گره آماده به کار، تقسیم سایت به واحدهای مستقل |
| مسیر ورود چندرشته‌ای برای حجم پالایشگاهی (صدها هزار نقطه با به‌روزرسانی ثانیه‌ای) | در برنامه موتور انتشار امروز ~۷۰ هزار به‌روزرسانی در ثانیه؛ بهینه‌سازی مسیر پردازش کامل |
| BACnet/IP و MS/TP، KNX، M‑Bus | در برنامه رابط کاربری، مدل داده و حلقهٔ نظرسنجی آماده است؛ لایهٔ پروتکل در حال تکمیل |
| PLC: OPC UA داخل درایور PLC، Beckhoff ADS | در برنامه (OPC UA مستقل هم‌اکنون کامل است) |
| تایپ‌های توئین عمومی در سرور (چیلر، پمپ، AHU) | در برنامه امروز در Twin Designer و لایهٔ رابط کاربری؛ سرور تایپ UPS را اجرا می‌کند |
| اتصال دادهٔ زندهٔ ماژول‌های هتل، تولید و کشاورزی | در توسعه صفحات و جریان کاری آماده؛ اتصال به نقاط و موجودیت‌های سرور در حال تکمیل |
| صفحات اختصاصی خورشیدی، آب، شارژ EV، ناوگان، موقعیت‌یابی داخلی، اطفا با دادهٔ زنده | در توسعه رابط کاربری کامل روی دادهٔ نمونه؛ پایش واقعی از طریق مدل عمومی نقاط ممکن است |
| اپلیکیشن موبایل بومی و حالت آفلاین کامل (PWA) | در برنامه نسخهٔ وب واکنش‌گرا و API موبایل ARG AI موجود است |
| نقشهٔ سه‌بعدی کروی داخل سامانه (Cesium/Mapbox) | در برنامه نقشهٔ دوبعدی با ۸ منبع کاشی و کرهٔ سه‌بعدی در سرور نقشهٔ آفلاین فعال است |
همزاد دیجیتال را زنده ببینید
دموی زندهٔ ArgBMS با همزادهای سه‌بعدی، داشبوردها و منطق واقعی.