MergenHub Envest
الرئيسية/المستندات/دليل المستخدم (داخل التطبيق، كامل)

مرجع خصائص JSON

المفاتيح المشتركة (common.*)

حقول مشتركة في متن كل كائن (قناة/جهاز/وسم). تطابق أسماء الخصائص المعيار الصناعي حرفياً (للتشغيل البيني).

common.ALLTYPES_NAMEاسم الكائن (إلزامي). اسم القناة/الجهاز/الوسم.
common.ALLTYPES_DESCRIPTIONالوصف (اختياري).
PROJECT_IDختم التزامن المتفائل. يُرجَع في كل استجابة GET ويُرسَل مجدداً في PUT. عند عدم التطابق يُرجَع 409.
FORCE_UPDATEtrue → يُتجاوز فحص PROJECT_ID (كتابة قسرية). تستخدمه العملاء من نوع DataExchanger.
ملاحظة إن servermain.CHANNEL_UNIQUE_ID وservermain.DEVICE_UNIQUE_ID وservermain.DEVICE_CHANNEL_ASSIGNMENT وPROJECT_ID يديرها الخادم (للقراءة فقط) — حتى لو أرسلتها في POST/PUT فإن الخادم هو من يحدد قيمتها.

خصائص القناة

servermain.MULTIPLE_TYPES_DEVICE_DRIVERاسم المشغّل (راجع أسماء المشغّلات). مرة واحدة لكل قناة.
servermain.CHANNEL_UNIQUE_IDمعرّف فريد تلقائي (للقراءة فقط).
servermain.CHANNEL_WRITE_OPTIMIZATIONS_METHODطريقة تحسين الكتابة (إسقاط المكرر / كتابة الأحدث).
servermain.CHANNEL_WRITE_OPTIMIZATIONS_DUTY_CYCLEالحد الأقصى لعدد عمليات الكتابة في كل دورة.
servermain.CHANNEL_NON_NORMALIZED_FLOATING_POINT_HANDLINGمعالجة قيم NaN/Inf العشرية (مثلاً التصفير).

مثال — إنشاء قناة

POST /config/v1/project/channels
{
  "common.ALLTYPES_NAME": "Modbus_1",
  "servermain.MULTIPLE_TYPES_DEVICE_DRIVER": "Modbus TCP/IP Ethernet"
}

خصائص الجهاز

servermain.DEVICE_ID_STRINGعنوان/معرّف الجهاز — خاص بالمشغّل (راجع أسماء المشغّلات).
servermain.DEVICE_MODELالطراز (خاص بالمشغّل؛ مثل S7-1200).
servermain.DEVICE_DATA_COLLECTIONtrue/false — تشغيل/إيقاف مسح الجهاز.
servermain.DEVICE_SIMULATEDtrue → بيانات اصطناعية (دون عتاد).
servermain.DEVICE_SCAN_MODE / ..._RATE_MSوضع المسح + المعدل (ms).
servermain.DEVICE_REQUEST_TIMEOUT_MILLISECONDSمهلة الطلب (ms).
servermain.DEVICE_RETRY_ATTEMPTSعدد المحاولات قبل انتهاء المهلة (الاتصال+الطلب).
servermain.DEVICE_INTER_REQUEST_DELAY_MILLISECONDSالتأخير بين الطلبات (ms).
servermain.DEVICE_AUTO_DEMOTION_*التراجع عند الفشل: ENABLE / DEMOTE_AFTER_SUCCESSIVE_TIMEOUTS / PERIOD_MS / DISCARD_WRITES.
servermain.DEVICE_TAG_GENERATION_*التوليد التلقائي للوسوم: ON_STARTUP / DUPLICATE_HANDLING / GROUP / ALLOW_SUB_GROUPS.

مثال — إنشاء جهاز

POST /config/v1/project/channels/Modbus_1/devices
{
  "common.ALLTYPES_NAME": "1001",
  "servermain.MULTIPLE_TYPES_DEVICE_DRIVER": "Modbus TCP/IP Ethernet",
  "servermain.DEVICE_ID_STRING": "192.168.1.50.1",
  "servermain.DEVICE_DATA_COLLECTION": true,
  "servermain.DEVICE_REQUEST_TIMEOUT_MILLISECONDS": 1000,
  "servermain.DEVICE_RETRY_ATTEMPTS": 3
}

خصائص الوسم والتحجيم

servermain.TAG_ADDRESSعنوان الجهاز (خاص بالمشغّل؛ مثل Modbus 400001).
servermain.TAG_DATA_TYPEنوع البيانات (Boolean/Word/Short/DWord/Long/Float/Double/String…).
servermain.TAG_READ_WRITE_ACCESS0 = Read Only، 1 = Read/Write.
servermain.TAG_SCAN_RATE_MILLISECONDSمعدل مسح الوسم (ms).
servermain.TAG_SCALING_TYPE0=بلا، 1=خطي، 2=جذر تربيعي…
..._RAW_LOW / _RAW_HIGHالمدى الخام للجهاز.
..._SCALED_LOW / _SCALED_HIGHالمدى الهندسي.
..._SCALED_DATA_TYPE / _CLAMP_LOW / _CLAMP_HIGH / _NEGATE_VALUEالنوع بعد التحجيم، التقييد، عكس الإشارة.

مثال — إضافة وسوم (دفعة، مصفوفة)

POST /config/v1/project/channels/Modbus_1/devices/1001/tags
[
  { "common.ALLTYPES_NAME": "Basinc", "servermain.TAG_ADDRESS": "400001",
    "servermain.TAG_DATA_TYPE": "Float", "servermain.TAG_READ_WRITE_ACCESS": 0 },
  { "common.ALLTYPES_NAME": "Setpoint", "servermain.TAG_ADDRESS": "400010",
    "servermain.TAG_DATA_TYPE": "Float", "servermain.TAG_READ_WRITE_ACCESS": 1 }
]
تحذير لا تعكس قيمة TAG_READ_WRITE_ACCESS: 0=RO، 1=RW. القيمة الخاطئة تجعل نقاط الضبط (setpoint) للقراءة فقط وتمنع الكتابة.

أسماء المشغّلات وDEVICE_ID_STRING

قيم MULTIPLE_TYPES_DEVICE_DRIVER للقناة وDEVICE_ID_STRING للجهاز:

Modbus TCP/IP Ethernet<IP>.unit مثل 192.168.1.50.1؛ بدون unit: <192.168.1.50>
Modbus RTU Serial / Modbus ASCII Serialمنفذ COM + unit (إعدادات القناة التسلسلية).
Siemens S7 TCP/IPIP؛ Rack/Slot في الطراز/المعرّف. مثل 10.0.0.5
OMRON FINS EthernetIP (+ إعدادات FINS SA1/DA1).
OMRON NJ EthernetIP (EtherNet/IP CIP رمزي).
Allen-Bradley ControlLogix EthernetIP,1,slot مثال 192.168.1.10,1,0؛ في Micro800 عنوان IP فقط.
Fatek FBsرقم المحطة (مثال 1)؛ عنوان IP والمنفذ في إعدادات Ethernet للجهاز.
KNXnet/IPلا يلزم معرّف؛ عنوان IP للواجهة والمنفذ (3671) في القناة.
BACnet/IPDevice Instance (مثال 1001)؛ عنوان IP في bacnet.DEVICE_IP_ADDRESS، ويُعثر عليه عبر Who-Is إذا كان فارغًا.
DNP Client EthernetIP:port,masterAddr,slaveAddr
IEC 60870-5-104 ClientIP:2404,commonAddr
IEC 61850 MMS ClientIP:102
MQTT Clientمضيف/منفذ الوسيط (broker).
Simulatorلا يلزم معرّف.

المعالجة الدفعية ورموز الحالة

عند إرسال الوسوم بـ POST على شكل مصفوفة تُعالَج دفعياً (batch). يتحدد رمز حالة HTTP بحسب النتيجة:

201 Createdنجحت جميعها.
207 Multi-Statusجزئي — نجح بعضها وفشل بعضها (النتائج الفردية في المتن).
400 Bad Requestفشلت جميعها. عند إنشاء قناة/جهاز يُرجَع 400 أيضاً إذا امتلأ حد المشغّل (property + شرح).
409 Conflictعدم تطابق PROJECT_ID (يُتجاوز بـ FORCE_UPDATE).
نصيحة الوسوم غير الصالحة تُتخطّى (استيراد متساهل)؛ ويُبلَّغ عن سبب تخطيها في الاستجابة/سجل الأحداث. يمكن استيراد التصديرات الحقيقية (آلاف الوسوم) بطلب واحد.
انظر أيضاًREST APIالصلاحيات