Remote commands to devices

استفاده از قابلیت‌های RPC

ThingsConnect به شما این امکان را می‌دهد تا از طریق برنامه‌های سمت سرور به دستگاه‌ها و بالعکس، فراخوانی‌های رویه‌ای راه دور (RPC) ارسال کنید. اساساً، این ویژگی به شما امکان می‌دهد تا دستورات را به دستگاه‌ها ارسال کرده و نتایج اجرای دستورات را دریافت کنید. این راهنما قابلیت‌های RPC در تینگزبورد را پوشش می‌دهد. پس از مطالعه این راهنما، با موضوعات زیر آشنا خواهید شد:

انواع RPC
موارد استفاده پایه‌ای از RPC
API های کلاینتی و سروری RPC
ویجت‌های RPC

ویژگی RPC در Thingsconnect را می‌توان بر اساس منشأ اجرای رویه راه دور به دو نوع تقسیم کرد: RPC منشأ گرفته از دستگاه و RPC منشأ گرفته از سرور. برای استفاده از نام‌های آشناتر، ما فراخوانی‌های RPC منشأ گرفته از دستگاه را به عنوان RPC سمت کلاینت و RPC منشأ گرفته از سرور را به عنوان RPC سمت سرور نام‌گذاری خواهیم کرد.

RPC سمت کلاینت

ویژگی RPC سمت کلاینت به شما این امکان را می‌دهد تا درخواست را از دستگاه به پلتفرم ارسال کرده و پاسخ را به دستگاه بازگردانید.

بیایید موارد استفاده معمولی از فراخوانی‌های RPC سمت کلاینت را بررسی کنیم:

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

در پشت صحنه، دستگاه یک پیام به پلتفرم ارسال می‌کند که توسط موتور قوانین (Rule Engine) پردازش می‌شود. موتور قوانین ممکن است با استفاده از ویژگی‌های دستگاه، تله‌متری یا هر داده دیگری که در پلتفرم ذخیره شده است، محاسباتی را انجام دهد. موتور قوانین همچنین ممکن است در صورت نیاز سیستم‌های خارجی را فراخوانی کند. پس از پردازش پیام، نتیجه به دستگاه بازگردانده می‌شود. به نمودار زیر توجه کنید:

درخواست RPC سمت کلاینت شامل دو فیلد است که هر دوی آن‌ها اجباری هستند:

method - نام روش برای متمایز کردن فراخوانی‌های RPC. به عنوان مثال، "getCurrentTime" یا "getWeatherForecast". مقدار این پارامتر یک رشته (string) است.
params - پارامترهای اضافی که برای پردازش درخواست استفاده می‌شوند. مقدار این پارامتر یک JSON است. اگر نیازی به پارامترها نیست، یک JSON خالی "{}" قرار دهید.

مثالی از درخواست RPC:

				
					{
   "method": "getCurrentTime",
   "params": {}
}

پاسخ RPC می‌تواند هر عدد، رشته یا JSON باشد. به عنوان مثال:

				
					1631881236974

ارسال RPC سمت کلاینت از دستگاه

ThingsConnect یک API برای ارسال دستورات فراخوانی رویه از راه دور (RPC) از دستگاه فراهم می‌کند. این API برای هر پروتکل شبکه پشتیبانی‌شده به‌صورت اختصاصی طراحی شده است. برای بررسی API و مشاهده مثال‌ها، می‌توانید به صفحه مرجع مربوطه مراجعه کنید:

مرجع API RPC سمت کلاینت MQTT
مرجع API RPC سمت کلاینت CoAP
مرجع API RPC سمت کلاینت HTTP

پروتکل‌های LwM2M و SNMP هنوز از RPC سمت کلاینت پشتیبانی نمی‌کنند.

پردازش RPC سمت کلاینت توسط پلتفرم

فرمان RPC سمت کلاینت به یک پیام موتور قوانین با نوع پیام "TO_SERVER_RPC_REQUEST" تبدیل می‌شود. این پیام شامل یک شناسه منحصربه‌فرد UUID است که در فیلد متادیتای "requestId" ذخیره می‌شود. شما می‌توانید زنجیره قوانین خود را برای پردازش پیام ورودی با استفاده از تبدیل، غنی‌سازی یا هر نوع گره قوانین دیگر طراحی کنید. پس از تبدیل پیام ورودی به پیام پاسخ، باید از گره "RPC Call Reply" برای ارسال پاسخ به دستگاه استفاده کنید.

به عنوان مثال، بیایید زنجیره قوانین ریشه را برای پردازش فرمان RPC سمت کلاینت "getCurrentTime" و پاسخ با زمان فعلی به میلی‌ثانیه‌ها اصلاح کنیم. ما از گره تبدیل "Script" با کد جاوااسکریپت زیر استفاده خواهیم کرد:

				
					var rpcResponse;
if (msg.method === "getCurrentTime"){
   rpcResponse = new Date().getTime();
} else {
   rpcResponse = "Unknown RPC request method: " + msg.method;  
}
return {msg: rpcResponse, metadata: metadata, msgType: msgType};

RPC سمت سرور

ویژگی RPC سمت سرور به شما این امکان را می‌دهد که درخواست‌هایی را از پلتفرم به دستگاه ارسال کرده و در صورت لزوم، پاسخ را به پلتفرم بازگردانید.

استفاده‌های رایج از تماس‌های RPC سمت سرور شامل انواع کنترل از راه دور است، مانند: راه‌اندازی مجدد، روشن/خاموش کردن موتور، تغییر وضعیت GPIO/عملگرها، تغییر پارامترهای پیکربندی و غیره.

RPC سمت سرور به دو دسته یک‌طرفه و دوطرفه تقسیم می‌شود:

درخواست RPC یک‌طرفه نیازی به دریافت پاسخ از دستگاه ندارد.

درخواست RPC دوطرفه انتظار دارد که پاسخ را از دستگاه در مدت زمان قابل پیکربندی دریافت کند.

قبل از نسخه 3.3، ThingsConnect تنها از RPC سبک پشتیبانی می‌کرد. تماس‌های RPC سبک معمولاً کوتاه‌مدت هستند، به طور معمول در مدت زمان 30 ثانیه که زمان پیش‌فرض برای هر تماس REST API به پلتفرم است. از آنجا که این تماس‌ها کوتاه‌مدت بودند، نیازی به ذخیره‌سازی آن‌ها در پایگاه داده نبود. این تماس‌ها در حافظه سرور باقی می‌ماندند و فرض بر این بود که اگر سرور دچار مشکل شود، ویجت داشبورد همان درخواست را به سرور دیگر ThingsConnect در خوشه ارسال خواهد کرد. تماس‌های RPC سبک منابع کمی مصرف می‌کنند، زیرا پردازش آن‌ها هیچ عملیات ورودی/خروجی‌ای به جز ذخیره‌سازی لاگ‌های حسابرسی و پیام‌های موتور قوانین در بر نمی‌گیرد.

از نسخه 3.3 به بعد، ThingsConnect پشتیبانی از تماس‌های RPC پایدار را اضافه کرده است. RPC پایدار دارای عمر قابل پیکربندی است و در پایگاه داده ذخیره می‌شود. RPC پایدار به‌ویژه زمانی مفید است که دستگاه شما ممکن است برای مدت طولانی در دسترس نباشد، که معمولاً به دلیل اتصال شبکه ضعیف یا حالت صرفه‌جویی در مصرف انرژی (PSM) اتفاق می‌افتد.

ساختار RPC سمت سرور

بدنه درخواست RPC سمت سرور شامل چندین فیلد است:

method: الزامی، نام متدی که برای تمایز تماس‌های RPC استفاده می‌شود. به عنوان مثال، “getCurrentTime” یا “getWeatherForecast”. مقدار این پارامتر از نوع رشته است.
params: الزامی، پارامترهایی که برای پردازش درخواست استفاده می‌شود. مقدار آن یک JSON است. در صورت عدم نیاز به پارامترها، JSON خالی "{}" را وارد کنید.
timeout: اختیاری، مقدار زمان پردازش به میلی‌ثانیه. مقدار پیش‌فرض آن 10000 (10 ثانیه) است و حداقل مقدار آن 5000 (5 ثانیه) است.
expirationTime: اختیاری، مقدار زمان اپوک (به میلی‌ثانیه، منطقه زمانی UTC). اگر موجود باشد، مقدار آن بر timeout تأثیر می‌گذارد.
persistent: اختیاری، به تفاوت [persistent] و [lightweight] RPC مراجعه کنید. مقدار پیش‌فرض آن "false" است.
retries: اختیاری، تعداد دفعاتی که RPC پایدار در صورت بروز خطا در شبکه و/یا طرف دستگاه دوباره ارسال می‌شود.
additionalInfo: اختیاری، متاداده‌ای برای RPC پایدار که به [رویدادهای RPC پایدار] اضافه خواهد شد.

مثال از درخواست RPC:

				
					{
   "method": "setGPIO",
   "params": {
     "pin": 4,
     "value": 1
   },
  "timeout": 30000
}

پاسخ RPC می‌تواند هر نوع JSON باشد. به عنوان مثال:

				
					{
   "pin": 4,
   "value": 1,
   "changed": true
}

ارسال RPC سمت سرور

RPC سمت سرور معمولاً از طریق API REST یا ویجت‌های داشبورد ارسال می‌شود. در واقع، ویجت‌های داشبورد از همان API REST استفاده می‌کنند. پس از دریافت RPC توسط پلتفرم، بارگذاری داده‌ها اعتبارسنجی شده و بررسی‌های مجوز انجام می‌شود. سپس، فرمان RPC سمت سرور به پیام موتور قوانین تبدیل می‌شود. موتور قوانین ممکن است فرمان را با پارامترهای اضافی غنی کرده و در نهایت، ارسال فرمان به دستگاه را انجام دهد.

بیایید به جزئیات نحوه ارسال فرمان بپردازیم:

استفاده از API REST

برای ارسال یک درخواست RPC، لازم است که یک درخواست HTTP POST به URL زیر ارسال کنید:

				
					http(s)://host:port/api/plugins/rpc/{callType}/{deviceId}

http(s)://host:port آدرس پایه سرور ThingsConnect شماست. به عنوان مثال، https://ThingsConnect.cloud
callType می‌تواند یکی از مقادیر oneway یا twoway باشد؛
deviceId شناسه دستگاه هدف شماست.

بدنه درخواست باید یک JSON معتبر با شیء درخواست RPC باشد که قبلاً درباره آن بحث کردیم.

برای مثال:

				
					curl -v -X POST -d @set-gpio-request.json http://localhost:8080/api/plugins/rpc/twoway/$DEVICE_ID \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"

لطفاً توجه داشته باشید که برای اجرای این درخواست، نیاز به جایگزینی $JWT_TOKEN با یک توکن دسترسی JWT معتبر دارید. این توکن باید به کاربری با نقش TENANT_ADMIN یا CUSTOMER_USER تعلق داشته باشد که مالک دستگاه شناسایی‌شده با $DEVICE_ID است. برای دریافت توکن، از راهنمای زیر استفاده کنید.

زمانی که کاربر RPC سبک را از طریق API REST ارسال می‌کند، تماس API شامل پاسخ از دستگاه یا کد خطا خواهد بود. به عنوان مثال:

				
					{
   "pin": 4,
   "value": 1,
   "changed": true
}

زمانی که کاربر درخواست پایدار RPC را از طریق REST API ارسال می‌کند، پاسخ شامل شناسه منحصر به فرد "rpcId" است. برای مثال:

				
					{
   "rpcId": "b10bb1a0-0afd-11ec-a08f-1b3182194747"
}

می‌توانید از این شناسه برای پیگیری وضعیت فرمان استفاده کنید. برای جزئیات بیشتر به وضعیت‌های RPC پایدار مراجعه کنید.

استفاده از داشبورد

ویجت‌های کنترلی برای ارسال دستورات RPC به دستگاه استفاده می‌شوند. محبوب‌ترین ویجت‌ها شامل "دکمه RPC"، "سوئیچ گرد"، "کنترل سوئیچ" و "کنترل ناب" هستند. تنظیمات پیشرفته این ویجت‌ها به شما امکان می‌دهد نام روش RPC و پارامترها را تعریف کنید. همچنین می‌توانید ویجت‌های سفارشی را توسعه داده و از API کنترل برای ارسال دستورات RPC استفاده کنید.

استفاده از موتور قوانین

همه دستورات RPC سمت سرور که از طریق ویجت‌ها یا REST API ارسال می‌شوند، در نهایت به پیام موتور قوانین با نوع پیام "RPC_CALL_FROM_SERVER_TO_DEVICE" تبدیل می‌شوند.

این پیام حاوی شناسه منحصربه‌فرد مبتنی بر UUID است که در فیلد متادیتای "requestUUID" ذخیره می‌شود. شما می‌توانید زنجیره قوانین خود را طراحی کنید تا پیام ورودی را با استفاده از تبدیل، غنی‌سازی یا هر نوع گره قانونی دیگر پردازش کنید. در نهایت، باید از گره درخواست تماس RPC برای ارسال پیام به دستگاه استفاده کنید.

همچنین می‌توانید RPC را با استفاده از گره تولیدکننده ایجاد کنید:

				
					var msg = { method: "rpcCommand", params: {} };
var metadata = { 
    expirationTime: new Date().getTime() + 60000,
    oneway: true,
    persistent: false
};
var msgType = "RPC_CALL_FROM_SERVER_TO_DEVICE";

return { msg: msg, metadata: metadata, msgType: msgType };

پردازش RPC سمت سرور در دستگاه

ThingsConnect یک API مناسب برای دریافت و پردازش دستورات RPC سمت سرور در دستگاه فراهم می‌کند. این API برای هر پروتکل شبکه پشتیبانی‌شده خاص است. شما می‌توانید API و مثال‌ها را در صفحه مرجع مربوطه مرور کنید:

MQTT RPC API reference
CoAP RPC API reference
HTTP RPC API reference

RPC پایدار

وضعیت‌ها

ThingsConnect وضعیت‌های RPC پایدار را پیگیری می‌کند. تعداد ۷ وضعیت در دسترس است:

QUEUED - RPC ایجاد و در پایگاه داده ذخیره شده است؛ هنوز تلاشی برای ارسال RPC به دستگاه انجام نشده است. ThingsConnect تلاش خواهد کرد تا RPC را به محض آنلاین شدن دستگاه یا اگر دستگاه هم‌اکنون آنلاین باشد، ارسال کند. به طور پیش‌فرض، پلتفرم تلاش خواهد کرد تا تمام تماس‌های RPC معلق را به‌طور همزمان ارسال کند. در موارد نادر، دستگاه‌های محدود و پیام‌های متعدد در صف ممکن است به بار شبکه یا دستگاه منجر شود. برای جلوگیری از بار اضافی، می‌توانید ارسال ترتیب‌دار تماس‌های RPC را با استفاده از پارامتر پیکربندی “ACTORS_RPC_SEQUENTIAL” فعال کنید.
SENT - ThingsConnect تلاشی برای ارسال RPC به دستگاه انجام داده است.
DELIVERED - دستگاه تأیید کرده است که RPC تحویل داده شده است؛ این آخرین مرحله پردازش برای RPC یک‌طرفه است.
SUCCESSFUL - ThingsConnect پاسخ برای RPC دوطرفه را دریافت کرده است.
TIMEOUT - لایه حمل‌ونقل ThingsConnect (MQTT/CoAP/LwM2M و غیره) زمان‌بر بودن تحویل RPC را تشخیص داده است. زمان‌بر بودن با استفاده از یکی از پارامترهای پیکربندی مربوطه کنترل می‌شود: MQTT_TIMEOUT (به‌طور پیش‌فرض ۱۰ ثانیه)، COAP_TIMEOUT (به‌طور پیش‌فرض ۱۰ ثانیه)، LWM2M_TIMEOUT (به‌طور پیش‌فرض ۱۲۰ ثانیه). به‌طور پیش‌فرض، پلتفرم تلاش مجدد برای ارسال RPC را انجام نمی‌دهد و وضعیت به FAILED تغییر می‌کند. شما می‌توانید تعداد تلاش‌های مجدد را در بدنه RPC پیکربندی کنید. حداکثر تعداد تلاش‌های مجدد با پارامتر پیکربندی “ACTORS_RPC_MAX_RETRIES” کنترل می‌شود (به‌طور پیش‌فرض ۵).
EXPIRED - RPC تحویل داده نشده است یا پلتفرم پاسخی از دستگاه در زمان انقضای پیکربندی شده دریافت نکرده است.
FAILED - تحویل RPC در طی تعداد تلاش‌های پیکربندی‌شده ناموفق بوده است یا فریمور دستگاه از چنین دستوری پشتیبانی نمی‌کند.

رویدادهای زنجیره قوانین

تغییرات در وضعیت‌های RPC به موتور قوانین به‌عنوان پیام‌های جداگانه ارسال می‌شود. هر وضعیت RPC دارای نوع پیام مربوطه است. به تصویر زیر مراجعه کنید:

پیام حاوی اطلاعات کامل درباره درخواست RPC است، از جمله شناسه‌های موجودیت و "additionalInfo" از بدنه درخواست RPC. پیام "RPC Successful" همچنین شامل پاسخ از دستگاه است. این پیام‌ها مفید هستند اگر بخواهید پاسخ دستگاه را در سیستم خارجی پردازش کنید.

مثال پیام موفق RPC را در زیر مشاهده کنید:

				
					{
    "id": {
        "entityType": "RPC",
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2"
    },
    "createdTime": 1632236465459,
    "tenantId": {
        "entityType": "TENANT",
        "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
    },
    "deviceId": {
        "entityType": "DEVICE",
        "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
    },
    "expirationTime": 1632236525354,
    "request": {
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2",
        "tenantId": {
            "entityType": "TENANT",
            "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
        },
        "deviceId": {
            "entityType": "DEVICE",
            "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
        },
        "oneway": false,
        "expirationTime": 1632236525354,
        "body": {
            "method": "rpcCommand",
            "params": "{}"
        },
        "persisted": true,
        "retries": null
    },
    "response": {
        "test": "passed"
    },
    "status": "SUCCESSFUL",
    "additionalInfo": "{\"param1\":\"value1\",\"param2\":\"value2\"}"
}

پیکربندی TTL

زمان عمر (TTL) RPC پایدار توسط مدیر سیستم در پروفایل مستاجر با استفاده از پارامتر پیکربندی "RPC TTL days" تنظیم می‌شود. مدیر سیستم می‌تواند پاک‌سازی کامل RPC پایدار از پایگاه داده را با استفاده از پارامتر پیکربندی "SQL_TTL_RPC_ENABLED" غیرفعال کند. فرکانس فرآیند پاک‌سازی RPC با استفاده از پارامتر "SQL_RPC_TTL_CHECKING_INTERVAL" کنترل می‌شود که به‌طور پیش‌فرض بر روی ۲ ساعت تنظیم شده است.

پنل IOT

نرم افزار موبایل

سخت افزار

فروش پنل

انرژی هوشمند

کشاورزی هوشمند

ردیابی ناوگان

اندازه گیری هوشمند

پایش کیفیت هوا

مدیریت پسماند

نظارت بر محیط زیست

دفتر هوشمند

اندازه گیری آب

خرده فروشی هوشمند

آبیاری هوشمند

تولید سخت افزار

توزیع کننده و نماینده ها

فروشگاه

درباره ما

فرم تماس با ما

اسناد سامانه اتصال اشیاء