قالب الجهاز (حزمة 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(ملف الحزمة).

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

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

لتغليف مشروع كامل استخدم 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 | الاسم المعروض في النموذج |
type | text (الافتراضي) أو 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 | — | الوصف |
enabled | true | إذا كانت false فلا يُمسح الجهاز |
scanMs | 1000 | معدل مسح الجهاز (ms) |
scanMode | 4 | 0 احترام العميل، 1 ليس أسرع من، 2 معدل ثابت، 3 استعلام عند الطلب، 4 احترام معدل الوسم |
timeouts | 3 / 1000 / 3 | connectS مهلة الاتصال (s)، requestMs مهلة الطلب (ms)، retries محاولات إعادة المحاولة |
settings | افتراضيات المشغّل | إعدادات المشغّل على مستوى الجهاز |
tags, groups | — | الوسوم ومجموعات الوسوم |
الوسم
| الحقل | الافتراضي | الوصف |
|---|---|---|
name | — | اسم الوسم (مطلوب، دون نقاط، فريد داخل الجهاز أو المجموعة) |
address | — | العنوان بصياغة المشغّل (مطلوب) |
type | Default | نوع البيانات (أدناه) |
access | read | read أو readwrite |
scanMs | 1000 | معدل مسح الوسم (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 | رقم الجهاز، مثل 1 | SINE:10:0:100, RAMP:30:0:500, RANDOM:20:80, REG:1 |
Modbus TCP/IP Ethernet | <IP>.Unit، مثل <192.168.1.10>.1 | 40001 سجل احتفاظ، 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.1 | DB1.DBD4, DB1.DBW2, DB1.DBB0, DB1.DBX0.3, MW10, I0.0, Q0.0 |
OMRON FINS Ethernet | <IP>.Node، مثل <192.168.1.10>.1 | D100, 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 لـ RTU | 100, IOA100, M_ME_NC.100.VALUE, C_SC_NA.3000.DIRECTVALUE |
IEC 61850 MMS Client | عنوان IP لـ IED | LD0/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>_…) |
type | Derived (تعبير)، 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 | — | الحد |
setpoint | 0 | نقطة الضبط لإنذارات الانحراف |
deadbandType, deadband | Absolute, 0 | النطاق الميت: None, Absolute, Percent |
rangeLow, rangeHigh | 0, 100 | النطاق للنطاق الميت بالنسبة المئوية |
onDelaySec, offDelaySec | 0 | تأخير التفعيل والإيقاف (s) |
severity | 500 | 1–1000؛ 800 فما فوق حرج |
message, area | — | الرسالة والمنطقة |
enabled | true | مفعّل |
الشاشات
للشاشات البنية نفسها المستخدمة في شاشات SCADA على الخادم. تتألف الشاشة من كائنات (widgets) موضوعة في فضاء إحداثيات (width × height).
| الحقل | الوصف |
|---|---|
id | فريد داخل الحزمة (مطلوب)؛ يُجدَّد عند التثبيت وتُنقل الروابط |
name | اسم الشاشة؛ وإذا احتوى على اسم الجهاز فإنه يُعاد تسميته عند التثبيت |
target | "server" (يُثبَّت على الخادم فقط)، أو "phone" (في وضع الهاتف فقط)، أو غائب (في الاثنين) |
parentId | id الشاشة الأم؛ فارغ للشاشة الرئيسية |
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)، فيمكن تثبيت الحزمة نفسها مرة ثانية دون تعارض.
إذا غيّر المستخدم اسم القناة والجهاز عند التثبيت، تُحدَّث الحزمة كما يلي:
- تنتقل جميع المسارات التي تبدأ بـ
Channel.Device(tagالكائنات على الشاشات، والقواعد، وtagالإنذارات، ومراجع{…}في التعبيرات) إلى الاسم الجديد. - تُعاد تسمية الوسوم المحسوبة التي يبدأ اسمها بـ
<OldDevice>_إلى<NewDevice>_، وتنتقل معها مراجع_AdvancedTags.…. - يُستبدل اسم الجهاز القديم في أسماء الشاشات وفي
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 من الجهاز والوثائق، وقد يطلب منك تفاصيل، ويُعدّ الحزمة (الوسوم والشاشات) ويختبرها ويضيفها إلى المكتبة بنفسه. وتظهر حالة الطلب (مستلم، قيد المراجعة، موافق عليه — قيد الإعداد، منشور، أو غير مقبول) وملاحظة الفريق في اللوحة؛ كما يُرسل القرار بالبريد الإلكتروني. يمكن للشركة أن يكون لديها عشرة طلبات معلقة كحد أقصى في آنٍ واحد.
MergenHub