عدادات إنترنت الأشياء: تسجيل الجهاز وكيفية توقيع قراءاته

أجهزة إنترنت الأشياء: تسجيل صورة AMI أو نقطة نهاية إنترنت الأشياء، ونسخ سرها (يظهر مرة واحدة)، وتدويره باستخدام السر الجديد، وكيفية توقيع الجهاز لكل طلب إلى /api/public/utilities/iot/reads - مع مثال على الطلب، والحدود وكل إجابة يمكن الحصول عليها.

يقوم عداد AMI أو IoT بإرسال قراءاته الخاصة إلى TRANXACT عبر بروتوكول HTTPS. يمتلك كل جهاز مفتاحًا يُنشئه الخادم (utd_ متبوعًا بـ 24 حرفًا ورقمًا) ومفتاحًا سريًا. يُثبت الجهاز هويته في كل طلب، فلا يستطيع أي شخص آخر إرسال قراءات لهذا العداد.

تسجيل جهاز

1. افتح CRM › الأدوات المساعدة › عدادات وقراءات المرافق أجهزة إنترنت الأشياء واضغط على جديد.
2. أدخل تسمية، واختر المقياس الذي يقرأه، واختر التوقيعات مع: hmac (توقيع HMAC-SHA256 لكل طلب - موصى به)، حامل (المفتاح والسر المرسلان كرمز مميز) أو كليهما.
3. حدد عدد القراءات في الدقيقة كحد أقصى لهذا الجهاز، وقم بتعيين البرنامج الثابت إذا كنت تعرفه.
4. احفظ. ستظهر الإجابة المفتاح والسر: "انسخ السر الآن - لن يظهر مرة أخرى". ضع كليهما في إعدادات الجهاز.

تدوير السر

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

كيفية توقيع الجهاز على القراءة

1. قم بإنشاء نص JSON: قائمة بالقراءات، كل منها يحتوي على وقت القراءة (وفقًا لمعيار ISO 8601) ووقت القراءة. البطارية والإشارة والبرنامج الثابت والتنبيهات اختيارية.
2. استخدم وقت يونكس الحالي بالثواني كطابع زمني.
3. احسب قيمة HMAC-SHA256، باستخدام سر الجهاز، للطابع الزمني، ثم نقطة، ثم بايتات نص الرسالة: "<timestamp>.<body>". اكتبها على شكل 64 حرفًا سداسيًا صغيرًا.
4. POST الجسم إلى /api/public/utilities/iot/reads مع الرؤوس X-Utility-Device (المفتاح)، X-Utility-Timestamp و X-Utility-Signature (الرمز السداسي العشري، مسبوق اختياريًا sha256=).

POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

وقد نجحت نفس التوقيعات في سطر الأوامر، لاختبار الجهاز قبل تثبيته:

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

قد يرسل الجهاز المُعدّ لوضع حامل البيانات (أو كليهما) بدلاً من ذلك: Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> بدون أي رؤوس توقيع. يُعدّ HMAC الخيار الأكثر أمانًا: فالسر لا ينتقل أبدًا، ولا يمكن إعادة إرسال الطلب المُلتقط.

الحدود

• يجب أن يكون الطابع الزمني في غضون 5 دقائق من ساعة الخادم: حافظ على ضبط ساعة الجهاز بواسطة NTP.
• يُرفض الطلب الموقّع نفسه مرتين باعتباره إعادة إرسال. تُحتسب القراءة الموجودة مسبقًا في الملف كنسخة مكررة وتُخزّن مرة واحدة.
• بحد أقصى 64 كيلوبايت و500 قراءة لكل طلب، وقراءات الجهاز الخاصة في الدقيقة بحد أقصى، و600 طلب في الدقيقة من عنوان واحد.
• يجب أن يكون الجهاز نشطًا ومتصلًا بجهاز القياس.

ما يحصل عليه الجهاز

الصحة وأجهزة الإنذار

• يقوم كل طلب بتحديث معلومات الجهاز المتعلقة بآخر ظهور له، ونسبة شحن البطارية، وقوة الإشارة بالديسيبل. يؤدي انخفاض مستوى شحن البطارية إلى أقل من 15% إلى ظهور تنبيه "انخفاض مستوى البطارية".
• أنواع الإنذارات التي قد يرسلها الجهاز: انخفاض مستوى البطارية، العبث، التسريب، التدفق العكسي، انقطاع التدفق، انقطاع الاتصال، وغيرها. إنذار واحد مفتوح من كل نوع لكل جهاز.
• يعرض تطبيق Device Alarms قائمةً بها؛ ويغلق تطبيق Clear أحدها مع ملاحظة. يؤدي حدوث تسريب إلى إنشاء طلب خدمة تحقيق في التسريب ذي أولوية عالية؛ كما يؤدي حدوث تنبيه عبث أو تدفق عكسي إلى إنشاء طلب خدمة أيضًا.
• يقوم جهاز قياس إنترنت الأشياء في لوحة المعلومات بالإبلاغ عن رقم (24 ساعة) عن عدد الأجهزة النشطة التي تم تلقي معلومات منها في اليوم الأخير.