MergenHub Envest
الرئيسية/المستندات/الجوال وقوالب الأجهزة

إنشاء قوالب الأجهزة (الحزم)

صيغة .mhpkg.json: المعاملات والقنوات والأجهزة والوسوم، والوسوم المحسوبة ودوال التعابير، والإنذارات، ومجموعات شاشات الخادم والهاتف، والتحقق، ومثال كامل، ومهارة الذكاء الاصطناعي، وإضافة جهاز إلى المكتبة.

قالب الجهاز (حزمة MergenHub) هو ملف JSON واحد يحمل الجهاز بالكامل: إعدادات القناة والمشغّل، والجهاز، وخريطة السجلات (الوسوم)، والوسوم المحسوبة، والإنذارات، وشاشات المشغّل. عند التثبيت لا يُطلب سوى القيم الخاصة بالموقع (عنوان IP، المنفذ، معرّف الوحدة…)، ويأتي كل ما عدا ذلك جاهزًا. امتداد الملف هو .mhpkg.json.

تشرح هذه الصفحة كيفية بناء الحزمة، ومعنى حقولها، وما يحدث عند التثبيت.

أين تُستخدم الحزم

  • واجهة ويب MergenHub — مربع الحوار Device Library (أيقونة الكتب في رأس شجرة المشروع، أو زر Device Library في عرض Connectivity، أو البطاقة في نافذة اختيار الشاشة الجديدة في SCADA). يقوم بالتثبيت من المكتبة، ويقوم Import from file بتثبيت ملف .mhpkg.json لديك.
  • MergenHub Mobile — معالج Add device (المكتبة، قوالبي، ملف، الحافظة، QR، عنوان)، وصفحة Templates، وImport package / template. راجع MergenHub Mobile.
  • Device Library — الحزم التي أعدّتها Envest واختبرتها منشورة على الموقع، وتقرؤها التطبيقات من واجهة API عامة: GET /api/v1/library (الفهرس)، GET /api/v1/library/{slug} (جهاز واحد)، GET /api/v1/library/{slug}/package (ملف الحزمة).
مربع حوار Device Library في واجهة ويب MergenHub
مربع حوار Device Library في واجهة ويب MergenHub

على خادم لا يملك اتصالًا بالإنترنت، نزّل الحزمة من الموقع وثبّتها باستخدام Import from file.

Import from file — تفاصيل التثبيت ونتيجة الفحص
Import from file — تفاصيل التثبيت ونتيجة الفحص

البدء السريع

أسهل طريقة هي البدء من جهاز يعمل:

  1. افتح MergenHub Mobile في وضع الهاتف، وعرّف الجهاز مع قناته وجهازه وبعض الوسوم، وتحقق من وصول القيم.
  2. في تبويب Kanallar (القنوات) افتح قائمة ⋯ الخاصة بالجهاز واختر Şablon olarak kaydet / paylaş (حفظ / مشاركة كقالب). أدخل الاسم والوصف والشركة المصنّعة والطراز؛ واترك Ekranları da al (تضمين الشاشات) مفعّلًا إذا أردت إرفاق الشاشات.
  3. احصل على الحزمة عبر Dosya olarak paylaş (المشاركة كملف) أو Panoya kopyala (النسخ إلى الحافظة). تُحوَّل عناوين IP في معرّف الجهاز والإعدادات تلقائيًا إلى المعامل {{ip}}.
  4. حرّر الملف في محرر نصوص أو بمساعدة مساعد ذكاء اصطناعي (أضف الوسوم، واكتب الأوصاف، وأضف الإنذارات والشاشات). يحتوي القسم guide في الملف المُصدَّر على قواعد التنسيق، ومفاتيح إعدادات المشغّلات المستخدمة، وأمثلة العناوين، وقائمة الرموز.
  5. أعد الحزمة إلى النظام: على الهاتف Cihaz ekle › Dosya, pano, QR ya da adres (إضافة جهاز › ملف أو حافظة أو QR أو عنوان)، وعلى الخادم Device Library › Import from file.
التصدير كقالب في MergenHub Mobile
التصدير كقالب في MergenHub Mobile

لتغليف مشروع كامل استخدم Daha › Proje › Projeyi dışa aktar (المزيد › المشروع › تصدير المشروع) على الهاتف (kind: "project").

بنية الملف

الحزمة هي كائن JSON واحد:

{
  "format": "mergenhub-package",
  "formatVersion": 1,
  "kind": "template",
  "meta": { "name": "…" },
  "parameters": [],
  "channels": [],
  "derived": [],
  "alarms": [],
  "screens": [],
  "notes": "…"
}
الحقلمطلوبالوصف
formatنعمدائمًا "mergenhub-package"
formatVersionموصى بهحاليًا 1؛ تُرفض الحزمة ذات الإصدار الأعلى مما يعرفه التطبيق
kindنعم"template" (قالب جهاز، تُطلب المعاملات عند التثبيت) أو "project" (مشروع كامل)
metaنعمالاسم والمعلومات الوصفية
parametersلاالقيم المطلوبة عند التثبيت
channelsنعمشجرة قناة ← جهاز ← وسم (قناة واحدة على الأقل)
derivedلاالوسوم المحسوبة (المتقدمة)
alarmsلاتعريفات الإنذارات
screensلاشاشات المشغّل
notesلانص حر (Markdown) يصف ما يفعله الجهاز
guideلاقسم توضيحي يُكتب عند التصدير؛ يُتجاهل عند الاستيراد

يحتوي قالب الجهاز على قناة واحدة بها جهاز واحد. عندها فقط يُطلب اسما القناة والجهاز عند التثبيت، وتنتقل المسارات عند تغيير الاسم.

meta

الحقلالوصف
nameالاسم المعروض للحزمة (مطلوب)، مثل "Example EA-100 Energy Meter"
descriptionملخص من جملة أو جملتين
vendor, model, versionالشركة المصنّعة والطراز وإصدار البرنامج الثابت للجهاز؛ تظهر في القوائم والبحث
authorمن أعدّها
keywordsكلمات البحث المفتاحية (مصفوفة)
homepageعنوان صفحة المنتج
createdAt, createdWithتُكتب تلقائيًا عند التصدير

المعاملات والعناصر النائبة

parameters هي الحقول التي تُطلب من المستخدم عند التثبيت. أينما ظهر {{key}} في أي قيمة نصية في الحزمة، يُستبدل بالقيمة التي أدخلها المستخدم.

"parameters": [
  { "key": "ip", "label": "IP address", "type": "text", "required": true, "placeholder": "192.168.1.50" },
  { "key": "port", "label": "Port", "type": "number", "default": 502, "group": "Connection" },
  { "key": "unit", "label": "Unit ID", "type": "number", "default": 1, "group": "Connection" }
]
الحقلالوصف
keyيبدأ بحرف أو _؛ ويحتوي على حروف وأرقام و_ (مثل ip وport وunit وfins_node)
labelالاسم المعروض في النموذج
typetext (الافتراضي) أو number أو select
defaultالقيمة الافتراضية
requiredإذا كانت true فلا يمكن ترك الحقل فارغًا
placeholder, hintمثال داخل الحقل ونص مساعدة أسفله
groupعنوان في النموذج؛ تُعرض حقول المجموعة نفسها معًا
optionsللنوع select: [{ "value": 1, "label": "TCP" }, …]

القواعد:

  • تعمل العناصر النائبة داخل القيم النصية فقط. لربط إعداد رقمي بمعامل، اكتبه كنص: "modbus_ethernet.DEVICE_ETHERNET_PORT_NUMBER": "{{port}}". تُحوَّل إعدادات المشغّل الرقمية إلى أرقام عند التثبيت.
  • يُبنى معرّف الجهاز عادةً من المعاملات: "id": "<{{ip}}>.{{unit}}".
  • إذا بقي أي {{…}} غير معبّأ بعد تطبيق القيم، يُمنع التثبيت.
  • اترك القيمة الافتراضية لعنوان IP فارغة وعيّن required: true؛ وضع عنوانًا مثاليًا في placeholder. بهذه الطريقة لا يستطيع أحد التثبيت دون إدخال العنوان.

القنوات والأجهزة والوسوم

"channels": [
  {
    "name": "Energy",
    "driver": "Modbus TCP/IP Ethernet",
    "settings": {},
    "devices": [
      {
        "name": "Meter1",
        "id": "<{{ip}}>.{{unit}}",
        "scanMs": 1000,
        "timeouts": { "connectS": 3, "requestMs": 1000, "retries": 3 },
        "settings": { "modbus_ethernet.DEVICE_ETHERNET_PORT_NUMBER": "{{port}}" },
        "tags": [
          { "name": "VoltageL1", "address": "30001", "type": "Float", "access": "read", "scanMs": 1000, "units": "V" }
        ],
        "groups": []
      }
    ]
  }
]

القناة

الحقلالوصف
nameاسم القناة (مطلوب، دون نقاط)
driverالاسم الكامل للمشغّل (الجدول أدناه)
settingsإعدادات المشغّل على مستوى القناة (مفاتيح متوافقة مع Kepware)
descriptionالوصف
devicesمصفوفة الأجهزة (مطلوبة)

الجهاز

الحقلالافتراضيالوصف
name—اسم الجهاز (مطلوب، دون نقاط)
idحسب المشغّلمعرّف الجهاز؛ يعتمد التنسيق على المشغّل
description—الوصف
enabledtrueإذا كانت false فلا يُمسح الجهاز
scanMs1000معدل مسح الجهاز (ms)
scanMode40 احترام العميل، 1 ليس أسرع من، 2 معدل ثابت، 3 استعلام عند الطلب، 4 احترام معدل الوسم
timeouts3 / 1000 / 3connectS مهلة الاتصال (s)، requestMs مهلة الطلب (ms)، retries محاولات إعادة المحاولة
settingsافتراضيات المشغّلإعدادات المشغّل على مستوى الجهاز
tags, groups—الوسوم ومجموعات الوسوم

الوسم

الحقلالافتراضيالوصف
name—اسم الوسم (مطلوب، دون نقاط، فريد داخل الجهاز أو المجموعة)
address—العنوان بصياغة المشغّل (مطلوب)
typeDefaultنوع البيانات (أدناه)
accessreadread أو readwrite
scanMs1000معدل مسح الوسم (ms)
description—الوصف؛ يظهر كوحدة في التطبيق إذا كان 6 أحرف أو أقل
units—الوحدة؛ تُستخدم كوصف عندما يكون description فارغًا
scaling—التحجيم (أدناه)

أنواع البيانات: Default, Boolean, Char, Byte, Short, Word, Long, DWord, Float, Double, String, BCD, LBCD, Date, LLong, QWord. Default هو النوع الذي يختاره المشغّل للعنوان.

التحجيم يحوّل القيمة الخام إلى وحدات هندسية؛ وتطبّقه عمليات الكتابة بالعكس:

"scaling": { "type": "linear", "rawLow": 0, "rawHigh": 10, "low": 0, "high": 1, "resultType": "Double", "units": "kWh" }

type هو linear أو sqrt (الجذر التربيعي)؛ وrawLow/rawHigh النطاق الخام، وlow/high النطاق بعد التحجيم؛ وresultType نوع البيانات بعد التحجيم (الافتراضي Double)؛ وclampLow وclampHigh يقيّدان عند الحدين، وnegate يعكس الإشارة.

المجموعات تنظّم الوسوم في مجلدات داخل الجهاز ويمكن تداخلها. مسار الوسم داخل مجموعة هو Channel.Device.Group.Tag.

"groups": [ { "name": "Energy", "description": "Counters", "tags": [ … ], "groups": [ … ] } ]

المشغّلات وصياغة العناوين

يأخذ driver الاسم الكامل للمشغّل. صياغة العناوين ومفاتيح الإعدادات متطابقة في خادم MergenHub وفي MergenHub Mobile؛ وللتفاصيل راجع مشغّلات البروتوكولات.

المشغّل (driver)معرّف الجهاز (id)أمثلة العناوين
Simulatorرقم الجهاز، مثل 1SINE:10:0:100, RAMP:30:0:500, RANDOM:20:80, REG:1
Modbus TCP/IP Ethernet<IP>.Unit، مثل <192.168.1.10>.140001 سجل احتفاظ، 30001 سجل دخل، 00001 ملف لولبي (coil)، 10001 دخل منفصل، 40001.3 بت، 40010.16H نص
Modbus RTU Serial, Modbus ASCII Serialعنوان التابع 1–247مثل Modbus TCP
Siemens S7 TCP/IP<IP>.Rack.Slot، مثل <192.168.0.1>.0.1DB1.DBD4, DB1.DBW2, DB1.DBB0, DB1.DBX0.3, MW10, I0.0, Q0.0
OMRON FINS Ethernet<IP>.Node، مثل <192.168.1.10>.1D100, D0.05, CIO10, W5.00, H2, A3, E100
OMRON NJ Ethernet<IP>PumpState, Line1.Valve[3], Matrix[1,2], Counter.5
MQTT Clientالوسيط host:port (يُتجاهل إذا حددت القناة وسيطًا)sensors/temp, sensors/pump1:/flow, plant/csv;idx=2;sep=;
DNP Client Ethernetعنوان IP للمحطة الفرعيةAI0, BI5, CTR2, AO1, BO3, 30.1.51.Value
IEC 60870-5-104 Clientعنوان IP لـ RTU100, IOA100, M_ME_NC.100.VALUE, C_SC_NA.3000.DIRECTVALUE
IEC 61850 MMS Clientعنوان IP لـ IEDLD0/MMXU1.MX.TotW.mag.f, LD0/XCBR1.ST.Pos.stVal
OPC UA Clientغير مستخدم (نقطة النهاية إعداد على مستوى القناة)ns=2;s=Channel.Device.Tag, ns=2;i=1001

مفاتيح الإعدادات الأكثر استخدامًا:

  • Modbus TCP (الجهاز): modbus_ethernet.DEVICE_ETHERNET_PORT_NUMBER (502)، modbus_ethernet.DEVICE_ZERO_BASED_ADDRESSING، modbus_ethernet.DEVICE_FIRST_WORD_LOW (ترتيب الكلمات للقيم 32 بت)، modbus_ethernet.DEVICE_HOLDING_REGISTERS (حجم الكتلة، 1–125).
  • Modbus RTU/ASCII (الجهاز): servermain.DEVICE_ETHERNET_COMMUNICATIONS_IP وservermain.DEVICE_ETHERNET_COMMUNICATIONS_PORT (الخادم التسلسلي)، إضافةً إلى مفاتيح modbus.DEVICE_….
  • Siemens S7 (الجهاز): siemens_tcpip_ethernet.DEVICE_COMMUNICATIONS_PORT_NUMBER (102)، siemens_tcpip_ethernet.DEVICE_S7_COMMUNICATIONS_CPU_RACK، …_CPU_SLOT، وللطراز servermain.DEVICE_MODEL (0 S7-200، 1 S7-300، 2 S7-400، 3 S7-1200، 4 S7-1500).
  • OMRON FINS: على القناة omron_fins_ethernet.CHANNEL_PORT_NUMBER (9600)؛ وعلى الجهاز omron_fins_ethernet.DEVICE_PROTOCOL (0 UDP، 1 TCP) وأرقام العقد.
  • MQTT (القناة): mqtt.BROKER_HOST, mqtt.PORT, mqtt.USERNAME, mqtt.PASSWORD, mqtt.QOS, mqtt.TRANSPORT.
  • عميل OPC UA (القناة): opcuaclient.CHANNEL_UA_SERVER_ENDPOINT_URL.

الإعداد الذي تتركه يأخذ القيمة الافتراضية للمشغّل. جميع مفاتيح إعدادات المشغّل مع شرحها موجودة في القسم guide.drivers في أي حزمة مُصدَّرة بذلك المشغّل.

الوسوم المحسوبة

تعرّف المصفوفة derived وسومًا محسوبة من وسوم أخرى. بعد التثبيت يكون مسارها _AdvancedTags.<name>؛ وتستخدم الشاشات والإنذارات هذا المسار.

"derived": [
  {
    "name": "Meter1_ApparentPower",
    "type": "Derived",
    "expression": "ROUND({Energy.Meter1.VoltageL1} * {Energy.Meter1.CurrentL1} / 1000, 2)",
    "scanRateMs": 1000,
    "description": "Apparent power (kVA)"
  }
]
الحقلالوصف
nameالاسم؛ فريد على مستوى الخادم — ابدأه باسم الجهاز (<Device>_…)
typeDerived (تعبير)، Totalizer, Average, Maximum, Minimum
expressionللنوع Derived التعبير؛ وللبقية مسار الوسم المصدر (دون أقواس معقوفة)
sampleSizeعدد العينات للمتوسط / الحد الأقصى / الحد الأدنى (الافتراضي 10)
scanRateMsمعدل التحديث (ms، الافتراضي 1000)
enabledالافتراضي true
descriptionالوصف
dataTypeرمز نوع بيانات النتيجة على الخادم (الافتراضي 9 = Double)؛ يُتجاهل على الهاتف

يجمع Totalizer القيمة × الثواني؛ وبالنسبة لدخل m³/h اقسم النتيجة على 3600.

مرجع الدوال

في التعبير يُكتب مرجع الوسم {Channel.Device.Tag} (ومع مجموعة {Channel.Device.Group.Tag}). العوامل: + - * / %، والمقارنات < و<= و> و>= و== و!= (1 إن كانت صحيحة، 0 إن كانت خاطئة)، والمنطق && و|| و! والأقواس. الفاصل العشري هو دائمًا نقطة (1.5). أسماء الدوال غير حساسة لحالة الأحرف؛ والدوال التي لا تأخذ وسائط تحتاج مع ذلك إلى أقواس (PI()). الحد الأقصى للتعبير 8000 حرف. قائمة الدوال متطابقة على الخادم والهاتف.

الدالةالوصف
ABS(x)القيمة المطلقة
SQRT(x)الجذر التربيعي (0 للمدخل السالب)
POW(x, y)x أس y
EXP(x), LN(x)e أس x، واللوغاريتم الطبيعي
LOG(x), LOG(x, base)اللوغاريتم بالأساس 10 أو بأساس محدد
ROUND(x), ROUND(x, digits)التقريب (النصف بعيدًا عن الصفر؛ 0–15 خانة)
FLOOR(x), CEIL(x)التقريب للأسفل / للأعلى
MOD(a, b)الباقي (0 إذا كان b = 0)
SIGN(x)الإشارة: −1, 0, 1
MIN(a, b, …), MAX(a, b, …)الأصغر / الأكبر
AVG(a, b, …), SUM(a, b, …)المتوسط / المجموع
IF(cond, a, b)a إذا كان cond غير صفري، وإلا b
CLAMP(x, low, high)التقييد ضمن نطاق
MAP(x, inLow, inHigh, outLow, outHigh)تحجيم خطي
LERP(a, b, t)استيفاء خطي بين a و b
POLY(x, c0, c1, c2, …)كثير حدود: c0 + c1·x + c2·x² + …
HYPOT(a, b)√(a² + b²)
SIN, COS, TAN, ASIN, ACOS, ATANحساب المثلثات (راديان)
ATAN2(y, x)ظل التمام العكسي بمعاملين
SINH, COSH, TANHالدوال الزائدية
DEG(x), RAD(x)من الراديان إلى الدرجات، ومن الدرجات إلى الراديان
PI(), E()الثوابت
RANDOM(), RANDOM(high), RANDOM(low, high), RND(…)رقم عشوائي؛ للاختبار فقط

أمثلة: ({C.D.A} + {C.D.B}) / 2، IF({C.D.Pressure} > 6, 1, 0)، MAX({C.D.Level} - {C.D.Static}, 0)، MAP({C.D.Raw}, 4, 20, 0, 10).

الإنذارات

"alarms": [
  { "name": "High voltage L1", "tag": "Energy.Meter1.VoltageL1", "conditionType": "Hi", "limit": 250,
    "deadband": 2, "severity": 700, "message": "Phase 1 voltage above 250 V", "enabled": true }
]
الحقلالافتراضيالوصف
name—اسم الإنذار
tag—المسار الكامل لوسم في الحزمة، أو _AdvancedTags.<name> (مطلوب، ويجب أن يوجد في الحزمة)
conditionType—HiHi, Hi, Lo, LoLo, DevHi, DevLo (انحراف)، RocHi, RocLo (معدل التغيّر، وحدات/ثانية)
limit—الحد
setpoint0نقطة الضبط لإنذارات الانحراف
deadbandType, deadbandAbsolute, 0النطاق الميت: None, Absolute, Percent
rangeLow, rangeHigh0, 100النطاق للنطاق الميت بالنسبة المئوية
onDelaySec, offDelaySec0تأخير التفعيل والإيقاف (s)
severity5001–1000؛ 800 فما فوق حرج
message, area—الرسالة والمنطقة
enabledtrueمفعّل

الشاشات

للشاشات البنية نفسها المستخدمة في شاشات SCADA على الخادم. تتألف الشاشة من كائنات (widgets) موضوعة في فضاء إحداثيات (width × height).

الحقلالوصف
idفريد داخل الحزمة (مطلوب)؛ يُجدَّد عند التثبيت وتُنقل الروابط
nameاسم الشاشة؛ وإذا احتوى على اسم الجهاز فإنه يُعاد تسميته عند التثبيت
target"server" (يُثبَّت على الخادم فقط)، أو "phone" (في وضع الهاتف فقط)، أو غائب (في الاثنين)
parentIdid الشاشة الأم؛ فارغ للشاشة الرئيسية
orderالترتيب بين الشاشات الفرعية
width, heightفضاء الإحداثيات؛ الهاتف بالوضع الرأسي 400 × 700 (أطول للشاشات الطويلة)، والخادم مثلًا 1200 × 700
backgroundلون الخلفية (#eef2f7)؛ في شاشات الهاتف اتركه فارغًا ليتبع السمة
group, zoneIdمجموعة الشاشة والمنطقة على الخادم؛ اتركهما فارغين في القوالب
widgetsالكائنات

مجموعتان من الشاشات

تحمل حزمة الجهاز الجيدة مجموعتين:

  • مجموعة الخادم ("target": "server") — شاشة رئيسية واحدة (parentId فارغ) تحتها شاشات الإعدادات (parentId = id الشاشة الرئيسية). في واجهة الويب تظهر الشاشة الرئيسية في القائمة وشاشات الإعدادات في فرعها. ضع أزرارًا (nav) من الشاشة الرئيسية إلى شاشات الإعدادات وبالعكس.
  • مجموعة الهاتف ("target": "phone") — شاشة Summary رأسية (القياسات وعناصر التحكم وأزرار إلى شاشات الإعدادات) مع شاشات إعدادات بعمود واحد كشاشات فرعية لها. في وضع الهاتف يظهر شريط تبويبات في الأعلى يضم Summary والشاشات الفرعية. سمِّ الشاشات <Device> — Summary و<Device> — Settings؛ وتعرض التبويبات الجزء الذي يلي "—".

عند التثبيت تُثبَّت المجموعة المطابقة للهدف فقط. الشاشة التي تنتمي أمها إلى المجموعة الأخرى تصبح شاشة رئيسية؛ وتُزال روابط nav إلى المجموعة الأخرى. الشاشة التي لا تحمل target تُثبَّت في الموضعين.

الكائنات

{ "id": "w2", "type": "display", "x": 24, "y": 80, "w": 220, "h": 80,
  "tag": "Energy.Meter1.VoltageL1", "props": { "label": "Voltage L1", "units": "V", "decimals": 1 } }
الحقلالوصف
idفريد داخل الحزمة (مثل w1 وw2 …)
typeنوع الكائن (أدناه)
x, y, w, hالموضع والحجم (بإحداثيات الشاشة)
rotالدوران (درجات)
tagمسار الوسم المربوط: Channel.Device.Tag أو _AdvancedTags.<name>
propsخصائص تعتمد على النوع
animsقواعد شرطية
onClick, navللانتقال إلى شاشة أخرى عند اللمس: "onClick": "nav" و"nav": "<screen id>"
popupScreenشاشة تُعرض كنافذة منبثقة (الخادم)
النوعوظيفتهprops الرئيسية
displayعرض قيمةlabel, units, decimals, color, fontSize
labelنص ثابت (بلا وسم)text, fontSize, color, align
lampمصباحlabel, onColor, offColor, onText, offText, blinkOn, onOp/onA/onB
buttonيكتب onValue/offValue عند الضغطlabel, onValue, offValue, onText, offText, onColor, offColor
switchمفتاح (يكتب مثل الزر)label, onValue, offValue, onText, offText, onColor
radioزر خيارlabel, onValue, offValue
inputإدخال قيمة (وسم قابل للكتابة)label, decimals
sfieldصف إعداد: تسمية + قيمة (+ وحدة)label, units, decimals, editable, step
gaugeمقياس بقرصlabel, min, max, units, decimals, fillColor
tank, levelbarمستوى الخزان، شريط المستوىlabel, min, max, units, decimals, fillColor
pump, motor, fan, valveأيقونات الآلات (تدور / يتغير لونها عند التشغيل)label, onColor, offColor, onText, offText, spin, blinkOn, onOp/onA/onB
pipeأنبوب؛ يتلوّن عند التدفقthickness, flowColor, onOp/onA
rectلوحة / مستطيل (بلا وسم)fill, stroke, radius
imageصورة (بلا وسم)src (data URI أو عنوان)
svgكائن من مكتبة الرموزlib2 (معرّف الرمز)، label, onOp/onA/onB, onColor, offColor

حالة التشغيل. بالنسبة للمصابيح والآلات والرموز، يُحدَّد متى يُعدّ الكائن "قيد التشغيل" بواسطة onOp (gt, ge, eq, ne, lt, le, between) وonA وonB؛ وبدونها يكون الكائن قيد التشغيل عندما تكون القيمة أكبر من 0.5.

القواعد الشرطية (anims): { "kind": "color", "tag": "", "op": "gt", "a": 80, "b": null, "p2": "#ef4444" }. قيم kind: color (يضبط اللون على p2)، blink، visible (يُخفي الكائن ما دام الشرط صحيحًا)، level (التعبئة: a الحد الأدنى، b الحد الأقصى، p2 اللون، op always). الوسم tag الفارغ يعني وسم الكائن نفسه.

الرموز. الحقل lib2 في كائن svg هو معرّف من مكتبة الرموز المدمجة (مثل en-pumps/en_pump_submersible_1 وen-meters/en_flowmeter_1 وpumps_centrifugal_pump_4). القائمة الكاملة للمعرّفات في القسم guide.symbols من الحزم المُصدَّرة.

يمكن لشاشات الخادم أيضًا استخدام أنواع الكائنات الأخرى في محرر SCADA على الويب؛ ويعرضها الهاتف كمربعات باهتة ويعطي الفحص تحذيرًا. وللشاشات التي يجب أن تعمل في الموضعين، استخدم الأنواع المذكورة في الجدول.

التسمية وإعادة التسمية عند التثبيت

  • أسماء القنوات والأجهزة والمجموعات والوسوم لا تحتوي على نقاط (.)؛ فالنقطة هي فاصل المسار. يجب أن تكون الأسماء فريدة على مستواها (دون حساسية لحالة الأحرف).
  • مسار الوسم هو Channel.Device.Tag (وفي مجموعة Channel.Device.Group.Tag). تستخدم الشاشات والإنذارات والتعبيرات دائمًا المسار الكامل.
  • اسم الجهاز فريد داخل قناته فقط؛ ويمكن تثبيت الحزمة نفسها في القناة نفسها مرات عديدة بأسماء أجهزة مختلفة.
  • أسماء الوسوم المحسوبة فريدة على مستوى الخادم. ابدأ اسم كل وسم محسوب باسم الجهاز: Meter1_ApparentPower. وعندما يتغير اسم الجهاز عند التثبيت تتغير البادئة أيضًا (Meter2_ApparentPower)، فيمكن تثبيت الحزمة نفسها مرة ثانية دون تعارض.

إذا غيّر المستخدم اسم القناة والجهاز عند التثبيت، تُحدَّث الحزمة كما يلي:

  1. تنتقل جميع المسارات التي تبدأ بـ Channel.Device (tag الكائنات على الشاشات، والقواعد، وtag الإنذارات، ومراجع {…} في التعبيرات) إلى الاسم الجديد.
  2. تُعاد تسمية الوسوم المحسوبة التي يبدأ اسمها بـ <OldDevice>_ إلى <NewDevice>_، وتنتقل معها مراجع _AdvancedTags.….
  3. يُستبدل اسم الجهاز القديم في أسماء الشاشات وفي text الخاص بكائنات label (ككلمة كاملة، إذا كان طوله 3 أحرف على الأقل) بالاسم الجديد.

التعارضات التي يتحقق منها التثبيت:

  • إذا كان اسم القناة مستخدمًا على الهدف مع مشغّل آخر، يُمنع التثبيت؛ وإذا كان مستخدمًا مع المشغّل نفسه، يُضاف الجهاز إلى القناة الموجودة.
  • إذا وُجد جهاز بالاسم نفسه في القناة، يُمنع التثبيت؛ ويقترح التطبيق أول اسم مرقّم شاغر (Meter1 ← Meter2).
  • إذا كان اسم وسم محسوب موجودًا بالفعل على الهدف، يُمنع التثبيت؛ ويحل اسم جهاز مختلف المشكلة.

التحقق والأخطاء الشائعة

يفحص MergenHub Mobile الحزمة قبل تثبيتها؛ وتُدرج المشكلات على بطاقة التثبيت. أما Import from file في واجهة الويب فيفحص المعاملات والأسماء والتعارضات لكنه لا يتحقق من العناوين مقابل المشغّل، لذا من الممارسات الجيدة تجربة الحزمة الجديدة على الهاتف أولًا.

الأخطاء (يُمنع التثبيت):

  • Bu bir MergenHub paketi değil (ليست حزمة MergenHub) — الحقل format مفقود أو خاطئ.
  • JSON hatası (satır …, sütun …) (خطأ JSON في السطر والعمود) — خطأ في الصياغة؛ يُعرض الموضع والنص المحيط.
  • Bilinmeyen sürücü "…" (مشغّل غير معروف) — اكتب الاسم الكامل للمشغّل في driver (مثل Modbus TCP/IP Ethernet).
  • Adres geçersiz (…) (عنوان غير صالح) — العنوان لا يطابق صياغة المشغّل؛ وتوضح الرسالة السبب (مثلًا في Modbus يجب أن يكون رقم المنطقة 0 أو 1 أو 3 أو 4).
  • Bilinmeyen veri tipi "…" (نوع بيانات غير معروف) — تُكتب أسماء الأنواع كما في القائمة أعلاه (Float وليس float32).
  • access "read" ya da "readwrite" olmalı (يجب أن يكون access هو read أو readwrite).
  • … adı tekrar ediyor (اسم مكرر)، … adında nokta olamaz (الاسم يحتوي على نقطة)، … adı boş (اسم فارغ).
  • Alarm …: Tag bulunamadı (الوسم غير موجود) — وسم الإنذار غير موجود في الحزمة.
  • Geçersiz parametre anahtarı (مفتاح معامل غير صالح) — يحتوي المفتاح على أحرف غير الحروف والأرقام و_.
  • {{…}} için değer girilmedi (لم تُدخل قيمة لعنصر نائب) — العنصر النائب ليس له معامل أو أن القيمة فارغة.

التحذيرات (يستمر التثبيت، لكن ألقِ نظرة):

  • Paket içinde olmayan tag'e bağlı (مرتبط بوسم غير موجود في الحزمة) — كائن شاشة أو قاعدة أو تعبير يستخدم مسارًا غير موجود في الحزمة؛ وغالبًا ما يكون خطأً مطبعيًا.
  • Gidilecek ekran pakette yok (الشاشة الهدف غير موجودة في الحزمة) — nav لا يطابق أي id لشاشة.
  • Bu uygulamanın tanımadığı nesne tipi (نوع كائن لا يعرفه هذا التطبيق) — لا يستطيع الهاتف رسمه؛ وقد يعمل على الخادم.
  • Sembol kütüphanede yok (الرمز غير موجود في المكتبة) — معرّف lib2 خاطئ.

يُجري الخادم تصريف التعبيرات عند التثبيت؛ والتعبير المعطوب (دالة غير معروفة، أو عدد وسائط خاطئ، أو فاصلة عشرية مثل 1,5) يُدرج على أنه "غير مثبّت" في النتيجة، وتُثبَّت الأجزاء الأخرى.

يتسامح التطبيق مع التعليقات // و/* */ والفواصل الزائدة في النهاية، لكن واجهة الويب لا تقبل التعليقات. اكتب الحزم بصيغة JSON عادية صالحة دون تعليقات.

مثال كامل

عدّاد طاقة واحد بـ Modbus TCP: ستة وسوم (واحد محجَّم واثنان قابلان للكتابة)، ووسم محسوب واحد، وإنذار واحد، وشاشة رئيسية وشاشة إعدادات في مجموعة الخادم، وشاشة Summary وشاشة إعدادات في مجموعة الهاتف. تجتاز هذه الحزمة فحص MergenHub Mobile دون أخطاء ودون تحذيرات.

{
  "format": "mergenhub-package",
  "formatVersion": 1,
  "kind": "template",
  "meta": {
    "name": "Example EA-100 Energy Meter",
    "description": "Single-phase energy metering, relay output and CT ratio setting.",
    "vendor": "Example",
    "model": "EA-100",
    "version": "1.0",
    "author": "Envest",
    "keywords": ["energy", "meter", "Modbus TCP"]
  },
  "parameters": [
    { "key": "ip", "label": "IP address", "type": "text", "required": true, "placeholder": "192.168.1.50", "hint": "Address of the meter on the network" },
    { "key": "port", "label": "Port", "type": "number", "default": 502, "group": "Connection" },
    { "key": "unit", "label": "Unit ID", "type": "number", "default": 1, "group": "Connection" }
  ],
  "channels": [
    {
      "name": "Energy",
      "driver": "Modbus TCP/IP Ethernet",
      "devices": [
        {
          "name": "Meter1",
          "id": "<{{ip}}>.{{unit}}",
          "scanMs": 1000,
          "timeouts": { "connectS": 3, "requestMs": 1000, "retries": 3 },
          "settings": { "modbus_ethernet.DEVICE_ETHERNET_PORT_NUMBER": "{{port}}" },
          "tags": [
            { "name": "VoltageL1", "address": "30001", "type": "Float", "access": "read", "scanMs": 1000, "units": "V" },
            { "name": "CurrentL1", "address": "30003", "type": "Float", "access": "read", "scanMs": 1000, "units": "A" },
            { "name": "ActivePower", "address": "30005", "type": "Float", "access": "read", "scanMs": 1000, "units": "kW" },
            { "name": "TotalEnergy", "address": "30007", "type": "DWord", "access": "read", "scanMs": 5000,
              "scaling": { "type": "linear", "rawLow": 0, "rawHigh": 10, "low": 0, "high": 1, "resultType": "Double", "units": "kWh" } },
            { "name": "RelayOutput", "address": "00001", "type": "Boolean", "access": "readwrite", "scanMs": 1000, "description": "Relay output (1 = energised)" },
            { "name": "CtRatio", "address": "40001", "type": "Word", "access": "readwrite", "scanMs": 5000, "description": "Current transformer ratio (e.g. 100 = 100/5 A)" }
          ]
        }
      ]
    }
  ],
  "derived": [
    {
      "name": "Meter1_ApparentPower",
      "type": "Derived",
      "expression": "ROUND({Energy.Meter1.VoltageL1} * {Energy.Meter1.CurrentL1} / 1000, 2)",
      "scanRateMs": 1000,
      "description": "Apparent power (kVA) = voltage × current / 1000"
    }
  ],
  "alarms": [
    {
      "name": "High voltage L1",
      "tag": "Energy.Meter1.VoltageL1",
      "conditionType": "Hi",
      "limit": 250,
      "deadband": 2,
      "severity": 700,
      "message": "Phase 1 voltage above 250 V",
      "enabled": true
    }
  ],
  "screens": [
    {
      "id": "ea100-main", "name": "Meter1 — Energy Meter", "target": "server", "parentId": "", "order": 0,
      "width": 1200, "height": 700, "background": "#eef2f7",
      "widgets": [
        { "id": "w1", "type": "label", "x": 24, "y": 16, "w": 700, "h": 40, "props": { "text": "ENERGY METER — Meter1", "fontSize": 24, "color": "#0f172a" } },
        { "id": "w2", "type": "display", "x": 24, "y": 80, "w": 220, "h": 80, "tag": "Energy.Meter1.VoltageL1", "props": { "label": "Voltage L1", "units": "V", "decimals": 1 } },
        { "id": "w3", "type": "display", "x": 264, "y": 80, "w": 220, "h": 80, "tag": "Energy.Meter1.CurrentL1", "props": { "label": "Current L1", "units": "A", "decimals": 2 } },
        { "id": "w4", "type": "display", "x": 504, "y": 80, "w": 220, "h": 80, "tag": "Energy.Meter1.ActivePower", "props": { "label": "Active power", "units": "kW", "decimals": 2 } },
        { "id": "w5", "type": "display", "x": 744, "y": 80, "w": 220, "h": 80, "tag": "Energy.Meter1.TotalEnergy", "props": { "label": "Total energy", "units": "kWh", "decimals": 1 } },
        { "id": "w6", "type": "gauge", "x": 24, "y": 180, "w": 240, "h": 220, "tag": "_AdvancedTags.Meter1_ApparentPower", "props": { "label": "Apparent power", "min": 0, "max": 50, "units": "kVA", "decimals": 2 } },
        { "id": "w7", "type": "switch", "x": 284, "y": 180, "w": 200, "h": 70, "tag": "Energy.Meter1.RelayOutput", "props": { "label": "Relay", "onValue": 1, "offValue": 0, "onText": "ON", "offText": "OFF", "onColor": "#22c55e" } },
        { "id": "w8", "type": "rect", "x": 24, "y": 620, "w": 200, "h": 56, "props": { "fill": "#1d4ed8", "stroke": "#1d4ed8", "radius": 10 }, "onClick": "nav", "nav": "ea100-settings" },
        { "id": "w9", "type": "label", "x": 24, "y": 620, "w": 200, "h": 56, "props": { "text": "Settings", "fontSize": 16, "color": "#ffffff" }, "onClick": "nav", "nav": "ea100-settings" }
      ]
    },
    {
      "id": "ea100-settings", "name": "Meter1 — Settings", "target": "server", "parentId": "ea100-main", "order": 1,
      "width": 1200, "height": 700, "background": "#eef2f7",
      "widgets": [
        { "id": "w10", "type": "label", "x": 24, "y": 16, "w": 700, "h": 40, "props": { "text": "SETTINGS — Meter1", "fontSize": 24, "color": "#0f172a" } },
        { "id": "w11", "type": "sfield", "x": 24, "y": 80, "w": 520, "h": 44, "tag": "Energy.Meter1.CtRatio", "props": { "label": "CT ratio", "decimals": 0, "editable": true, "step": 5 } },
        { "id": "w12", "type": "rect", "x": 24, "y": 620, "w": 200, "h": 56, "props": { "fill": "#1d4ed8", "stroke": "#1d4ed8", "radius": 10 }, "onClick": "nav", "nav": "ea100-main" },
        { "id": "w13", "type": "label", "x": 24, "y": 620, "w": 200, "h": 56, "props": { "text": "‹ Main screen", "fontSize": 16, "color": "#ffffff" }, "onClick": "nav", "nav": "ea100-main" }
      ]
    },
    {
      "id": "ea100-phone", "name": "Meter1 — Summary", "target": "phone", "parentId": "", "order": 0,
      "width": 400, "height": 700, "background": "",
      "widgets": [
        { "id": "w14", "type": "rect", "x": 0, "y": 0, "w": 400, "h": 64, "props": { "fill": "#1d4ed8", "stroke": "#1d4ed8", "radius": 0 } },
        { "id": "w15", "type": "label", "x": 14, "y": 8, "w": 372, "h": 48, "props": { "text": "Energy Meter", "fontSize": 18, "color": "#ffffff", "align": "left" } },
        { "id": "w16", "type": "display", "x": 8, "y": 76, "w": 188, "h": 62, "tag": "Energy.Meter1.VoltageL1", "props": { "label": "Voltage L1", "units": "V", "decimals": 1 } },
        { "id": "w17", "type": "display", "x": 204, "y": 76, "w": 188, "h": 62, "tag": "Energy.Meter1.CurrentL1", "props": { "label": "Current L1", "units": "A", "decimals": 2 } },
        { "id": "w18", "type": "display", "x": 8, "y": 146, "w": 188, "h": 62, "tag": "Energy.Meter1.ActivePower", "props": { "label": "Active power", "units": "kW", "decimals": 2 } },
        { "id": "w19", "type": "display", "x": 204, "y": 146, "w": 188, "h": 62, "tag": "Energy.Meter1.TotalEnergy", "props": { "label": "Total energy", "units": "kWh", "decimals": 1 } },
        { "id": "w20", "type": "gauge", "x": 106, "y": 220, "w": 188, "h": 178, "tag": "_AdvancedTags.Meter1_ApparentPower", "props": { "label": "Apparent power", "min": 0, "max": 50, "units": "kVA", "decimals": 2 } },
        { "id": "w21", "type": "switch", "x": 8, "y": 410, "w": 384, "h": 58, "tag": "Energy.Meter1.RelayOutput", "props": { "label": "Relay", "onValue": 1, "offValue": 0, "onText": "ON", "offText": "OFF", "onColor": "#22c55e" } },
        { "id": "w22", "type": "rect", "x": 8, "y": 480, "w": 188, "h": 48, "props": { "fill": "#1d4ed8", "stroke": "#1d4ed8", "radius": 10 }, "onClick": "nav", "nav": "ea100-phone-settings" },
        { "id": "w23", "type": "label", "x": 8, "y": 480, "w": 188, "h": 48, "props": { "text": "Settings", "fontSize": 14, "color": "#ffffff" }, "onClick": "nav", "nav": "ea100-phone-settings" }
      ]
    },
    {
      "id": "ea100-phone-settings", "name": "Meter1 — Settings", "target": "phone", "parentId": "ea100-phone", "order": 1,
      "width": 400, "height": 700, "background": "",
      "widgets": [
        { "id": "w24", "type": "label", "x": 12, "y": 12, "w": 376, "h": 30, "props": { "text": "CURRENT TRANSFORMER", "fontSize": 13, "color": "#3b82f6", "align": "left" } },
        { "id": "w25", "type": "sfield", "x": 8, "y": 48, "w": 384, "h": 44, "tag": "Energy.Meter1.CtRatio", "props": { "label": "CT ratio", "decimals": 0, "editable": true, "step": 5 } }
      ]
    }
  ],
  "notes": "# Example EA-100\n\nReads voltage, current, active power and total energy; the relay output and the CT ratio are writable. The energy counter has 0.1 kWh resolution (raw value / 10)."
}

إذا ثبّتَّ هذه الحزمة باسم الجهاز Meter2، تصبح مسارات الوسوم Energy.Meter2.…، والوسم المحسوب Meter2_ApparentPower، وأسماء الشاشات Meter2 — ….

العمل مع مساعد ذكاء اصطناعي

صُمّم تنسيق الحزمة ليقرأه ويكتبه مساعدو الذكاء الاصطناعي. يمكنك تزويد المساعد بخريطة سجلات الجهاز أو دليله أو ورقة بياناته ليُعدّ لك الحزمة.

نزّل مهارة قالب جهاز MergenHub (zip). تحتوي على:

  • SKILL.md — سير العمل والقواعد الصارمة التي يتبعها المساعد.
  • reference/format.md — مرجع موجز لكل حقل.
  • reference/drivers.md — أسماء المشغّلات وتنسيقات معرّف الجهاز وصياغة العناوين.
  • reference/expressions.md — دوال التعبيرات.
  • examples/minimal-modbus.mhpkg.json — مثال كامل يجتاز الفحص.

ارفع ملف zip كمهارة في تطبيق Claude، أو فك ضغطه في ~/.claude/skills/ لاستخدامه مع Claude Code؛ وفي حال مساعد لا يدعم المهارات، أرفق الملفات بالمحادثة. ثم اطلب مثلًا: "Build a MergenHub template for this energy meter from the attached register table; ask for IP, port and unit ID at installation; add an alarm at 250 V on the voltage."

افتح ملف المساعد أولًا في MergenHub Mobile عبر Cihaz ekle › Dosya, pano, QR ya da adres › Panodan yapıştır (اللصق من الحافظة) وانظر إلى نتيجة الفحص؛ ثم ثبّته على الخادم.

إدراج جهاز في المكتبة الرسمية

لإضافة جهاز إلى Device Library، أرسل طلبًا من لوحة العميل على الموقع: Panel › Device requests › New request. يفتح الرابط Ekleme isteği gönderin أسفل قائمة المكتبة في MergenHub Mobile ومربع حوار المكتبة في واجهة الويب الصفحة نفسها.

يطلب النموذج العلامة التجارية والطراز وإصدار البرنامج الثابت والفئة وبروتوكول الاتصال وصفحة المنتج وما يفعله الجهاز والبيانات التي تريد مراقبتها وتفاصيل الاتصال. يمكنك إرفاق ما يصل إلى خمسة ملفات (10 MB لكل منها): صورة، وخريطة السجلات، ودليل — وحزمة .mhpkg.json التي أعددتها.

لا تُنشر الطلبات تلقائيًا أبدًا. يتحقق فريق Envest من الجهاز والوثائق، وقد يطلب منك تفاصيل، ويُعدّ الحزمة (الوسوم والشاشات) ويختبرها ويضيفها إلى المكتبة بنفسه. وتظهر حالة الطلب (مستلم، قيد المراجعة، موافق عليه — قيد الإعداد، منشور، أو غير مقبول) وملاحظة الفريق في اللوحة؛ كما يُرسل القرار بالبريد الإلكتروني. يمكن للشركة أن يكون لديها عشرة طلبات معلقة كحد أقصى في آنٍ واحد.