کار با ویژگیهای دستگاههای اینترنت اشیا
اختصاص ویژگیهای سفارشی به موجودیتها و مدیریت ویژگیها
پلتفرم ThingsConnect امکان اختصاص ویژگیهای سفارشی به موجودیتها و مدیریت این ویژگیها را فراهم میکند. این ویژگیها در پایگاه داده ذخیره شده و ممکن است برای نمایش و پردازش دادهها مورد استفاده قرار گیرند.
ویژگیها به صورت جفتهای کلید-مقدار تلقی میشوند. انعطافپذیری و سادگی فرمت کلید-مقدار، ادغام آسان و بیدردسر با تقریباً هر دستگاه اینترنت اشیای موجود در بازار را ممکن میسازد. کلید همواره یک رشته است و اساساً نام ویژگی را مشخص میکند، در حالی که مقدار ویژگی میتواند یکی از انواع رشته، بولین، عدد اعشاری، عدد صحیح یا JSON باشد. برای مثال:
پلتفرم ThingsConnect امکان اختصاص ویژگیهای سفارشی به موجودیتها و مدیریت این ویژگیها را فراهم میکند. این ویژگیها در پایگاه داده ذخیره شده و ممکن است برای نمایش و پردازش دادهها مورد استفاده قرار گیرند.
ویژگیها به صورت جفتهای کلید-مقدار تلقی میشوند. انعطافپذیری و سادگی فرمت کلید-مقدار، ادغام آسان و بیدردسر با تقریباً هر دستگاه اینترنت اشیای موجود در بازار را ممکن میسازد. کلید همواره یک رشته است و اساساً نام ویژگی را مشخص میکند، در حالی که مقدار ویژگی میتواند یکی از انواع رشته، بولین، عدد اعشاری، عدد صحیح یا JSON باشد. برای مثال:
{
"firmwareVersion":"v2.3.1",
"booleanParameter":true,
"doubleParameter":42.0,
"longParameter":73,
"configuration": {
"someNumber": 42,
"someArray": [1,2,3],
"someNestedObject": {"key": "value"}
}
}
نام ویژگیها
به عنوان یک کاربر پلتفرم، شما میتوانید هر نامی را برای ویژگیها تعریف کنید. با این حال، توصیه میکنیم از سبک نوشتاری camelCase استفاده کنید. این کار نوشتن توابع سفارشی جاوا اسکریپت برای پردازش و نمایش دادهها را آسانتر میکند.
انواع ویژگیها
سه نوع ویژگی وجود دارد. بیایید آنها را با مثالهایی بررسی کنیم:
ویژگیهای سمت سرور
این نوع ویژگی تقریباً توسط هر موجودیت پلتفرم پشتیبانی میشود: دستگاه، دارایی، مشتری، مستأجر، کاربر و غیره. ویژگیهای سمت سرور ویژگیهایی هستند که شما میتوانید از طریق رابط کاربری مدیریت یا APIهای REST پیکربندی کنید. نرمافزار دستگاه نمیتواند به ویژگیهای سمت سرور دسترسی پیدا کند. این ویژگیها معمولاً برای مدیریت و نگهداری دادههای ثابت و پیکربندیهای سیستمی استفاده میشوند که توسط کاربران پلتفرم تنظیم میشوند و از سوی دستگاهها تغییر نمیکنند.
فرض کنید میخواهید یک راهکار نظارت بر ساختمان بسازید و چند مثال را بررسی کنید:
- عرض جغرافیایی، طول جغرافیایی و آدرس نمونههای خوبی از ویژگیهای سمت سرور هستند که میتوانید به داراییهایی مانند ساختمانها یا املاک دیگر اختصاص دهید. میتوانید از این ویژگیها در ابزارک نقشه در داشبورد خود استفاده کنید تا مکان ساختمانها را به تصویر بکشید.
- ویژگی floorPlanImage میتواند حاوی یک URL به تصویر باشد. میتوانید از این ویژگی برای نمایش پلان طبقات در ابزارک نقشه تصویری استفاده کنید.
- ویژگیهای maxTemperatureThreshold و temperatureAlarmEnabled میتوانند برای پیکربندی و فعال/غیرفعال کردن هشدارها برای یک دستگاه یا دارایی خاص استفاده شوند.
رابط کاربری مدیریت
- به قسمت دستگاهها (Devices) بروید.روی سطر دستگاه مورد نظر کلیک کنید تا جزئیات دستگاه باز شود.برگه "Attributes" را انتخاب کنید.دامنه "Server attributes" را انتخاب کنید.روی آیکون "+" کلیک کنید.
- نام ویژگی جدید را وارد کنید. نوع مقدار ویژگی را انتخاب کرده و مقدار ویژگی را وارد کنید.
- با استفاده از "آخرین زمان بهروزرسانی" مرتبسازی کنید تا به سرعت ویژگی تازه ایجاد شده را پیدا کنید.
REST API
از مستندات API مبتنی بر REST برای دریافت مقدار توکن JWT استفاده کنید. از این توکن برای پر کردن هدر 'X-Authorization' و احراز هویت درخواست API خود استفاده خواهید کرد.
یک درخواست POST با نمایش JSON از ویژگی به URL زیر ارسال کنید:
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SERVER_SCOPE
مثال زیر یک ویژگی با نام "newAttributeName" و مقدار "newAttributeValue" برای دستگاهی با شناسه ‘ad17c410-914c-11eb-af0c-d5862211a5f6’ در سرور ThingsConnect Cloud ایجاد میکند:
curl -v 'https://thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SERVER_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'
به طور مشابه، میتوانید از فرمان زیر برای بازیابی تمامی ویژگیهای سمت سرور استفاده کنید:
curl -v -X GET 'https://thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SERVER_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json'
خروجی شامل 'key'، 'value' و زمانسنج آخرین بهروزرسانی خواهد بود:
[
{
"lastUpdateTs": 1617633139380,
"key": "newAttributeName",
"value": "newAttributeValue"
}
]
به عنوان جایگزینی برای curl، میتوانید از کلاینتهای REST جاوا یا پایتون استفاده کنید.
ویژگیهای مشترک
این نوع ویژگیها فقط برای دستگاهها در دسترس است و مشابه ویژگیهای سمت سرور میباشد، اما یک تفاوت مهم دارد. نرمافزار یا برنامه دستگاه میتواند مقدار ویژگیهای مشترک را درخواست کند یا بهروزرسانیهای آنها را مشترک شود. دستگاههایی که از پروتکلهای ارتباطی دوطرفه مانند MQTT استفاده میکنند، میتوانند به بهروزرسانیهای ویژگیها مشترک شده و اعلانها را بهصورت بلادرنگ دریافت کنند. دستگاههایی که از پروتکلهای ارتباطی درخواست-پاسخ مانند HTTP استفاده میکنند، میتوانند بهصورت دورهای مقدار ویژگیهای مشترک را درخواست کنند.
رایجترین مورد استفاده از ویژگیهای مشترک، ذخیره تنظیمات دستگاه است. بیایید همان راهکار نظارت بر ساختمان را فرض کنیم و چند مثال را بررسی کنیم:
ویژگی targetFirmwareVersion ممکن است برای ذخیره نسخه میانافزار (Firmware) یک دستگاه خاص استفاده شود.
ویژگی maxTemperature ممکن است برای فعالسازی خودکار سیستم HVAC در صورت بیش از حد گرم بودن اتاق استفاده شود.
کاربر میتواند ویژگی را از طریق رابط کاربری (UI) تغییر دهد. اسکریپت یا برنامه سمت سرور دیگری میتواند مقدار ویژگی را از طریق REST API تغییر دهد.
رابط کاربری مدیریت
REST API
از مستندات REST API برای دریافت مقدار توکن JWT استفاده کنید. از این مقدار برای پر کردن هدر ‘X-Authorization’ و احراز هویت درخواست REST API خود استفاده خواهید کرد.
درخواست POST با نمایش JSON از ویژگی را به URL زیر ارسال کنید:
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SHARED_SCOPE
مثال زیر یک ویژگی با نام "newAttributeName" و مقدار "newAttributeValue" برای دستگاه با شناسه ‘ad17c410-914c-11eb-af0c-d5862211a5f6’ در سرور ThingsConnect Cloud ایجاد میکند:
curl -v 'https://thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SHARED_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'
به طور مشابه، میتوانید از فرمان زیر برای بازیابی تمامی ویژگیهای سمت سرور استفاده کنید:
curl -v -X GET 'https://thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SHARED_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
خروجی شامل 'key'، 'value' و زمانسنج آخرین بهروزرسانی خواهد بود:
[
{
"lastUpdateTs": 1617633139380,
"key": "newAttributeName",
"value": "newAttributeValue"
}
]
رابط برنامهنویسی کاربردی (API) برای firmware دستگاه یا برنامهها:
- درخواست ویژگیهای مشترک از سرور: MQTT API، CoAP API، HTTP API، LwM2M API؛
- اشتراکگذاری بهروزرسانیهای ویژگیهای مشترک از سرور: MQTT API، CoAP API، HTTP API، LwM2M API؛
ویژگیهای سمت کلاینت
این نوع ویژگیها فقط برای دستگاهها در دسترس است. برای گزارش دادههای نیمهثابت مختلف از دستگاه (کلاینت) به ThingsConnect (سرور) استفاده میشود. این ویژگیها مشابه ویژگیهای مشترک هستند، اما یک تفاوت مهم دارند. میانافزار/برنامه دستگاه میتواند مقدار ویژگیها را از دستگاه به پلتفرم ارسال کند.
رایجترین مورد استفاده از ویژگیهای سمت کلاینت، گزارش وضعیت دستگاه است. بیایید همان راهکار نظارت بر ساختمان را فرض کنیم و چند مثال را بررسی کنیم:
ویژگی currentFirmwareVersion ممکن است برای گزارش نسخه میانافزار/برنامه نصب شده دستگاه به پلتفرم استفاده شود.
ویژگی currentConfiguration ممکن است برای گزارش پیکربندی فعلی میانافزار/برنامه به پلتفرم استفاده شود.
ویژگی currentState ممکن است برای نگهداری و بازیابی وضعیت فعلی میانافزار/برنامه از طریق شبکه استفاده شود، در صورتی که دستگاه حافظه پایدار نداشته باشد.
کاربر و برنامههای سمت سرور میتوانند ویژگیهای سمت کلاینت را از طریق UI یا REST API مشاهده کنند، اما نمیتوانند آنها را تغییر دهند. به طور کلی، مقدار ویژگی سمت کلاینت برای UI یا REST API فقط قابل خواندن است.
دریافت ویژگیهای سمت کلاینت از طریق REST API
از مستندات REST API برای دریافت مقدار توکن JWT استفاده کنید. این توکن برای پر کردن هدر ‘X-Authorization’ و احراز هویت درخواست REST API شما به کار خواهد رفت.
درخواست GET را به URL زیر ارسال کنید:
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/CLIENT_SCOPE
مثال زیر تمامی ویژگیها را برای دستگاه با شناسه ‘ad17c410-914c-11eb-af0c-d5862211a5f6’ از سرور ThingsConnect Cloud بازیابی میکند:
curl -v -X GET 'https://thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/CLIENT_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
خروجی شامل 'key'، 'value' و زمانسنج آخرین بهروزرسانی خواهد بود:
[
{
"lastUpdateTs": 1617633139380,
"key": "newAttributeName",
"value": "newAttributeValue"
}
]
به عنوان جایگزینی برای curl، میتوانید از کلاینتهای REST جاوا یا پایتون استفاده کنید.
رابط برنامهنویسی کاربردی (API) برای firmware دستگاه یا برنامهها:
- انتشار ویژگیهای سمت کلاینت به سرور: MQTT API، CoAP API، HTTP API؛
- درخواست ویژگیهای سمت کلاینت از سرور: MQTT API، CoAP API، HTTP API.
پایداری ویژگیها
ThingsConnect آخرین مقدار ویژگی و زمان آخرین تغییر را در پایگاه داده SQL ذخیره میکند. این امر امکان استفاده از فیلترهای موجودیت در داشبوردها را فراهم میآورد. تغییرات در ویژگیها که توسط کاربر ایجاد میشود، در گزارشهای حسابرسی ثبت میگردد.
رابط برنامهنویسی کاربردی (API) جستجوی دادهها
کنترلر تلهمتری (Telemetry Controller) رابط برنامهنویسی کاربردی (REST API) زیر را برای بازیابی دادههای موجودیت ارائه میدهد:
تصویرسازی دادهها
ما فرض میکنیم که ویژگیهای دستگاه را بهدرستی پیکربندی کردهاید. اکنون میتوانید از آنها در داشبوردهای خود بهرهبرداری کنید. برای شروع، پیشنهاد میکنیم بخش مرور داشبوردها را بررسی کنید. پس از آشنایی با نحوه ایجاد داشبوردها و پیکربندی منابع داده، میتوانید از گیجهای دیجیتال و آنالوگ برای نمایش مقادیر عددی نظیر دما، سرعت، فشار و غیره استفاده کنید. همچنین، میتوانید از کارتها برای نمایش چندین ویژگی به صورت کارت یا جدول موجودیت بهره ببرید.
علاوه بر این، میتوانید از ویجتهای ورودی استفاده کنید تا به کاربران داشبورد امکان دهید مقادیر ویژگیها را در داشبورد تغییر دهند.
موتور قوانین
موتور قوانین مسئول پردازش تمامی دادهها و رویدادهای ورودی است. در زیر، رایجترین سناریوهای استفاده از ویژگیها در موتور قوانین آورده شده است:
تولید هشدارها بر اساس عبارات منطقی در مقایسه با مقادیر ویژگیها:
از قوانین هشدار برای پیکربندی شرایط هشدار متداول از طریق رابط کاربری استفاده کنید یا از گرههای فیلتر برای پیکربندی شرایط خاصتر با استفاده از توابع JS سفارشی بهره ببرید.
تغییر ویژگیهای سمت کلاینت پیش از ذخیره آنها در پایگاه داده:
از گره نوع پیام برای فیلتر کردن پیامهای حاوی درخواست "Post attributes" استفاده کنید و سپس از گرههای قانون تحول برای اصلاح پیامهای خاص استفاده کنید.
واکنش به تغییرات ویژگیهای سمت سرور:
از گره نوع پیام برای فیلتر کردن پیامهای حاوی اعلان "Attributes Updated" استفاده کنید و سپس از گرههای عمل یا خارجی برای واکنش به این رویدادهای ورودی بهره ببرید.
دریافت مقادیر ویژگیها برای تحلیل تلهمتری ورودی از دستگاه:
از گرههای تقویت برای افزودن ویژگیهای دستگاه، داراییهای مرتبط، مشتری یا مستأجر به پیامهای تلهمتری ورودی استفاده کنید. این تکنیک به شما این امکان را میدهد که منطق و پارامترهای پردازش را بر اساس تنظیمات ذخیرهشده در ویژگیها تغییر دهید.
بهبود عملکرد
برای دستیابی به عملکرد بهینهتر، میتوانید از کش ویژگیها استفاده کنید (به خصوصیت cache.attributes.enabled در تنظیمات پیکربندی مراجعه کنید).
با فعالسازی کش ویژگیها، ThingsConnect تنها یک بار ویژگی خاص را از پایگاه داده بارگذاری میکند و تمام درخواستهای بعدی برای آن ویژگی از کش سریعتر بارگذاری میشود.
توجه: اگر از کش Redis استفاده میکنید، اطمینان حاصل کنید که maxmemory-policy را به allkeys-random تغییر دهید تا از پر شدن تمام حافظه موجود توسط Redis جلوگیری کنید.