شروع به کار #

آشنایی با CoAP #

CoAP یک پروتکل ارتباطی سبک برای دستگاه‌های IoT مناسب است. برای اطلاعات بیشتر در رابطه با پروتکل CoAP به سایت ietf.org مراجعه فرمایید. پروتکل CoAP بر پایه ارتباط UDP است. این پروتکل بسیار شیبه به HTTP و مبتنی بر مدل request-response است. observerهای CoAP به شما امکان می‌دهد تا به تغییرات منابع مشترک شوید (subscribe کنید). پلتفرم ویرالینک به عنوان سرور CoAP عمل می‌کند که هم درخواست‌های عادی و هم درخواست‌های observe را پشتیبانی می‌کند.

نصب کتابخانه‌های CoAP #

برای اتصال به سرور‌های CoAP پلتفرم ویرالینک، شما نیاز به کتابخانه‌های سمت کاربر (CoAP Client Libraries) دارید. بسته به بستری که در آن کار می‌کنید کتابخانه‌های متعددی وجود دارد که می‌توانید به سادگی پیدا کنید. در مثال‌های این مستندات از کتابخانه CoAP Cli استفاده می‌شود. برای نصب این ابزار ها می‌توانید به بخش شروع به کار با ویرالینک مراجعه فرمایید.

CoAP ‌Cli پارامتر‌های پرس و جو (query parameters) را پشتیبانی نمی‌کند. در صورت نیاز به query parameters، می‌توانید coap client را نصب کنید. برای نصب coap client در محیط ubuntu دستور زیر را اجرا کنید:

Ubuntu 20.04

sudo apt install libcoap2-bin

Ubuntu 18.04

sudo apt install libcoap1-bin

اتصال به CoAP و خطاهای احتمالی #

ما برای اتصال به CoAP از توکن دسترسی (access token) استفاده خواهیم کرد که جلوتر در مثال‌ها ACCESS_TOKEN$ می‌نامیم. برنامه‌هایی که می‌خواهند درخواست CoAP دهند بایستی توکن دسترسی ACCESS_TOKEN$ را به عنوان پارامتر همراه با درخواست خود ارسال کنند. کد‌ها و خطا‌های احتمالی به شرح زیر است:

• 4.00 Bad Request – آدرس، پارامتر و یا بدنه پیام نامعتبر
• 4.01 Unauthorized – توکن دسترسی نامعتبر
• 4.04 Not Found – خطای عدم وجود منبع مدنظر

فرمت کلید-مقدار (Key-value format) #

به صورت پیشفرض ویرالینک محتوای کلید-مقدار در قالب json را پشتیبانی می‌کند. کلید همیشه به صورت یک رشته متن (String) بوده و نام صفت را مشخص میکند. مقدار یک صفت میتواند شامل string (رشته), boolean (منطقی), double (عدد اعشاری) , integer (عدد صحیح) و یا json باشد. برای مثال:

{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

API ارسال داده‌های‌سری زمانی #

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry

ساده ترین شکل فرمت داده‌ها

{"key1":"value1", "key2":"value2"}

یا

[{"key1":"value1"}, {"key2":"value2"}]

توجه داشته باشید که در هنگام دریافت پیام به صورت پیشفرض زمان timestamp آن لحظه ثبت خواهد شد. در صورتی که بخواهید زمان timestamp دلخواه خود و یا دستگاه را برای پیام مد نظر ثبت کنید میتوانید آن را در فرمت زیر ارسال نمایید.

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

در مثال بالا مقدار 1451649600512 زمان timestamp در واحد میلی ثانیه است. بنابراین این زمان معادل است با Fri, 01 Jan 2016 12:00:00.512 GMT.

{
  "ts": 1451649600512,
  "values": {
    "stringKey": "value1",
    "booleanKey": true,
    "doubleKey": 42.0,
    "longKey": 73,
    "jsonKey": {
      "someNumber": 42,
      "someArray": [1, 2, 3],
      "someNestedObject": {
        "key": "value"
      }
    }
  }
}

[{"key1":"value1"}, {"key2":true}]

{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

# Publish data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data-as-object.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry

# Publish data as an array of objects without timestamp (server-side timestamp will be used)
cat telemetry-data-as-array.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry

# Publish data as an object with timestamp (telemetry timestamp will be used)
cat telemetry-data-with-ts.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/telemetry

API صفت‌ها #

به کمک API صفت ها میتوانید:

• ارسال صفت‌‌های سمت کاربر (client-side attributes) به سرور
• درخواست مقادیر صفت های سمت کاربر و مشترک (shared attributes) از سرور
• subscribe کردن به صفت‌های مشترک از سرور (تا در زمان تغییر صفت‌ها در لحظه با خبر شوید).

ارسال صفت‌ها به سرور #

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

# Publish client-side attributes update
cat new-attributes-values.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes

API درخواست مقادیر صفت‌ها از سرور #

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

{"key1":"value1"}

# Send CoAP attributes request
coap-client -m get "coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

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

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

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes

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

{"key1":"value1"}

# Subscribe to attribute updates
coap get -o coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/attributes

RPC API #

RPC سمت سرور (Server-side RPC) #

RPC‌های سمت سرور دستورات RPC درخواستی از سمت سرور هستند که به دستگاه ارسال می شوند. دستگاه بایستی پس از اجرای دستورات نتیجه آن را به سرور ارسال کند.
برای مشترک شدن به دستورات RPC از سرور کافیست درخواست GET را به آدرس زیر ارسال کنید. با این کار دستورات RPC درخواستی از سمت سرور را در همان لحظه دریافت خواهید کرد.

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

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

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

توضیح پارامتر ها:

• id – شناسه درخواست
• method – نام تابع RPC, string
• params – پارامتر های تابع RPC, json object

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc/{$id}

که id$ شناسه درخواست میباشد.

{"result":"ok"}

# Publish response to RPC request
cat rpc-response.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc/1

# Subscribe to RPC requests
coap get -o coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

RPC سمت کاربر (Client-side RPC) #

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

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

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

{"time":"2016 11 21 12:54:44.287"}

{"method": "getTime", "params":{}}

# Post client-side rpc request
cat rpc-client-request.json | coap post coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/rpc

درخواست تخصیص دستگاه #

در صورتی که با ویژگی تخصیص خودکار دستگاه آشنایی ندارید، ابتدا آن را مطالعه بفرمایید.
برای درخواست تخصیص دستگاه درخواست POST را به آدرس زیر ارسال نمایید.

coap://console.viralink.ir/api/v1/$ACCESS_TOKEN/claim

فرمت پشتیانی شده برای محتوای پیام

{"secretKey":"value", "durationMs":60000}

توجه نمایید که فیلد های بالا اختیاری است. در صورتی که secretKey در پیام وجود نداشته باشد، یک رشته متن (string) خالی به عنوان مقدار پیشفرض ارسال میشود و همچنین در صورتی که durationMs وجود نداشته باشد، مقدار پیشفرض device.claim.duration استفاده خواهد شد.