مرجع MQTT Gateway API
مقدمه
در ThingsConnect، Gateway نوعی دستگاه خاص است که میتواند به عنوان پلی میان دستگاههای خارجی متصل به سیستمهای مختلف و ThingsConnect عمل کند. API Gateway این امکان را فراهم میکند تا دادهها بین چندین دستگاه و پلتفرم از طریق یک اتصال MQTT مبادله شوند. Gateway همچنین به عنوان یک دستگاه در ThingsConnect فعالیت میکند و میتواند از API دستگاه MQTT موجود برای گزارش آمار، دریافت بهروزرسانیهای پیکربندی و بسیاری قابلیتهای دیگر استفاده کند.
MQTT API پایه
برای آگاهی از فرمت دادهها، گزینههای احراز هویت و سایر موارد، لطفاً به API دستگاه عمومی MQTT مراجعه کنید.
API اتصال دستگاه
برای اطلاع ThingsConnect از اتصال دستگاه به Gateway، لازم است پیام زیر منتشر شود:
Topic: v1/gateway/connect
Message: {"device":"Device A"}
که در آن Device A نام دستگاه شما است.
پس از دریافت، ThingsConnect دستگاهی با نام مشخصشده را جستجو یا ایجاد میکند. همچنین، ThingsConnect پیامهایی درباره بهروزرسانیهای جدید ویژگیها و دستورات RPC مربوط به یک دستگاه خاص را به این Gateway ارسال میکند.
API قطع اتصال دستگاه
برای اطلاع ThingsConnect از قطع اتصال دستگاه از Gateway، لازم است پیام زیر منتشر شود:
Topic: v1/gateway/disconnect
Message: {"device":"Device A"}
که در آن Device A نام دستگاه شما است.
پس از دریافت، ThingsConnect دیگر بهروزرسانیهای مربوط به این دستگاه خاص را به این Gateway ارسال نخواهد کرد.
API ویژگیها
API ویژگیهای ThingsConnect به دستگاهها این امکان را میدهد تا:
- ویژگیهای دستگاه سمت کلاینت را به سرور ارسال کنند.
- ویژگیهای دستگاه سمت کلاینت و ویژگیهای مشترک دستگاه را از سرور درخواست کنند.
- برای دریافت بهروزرسانیهای ویژگیهای مشترک از سرور اشتراک بگیرند.
بهروزرسانی ویژگیها را به سرور ارسال کنند.
برای ارسال ویژگیهای دستگاه سمت کلاینت به گره سرور ThingsConnect، پیام PUBLISH را به موضوع زیر ارسال کنید:
Topic: v1/gateway/attributes
Message: {"Device A":{"attribute1":"value1", "attribute2": 42}, "Device B":{"attribute1":"value1", "attribute2": 42}}
که در آن Device A و Device B نام دستگاههای شما هستند و attribute1 و attribute2 کلیدهای ویژگیها میباشند.
درخواست مقادیر ویژگی از سرور
برای درخواست ویژگیهای دستگاه سمت کلاینت یا ویژگیهای مشترک دستگاه از گره سرور ThingsConnect، پیام PUBLISH را به موضوع زیر ارسال کنید:
Topic: v1/gateway/attributes/request
Message: {"id": $request_id, "device": "Device A", "client": true, "key": "attribute1"}
که در آن $request_id شناسه درخواست شما به صورت عدد صحیح است، Device A نام دستگاه شما است، client محدوده ویژگی کلاینت یا مشترک را مشخص میکند و key کلید ویژگی میباشد.
پیش از ارسال پیام PUBLISH با درخواست، کلاینت باید به موضوع زیر اشتراک بگیرد:
Topic: v1/gateway/attributes/response
و انتظار دریافت پیامهایی با نتیجه در فرمت زیر را داشته باشد:
Message: {"id": $request_id, "device": "Device A", "value": "value1"}
اشتراک در بهروزرسانی ویژگیها از سرور
برای اشتراک در تغییرات ویژگیهای مشترک دستگاه، پیام SUBSCRIBE را به موضوع زیر ارسال کنید:
v1/gateway/attributes
Message: {"device": "Device A", "data": {"attribute1": "value1", "attribute2": 42}}
API ارسال دادههای تلهمتری
برای ارسال دادههای تلهمتری دستگاه به گره سرور ThingsConnect، پیام PUBLISH را به موضوع زیر ارسال کنید:
Topic: v1/gateway/telemetry
پیام:
{
"Device A": [
{
"ts": 1483228800000,
"values": {
"temperature": 42,
"humidity": 80
}
},
{
"ts": 1483228801000,
"values": {
"temperature": 43,
"humidity": 82
}
}
],
"Device B": [
{
"ts": 1483228800000,
"values": {
"temperature": 42,
"humidity": 80
}
}
]
}
که در آن Device A و Device B نام دستگاههای شما هستند، temperature و humidity کلیدهای تلهمتری و ts زمانسنج یونیکس به میلیثانیه است.
API دستورات از راه دور (RPC)
دستورات RPC سمت سرور
برای اشتراک در دستورات RPC از سرور، پیام SUBSCRIBE را به موضوع زیر ارسال کنید:
v1/gateway/rpc
و انتظار دریافت پیامهایی با دستورات جداگانه در فرمت زیر را داشته باشید:
{"device": "Device A", "data": {"id": $request_id, "method": "toggle_gpio", "params": {"pin":1}}}
پس از پردازش دستور توسط دستگاه، Gateway میتواند دستورات را با فرمت زیر بازگرداند:
{"device": "Device A", "id": $request_id, "data": {"success": true}}
که در آن $request_id شناسه درخواست شما به صورت عدد صحیح است، Device A نام دستگاه شما و method نام روش RPC شما میباشد.
API ادعای مالکیت دستگاهها
برای دریافت اطلاعات بیشتر در مورد ویژگی ادعای مالکیت دستگاهها، لطفاً به مقاله مربوطه مراجعه کنید.
برای آغاز فرآیند ادعای مالکیت دستگاه، پیام PUBLISH را به موضوع زیر ارسال کنید:
Topic: v1/gateway/claim
پیام:
{
"Device A": {
"secretKey": "value_A",
"durationMs": 60000
},
"Device B": {
"secretKey": "value_B",
"durationMs": 60000
}
}
که در آن Device A و Device B نام دستگاههای شما هستند و secretKey و durationMs کلیدهای اختیاری میباشند. در صورتی که secretKey مشخص نشود، مقدار پیشفرض یک رشته خالی در نظر گرفته میشود. اگر durationMs مشخص نشود، پارامتر سیستمی device.claim.duration از فایل /etc/thingsboard/conf/thingsboard.yml استفاده میشود.
سفارشیسازی پروتکل
انتقال MQTT میتواند برای یک مورد استفاده خاص بهطور کامل با تغییر ماژول مربوطه سفارشیسازی شود.
گامهای بعدی
- راهنماهای شروع سریع - این راهنماها نمای کلی از ویژگیهای اصلی ThingsConnect ارائه میدهند و برای تکمیل در ۱۵ تا ۳۰ دقیقه طراحی شدهاند.
- بصریسازی داده - این راهنماها شامل دستورالعملهای پیکربندی داشبوردهای پیچیده ThingsConnect هستند.
- پردازش داده و اقدامات - نحوه استفاده از موتور قوانین ThingsConnect را بیاموزید.
- تحلیل دادههای IoT - نحوه استفاده از موتور قوانین برای انجام وظایف تحلیلی پایه را بیاموزید.
- نمونههای سختافزار - نحوه اتصال پلتفرمهای مختلف سختافزاری به ThingsConnect را یاد بگیرید.
- ویژگیهای پیشرفته - با ویژگیهای پیشرفته ThingsConnect آشنا شوید.
- مشارکت و توسعه - درباره مشارکت و توسعه در ThingsConnect اطلاعات کسب کنید.