اعلام مالکیت دستگاه‌ها

توصیف سناریوی کاربرد

به عنوان یک مالک (Tenant)، می‌خواهم بتوانم دستگاه‌هایم را از طریق اسکریپت یا رابط کاربری پیش‌پیکربندی کنم. مشتریان من دستگاه‌ها را مستقیماً از من یا از طریق توزیع‌کنندگان خریداری می‌کنند. مایلم که مشتریان پس از دریافت فیزیکی دستگاه، آن‌ها را از طریق کد QR یا تکنیکی مشابه ادعا کنند.

هنگامی که دستگاه ادعا شد، مشتری به مالک آن تبدیل می‌شود و کاربران مشتری می‌توانند به داده‌های دستگاه دسترسی داشته باشند و آن را کنترل کنند.

سناریوهای ادعای دستگاه

کاربر ThingsConnect می‌تواند دستگاه را ادعا کند اگر نام دستگاه و کلید مخفی (Secret Key) را "بداند". کلید مخفی اختیاری است، همیشه زمان انقضا دارد و ممکن است با گذشت زمان تغییر کند.

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

  1. سناریوی کلید از سمت دستگاه: دستگاه شامل یک ویژگی expirationTime در سمت سرور است که حاوی زمان انقضا است. دستگاه درخواست ادعای خود را با داده‌های ادعایی به ThingsConnect ارسال می‌کند و تنها پس از این مشتری قادر است با استفاده از ابزارک ادعای دستگاه، دستگاه را ادعا کند.
  2. سناریوی کلید از سمت سرور: دستگاه شامل یک ویژگی claimingData در سمت سرور است که حاوی داده‌های ادعایی است و مشتری با استفاده از ابزارک ادعای دستگاه، دستگاه را ادعا می‌کند.

برای جزئیات بیشتر به ادامه مطلب مراجعه کنید.

ادعای مالکیت با استفاده از سناریوی کلید سمت دستگاه
ادعای مالکیت با استفاده از سناریوی کلید سمت سرور

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

به طور پیش‌فرض، می‌توانید تاریخ انقضا را به‌عنوان زمانی که درخواست دریافت شده است به‌علاوه یک روز تنظیم کنید. برای افزایش مدت زمان، باید مقدار پارامتر caffeine.specs.claimDevices.timeToLiveInMinutes را در فایل thingsconnect.yaml بیشتر کنید.

سرور ThingsConnect اطلاعات ادعا (Claiming Information) را برای مدت اعتبار کلید ذخیره می‌کند. نمودار زیر را مشاهده کنید.

image

دستگاه می‌تواند اطلاعات ادعا را با استفاده از تمام پروتکل‌های حمل‌ونقل پشتیبانی‌شده به ThingsConnect ارسال کند. بدنه پیام شامل دو پارامتر است: secretKey و durationMs که ممکن است به‌صورت اختیاری مشخص شوند. پارامتر secretKey به فرآیند ادعا امنیت اضافه می‌کند. پارامتر durationMs زمان انقضای ادعا را تعیین می‌کند. در صورتی که پارامتر secretKey مشخص نشود، مقدار پیش‌فرض آن رشته خالی است. اگر پارامتر durationMs مشخص نشده باشد، از پارامتر سیستمی device.claim.duration (در فایل /etc/thingsconnect/conf/thingsconnect.yml) استفاده می‌شود.

برای فعال‌سازی ویژگی ادعای دستگاه‌ها، پارامتر سیستمی security.claim.allowClaimingByDefault (به راهنمای تنظیمات مراجعه کنید) باید روی true تنظیم شود. در غیر این صورت، ویژگی server-side با نام claimingAllowed با مقدار true برای دستگاه‌های پیکربندی‌شده ضروری است.

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

  • API دستگاه MQTT
  • API دستگاه CoAP
  • API دستگاه HTTP
  • API دروازه MQTT

پس از ارسال اطلاعات ادعا، دستگاه می‌تواند کلید محرمانه (Secret Key) را به‌صورت متن ساده یا از طریق کد QR نمایش دهد. کاربر باید این کلید را اسکن کرده و از آن برای ارسال درخواست ادعا (Claiming Request) استفاده کند. درخواست ادعا شامل نام دستگاه و کلید محرمانه است. شما می‌توانید از آدرس MAC یا ویژگی‌های منحصربه‌فرد دیگر به‌عنوان نام دستگاه استفاده کنید. دستورالعمل ارسال درخواست ادعا را اینجا مشاهده کنید.

توجه: کلید محرمانه می‌تواند یک رشته خالی باشد. این ویژگی مفید است اگر دستگاه شما هیچ راهی برای نمایش کلید محرمانه نداشته باشد. به عنوان مثال، می‌توانید اجازه دهید دستگاه ظرف 30 ثانیه پس از فشردن دکمه ادعا روی دستگاه، ادعا شود. در این حالت کاربر فقط باید نام دستگاه (آدرس MAC، و غیره) را بداند.

سرور درخواست ادعا را تأیید کرده و با پاسخ ادعا (Claiming Response) که شامل وضعیت عملیات ادعا و شناسه دستگاه (Device ID) است، پاسخ می‌دهد.

پس از تنظیم اطلاعات ادعا، کاربر مشتری می‌تواند از ویجت Claim Device استفاده کند.

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

ابزارک ادعای دستگاه

  • شما می‌توانید ابزارک ادعای دستگاه را در بخش Static widget از مجموعه ابزارک‌های Input پیدا کنید. ابزارک ادعای دستگاه بسیار ساده است و امکان وارد کردن نام دستگاه و کلید مخفی (Secret Key) را فراهم می‌کند.
  • این امکان وجود دارد که فیلد ورودی کلید مخفی را "پنهان" کرده و برچسب‌ها را در تنظیمات عمومی (General settings) تغییر دهید. همچنین می‌توانید در بخش تنظیمات پیام‌ها (Message settings) انواع پیام‌ها را برای کاربر پیکربندی کنید.
  • در نهایت، می‌توانید دستگاه ادعا شده را به موجودیت فعلی داشبورد مرتبط کنید. این قابلیت زمانی مفید است که چندین دارایی داشته باشید و بخواهید دستگاه خود را به یکی از آن‌ها مرتبط کنید.

درخواست API برای ثبت دستگاه

درخواست ثبت به‌صورت یک درخواست POST به URL زیر ارسال می‌شود:

				
					http(s)://host:port/api/customer/device/$DEVICE_NAME/claim
				
			

برای تغییر این متن بر روی دکمه ویرایش کلیک کنید. لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ و با استفاده از طراحان گرافیک است.

				
					{
  "secretKey":"value"
}
				
			

توجه: پیام شامل پارامتر durationMs نیست و پارامتر secretKey اختیاری است.

هر زمان که ثبت دستگاه موفقیت‌آمیز باشد، دستگاه به یک مشتری خاص اختصاص داده می‌شود. در صورتی که پارامتر سیستمی allowClaimingByDefault برابر با false باشد، ویژگی claimingAllowed به‌طور خودکار حذف می‌شود.

علاوه بر این، امکان بازپس‌گیری دستگاه نیز وجود دارد، به این معنی که دستگاه از مشتری لغو تخصیص می‌شود. در این حالت، ویژگی claimingAllowed دوباره ظاهر می‌شود، در صورتی که پارامتر allowClaimingByDefault برابر با false باشد.

برای اطلاعات بیشتر در مورد مراحل فوق، به موارد زیر مراجعه کنید.

درخواست API برای بازپس‌گیری دستگاه

برای بازپس‌گیری دستگاه، می‌توانید یک درخواست DELETE به URL زیر ارسال کنید (فراموش نکنید که نام دستگاه را با نام صحیح جایگزین کنید):

				
					curl -X DELETE https://thingsboard.cloud/api/customer/device/$DEVICE_NAME/claim
				
			

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

				
					{
  "result": {},
  "setOrExpired": true
}
				
			

اسکریپت‌های مثال پایتون

در این بخش می‌توانید مثال‌های کدی برای ویژگی ثبت دستگاه را مشاهده کنید.
ما از ماژول پایتون tb-mqtt-client برای اتصال و ثبت دستگاه استفاده خواهیم کرد.
شما می‌توانید آن را با استفاده از فرمان زیر نصب کنید:

				
					pip3 install tb-mqtt-client --user
				
			

مثال پایه برای ثبت دستگاه

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

شرح مورد: ما یک دستگاه با نام Test claiming device در ThingsConnect داریم.
این دستگاه دارای اعتبارسنجی توکن دسترسی به‌صورت Eypdinl1gUF5fSerOPJF است.

ما باید اسکریپت زیر را دانلود کرده و آن را اجرا کنیم تا درخواست ثبت را به سرور ارسال کنیم.

				
					#
# Copyright © 2016-2024 The Thingsboard Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

from tb_device_mqtt import TBDeviceMqttClient

def collect_required_data():
    config = {}
    print("\n\n", "="*80, sep="")
    print(" "*20, "ThingsBoard basic device claiming example script.", sep="")
    print("="*80, "\n\n", sep="")
    host = input("Please write your ThingsBoard server hostname or leave it blank to use default (thingsboard.cloud): ")
    config["host"] = host if host else "mqtt.thingsboard.cloud"
    token = ""
    while not token:
        token = input("Please write accessToken for device: ")
        if not token:
            print("Access token is required!")
    config["token"] = token
    config["secret_key"] = input("Please write secret key for claiming request: ")
    if not config["secret_key"]:
        print("Please make sure that you have claimingData in server attributes for device to use this feature without device secret in the claiming request.")
    duration_ms = input("Please write duration in milliseconds for claiming request or leave it blank to use default (30000): ")
    config["duration_ms"] = int(duration_ms) if duration_ms else 30000
    print("\n", "="*80, "\n", sep="")
    return config


if __name__ == '__main__':
    config = collect_required_data()
    client = TBDeviceMqttClient(config["host"], username=config["token"])
    client.connect()
    rc = client.claim(secret_key=config["secret_key"], duration=config["duration_ms"]).get()
    if rc == 0:
        print("Claiming request was sent, now you should use claiming device widget to finish the claiming process.")
				
			

مراحل بعدی

  • راهنماهای شروع به کار - این راهنماها یک مرور سریع از ویژگی‌های اصلی ThingsConnect را ارائه می‌دهند. طراحی شده‌اند تا در ۱۵ تا ۳۰ دقیقه به پایان برسند.
  • اتصال دستگاه - نحوه اتصال دستگاه‌ها بر اساس فناوری یا راه‌حل ارتباطی خود را یاد بگیرید.
  • بصری‌سازی داده‌ها - این راهنماها شامل دستورالعمل‌هایی برای پیکربندی داشبوردهای پیچیده ThingsConnect هستند.
  • پردازش داده‌ها و اقدامات - نحوه استفاده از موتور قوانین ThingsConnect را یاد بگیرید.
  • تحلیل داده‌های IoT - نحوه استفاده از موتور قوانین برای انجام وظایف تحلیلی پایه را یاد بگیرید.
  • نمونه‌های سخت‌افزار - نحوه اتصال پلتفرم‌های مختلف سخت‌افزاری به ThingsConnect را یاد بگیرید.
  • مشارکت و توسعه - با مشارکت و توسعه در ThingsConnect آشنا شوید.
1
2

1

عناوین هر بخش