مقدمه #

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

پیشنهاد ما برای موارد کم ترافیک استفاده از ماژول وای‌فای ESP32 که از پروتکل‌های ارتباطی مختلفی پشتیبانی می‌کند و قابلیت اتصال به Lan هم دارد و برای موارد تخصصی‌تر استفاده از کامپیوترهای کوچک مانند رزبری پای RaspberryPi و هم رده‌هایش که دارای قدرت پردازشی بیشتریست، می‌باشد.

MQTT API پایه #

لطفاً برای دریافت اطلاعات در مورد قالب داده ها، راهکارهای احراز هویت و غیره به MQTT API دستگاه مراجعه کنید.

API ارسال وضعیت اتصال دستگاه #

برای ارسال وضعیت اتصال دستگاهی که به درگاه متصل است، باید پیام زیر را منتشر کنید:

Topic: 
v1/gateway/connect

Message: 
{"device":"Device A"}

که در آن Device A نام دستگاه شما است.

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

API ارسال وضعیت قطع اتصال دستگاه #

برای ارسال وضعیت به ویرالینک مبنی بر اینکه دستگاه از درگاه قطع شده است، باید پیام زیر را منتشر کنید:

Topic: 
v1/gateway/disconnect

Message: 
{"device":"Device A"}

که در آن Device A نام دستگاه شما است.

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

API صفت‌ها #

API صفت های ویرالینک در دستگاه ها قابلیت های زیر را ایجاد می‌کند:

• صفت‌های دستگاه سمت سرویس گیرنده را در سرور آپلود کنید.
• صفت‌های دستگاه سمت سرویس گیرنده و اشتراک‌گذاری شده را از سرور درخواست کنید.
• در صفت‌های دستگاه مشترک از سرور مشترک شوید.
• به روزرسانی صفت را در سرور منتشر کنید.
• به منظور انتشار صفت‌های دستگاه سمت سرویس گیرنده در گره سرور ویرالینک، به موضوع:

v1/gateway/attributes

پیام زیر را بفرستید.

{"Device A":{"attribute1":"value1", "attribute2": 42}, "Device B":{"attribute1":"value1", "attribute2": 42}}

که در آن Device A و Device B نام دستگاه شما هستند، attribute1 و attribute2 کلیدهای صفت‌ها هستند.

درخواست صفت‌ها از سرور #

برای درخواست صفت‌های دستگاه سمت سرویس گیرنده(client-attributes) یا مشترک(shared-attributes) از سرور ویرالینک، به موضوع :

v1/gateway/attributes/request

پیام زیر را بفرستید.

{"id": $request_id, "device": "Device A", "client": true, "key": "attribute1"}

که در آن $request_id شناسه درخواست شما است، Device A نام دستگاه شما است، client تعیین می‌کند که صفت سمت سرویس گیرنده یا صفت مشترک می‌باشد و key کلید صفت است.

قبل از ارسال پیام، client باید به موضوع زیر مشترک (Subscribe) شود.

v1/gateway/attributes/response

و منتظر پیام‌هایی با فرمت زیر باشد:

{"id": $request_id, "device": "Device A", "value": "value1"}

مشترک شدن به بروزرسانی‌های صفت‌ها از طرف سرور #

برای اشتراک در تغییرات صفت‌های مشترک دستگاه، به موضوع زیر مشترک شوید:

v1/gateway/attributes

و منتظر پیام هایی با فرمت زیر باشید:

{"device": "Device A", "data": {"attribute1": "value1", "attribute2": 42}}

آپلود داده‌های تلمتری #

به منظور انتشار تله‌متری دستگاه به سرور ویرالینک، به موضوع :

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 نام دستگاه شما هستند، temprature (دما) و humidity (رطوبت) کلیدهای تله‌متری هستند و ts زمان یونیکس(unix timestamp) بر حسب میلی ثانیه است.

RPC API #

Server-side RPC #

برای اشتراک در دستورات RPC از سرور به موضوع زیر مشترک شوید:

v1/gateway/rpc

و منتظر پیام هایی با دستورات فردی در قالب زیر باشید:

{"device": "Device A"، "data": {"id": $request_id, "method": "toggle_gpio"، "params": {"pin":1}}}

هنگامی که دستور توسط دستگاه پردازش شد، درگاه می تواند دستورات را با استفاده از فرمت زیر ارسال کند:

{"device": "Device A"، "id": $request_id، "data": {"success": true}}

که در آن $request_id شناسه درخواست عددی شما است، Device A نام دستگاه شما و method نام تابع RPC شما است.

API تخصیص خودکار دستگاه‌ها (Claiming devices API) #

لطفاً مقاله مربوطه را برای دریافت اطلاعات بیشتر در مورد تخصیص خودکار دستگاه‌ها مشاهده کنید.

برای شروع تخصیص دستگاه، به موضوع :

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 مشخص نشده باشد، از مقدار پیش فرض استفاده می شود.