مستندات ویرالینک

پروفایل‌های دستگاه (Device Profiles)

مقدمه #

شما به عنوان یک مدیر می‌توانید پیکربندی‌های مشترک چندین دستگاه را توسط یک پروفایل دستگاه انجام دهید. هر دستگاه در ویرالینک تنها می‌تواند یک پروفایل داشته باشد.

تنظیمات پروفایل دستگاه #

زنجیره قواعد (Rule Chain) #

به صورت پیشفرض تمام پیام ها و رویدادهای ورودی برای تمامی دستگاه‌ها توسط زنجیره قواعد ریشه (Root Rule Chain) پردازش می‌شود. با افزایش تعداد دستگاه هایتان زنجیره ریشه یا اصلی شما یعنی Root Rule Chain می‌تواند پیچیده‌تر شود. شما می‌توانید در این بخش زنجیره قواعد خود را تعریف کنید تا از این پس تمام داده‌های تله متری، وضعیت دستگاه (Active یا Inactive) و رویداد‌های طول عمر دستگاه (Created, Updated, Deleted) توسط زنجیره قواعد مشخص‌شده، دریافت و پردازش شود. شما می‌توانید هنگام تعریف پروفایل دستگاه و یا در بخش جزئیات پروفایل‌های موجود زنجیره قواعد مد نظر خود را پیکربندی نمایید.

نام صف (Queue Name) #

به صورت پیشفرض صف Main برای تمامی پیام‌ها و رویداد‌های ورودی از تمام دستگاه‌ها استفاده می‌شود. در برخی موارد شاید تمایل داشته باشید تا از صف‌های مجزا برای دستگاه‌های متفاوت استفاده نمایید. برای مثال مجزا کردن (ایزوله سازی) پردازش داده‌های هشدار آتش یا دود (که از سنسور های مربوطه دریافت میشود) با دیگر دستگاه‌ها. در این صورت اگر صف شما با میلیون ها درخواست ورودی از دیگر دستگاه‌ها (مثل سنسور اندازه گیری آب) پر شود، داده‌های حیاتی شما از سنسور دود یا آتش بلادرنگ گزارش و پردازش خواهد شد و در صورت نیاز هشدار مربوطه فعال می‌شود. جداسازی صف‌ها همچنین به شما امکان شخصی سازی استراتژی‌های Submit و Processing متفاوت میدهد.
توجه بسیار مهم: در صورتی که از صف‌های پیشفرض استفاده ننمایید و اقدام به تعریف صف مجزا برای خود نمایید برای فعال سازی آن با پشتیبانی ویرالینک تماس حاصل نمایید.

پیکربندی ارتباط (Transport) #

در پیکربندی ارتباط دوگزینه برای انتخاب وجود دارد: پیشفرض (Default) و MQTT

نوع ارتباط پیشفرض (Default Transport Type) #

با انتخاب این گزینه شما می‌توانید از API های پیشفرض برای CoAP، HTTP و MQTT برای ارتباط با دستگاه های خود استفاده نمایید. در این گزینه پیکربندی خاصی برای شما وجود ندارد.

نوع ارتباطی MQTT یا (MQTT Transport Type) #

با انتخاب این گزینه می‌توانید از تنظیمات پیشرفته برای پیکربندی ارتباط MQTT استفاده نمایید. با انتخاب این گزینه از فیلتر های تاپیک های شخصی MQTT (MQTT Topics filters) برای داده‌های زمانی و صفت‌ها استفاده کنید.

تنظیمات نوع ارتباطی MQTT به شرح زیر است

فیلتر های تاپیک دستگاه برای پروتکل MQTT یا (MQTT Device topic filters): #

فیلتر‌های تاپیک MQTT از wildcard‌های تکی (single) ‘+’ و چند سطحی (multi-level) ‘#’ پشتیبانی میکند و به شما اجازه می‌دهد تا دستگاه‌هایی که محتوای داده‌های خود را (payload) مبتنی بر JSON یا Protobuf روی پروتکل MQTT ارسال میکند، به ویرالینک وصل نمایید. برای مثال، پیکربندی انجام شده در عکس زیر به شما اجازه میدهد تا داده‌های زمانی با دستور زیر انتشار دهید.

mosquitto_pub -h 'console.viralink.io' -i 'c1' -u 't1' -P 'secret' -t '/telemetry' -m '{"humidity": 10.3}'

و همچنین صفت خود را با دستور زیر بروز رسانی نمایید

mosquitto_pub -h 'console.viralink.io' -i 'c1' -u 't1' -P 'secret' -t '/attributes' -m '{"firmwareVersion": "1.3"}'

فرض می‌کنیم که دستگاه شما اعتبارنامه‌اش (Credentials) از نوع Basic MQTT Credentials بوده و دارای شناسه کاربری (Client id) با مقدار ‘c1’، نام کاربری (username) با مقدار ‘t1’ و رمزعبور (Password) با مقدار ‘secret’ است.

محتوای دستگاه MQTT (MQTT device payload): #

به صورت پیشفرض، ویرالینک انتظار دارد تا دستگاه‌ها داده های خود را به صورت JSON ارسال نمایند. همچنین می‌توانید داده های خود را به صورت Protocol Buffers ارسال نمایید.
Protocol Buffer ها یا Protobuf، یک زبان برای سریالایز (Serialize) کردن داده‌های ساخت یافته است.
پلتفرم ویرالینک از شمای (schemas) پروتکل protobuf برای ارسال داده‌های تله متری و ارسال صفت پشتیبانی می‌کند. ویرالینک ساختار protobuf را به صورت داینامیک پردازش می‌کند ولی برخی از امکانات protobuf مثل OneOf, extensions و maps را پشتیبانی نمی‌کند.

قواعد هشدار (Alarm Rules) #

کاربران ویرالینک میتوانند از سناریو نویسی گرافیکی برای پیکربندی هشدار‌ها استفاده نمایند. برای استفاده از بخش قدرتمند سناریو نویسی کمی دانش برنامه نویسی(جاوا اسکریپت) نیاز است. در بخش قواعد هشدار سعی شده تا پیکربندی هشدار‌ها ساده‌تر شود. به کمک این بخش نیازی به یادگیری سناریو نویسی برای پیکربندی منطق پردازشی خود ندارید. در حقیقت موتور سناریو نویسی قواعد هشدار را با استفاده از گره “Device Profile” بررسی و ارزیابی می‌کند.
قواعد هشدار شامل پیکربندی‌های زیر است:

  • نوع هشدار (Alarm Type): نوع هشدار بایستی منحصر به فرد باشد.
  • شرط ایجاد (Create Conditions): تعریف معیارهایی که منجر به ایجاد یا بروز رسانی هشدار خواهد شد. شرط ایجاد شامل پیکربندی‌های زیر است:
    • سطح هشدار (Severity): برای ایجاد / به‌روزرسانی هشدار استفاده خواهد شد. ویرالینک شرایط را بر حسب سطح هشدار از بالا به پایین (بحرانی [Critical]، مهم [Major]، جزئی [Minor] و اخطار [Warning]) بررسی میکند. برای مثال، در صورتی که شرایط ایجاد هشدار بحرانی بر اساس معیار‌های تعریف شده برقرار باشد (هشدار بحرانی ایجاد یا بروز رسانی شود)، ویرالینک هشدار بحرانی را فعال و بقیه سطح هشدار‌ها را (مهم، جزئی، اخطار) را بررسی نمیکند. سطح هشدار‌ها به ازای هر قاعده هشدار بایستی یکتا باشد (دو قاعده هشدار نمی‌توانند با یک سطح هشدار ایجاد شوند).
    • فیلتر‌های کلید (Key Filters): لیستی از عبارت‌های منطقی که صفت‌ها یا داده‌های تله‌متری را فیلتر می‌کند. برای مثال “(temperature < 0 OR temperature > 20) AND softwareVersion = ‘2.5.5’“;
    • نوع شرط (Condition Type): ساده (simple)، مستمر (duration)، تکرار شونده (repeating). برای مثال ۳ بار پشت سرهم یا در مدت زمان مستمر ۵ دقیقه. در شرط ساده هشدار یکبار برای اولین رویداد منطبق فعال خواهد شد.
    • زمانبندی (Schedule): تعریف اینکه در چه زمان‌هایی هشدار فعال شود. همیشه فعال، در یک زمان خاص فعال شود و یا به صورت سفارشی تنظیم نمایید.
    • جزئیات (Details): قالب جزئیات هشدار از سینتکس ${attributeName} برای جایگزینی مقادیر داده‌های تله‌متری یا صفت پشتیبانی می‌کند.
  • پاک سازی شرط (Clear Condition): معیارهایی را برای پاک شدن هشدار مشخص می کند.
  • تنظیمات پیشرفته (Advanced Settings): انتشار هشدار به دارایی‌ها، مشتری‌ها، مدیر یا دیگر موجودیت‌های مرتبط را تعریف می‌کند.

اجازه دهید تا با چند مثال با نحوه استفاده از قواعد هشدار آشنا شویم. فرض می‌کنیم که می‌خواهیم داده‌های دماسنج داخل فریز را ثبت کنیم.
همچنین قبلا یک پروفایل دستگاه به نام “Temperature Sensors” ایجاد کردیم و دستگاه داده‌های سنسور خود را با توکن دسترسی “ACCESS_TOKEN” به پلتفرم ویرالینک ارسال می‌کند. دستور زیر داده فرضی دماسنج را به پلتفرم ارسال می نماید.

mosquitto_pub -d -h 'console.viralink.io' -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m '{"temperature": 5.3}'

مثال ۱: شرط هشدار ساده #

در این مثال قصد داریم یک هشدار بحرانی (Critical) برای زمانی که دما داخل فریزر بالاتر از ۱۰ درجه باشد.

  1. در بخش پروفایل های دستگاه (device profiles) دکمه “ویرایش” را بزنید.
  2. دکمه “افزودن قاعده هشدار (Add alarm rule) را بزنید.
  3. نوع هشدار خود (Alarm Type) را وارد نمایید و روی علامت “+” کلیک کنید.
  4. روی دکمه “افزودن فیلتر کلید” (Add Key Filter) کلید کنید.
  5. نوع کلید را بر روی “داده زمانی” (Timeseries) قرار دهید. نام کلید را “temperature” وارد نمایید. نوع مقدار را “Numeric” انتخاب نمایید. و در انتها دکمه افزودن را بزنید.
  6. فیلد عملیات (operation) را بر روی “بزرگتر از” (greater than) قرار داده و مقدار حد آستانه را وارد نمایید. در انتها دکمه افزودن را بزنید.
  7. کلید ذخیره سازی را بزنید.
  8. در انتها تغییرات خود را اعمال نمایید.

مثال ۲: شرط هشدار مستمر #

در این مثال قصد داریم تا مثال ۱ را به گونه ای تغییر دهیم که هشدار زمامی فعال شود که دما برای حداقل برای یک دقیقه از حد آستانه فراتر رود.

  1. نوع شرط را از “ساده” به “مستمر” (Duration) تغییر میدهیم.
  2. مقدار را برابر یک و واحد آن را دقیقه قرار دهید.
  3. تغییرات را اعمال کنید.

مثال۳: شرط هشدار تکرار شونده #

در این مثال قصد داریم تا مثال ۱ را به گونه ای تغییر دهیم که هشدار زمامی فعال شود که دما برای حداقل ۳ مرتبه از حد آستانه عبور کند.

  1. نوع شرط را از “ساده” به “تکرار شونده” (Repeating) تغییر دهید.
  2. مقدار را برابر ۳ قرار دهید.
  3. تغییرات را اعمال کنید.

مثال ۴: پاک کردن هشدار #

در این مثال قصد داریم در صورتی که دمای فریزر به حالت عادی بازگشت به صورت خوکار هشدار فعال شده را پاک کنیم.

  1. در بخش پروفایل های دستگاه (device profiles) دکمه “ویرایش” را بزنید. بر روی دکمه “افزودن شرط پاک کردن” (Add clear condition) بزنید.
  2. روی علامت “+” کلیک کنید.
  3. فیلتر کلید مد نظر را ایجاد کنید.
  4. تغییرات را اعمال کنید.

مثال ۵: تعریف زمانبندی قاعده هشدار #

فرض کنید میخواهیم که هشدار تنها در زمان های اداری بررسی شود.

  1. زمانبندی هشدار را ویرایش کنید
  2. منطقه زمانی، روزهای مد نظر، زمان مد نظر خود را پیکربندی نمایید.
  3. تغییرات را اعمال کنید.

مثال ۶: تنظیم حد آستانه #

فرض کنید که میخواهیم امکان تغییر حد آستانه را از داشبورد رابط کاربری ایجاد کنیم. همچنین با افزودن یک متغییر (flag) امکان فعال یا غیر فعال کردن هشدار را برای هر دستگاه مشخص کنیم. برای این کار از دو متغییر در قواعد هشدار استفاده می کنیم. صفت منطقی “temperatureAlarmFlag” برای فعال و غیر فعال کردن و صفت عددی “temperatureAlarmThreshold” برای مشخص کردن حد آستانه هشدار. میخواهیم هشدار تنها زمانی فعال شود که مقدار temperatureAlarmFlag برابر True و دما بیشتر از temperatureAlarmThreshold باشد. به عبارتی:

temperatureAlarmFlag = True AND temperature is greater than temperatureAlarmThreshold
  1. ویرایش فیلتر کلید دما و تغییر به حالت پویا. (Switch to dynamic value)
  2. انتخاب “نوع منبع پویا” (dynamic source type) و temperatureAlarmThreshold را وارد کرده و دکمه بروز رسانی را بزنید
  3. افزودن فیلتر کلید temperatureAlarmFlag و سپس کلید افزودن را بزنید
  4. در انتها تغییرات خود را ذخیره کنید.
  5. صفت های دستگاه را به صورت دستی و یا از طریق اسکریپت ایجاد نمایید.

مثال ۷: تنظیم حد آستانه به صورت پویا مبتنی بر صفت مشتری #

در مثال ۶ یادگرفتیم که چگونه قاعده ای را براساس مقدار صفتی به نام temperatureAlarmFlag فعال یا غیر فعال کنیم. اما در صورتی که بخواهیم یک قاعده را برای تمام دستگاه های متلعق به یک مشتری را فعال یا غیر فعال کنیم چه کنیم؟ برای اینکه تمام دستگاه ها را یک به یک پیکربندی نکنیم، میتوانیم با مقایسه مقدار constant و مقدار صفت مشتری قواعد هشدار را پیکربندی کنیم. برای این اینکار شما بایستی نوع کلید را constant انتخاب کرده و با صفت مد نظر خود عملیات مقایسه را انجام دهید.

گره قاعده پروفایل دستگاه (Device profile rule node) #

وظیفه اصلی گره گروفایل دستگاه ایجاد و یا پاک کردن هشدار ها بر اساس قوانین تعریف شده در پروفایل دستگاه مرتبط است. به صورت پیشفرض این گره اولین گره از زنجیره قواعد پردازش در زنجیره قواعد است. این گره تمام پیام های ورودی را پردازش و نسبت به مقدار های صفت و یا داده های زمانی واکنش نشان میدهد. دو تنظیم مهم در پیکربندی این گره وجود دارد
persist state of alarm rule – با فعال کردن این گزینه این گره وضعیت پردازش را ذخیره میکند. به صورت پیشفرض این گزینه غیر فعال است. در صورتی که شرط مستمر یا تکرارشونده دارید این گزینه میتواند کاربردی باشد. فرض میکنیم که یک شرط مستمر “emperature is greater than 50 for 1 hour” داریم و اولین رویداد در ساعت ۱ بعد از ظهر گزارش شده. در ساعت ۲ بعد از ظهر شما هشدار خود را دریافت خواهید کرد‌(ب فرض اینکه دما تغییر نکند). اما در صورتی که مشکل پیش بیاید و سرور در بین ساعت ۱ تا ۲ بعد از ظهر ریستارت شود.گره بایستی وضعیت قبلی را از پایگاه داده استعلام کند. در صورتی که گزینه Fetch state of alarm rules را فعال کنید این گره قاعده میتواند حتی پس از ریستارت هشدار را فعال نماید. به صورت پیشفرض این گزینه به دلایل کاهش بارکاری سرور غیر فعال است. تنها در صورت نیاز و حیاتی بودن شرایط آن را فعال نمایید.
Fetch state of alarm rules – با فعال کردن این گزینه گره وضعیت قبلی را از پایگاه داده استعلام میکند. به صورت پیشفرض غیر فعال است. این گزینه را زمانی فعال کنید که گزینه persist state of alarm rule فعال باشد.

اطلاع رسانی درباره هشدار ها (Alarms Notifications) #

در صورتی که تمایل دارید تا هشدار های ایجاد شده ( و یا بروزرسانی شده) را از کانال های دیگری همچون (تلگرام، پیامک، ایمیل) دریافت کنید گره پروفایل دستگاه سه خروجی اصلی دارد که میتواند با پیکربندی آنها هشدار خود را از کانال های دلخواه خود دریافت کنید. خروجی های گره پروفایل دستگاه عبارت است از ‘Alarm Created’, ‘Alarm Severity Updated’, و ‘Alarm Cleared’.

همچنین میتوانید راهنمای ارسال هشدار از طریق ایمیل و یا اطلاع رسانی از طریق تلگرام مطالعه بفرمایید.

برای جلوگیری از دریافت دو مرتبه ای یک هشدار نوع خروجی ‘Alarm Updated’ را در اعمال نکنید.