ویرالینک این امکان را به شما می‌دهد تا به موجودیت‌های خود صفت‌های سفارشی اختصاص دهید و آنها را مدیریت کنید. این صفت‌ها به صورت جفت کلید-مقدار (key-value) می‌باشند، که این ساختار انعطاف‌پذیر باعث می‌شود با دستگاه‌های اینترنت اشیا موجود در بازار به آسانی تبادل داده انجام گیرد.
کلید همیشه به صورت یک رشته متن (String) بوده و نام صفت را مشخص میکند. مقدار یک صفت می‌تواند شامل string (رشته), boolean (منطقی), double (عدد اعشاری) , integer (عدد صحیح) و یا json باشد. برای مثال:

{
 "firmwareVersion":"v2.3.1", 
 "booleanParameter":true, 
 "doubleParameter":42.0, 
 "longParameter":73, 
 "configuration": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

نام صفت #

توصیه می‌شود که نام کلید‌ها را به صورت camelCase بنویسید

انواع صفت‌ها #

صفت‌ها به سه گروه اصلی تقسیم می‌شوند:

صفت های سمت سرور #

این صفت‌ها از سمت سرور (از طریق رابط کاربری و یا API) گزارش داده شده و مدیریت می‌شوند. این صفت‌ها توسط برنامه‌های دستگاه‌ها (Device Firmware) قابل مشاهده نیستند. تقریبا تمام موجودیت‌های ویرالینک از صفت‌های سمت سرور پشتیبانی می‌کند.
فرض کنیم که میخواهیم یک سیستم مانیتورینگ یک ساختمان را توسعه دهیم. نمونه هایی از صفت های سمت سرور که برای این مثال وجود دارد:

1. latitude, longitude (طول و عرض جغرافیایی): این صفت‌ها که در سمت سرور ذخیره می‌شود نشان دهنده موقعیت جغرافیایی ساختمان است که میتوان از آن‌ها در تعیین مکان جغرافیایی روی نقشه در داشبورد استفاده کرد.
2. floorPlanImage: یک لینک از نمای ساختمان که برای نمایش دادن آن روی داشبورد می‌توان استفاده کرد.
3. maxTemperatureThreshold و temperatureAlarmEnabled: پیکربندی حد آستانه و فعال و غیرفعال کردن هشدار برای یک دستگاه یا دارایی

رابط کاربری تحت وب #

• به بخش دستگاه‌ها بروید. بر روی دستگاه مد نظر خود کلیک کنید. تب “صفت‌ها” را انتخاب نمایید. “صفت‌های سرور” را انتخاب نمایید. بر روی علامت + کلید کنید.
• نام صفت جدید خود را وارد کرده و نوع مقدار صفت را انتخاب کنید و در انتها مقدار آن را وارد کنید.
• می‌توانید بر اساس “آخرین زمان بروزرسانی” مرتب کنید تا صفت‌هایی که اخیرا ایجاد کردید به راحتی پیدا کنید.

امکان وارد نمون به صورت انبوه به شما اجازه میدهد تا به کمک فایل‌های csv چندین دستگاه و صفت‌های آن‌ها را یکجا وارد نمایید.

REST API #

در ابتدا به کمک راهنمای REST API توکن معتبر خود را تهیه کنید. سپس درخواست خود را با افزودن یک Header به نام X-Authorization درخواست های REST API خود را ارسال نمایید.
کافیست به آدرس زیر زیر یک درخواست POST ارسال نمایید

https://console.viralink.io/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SERVER_SCOPE

مثال زیر یک صفت جدید به نام “newAttributeName” و مقدار “newAttributeValue” برای دستگاه با آیدی ‘ad17c410-914c-11eb-af0c-d5862211a5f6’ ایجاد میکند.

curl -v 'https://console.viralink.io/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"}'

همچنین میتوانید توسط مثال زیر تمام صفت‌های سمت سرور را از طریق REST API دریافت کنید.

curl -v -X GET 'https://console.viralink.io/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' 

خروجی مثال بالا به شکل زیر خواهد بود

[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

همچنین به جای دستور curl می‌توانید از sdkهای جاوا و پایتون استفاده نمایید.

صفت‌های مشترک #

این نوع صفت‌ها شبیه صفت‌های سمت سرور است اما یک تفاوت اصلی دارد. برنامه دستگاه‌ها (Device Firmware) میتواند مقادیر صفت های مشترک را درخواست و دریافت کند. دستگاهی که از طریق رابط MQTT به پلتفرم وصل است میتواند با subscribe کردن به صفت‌های مشترک، هنگام به روزرسانی صفت‌ها همان لحظه این تغییرات را دریافت کند. دستگاه هایی که از طریق پروتکل HTTP وصل است می‌تواند در مدت زمان‌های مشخص مقادیر صفت‌های مشترک را دریافت کند.
بیشترین استفاده از صفت‌های مشترک در ذخیره سازی تنظیمات دستگاه‌ها است. در مثال سیستم مانیتورینگ مثال‌هایی از صفت های مشترک عبارت است از

1. targetFirmwareVersion: صفتی برای ذخیره سازی آخرین نسخه قابل بروزرسانی firmware دستگاه
2. maxTemperature: صفتی برای حداکثر دمای مجاز برای اتاق که به صورت خودکار سیستم تهویه را روشن نماید

رابط کاربری تحت وب #

REST API #

دقیقا شبیه صفت های سمت سرور بوده با این تفاوت که بایستی به آدرس زیر درخواست POST ارسال کنید

https://console.viralink.io/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SHARED_SCOPE

API برای برنامه یا firmware دستگاه‌ها #

• درخواست صفت های مشترک از سرور ویرالینک: MQTT_API, CoAP_API, HTTP_API
• subscribe کردن به صفت های مشترک از سرور ویرالینک: MQTT_API, CoAP_API, HTTP_API

نکته: در صورتی که در زمان بروزرسانی صفت‌ها دستگاه آفلاین شود بروزرسانی آن صفت را از دست خواهد داد. بنابراین توصیه میشود هنگام روشن شدن دستگاه به صفت‌های مد نظر subscribe کرده و در هنگام اتصال (و یا اتصال مجدد) به پلتفرم آخرین مقادیر صفت‌ها را از سرور درخواست کنید.

صفت‌های سمت کاربر #

این نوع صفت‌ها تنها برای دستگاه‌ها قابل دسترس است. این صفت برای ارسال گزارش‌های متفاوت از دستگاه به پلتفرم استفاده میشود. صفت‌های سمت کاربر شبیه صفت‌های مشترک بوده با این تفاوت که برنامه دستگاه (Device Firmware) می‌تواند مقادیر صفت‌ها را به پلتفرم ارسال و بروزرسانی کند.
بیشترین استفاده از صفت‌های سمت کاربر در ارسال وضعیت دستگاه‌ها است. در مثال سیستم مانیتورینگ مثال هایی از صفت های سمت کاربر عبارت است از

1. currentFirmwareVersion: صفتی برای گزارش نسخه برنامه یا firmware نصب شده بر روی دستگاه که از سمت دستگاه به پلتفرم گزارش میشود.
2. currentConfiguration: صفتی برای ارسال پیکربندی فعلی firmware یا برنامه دستگاه

کاربر و برنامه های سمت سرور می‌توانند صفت‌ها و مقادیر آن‌ها را از طریق رابط کاربری و یا REST API دریافت کنند اما نمی‌توانند آن ها را تغییر دهند. اساسا مقادیر صفت‌های سمت کاربر برای برنامه های سمت سرور به صورت تنها-قابل-خواندن (read-only) می‌باشد.

دریافت صفت‌های سمت کاربر از طریق REST API #

دقیقا شبیه صفت‌های سمت سرور بوده با این تفاوت که بایستی به آدرس زیر درخواست POST ارسال کنید.

https://console.viralink.io/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/CLIENT_SCOPE

API برای برنامه یا firmware دستگاه‌ها #

• درخواست صفت های مشترک از سرور ویرالینک: MQTT_API, CoAP_API, HTTP_API
• اشتراک به صفت های مشترک از سرور ویرالینک: MQTT_API, CoAP_API, HTTP_API

API برای پرس و جو داده‌ها (Data Query API) #

بخش telemetry-controller در REST API به شما امکان دریافت داده‌های مختلف را فراهم میکند

مصورسازی داده ها #

پس از ایجاد صفت‌های دستگاه ها شما میتوانید از آن‌ها در داشبورد‌های خود استفاده نمایید. شما می‌توانید ابتدا مستندات شروع به کار با داشبورد‌ها را مطالعه نمایید و سپس از ابزارک‌های دیجیتالی و آنالوگی در مصورسازی داده‌هایی مانند دما، سرعت، فشار یا دیگر مقادیر عددی استفاده نمایید.
همچنین در صورتی که می‌خواهید مقادیر صفت‌های خود را از داشبورد تغییر دهید می‌توانید از ابزارک های ورودی استفاده نمایید.

موتور قواعد #

وظیفه موتور قواعد پردازش تمام داده‌ها و رویداد های ورودی است. عناوین زیر نمونه سناریو‌هایی هستند که در آن‌ها از صفت‌ها استفاده می‌شود:

• تولید هشدار بر اساس عبارت های منطقی به کمک مقادیر صفت‌ها
  به کمک قواعد هشدار می‌توانید برای پیکربندی رایج ترین شرایط هشدار از طریق کنسول ویرالینک(UI) استفاده کنید و یا به کمک گره‌های فیلتر برای پیکربندی شرایط پیچیده از توابع JS استفاده کنید.
  
• تغییر صفت‌های ورودی سمت کاربر قبل از ذخیره سازی آن در ویرالینک
  به کمک گره message type switch پیام هایی که حاوی درخواست “Post Atrributes” هستند را فیلتر کرده و سپس به کمک گره transformation rule node آن را تغییر دهید.
  
• واکنش نسبت به تغییر صفت‌های سمت سرور
  message type switch پیام‌هایی که حاوی “Atrributes Updated” هستند را فیلتر کرده و سپس به کمک action یا external نسبت به آن واکنش دهید.
  
• دریافت مقادیر صفت‌ها برای تحلیل داده‌های ورودی تله متری از دستگاه
  به کمک گره enrichment داده‌های ورودی تله متری از دستگاه را با صفت‌های دستگاه، دارایی مرتبط، مشتری و یا مدیر غنی سازی کنید. این تکنیک به شما اجازه می‌دهد تا منطق و پارامتر‌های خود را بر اساس تنظیمات ذخیره شده در صفت‌ها پردازش کنید.