مرجع API دستگاه LWM2M
پیشنیازها
پیش از شروع، فرض میکنیم که شما راهنمای عمومی "شروع کار" با ThingsConnect را مطالعه کرده و با آن آشنا شدهاید.
اصول اولیه LwM2M
LwM2M یک پروتکل مدیریت دستگاه است که برای دستگاههای محدود و نیازهای محیط ماشین به ماشین (M2M) طراحی شده است. اطلاعات بیشتر درباره LwM2M را میتوانید اینجا پیدا کنید. یکی از مزایای کلیدی این پروتکل، کتابخانهای غنی از ساختارهای دادهای است که به عنوان "ثبت اشیا و منابع LwM2M" شناخته میشود. فهرست بهروز اشیای موجود در این مخزن گیتهاب قرار دارد.
این ثبت به سریالسازی/دیسریالسازی کارآمد دادههای تلهمتری کمک میکند. پروتکل LwM2M فرآیندهایی مانند ثبت دستگاه، پیکربندی، مدیریت و بهروزرسانیهای نرمافزاری/سختافزاری را تعریف میکند.
دستگاه LwM2M در زمان ثبت، فهرستی از اشیای LwM2M پشتیبانیشده توسط خود را ارائه میدهد. هر شیء LwM2M دارای یک شناسه (ID)، نسخه و یک یا چند نمونه است. هر نمونه از شیء شامل چندین منبع است.
"منبع" در LwM2M یک مفهوم کلیدی است که دادههایی را نشان میدهد که میتوانید از دستگاه دریافت یا به آن ارسال کنید. بهعنوان مثال، منبع "3.0.2" همواره شماره سریال دستگاه را نشان میدهد، جایی که "3" شناسه شیء، "0" نمونه شیء و "2" شناسه منبع است.
هر منبع دارای ویژگیهای اصلی زیر است:
- نام: نام قابلخواندن برای انسان
- نوع: نوع داده، مانند رشته، عدد صحیح و غیره
- عملیات: شامل R (خواندن)، RW (خواندن-نوشتن)، E (اجرا) و غیره
شروع به کار
این بخش از مستندات به راهاندازی اولین دستگاه LwM2M در ThingsConnect اختصاص دارد. برای شبیهسازی دستگاه LwM2M، از کلاینت تست Eclipse Wakaama استفاده خواهیم کرد.
Title text example
مدیر سیستم میتواند مدلهای LwM2M را از طریق رابط کاربری "کتابخانه منابع" در منوی "تنظیمات سیستم" بارگذاری کند. امکان بارگذاری چندین فایل بهطور همزمان وجود دارد. توصیه میشود فهرست مدلهای موجود را از مخزن رسمی گیتهاب دانلود کرده و تمامی آنها را وارد کنید. توجه داشته باشید که مدلهای LwM2M دارای نسخهبندی هستند، بنابراین اطمینان حاصل کنید که نسخههای آپلودشده با نسخههای اشیای LwM2M دستگاههای شما مطابقت دارند.
- وارد حساب کاربری خود در ThingsConnect شوید و به مسیر تنظیمات سیستم -> کتابخانه منابع بروید، سپس روی دکمه "+" کلیک کنید.
- فایلهای مدل منابع را بارگذاری کنید.
- اطمینان حاصل کنید که فایلهای جدید در فهرست قابل مشاهده هستند.
مدیر Tenant میتواند از مدلهای LwM2M که توسط مدیر سیستم تعریف شدهاند استفاده کرده یا آنها را برای Tenant خاص بازنویسی کند.
- مدیر Tenant اجازه ندارد فایلهایی را که توسط مدیر سیستم بارگذاری شدهاند حذف کند.
- مدیر Tenant میتواند فایلهای مدل منابعی را که مدیر سیستم برای همان منبع بارگذاری کرده است، بارگذاری و بازنویسی کند.
- مدیر Tenant میتواند فایلهایی را که خودش بارگذاری کرده است حذف کند.
- اگر مدیر Tenant فایلهای خود را حذف کند، فایلهای بارگذاریشده توسط مدیر سیستم همچنان باقی خواهند ماند.
گام 2. تعریف پروفایل دستگاه LwM2M
پس از بارگذاری مدلهای LwM2M، شما آمادهاید از آنها برای تعریف پروفایل دستگاه استفاده کنید. برای اطلاعات بیشتر در مورد پروفایلهای دستگاه، به مستندات عمومی پروفایل دستگاه مراجعه کنید.
گام 2.1 ایجاد پروفایل LwM2M
گام مهم در این مرحله انتخاب نوع انتقال LwM2M در مرحله "پیکربندی انتقال" است. پیکربندی انتقال به ما این امکان را میدهد که فهرستی از اشیاء LwM2M که دستگاههای شما از آنها پشتیبانی میکنند، تعریف کنیم.
- به بخش پروفایلهای دستگاه بروید، بر روی "+" کلیک کنید، نام پروفایل را وارد کرده و قانون زنجیرهای را انتخاب یا ایجاد کنید که پیامها را پردازش خواهد کرد.
- نوع انتقال "LwM2M" را از منوی کشویی انتخاب کنید.
- پروفایل جدید با موفقیت ایجاد شد.
گام 2.2 انتخاب اشیاء LwM2M
بیایید پروفایلی را تعریف کنیم که از اشیاء دستگاه (id: 3)، اتصال (id: 4)، بروزرسانی فریمور (id: 5) و نظارت بر موقعیت (id: 6) پشتیبانی کند:
به بخش پروفایلهای دستگاه بروید، گزینه "LWM2M" را انتخاب کنید، به تب "پیکربندی انتقال" بروید و بر روی دکمه "ویرایش" کلیک کنید.
اشیاء را از منوی کشویی اضافه کنید. اشیاء باید به کتابخانه منابع آپلود شده باشند.
گام 2.3 پیکربندی نگاشت
ممکن است متوجه شوید که شیء دستگاه از اطلاعات سازنده، مدل و شماره سریال پشتیبانی میکند. بیایید ThingsConnect را پیکربندی کنیم تا این دادهها را هنگام اتصال دستگاه دریافت کرده و به عنوان ویژگیهای ThingsConnect ذخیره کند. همچنین، میخواهیم قدرت سیگنال رادیویی، کیفیت لینک و موقعیت دستگاه را نظارت کرده و آنها را به عنوان دادههای Telemetry به ThingsConnect ارسال کنیم. ویژگی "نظارت" یک ویژگی قدرتمند در LwM2M است که به دستگاه دستور میدهد تا تغییرات این مقادیر را گزارش کند. همچنین میتوانید شرایطی برای گزارش منابع خاص از طریق ویژگیهای LwM2M تعریف کنید. این تنظیمات در مستندات پیشرفته پوشش داده شده است.
- برای دادههایی که میخواهید هنگام اتصال دستگاه دریافت کرده و به عنوان ویژگیهای ThingsConnect ذخیره شوند، کادر "Attributes" را تیک بزنید.
- اگر میخواهید سرور آنها را نظارت کرده و مقادیر بهروزرسانیشده را دریافت کند، کادرهای Telemetry و/یا Observe را تیک بزنید.
- تغییرات را ذخیره کنید.
توجه: اگر تمام گزینهها را از شیء (Telemetry، Attributes، Observe) حذف کنید، این شیء در پروفایل دستگاه نمایش داده نخواهد شد.
پیکربندی انتقال همچنین به شما این امکان را میدهد که راهاندازی اولیه (bootstrap) و تنظیمات دیگر را تعریف کنید.
گام 3. تعریف اعتبارنامههای دستگاه LwM2M
ما فرض میکنیم که شما پروفایل دستگاه LwM2M را با استفاده از گام قبلی ایجاد کردهاید.
حال، بیایید دستگاه را با استفاده از پروفایل خود ایجاد کرده و اعتبارنامههای LwM2M را پیکربندی کنیم. ThingsConnect از 4 نوع مختلف اعتبارنامه پشتیبانی میکند: کلید اشتراک پیشین (PSK)، کلید عمومی خام (RPK)، گواهینامه X.509 و حالت "بدون امنیت".
- حالت پیشفرض: حالت بدون امنیت
- اضافه کردن اعتبارنامههای دستگاه: کلید اشتراک پیشین
- اضافه کردن اعتبارنامههای دستگاه: کلید عمومی خام
- اضافه کردن اعتبارنامههای دستگاه: گواهینامه X.509
برای سادگی، ما دستگاه را با استفاده از UDP ساده و حالت "بدون امنیت" متصل خواهیم کرد. برای اتصال چنین دستگاهی تنها کافی است نام نقطهانتهایی آن را در اعتبارنامههای دستگاه مشخص کنیم.
- در حالت "بدون امنیت"، نام مشتری نقطهانتهایی (Endpoint Client Name) برای شناسایی دستگاه استفاده میشود.
شما میتوانید از انواع دیگر اعتبارنامهها با حالت DTLS فعال استفاده کنید. برای اطلاعات بیشتر، پیکربندی DTLS را مشاهده کنید.
گام 4. اتصال دستگاه
ما فرض میکنیم که شما اعتبارنامههای دستگاه LwM2M را با استفاده از گام قبلی فراهم کردهاید و همچنین کلاینت آزمایشی Eclipse Wakaama را ساختهاید. حالا شما آمادهاید دستگاه را روشن کرده و دادههای ورودی telemetry را مشاهده کنید.
بیایید کلاینت آزمایشی را راهاندازی کنیم:
./lwm2mclient -h demo.thingsboard.io -n UniqueEndpointName -p 5685 -c
در اینجا:
- «demo.ThingsConnect.io» نام میزبان سرور LwM2M است؛
- «5685» پورت سرور LwM2M است؛
- «UniqueEndpointName» نام منحصر به فرد نقطهانتهایی شما است. لطفاً این را با IMEI یا شناسه منحصر به فرد دیگری جایگزین کنید.
پیادهسازی انتقال LwM2M همچنین گزارشات ارتباط با دستگاه را در telemetry ذخیره میکند. شما باید «transportLog» را در تب telemetry دستگاه مشاهده کنید.
- پنجره ترمینال با کلاینت Wakaama
- شما میتوانید آخرین پیام را در بخش Transport Log مشاهده کنید.
پشتیبانی LwM2M در ThingsConnect
ThingsConnect هم سرور LwM2M و هم سرور راهاندازی (bootstrap) را پیادهسازی میکند که از UDP ساده و DTLS (انتقال امن بر روی UDP) پشتیبانی میکنند. به عنوان یک کاربر پلتفرم، شما قادر خواهید بود تا دستگاه را راهاندازی کرده و نگاشت بین منابع LwM2M و ویژگیهای دستگاه و دادههای سری زمانی ThingsConnect را تعریف کنید. این نگاشت در پروفایل دستگاه مربوطه پیکربندی میشود. برای توضیح اصول اولیه، ما از برخی اسکرینشاتهای پروفایل دستگاه LwM2M استفاده خواهیم کرد. برای دستورالعمل گام به گام جهت ایجاد پروفایل دستگاه، راهنمای "شروع به کار" را مشاهده کنید.
خواندن منابع LwM2M به ویژگیهای ThingsConnect
شما میتوانید پروفایل دستگاه را پیکربندی کنید تا یک منبع خاص LwM2M را بخواند و نظارت کند. مقادیر منبع ممکن است به عنوان ویژگیهای دستگاه ذخیره شوند. برای انجام این کار، کادر "Attribute" را برای منبع مربوطه تیک بزنید. شما میتوانید نام کلید بهطور خودکار تولید شده را تغییر داده و نام ویژگی را در ThingsConnect تعریف کنید. به عنوان مثال، بیایید پلتفرم را پیکربندی کنیم تا منبع LwM2M /3/0/2 (شماره سریال دستگاه) را بخواند و آن را به عنوان ویژگی serialNumber در ThingsConnect ذخیره کند:
ThingsConnect مقدار ویژگی را در حین ثبت دستگاه (عملیات LwM2M “Register”) یا در حین بهروزرسانی ثبتنام (عملیات LwM2M “Update”) میخواند.
توجه:
ما به طور اختیاری میتوانیم عملیات “Observe” را صادر کنیم تا مطمئن شویم که بهروزرسانیهای منبع LwM2M را دنبال میکنیم. برای انجام این کار، کادر "Observe" را برای منبع مربوطه تیک بزنید. بیایید ThingsConnect را پیکربندی کنیم تا منبع LwM2M /3/0/15 (منطقه زمانی) را نظارت کرده و آن را به عنوان ویژگی timezone ذخیره کند:
با استفاده از پیکربندی فوق، اطمینان حاصل میکنیم که ویژگی timezone همیشه جدیدترین مقدار منبع منطقه زمانی را شامل خواهد شد.
نوشتن منابع LwM2M از طریق بهروزرسانی ویژگیهای ThingsConnect
ویژگیهای مشترک ThingsConnect برای ارسال بهروزرسانیهای پیکربندی به دستگاه استفاده میشوند. شما میتوانید ویژگی مشترک را از طرق مختلف تغییر دهید - از طریق رابط کاربری مدیریت، ویجت داشبورد، API REST، یا گرههای موتور قوانین. زمانی که ویژگی مشترک را تغییر میدهید، ThingsConnect به جستجو برای نگاشت بین کلید ویژگی و منبع LwM2M خواهد پرداخت. اگر منبع به عنوان ویژگی علامتگذاری شده باشد، پلتفرم عملیات نوشتن LwM2M را به دستگاه LwM2M ارسال خواهد کرد.
برای مثال، از مثال منطقه زمانی برای ویژگیهای خواندنی استفاده کنید.
خواندن منابع LwM2M به دادههای سری زمانی
شما میتوانید پروفایل دستگاه را پیکربندی کنید تا یک منبع خاص LwM2M را بخواند و نظارت کند. مقادیر منبع ممکن است به عنوان دادههای سری زمانی دستگاه ذخیره شوند. برای انجام این کار، کادر "Telemetry" را برای منبع مربوطه تیک بزنید. شما میتوانید نام کلید بهطور خودکار تولید شده را تغییر داده و کلید دادههای سری زمانی را در ThingsConnect تعریف کنید. به عنوان مثال، بیایید پلتفرم را پیکربندی کنیم تا منابع LwM2M زیر را بخواند: /3/0/7 (ولتاژ منبع تغذیه)، /3/0/8 (جریان منبع تغذیه)، /3/0/9 (سطح باتری)، و /3/0/10 (حافظه آزاد) و آنها را به عنوان دادههای سری زمانی در ThingsConnect ذخیره کند:
اجرای عملیات LwM2M با استفاده از فرمان RPC درThingsConnect
ThingsConnect از عملیات LwM2M به صورت درخواستشده با استفاده از ویژگی RPC (تماس از راه دور) پشتیبانی میکند. ما همچنین از "فرمان" به جای RPC برای سادگی استفاده میکنیم. شما میتوانید فرمان را از طریق API REST، ویجت داشبورد، موتور قوانین یا اسکریپت سفارشی ارسال کنید. ساختار فرمان در اینجا مستند شده است.
ویژگیهای کلیدی فرمان عبارتند از روش (method) و پارامترها (params). روش، عملیات LwM2M را تعریف میکند و یکی از موارد زیر است:
- Execute - توسط سرور LwM2M برای آغاز یک عمل استفاده میشود؛
- Read - دسترسی به مقدار یک منبع؛
- Discover - کشف منابع LwM2M موجود در یک شی یا نمونه شی؛
- WriteUpdate - تغییر مقدار یک منبع؛
- WriteAttributes - تغییر ویژگیهای یک منبع؛
- ReadComposite - خواندن انتخابی هر ترکیبی از اشیاء؛
- WriteComposite - تغییر مقادیر چندین منبع مختلف در نمونههای مختلف یک یا چند شیء؛
- Delete - حذف یک نمونه شیء از دستگاه LwM2M؛
- Observe - آغاز درخواست نظارت برای تغییرات یک منبع خاص؛
- ObserveCancel - پایان رابطه نظارتی که قبلاً با عملیات "Observe" ایجاد شده است؛
- ObserveCancelAll - عملیات خاص ThingsConnect و امکان لغو تمام نظارتها روی دستگاه به طور همزمان؛
- ObserveReadAll - عملیات خاص ThingsConnect و امکان دریافت تمام نظارتهایی که روی دستگاه تنظیم شدهاند؛
- DiscoverAll - عملیات خاص ThingsConnect و امکان دریافت سلسلهمراتب اشیاء و منابع، نمونهسازی شده در دستگاه.
پارامترها معمولاً یک JSON هستند که شناسه منبع یا چندین شناسه منبع را تعریف میکند. به عنوان مثال، برای راهاندازی مجدد دستگاه، باید عملیات منبع /3/0/4 (Reboot) را اجرا کنید.
بنابراین، فرمان RPC زیر باید به ThingsConnect ارسال شود:
{
"method": "Execute",
"params": {"id": "/3/0/4"}
}
ما یک داشبورد ساده آماده کردهایم که امکان اجرای فرمانها به دستگاه (/3/0/4 Reboot) و بروزرسانی ویژگیهای دستگاه (/3/0/15 Timezone) را فراهم میکند. شما میتوانید پس از تکمیل راهنمای "شروع به کار" زیر، این داشبورد را از گیت دریافت کنید. فراموش نکنید که نام مستعار داشبورد را تغییر دهید.
فرمانهای RPC
انتقال LwM2M از فرمانهای RPC پشتیبانی میکند که زیرمجموعهای از رابط مدیریت دستگاه و فعالسازی سرویس و رابط گزارشدهی اطلاعات را منعکس میکند.
رابط مدیریت دستگاه و فعالسازی سرویس توسط سرور LwM2M برای دسترسی به نمونههای شیء و منابع موجود در یک دستگاه LwM2M ثبتنام شده استفاده میشود. عملیاتهایی که یک منبع پشتیبانی میکند در تعریف شیء با استفاده از الگوی شیء تعریف میشود.
رابط گزارشدهی اطلاعات توسط سرور LwM2M برای مشاهده هرگونه تغییر در یک منبع در یک دستگاه LwM2M ثبتنام شده استفاده میشود و هنگامی که مقادیر جدید در دسترس باشند، اعلانهایی دریافت میکند. این رابطه مشاهدات با ارسال یک عملیات "مشاهده" یا "مشاهده ترکیبی" به دستگاه LwM2M برای یک شیء، یک نمونه شیء یا یک منبع آغاز میشود. مشاهدات زمانی پایان مییابد که عملیات "لغو مشاهده" یا "لغو مشاهده ترکیبی" انجام شود.
ما از ویجت ترمینال اشکالزدایی برای ارسال فرمانها به دستگاه استفاده خواهیم کرد.
برای اجرای فرمانهای مربوط به ویژگیها دو روش برای مشخص کردن منبع هدف وجود دارد: از طریق شناسه منبع و از طریق کلید.
شناسه منبع ترکیبی از اعداد "/ObjectId/ObjectInstance/ResourceID" است که در آن:
- «ObjectId» نشاندهنده شماره شیء است. اشیاء برای گروهبندی منابع بر روی دستگاه استفاده میشوند که به عملکرد خاصی مربوط هستند.
- «ObjectInstance» نشاندهنده نمونه شیء برای خواندن است.
- «ResourceID» نشاندهنده منبع برای خواندن است.
مثالی از تماس ساده RPC برای REST API:
{
"method": "Read",
"params": {"id": "/3/0/9"}
}
یا
{
"method": "Read",
"params": {"key": "batteryLevel"}
}
مثالی از ورودی مربوطه در ترمینال اشکالزدایی:
Read {"id":"/3/0/9"}
کلید یک نام سفارشی و کاربرپسند است که به ویژگی خاصی اختصاص داده میشود.
مثال برای ترمینال اشکالزدایی RPC:
Read {"key":"batteryLevel"}
برای استفاده از کلید، باید آن را به ویژگی در بخش پیکربندی پروفایل دستگاه اختصاص دهید:
- به صفحه Device Profiles بروید.
- نام پروفایل مورد نظر را انتخاب کنید.
- روی دکمه "مداد" در گوشه بالای سمت راست
- کلیک کنید تا پروفایل ویرایش شود.
- به تب Transport configuration بروید.
- به تب LWM2M Model بروید.
- شیء هدف را انتخاب کنید و لیست ویژگیها را باز کنید.
- کادر "Attribute" را برای ویژگی مورد نظر علامتگذاری کرده و نام کلید را وارد کنید.
- روی Save کلیک کنید.
در زیر میتوانید مثالهایی از نحوه استفاده از دستوراتی که توسط پلتفرم ThingsConnect برای پروتکل LWM2M پشتیبانی میشوند، مشاهده کنید. لطفاً توجه داشته باشید که ممکن است مشتری هدف شما از تمامی این دستورات پشتیبانی نکند، بنابراین برای اطلاعات دقیقتر در مورد دستورات پشتیبانی شده به مستندات مشتری مراجعه فرمایید.
عملیات خواندن
عملیات "خواندن" برای دسترسی به مقدار یک منبع، یک نمونه منبع، آرایهای از نمونههای منبع، یک نمونه شیء یا تمامی نمونههای شیء یک شیء استفاده میشود.
مثال: خواندن مقدار منبع از طریق شناسه
مثال از فراخوانی ساده RPC برای API REST:
{
"method": "Read",
"params": {"id": "/3/0/9"}
}
مثال ورودی مربوطه در ترمینال اشکالزدایی:
# Request:
Read {"id":"/3/0/9"}
# Response:
{"result":"CONTENT","value":"LwM2mSingleResource [id=9, value=100, type=INTEGER]"}
مثالهای بیشتر:
خواندن مقدار منبع از طریق شناسه و نسخه
# Request:
Read {"id":"/3_1.0/0/9"}
# Response:
{"result":"CONTENT","value":"LwM2mSingleResource [id=9, value=20, type=INTEGER]"}
خواندن مقدار منبع از طریق کلید
# Request:
Read {"key":"batteryLevel"}
# Response:
{"result":"CONTENT","value":"LwM2mSingleResource [id=9, value=27, type=INTEGER]"}
خواندن نمونه شیء
# Request:
Read {"id":"/3/0"}
# Response:
{"result":"CONTENT","value":"LwM2mObjectInstance [id=0, resources={0=LwM2mSingleResource [id=0, value=Thingsboard Test Device,
type=STRING], 1=LwM2mSingleResource [id=1, value=Model 500, type=STRING], 2=LwM2mSingleResource [id=2, value=TH-500-000-0001,
type=STRING], 3=LwM2mSingleResource [id=3, value=TestThingsboard@TestMore1024_2.04, type=STRING], 6=LwM2mSingleResource [id=6,
value=1, type=INTEGER], 7=LwM2mSingleResource [id=7, value=96, type=INTEGER], 8=LwM2mSingleResource [id=8, value=37, type=INTEGER],
9=LwM2mSingleResource [id=9, value=75, type=INTEGER], 10=LwM2mSingleResource [id=10, value=110673, type=INTEGER],
11=LwM2mMultipleResource [id=11, values={0=LwM2mResourceInstance [id=0, value=1, type=INTEGER]}, type=INTEGER], 13=LwM2mSingleResource
[id=13, value=Thu Jul 01 16:39:49 EEST 2021, type=TIME], 14=LwM2mSingleResource [id=14, value=+03, type=STRING], 15=LwM2mSingleResource
[id=15, value=Europe/Kiev, type=STRING], 16=LwM2mSingleResource [id=16, value=U, type=STRING], 17=LwM2mSingleResource
[id=17, value=smart meters, type=STRING], 18=LwM2mSingleResource [id=18, value=1.01, type=STRING], 19=LwM2mSingleResource [id=19,
value=1.02, type=STRING], 20=LwM2mSingleResource [id=20, value=2, type=INTEGER], 21=LwM2mSingleResource [id=21, value=256000, type=INTEGER]}]"}
عملیات کشف
عملیات "کشف" برای شناسایی منابع LwM2M موجود در اشیا یا نمونههای شیء استفاده میشود. این عملیات میتواند برای شناسایی منابعی که در یک نمونه شیء خاص ایجاد شدهاند، مورد استفاده قرار گیرد. دادههای بازگشتی شامل لیستی از لینکهای CoRE با فرمت application/link-format مطابق با RFC6690 برای هر شیء هدف، نمونه شیء، یا منبع است، به همراه ویژگیهای اختصاص داده شده یا متصل به آنها، از جمله ویژگی نسخه شیء در صورت نیاز.
نمونهای از ورودی مربوطه در ترمینال دیباگ:
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "Discover",
"params": {"id": "/3"}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
Discover {"id":"/3"}
# Response:
{"result":"CONTENT","value":"3>,3/0/0>,3/0/1>,3/0/2>,3/0/3>,3/0/4>,3/0/5>,3/0/6>,3/0/7>,3/0/8>,3/0/9>,3/0/10>,3/0/11>,3/0/12>,3/0/13>,3/0/
14>,3/0/15>,3/0/16>"}
مثالهای بیشتر:
کشف منابع متصل به نمونه شیء
# Request:
Discover {"id":"/3/0"}
# Response:
{"result":"CONTENT","value":"3/0>,3/0/0>,3/0/1>,3/0/2>,3/0/3>,3/0/4>,3/0/5>,3/0/6>,3/0/7>,3/0/8>,3/0/9>,3/0/10>,3/0/11>,3/0/12>,3/0/13>,3/
0/14>,3/0/15>,3/0/16>"}
بررسی اینکه آیا منبع با شناسه (Id) ایجاد شده است
# Request:
Discover {"id":"/3/0/1"}
# Response:
{"result":"CONTENT","value":"3/0/1>"}
بررسی اینکه آیا ویژگی با کلید (Key) ایجاد شده است
# Request:
Discover {"key":"batteryLevel"}
# Response:
{"result":"CONTENT","value":"3/0/9>"}
عملیات نوشتن
عملیات "نوشتن" برای تغییر مقدار یک منبع، مقدار یک نمونه منبع، مقادیر آرایهای از نمونههای منابع یا مقادیر چند منبع از یک نمونه شیء استفاده میشود. عملیات "نوشتن" همچنین میتواند برای درخواست حذف یا تخصیص نمونههای خاص از یک منبع چندنمونهای مورد استفاده قرار گیرد.
درخواست شامل مقدار قابل نوشتن است که در یکی از فرمتهای داده تعریفشده در بخش 7.4 (فرمتهای داده برای انتقال اطلاعات منابع) کدگذاری میشود. این فرمتها شامل: متن ساده (Plain Text)، داده مبهم (Opaque)، TLV، JSON، لینک CoRE، CBOR، SenML JSON، و SenML CBOR میباشند.
دو مکانیزم برای تغییر چند منبع یا آرایهای از نمونههای منابع وجود دارد:
جایگزینی (Replace): شیء یا منبع (ها) را با مقدار جدید ارائهشده در عملیات "نوشتن" جایگزین میکند. در صورتی که منبع یک منبع چندنمونهای باشد، آرایه موجود از نمونههای منبع جایگزین میشود، به شرطی که کلاینت LwM2M این عملیات را مجاز بداند.
بهروزرسانی جزئی (Partial Update): منابع ارائهشده در مقدار جدید را بهروزرسانی میکند و سایر منابع موجود را بدون تغییر باقی میگذارد. اگر منبع یک منبع چندنمونهای باشد، آرایه موجود از نمونههای منابع بهروزرسانی میشود، به این معنا که برخی نمونهها ممکن است ایجاد یا بازنویسی شوند، به شرطی که کلاینت LwM2M چنین عملیاتی را مجاز بداند. حذف از طریق بهروزرسانی جزئی امکانپذیر نیست.
مثال: بهروزرسانی نوشتاری یک منبع از یک نمونه شیء
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "WriteUpdate",
"params": {"id":"/3/0","value":{"14":"+5","15":"Kiyv/Europe"}}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
WriteUpdate {"id":"/3/0","value":{"14":"+5","15":"Kiyv/Europe"}}
# Response:
{"result":"CHANGED"}
Title text example
بهروزرسانی نوشتاری چند منبع از یک نمونه شیء
# Request:
WriteUpdate {"id": "/19/0","value": {"0":{"0":"00ad456756", "25":"25ad456756"}}}
# Response:
{"result":"CHANGED"}
بهروزرسانی نوشتاری چندین منبع
# Request:
WriteUpdate {"id": "/19/0/0","value": {"0":"00ad456756", "25":"25ad456756"}}
# Response:
{"result":"CHANGED"}
جایگزینی نوشتاری یک منبع
# Request:
WriteReplace {"id":"/19/0/0","value":"0081"}
# Response:
{"result":"CHANGED"}
جایگزینی نوشتاری یک منبع با استفاده از کلید
# Request:
WriteReplace {"key":"timezone","value":"+10"}
# Response:
{"result":"CHANGED"}
جایگزینی نوشتاری چندین منبع
# Request:
WriteReplace {"id": "/19_1.1/0/0","value": {"0":"00ad456797", "25":"25ad456700"}}
# Response:
{"result":"CHANGED"}
عملیات نوشتن ویژگیها
فقط ویژگیهای مربوط به کلاس NOTIFICATION میتوانند با استفاده از عملیات "نوشتن ویژگیها" تغییر یابند. بخش ویژگیهای شیء و منبع توضیحاتی در مورد ویژگیهای پشتیبانیشده توسط عملیات "نوشتن ویژگیها" ارائه میدهد که شامل: حداقل دوره (Minimum Period)، حداکثر دوره (Maximum Period)، بزرگتر از (Greater Than)، کوچکتر از (Less Than) و گام (Step) میباشد. این عملیات امکان تغییر چندین ویژگی را در یک عملیات واحد فراهم میکند.
مثال: نوشتن چندین ویژگی
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "WriteAttributes",
"params": {"id":"/19/0/0","attributes":{"pmax":120, "pmin":10}}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
WriteAttributes {"id":"/19/0/0","attributes":{"pmax":120, "pmin":10}}
# Response:
{"result":"CHANGED"}
عملیات خواندن مرکب
کلاینت LwM2M ممکن است از عملیات "خواندن مرکب" پشتیبانی کند. عملیات "خواندن مرکب" به سرور LwM2M این امکان را میدهد که به صورت انتخابی ترکیبی از اشیا، نمونههای شیء، منابع و/یا نمونههای منابع از اشیا مختلف یا مشابه را در یک درخواست واحد بخواند. لیست عناصر قابل خواندن بهصورت یک SenML Pack ارائه میشود، جایی که رکوردها شامل فیلدهای Base Name و/یا Name هستند اما فیلد Value ندارند. عملیات خواندن مرکب بهصورت غیراتمی در نظر گرفته میشود و کلاینت بر اساس بهترین تلاش ممکن آن را مدیریت میکند. به این معنا که اگر هر یک از منابع درخواستشده مقدار معتبری برای بازگشت نداشته باشند، در پاسخ گنجانده نخواهند شد.
مثال: خواندن چندین شیء
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "ReadComposite",
"params": {"ids":["/3/0/9", "/1_1.2"]}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
ReadComposite {"ids":["/3/0/9", "/1_1.2"]}
# Response:
{"result":"CONTENT","value":"{/3/0/9=LwM2mSingleResource [id=9, value=75, type=INTEGER], /1=LwM2mObject [id=1, instances={0=LwM2mObjectInstance [id=0, resources={0=LwM2mSingleResource [id=0, value=123, t
ype=INTEGER], 1=LwM2mSingleResource [id=1, value=300, type=INTEGER], 6=LwM2mSingleResource [id=6, value=false, type=BOOLEAN], 22=LwM2mSingleResource [id=22, value=U, type=STRING], 7=LwM2mSingleResource [
id=7, value=U, type=STRING]}]}]}"
مثالهای بیشتر:
خواندن مرکب چندین منبع با استفاده از کلیدها
# Request:
ReadComposite {"keys":["state", "updateResult", "pkgversion", "batteryLevel"]}
# Response:
{"result":"CONTENT","value":"{/5/0/7=LwM2mSingleResource [id=7, value=, type=STRING], /5/0/5=LwM2mSingleResource [id=5, value=0,
type=INTEGER], /5/0/3=LwM2mSingleResource [id=3, value=0, type=INTEGER], /
3/0/9=LwM2mSingleResource [id=9, value=81, type=INTEGER]}"}
خواندن مرکب چندین نمونه شیء
# Request:
ReadComposite {"ids":["/3/0", "/1_1.2/0"]}
# Response:
{"result":"CONTENT","value":"{/3/0=LwM2mObjectInstance [id=0, resources={0=LwM2mSingleResource [id=0, value=Thingsboard Test Device,
type=STRING], 1=LwM2mSingleResource [id=1, value=Model 500, type=STRING], 2=LwM2mSingleResource [id=2, value=TH-500-000-0001, type=STRING],
3=LwM2mSingleResource [id=3, value=TestThingsboard@TestMore1024_2.04, type=STRING], 6=LwM2mSingleResource [id=6, value=1, type=INTEGE
R], 7=LwM2mSingleResource [id=7, value=2, type=INTEGER], 8=LwM2mSingleResource [id=8, value=61, type=INTEGER], 9=LwM2mSingleResource [id=9,
value=25, type=INTEGER], 10=LwM2mSingleResource [id=10, value=102044, type=INTEGER], 11=LwM2mMultipleResource [id=11,
values={0=LwM2mResourceInstance [id=0, value=1, type=INTEGER]}, type=INTEGER], 13=LwM2mSingleResource [id=13,
value=Thu Jul 01 16:49:25 EEST 2021, type=TIME], 14=LwM2mSingleResource [id=14, value=+03, type=STRING], 15=LwM2mSingleResource [id=15,
value=Europe/Kiev, type=STRING], 16=LwM2mSingleResource [id=16, value=U, type=STRING], 17=LwM2mSingleResource [id=17, value=smart meters,
type=STRING], 18=LwM2mSingleResource [id=18, value=1.01, type=STRING], 19=LwM2mSingleResource [id=19, value=1.02, type=STRING],
20=LwM2mSingleResource [id=20, value=1, type=INTEGER], 21=LwM2mSingleResource [id=21, value=256000, type=INTEGER]}], /1/0=LwM2mObjectInstance
[id=0, resources={0=LwM2mSingleResource [id=0, value=123, type=INTEGER], 1=LwM2mSingleResource [id=1, value=300, type=INTEGER],
6=LwM2mSingleResource [id=6, value=false, type=BOOLEAN], 22=LwM2mSingleResource [id=22, value=U, type=STRING], 7=LwM2mSingleResource [id=7,
value=U, type=STRING]}]}"}
عملیات نوشتن مرکب
کلاینت LwM2M ممکن است از عملیات "نوشتن مرکب" پشتیبانی کند. برخلاف عملیات "نوشتن" که دامنه آن محدود به منابع یک نمونه از یک شیء واحد است، عملیات "نوشتن مرکب" به سرور این امکان را میدهد تا مقادیر تعدادی از منابع مختلف را در نمونههای مختلف یک یا چند شیء بهروزرسانی کند. عملیات "نوشتن مرکب" لیستی از تمام منابعی که باید بهروزرسانی شوند و مقادیر جدید آنها را با استفاده از فرمت SenML JSON/CBOR ارائه میدهد. برخلاف عملیات "نوشتن"، منابعی که ارائه نمیشوند تحت تاثیر این عملیات قرار نمیگیرند.
عملیات "نوشتن مرکب" اتمی است و نمیتواند نیمهموفق باشد. به این معنا که اگر کلاینت از این عملیات پشتیبانی کند، باید درخواست سرور را رد کند اگر نتواند تمام مقادیر درخواستشده را به لیست منابع درخواستشده بنویسد. بنابراین، قبل از پردازش عملیات "نوشتن مرکب"، کلاینت باید اطمینان حاصل کند که تمام اشیاء مورد نظر وجود دارند و سرور دسترسی نوشتن به آن اشیاء و منابع دارد.
مثال: نوشتن مرکب به چندین شیء
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "WriteComposite",
"params": {"nodes":{"/3/0/14":"+04", "/1/0/2":100, "/5/0/1":"coap://localhost:5685"}}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
WriteComposite {"nodes":{"/3/0/14":"+04", "/1/0/2":100, "/5/0/1":"coap://localhost:5685"}}
# Response:
{"result":"CHANGED"}
مثالهای بیشتر:
نوشتن مرکب با استفاده از چندین کلید
# Request:
WriteComposite {"nodes":{"/3/0/14":"+04", "/1/0/2":100, "/5/0/1":"coap://localhost:5685"}}
# Response:
{"result":"CHANGED"}
عملیات اجرا
عملیات "اجرا" توسط سرور LwM2M برای شروع یک عمل خاص استفاده میشود و تنها میتواند روی منابع فردی انجام شود.
مثال: اجرای یک منبع
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "Execute",
"params": {"id":"5/0/2"}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
Execute {"id":"5/0/2"}
# Response:
{"result":"CHANGED"}
عملیات حذف
عملیات "حذف" برای حذف یک نمونه شیء در کلاینت LwM2M توسط سرور LwM2M استفاده میشود. نمونه شیء که توسط سرور LwM2M در کلاینت LwM2M حذف میشود، باید نمونه شیئی باشد که توسط کلاینت LwM2M به سرور LwM2M با استفاده از عملیاتهای "ثبت" و "بهروزرسانی" از رابط ثبتنام کلاینت اعلام شده باشد.
تنها استثنا در این خصوص، نمونه تکشیء شیء دستگاه اجباری (ID:3) است که نباید تحت تاثیر هیچ عملیات حذف قرار گیرد.
مثال: حذف یک نمونه شیء
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "Observe",
"params": {"id":"/3/0/9"}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
Observe {"id":"/3/0/9"}
# Response:
{"result":"CONTENT","value":"LwM2mSingleResource [id=9, value=28, type=INTEGER]"}
عملیات مشاهده
سرور LwM2M درخواست مشاهده برای تغییرات یک منبع خاص، منابع درون یک نمونه شیء یا برای تمامی نمونههای شیء یک شیء در داخل کلاینت LwM2M را آغاز میکند. پارامترهای مربوط به عملیات "مشاهده" در ویژگیهای اعلان و عملیات "نوشتن ویژگیها" توضیح داده شده است و این پارامترها از طریق عملیات "نوشتن ویژگیها" پیکربندی میشوند.
مثال: مشاهده یک منبع
نمونه فراخوانی RPC برای API مبتنی بر REST:
{
"method": "Observe",
"params": {"id":"/3/0/9"}
}
نمونهای از ورودی مربوطه در ترمینال دیباگ:
# Request:
Observe {"id":"/3/0/9"}
# Response:
{"result":"CONTENT","value":"LwM2mSingleResource [id=9, value=28, type=INTEGER]"}
مثالهای بیشتر:
مشاهده نمونه شیء
# Request:
Observe {"id":"/3/0"}
# Response:
{"result":"CONTENT","value":"LwM2mObjectInstance [id=0, resources={0=LwM2mSingleResource [id=0, value=Thingsboard
Test Device, type=STRING], 1=LwM2mSingleResource [id=1, value=Model 500, type=STRING], 2=LwM2mSingleResource [id=2,
value=TH-500-000-0001, type=STRING], 3=LwM2mSingleResource [id=3, value=TestThingsboard@TestMore1024_2.04, type=STRING],
6=LwM2mSingleResource [id=6, value=1, type=INTEGER], 7=LwM2mSingleResource [id=7, value=90, type=INTEGER], 8=LwM2mSingleResource
[id=8, value=29, type=INTEGER], 9=LwM2mSingleResource [id=9, value=19, type=INTEGER], 10=LwM2mSingleResource [id=10, value=76962,
type=INTEGER], 11=LwM2mMultipleResource [id=11, values={0=LwM2mResourceInstance [id=0, value=1, type=INTEGER]}, type=INTEGER],
13=LwM2mSingleResource [id=13, value=Wed Jul 31 22:49:45 EET 1940, type=TIME], 14=LwM2mSingleResource [id=14, value=+5, type=STRING],
15=LwM2mSingleResource [id=15, value=Kiyv/Europe, type=STRING], 16=LwM2mSingleResource [id=16, value=U, type=STRING],
17=LwM2mSingleResource [id=17, value=smart meters, type=STRING], 18=LwM2mSingleResource [id=18, value=1.01, type=STRING],
19=LwM2mSingleResource [id=19, value=1.02, type=STRING], 20=LwM2mSingleResource [id=20, value=6, type=INTEGER], 21=LwM2mSingleResource
[id=21, value=256000, type=INTEGER]}]"}
لغو عملیات مشاهده
عملیات "لغو مشاهده" از سمت سرور LwM2M به کلاینت LwM2M ارسال میشود تا رابطه مشاهدهای که قبلاً با استفاده از عملیات "مشاهده" ایجاد شده است، خاتمه یابد.
مثال: لغو مشاهده برای یک منبع بر اساس شناسه (ID)
مثال فراخوانی RPC برای API مبتنی بر REST:
{
"method": "ObserveCancel",
"params": {"id":"/5/0/7"}
}
مثال ورودی مربوطه در ترمینال اشکالزدایی:
# Request:
ObserveCancel {"id":"/5/0/7"}
# Response:
{"result":"CONTENT","value":"1"}
مثالهای بیشتر:
مثال: لغو مشاهده برای یک منبع بر اساس کلید (Key)
# Request:
ObserveCancel {"key":"updateResult"}
# Response:
{"result":"CONTENT","value":"1"}
عملیات لغو همه مشاهدات
عملیات "لغو همه مشاهدات" یک عملیات خاص در ThingsConnect است که به شما امکان میدهد تمام مشاهدات روی دستگاه را بهصورت همزمان لغو کنید.
مثال: لغو همه مشاهدات
مثال فراخوانی RPC برای API مبتنی بر REST:
{
"method": "ObserveCancelAll",
"params": {}
}
مثال ورودی مربوطه در ترمینال اشکالزدایی:
# Request:
ObserveCancelAll
# Response:
{"result":"CONTENT","value":"8"} // - cancelled 8 observations
عملیات خواندن همه مشاهدات
عملیات "خواندن همه مشاهدات" یک عملیات خاص در ThingsConnect است که به شما امکان میدهد تمام مشاهداتی که روی دستگاه تنظیم شدهاند را بازیابی کنید.
مثال: خواندن همه مشاهدات
مثال فراخوانی RPC برای API مبتنی بر REST:
{
"method": "ObserveReadAll",
"params": {}
}
مثال ورودی مربوطه در ترمینال اشکالزدایی:
# Request:
ObserveReadAll
# Response:
{"result":"CONTENT","value":"[\"/5/0/7\",\"/3/0/3\",\"/5/0/3\",\"/5/0/5\"]"}
عملیات کشف همه
عملیات "کشف همه مشاهدات" یک عملیات خاص در ThingsConnect است که به شما امکان میدهد ساختار سلسلهمراتبی اشیاء و منابع ایجاد شده روی کلاینت را مشاهده کنید. زمانی که عملیات Discover All اجرا میشود، هیچ درخواستی به دستگاه کلاینت ارسال نمیکند؛ بلکه مدل LwM2M دستگاه کلاینت را که در هنگام اتصال دستگاه به سرور ایجاد شده است، بازمیگرداند. این فرمان برای تنظیم دستگاه و رفع اشکال بسیار مفید است، زیرا به شما امکان میدهد اشیاء موجود و نسخههای آنها را مشاهده کنید.
مثال: کشف همه منابع
مثال فراخوانی RPC برای API مبتنی بر REST:
{
"method": "DiscoverAll",
"params": {}
}
مثال ورودی مربوطه در ترمینال اشکالزدایی:
# Request:
DiscoverAll
# Response:
{"result":"CONTENT","value":"[{\"url\":\"/\",\"attributes\":{\"ct\":\"110\",\"rt\":\"\\\"oma.lwm2m\\\"\"}},
{\"url\":\"/1\",\"attributes\":{\"ver\":\"1.1\"}},{\"url\":\"/1/0\",\"attributes\":{}},{\"url\":\"/2/0\",
\"attributes\":{}},{\"url\":\"/3/0\",\"attributes\":{}},{\"url\":\"/4/0\",\"attributes\":{}},{\"url\":\"/5/0\",
\"attributes\":{}},{\"url\":\"/6/0\",\"attributes\":{}},{\"url\":\"/7/0\",\"attributes\":{}},{\"url\":\"/31024\",
\"attributes\":{\"ver\":\"1.0\"}},{\"url\":\"/31024/10\",\"attributes\":{}},{\"url\":\"/31024/11\",\"attributes\":{}},
{\"url\":\"/31024/12\",\"attributes\":{}}]"}
بهروزرسانیهای سفتافزار از راه دور (OTA)
پروتکل LwM2M به شما امکان میدهد تا بهروزرسانیهای سفتافزار را از راه دور (OTA) به دستگاهها بارگذاری و توزیع کنید. لطفاً ابتدا مقاله بهروزرسانیهای OTA را بخوانید تا با نحوه بارگذاری و مدیریت بستههای سفتافزار و فرآیند بهروزرسانی آشنا شوید.
پروتکل LwM2M، شیء شماره 5: شیء بهروزرسانی سفتافزار را برای اهداف OTA تعریف میکند. این شیء امکان مدیریت تصاویر سفتافزار را فراهم میکند و شامل منابعی برای نصب بسته سفتافزار، بهروزرسانی سفتافزار و انجام اقدامات پس از بهروزرسانی است.
توجه: شیء شماره 5 یک شیء اختیاری است و ممکن است توسط برخی دستگاهها پشتیبانی نشود.
برای اجرای بهروزرسانی با استفاده از شیء شماره 5، باید اطمینان حاصل کنید که این شیء در مدل LwM2M موجود در پروفایل دستگاه حضور دارد. همچنین لازم است مشاهده (Observation) برای ویژگیهای زیر روی دستگاه تنظیم شود. این ویژگیها توسط سرور برای دریافت بازخورد از وضعیت فرآیند بهروزرسانی استفاده میشوند:
"/3/0/3" - Firmware Version
"/5/0/3" - State
"/5/0/5" - Update Result
"/5/0/7" - PkgVersion
فرآیند بهروزرسانی سفتافزار در اینجا توضیح داده شده است: مکانیسمهای بهروزرسانی سفتافزار، که بهصورت یک نمودار حالت UML 2.0 توصیف شده است. این نمودار شامل حالتها (با مستطیلهای گرد) و انتقالها (پیکانهایی که حالتها را به هم متصل میکنند) است.
چندین روش برای اجرای بهروزرسانیهای سفتافزار OTA با استفاده از انتقال LwM2M وجود دارد. شما میتوانید استراتژی مناسب را در پروفایل دستگاه انتخاب کنید، تا برای تمام دستگاههای این پروفایل اعمال شود:
آپلود بهروزرسانی سفتافزار بهصورت فایل باینری با استفاده از شیء شماره 5 و منبع 0
بسته سفتافزار از سرور مستقیماً از طریق انتقال بلوکوار (block-wise) به منبع شماره 0 در شیء شماره 5 دستگاه ارسال میشود. پس از اتمام دانلود، فرآیند بهروزرسانی باید با استفاده از منبع اجرایی “/5/0/2” آغاز شود. فرآیند کامل در اینجا توضیح داده شده است: مثال از ارسال تصویر سفتافزار از یک سرور LwM2M به یک کلاینت LwM2M.
ایجاد خودکار URL CoAP برای دانلود بسته و ارسال سفتافزار از طریق شیء شماره 5 و منبع 1
این گزینه امکان اجرای بهروزرسانی سفتافزار را با فایل تصویری که در یک فضای ذخیرهسازی شخص ثالث قرار دارد، فراهم میکند. در این روش، سرور یک URL CoAP ایجاد کرده و آن را به کلاینت ارسال میکند. کلاینت تصویر سفتافزار را مستقیماً از منبع خارجی دانلود میکند، بدون اینکه تصویر به سرور منتقل شود. پس از اتمام دانلود، فرآیند بهروزرسانی باید با استفاده از منبع اجرایی “/5/0/2” آغاز شود. فرآیند کامل در اینجا توضیح داده شده است: مثال از دانلود تصویر سفتافزار توسط کلاینت.
بهروزرسانی نرمافزار از راه دور (OTA)
پروتکل LwM2M به شما امکان میدهد تا بهروزرسانیهای نرمافزاری را از راه دور (OTA) به دستگاهها بارگذاری و توزیع کنید. لطفاً ابتدا مقاله بهروزرسانیهای OTA را بخوانید تا با نحوه بارگذاری و مدیریت بستههای نرمافزاری و فرآیند بهروزرسانی آشنا شوید.
فرآیند بهروزرسانی نرمافزار دستگاه با فرآیند بهروزرسانی سفتافزار تفاوتهایی دارد:
فرآیند مدیریت نرمافزار به دو زیر فرآیند تقسیم میشود:
فرآیند نصب بسته
فرآیند فعالسازی نرمافزار
پروتکل LwM2M، شیء شماره 9: شیء مدیریت نرمافزار را برای مدیریت نرمافزار تعریف میکند. این شیء امکان مدیریت از راه دور نرمافزار را در دستگاههای M2M فراهم میکند و شامل منابعی برای تحویل، اجرای نصب، فعالسازی بستههای نرمافزاری و گزارش وضعیتها است.
توجه: شیء شماره 9 یک شیء اختیاری است و ممکن است توسط برخی دستگاهها پشتیبانی نشود.
برای اجرای بهروزرسانی با استفاده از شیء شماره 9، باید اطمینان حاصل کنید که این شیء در مدل LwM2M موجود در پروفایل دستگاه حضور دارد. همچنین لازم است مشاهده (Observation) برای ویژگیهای زیر روی دستگاه تنظیم شود. این ویژگیها توسط سرور برای دریافت بازخورد از وضعیت فرآیند بهروزرسانی استفاده میشوند:
"/3/0/19" - Software Version
"/9/0/0" - PkgName
"/9/0/1" - PkgVersion
"/9/0/2" - Package ID
"/9/0/3" - Package URI
"/9/0/7" - Update State
"/9/0/9" - Update result
روشهای متعددی برای اجرای بهروزرسانی نرمافزار از راه دور (OTA) با استفاده از پروتکل انتقال LwM2M وجود دارد. شما میتوانید استراتژی مورد نظر را در پروفایل دستگاه انتخاب کنید تا برای تمامی دستگاههای آن پروفایل اعمال شود:
ارسال بهروزرسانی نرمافزار بهصورت فایل باینری با استفاده از شیء شماره 9 و منبع 2
بسته نرمافزار از سرور مستقیماً از طریق انتقال بلوکوار (block-wise) به منبع شماره 2 در شیء شماره 9 دستگاه ارسال میشود.
ایجاد خودکار URL CoAP برای دانلود بسته و ارسال نرمافزار از طریق شیء شماره 9 و منبع 3
این گزینه امکان اجرای بهروزرسانی نرمافزار را با فایل تصویری که در یک فضای ذخیرهسازی شخص ثالث قرار دارد، فراهم میکند. در این روش، سرور یک URL CoAP ایجاد کرده و آن را به کلاینت ارسال میکند. کلاینت تصویر نرمافزار را مستقیماً از منبع خارجی دانلود میکند، بدون اینکه تصویر به سرور منتقل شود.
موضوعات پیشرفته
ویژگیهای شیء و منبع
توجه داشته باشید که ویژگیها در زمینه LwM2M با ویژگیهای سرور، کلاینت یا ویژگیهای اشتراکی در پلتفرم ThingsConnect تفاوت داشته و ارتباطی با آنها ندارند.
در پروتکل LwM2M، ویژگیها متادیتاهایی هستند که میتوانند به یک شیء، نمونهای از شیء، یا یک منبع متصل شوند. این ویژگیها میتوانند نقشهای متنوعی ایفا کنند؛ از انتقال اطلاعات تا تنظیم پارامترها برای انجام اقدامات خاص روی کلاینت LwM2M (مانند ارسال اعلانها).
ویژگیهایی که به اشیاء، نمونههای اشیاء، و منابع متصل میشوند، به ترتیب بهصورت زیر نامگذاری میشوند: ویژگی شیء: O-Attribute، ویژگی نمونه شیء: OI-Attribute، ویژگی منبع: R-Attribute
این ویژگیها ممکن است در payload پیامهای ثبت نام و کشف منتقل شوند. همچنین، در صورت قابل نوشتن بودن، میتوانند از طریق عملیات Write-Attributes بهروزرسانی شوند.
ویژگیهای کلاس PROPERTIES یا ویژگیهای شیء
نقش این ویژگیها ارائه متادیتاهایی است که ممکن است اطلاعات مفیدی را برای سرور LwM2M فراهم کند، بهعنوان مثال، تسهیل مدیریت دادهها.
پلتفرم ThingsConnect از ویژگی نسخه شیء (Object Version) پشتیبانی میکند که نسخه شیء مرتبط را نشان میدهد و در نتایج فرمان DiscoverAll نمایش داده میشود.
برای جزئیات بیشتر درباره ویژگیهای موجود در اشیاء LwM2M میتوانید به منبع PROPERTIES Class Attributes مراجعه کنید.
ویژگیهای کلاس NOTIFICATION یا ویژگیهای منابع
نقش این ویژگیها (R-Attributes) ارائه پارامترهایی برای عملیات Notify است که برای مشاهده منابع استفاده میشود. هر منبع قابلخواندن میتواند دارای این نوع ویژگیها باشد.
ویژگیهای NOTIFICATION زیر در پلتفرم ThingsConnect برای تنظیم پارامترهای مشاهده در دسترس هستند:
- pmin - حداقل دوره زمانی
- تعریف: حداقل زمان به ثانیه که کلاینت LwM2M باید بین دو اعلان منتظر بماند.
رفتار: اگر تولید یک اعلان برای منبع مشاهدهشده مورد انتظار باشد اما زمان آن قبل از انقضای pmin باشد، اعلان باید به محض انقضای pmin ارسال شود.
پیشفرض: در صورت نبود این پارامتر، حداقل دوره زمانی توسط مقدار پیشفرضی که در حساب سرور LwM2M تنظیم شده، تعریف میشود. - pmax - حداکثر دوره زمانی
- تعریف: حداکثر زمان به ثانیه که کلاینت LwM2M میتواند بین دو اعلان منتظر بماند.
رفتار: پس از انقضای pmax از آخرین اعلان، باید یک اعلان جدید ارسال شود.
پیشفرض: در صورت نبود این پارامتر، مقدار پیشفرض در حساب سرور LwM2M یا مقدار 0 در نظر گرفته میشود. مقدار 0 به معنی نادیدهگرفتن pmax است.
محدودیتها: مقدار pmax باید بزرگتر از pmin باشد، در غیر این صورت pmax نادیده گرفته میشود. - gt - بزرگتر از
- تعریف: مقدار آستانهای بالایی که وقتی مقدار منبع مشاهدهشده از آن عبور کند، کلاینت باید سرور را مطلع کند.
رفتار: این اعلان باید با توجه به مقدار pmin و شرایط تغییر معتبر (Notification Conditions) ارسال شود. - lt - کوچکتر از
- تعریف: مقدار آستانهای پایینی که وقتی مقدار منبع مشاهدهشده از آن عبور کند، کلاینت باید سرور را مطلع کند.
رفتار: این اعلان باید با توجه به مقدار pmin و شرایط تغییر معتبر ارسال شود. - st - گام (Step)
- تعریف: مقدار تغییر آستانهای که وقتی مقدار منبع مشاهدهشده از آن عبور کند، کلاینت باید سرور را مطلع کند.
رفتار: این اعلان نیز با توجه به pmin و شرایط تغییر معتبر ارسال میشود.
لطفاً برای اطلاعات بیشتر در مورد تمام ویژگیهای اعلان (NOTIFICATION) موجود در LwM2M به اینجا مراجعه کنید.
ویژگیهای اعلان میتوانند در پروفایل دستگاه تنظیم شوند. لطفاً دستورالعمل زیر را دنبال کنید:
پیکربندی DTLS
پلتفرم ThingsConnect از اتصال ایمن با استفاده از DTLS پشتیبانی میکند. DTLS که مخفف Datagram Transport Layer Security است، بر اساس پروتکل Transport Layer Security (TLS) طراحی شده و بر روی پروتکل User Datagram Protocol (UDP) ساخته شده است. ThingsConnect امکان استفاده از DTLS برای اتصال LwM2M دستگاهها را فراهم میکند.
میتوانید اطلاعات کامل درباره امنیت مبتنی بر DTLS در LwM2M را اینجا بیابید.
سه روش احراز هویت در ThingsConnect برای DTLS در LwM2M وجود دارد:
استفاده از کلید از پیشبهاشتراکگذاشتهشده (PSK)
استفاده از کلید عمومی خام (RPK)
استفاده از گواهی X.509
برای استفاده از DTLS، دستگاه کاربر باید با استفاده از پورت امن 5686 به سرور ThingsConnect متصل شود.
برای اهداف آموزشی، از Leshan Demo Client استفاده خواهیم کرد. برای دانلود و پیکربندی لطفاً به لینک اینجا مراجعه کنید.
1. حالت کلید پیشبهاشتراکگذاشتهشده (PSK)
پروفایل کلید پیشبهاشتراکگذاشتهشده (PSK) سادهترین و کارآمدترین راهکار برای ادغام DTLS در LwM2M است، زیرا مجموعه رمزنگاریهای پیشبهاشتراکگذاشتهشده که در [RFC7925] پیشنهاد شدهاند، به کمترین فضای حافظه و RAM در دستگاه شما نیاز دارند.
الگوریتمهای رمزنگاری متقارن به حداقل بار محاسباتی نیاز دارند و اندازه پیامهای تبادلشده نیز حداقل نگه داشته میشود. با این حال، نقطه ضعف این روش این است که کلیدهای متقارن باید پیش از ارتباط به هر دو نقطهی ارتباطی پیکربندی شوند.
برای پیکربندی اتصال در پروفایل دستگاه، تنها به سه رشته نیاز است:
- نام کلاینت Endpoint: برای شناسایی دستگاه استفاده میشود و میتواند هر رشته متنی باشد.
- کلید هویت کلاینت (PSK identity): هر رشته متنی.
- کلید PSK (کلید امنیتی): باید به صورت رشتهای تصادفی در فرمت HexDec باشد و طول آن میتواند 32، 64 یا 128 کاراکتر باشد.
مثال استفاده از Leshan Demo Client:
Endpoint client name= "ClientPsk";
Client identity (PSK identity) = "ClientPskIdentity";
Client key (PSK key or PSK security key) = "0123456789ABCDEF0123456789ABCDEF";
نمونه دستور برای اجرای "Leshan client demo" در حالت PSK:
java -jar leshan-client-demo.jar -u localhost:5686 -lh 0.0.0.0 -lp 10004 -n ClientPsk -i ClientPskIdentity
-p 0123456789ABCDEF0123456789ABCDEF
Leshan Client Demo Interactive Console :
...
DefaultRegistrationEngine 2021-09-30 19:09:52,789 [INFO] Trying to register to coaps://192.168.1.81:5686 ...
LeshanClientDemo 2021-09-30 19:09:52,830 [INFO] DTLS Full Handshake initiated by client : STARTED ...
LeshanClientDemo 2021-09-30 19:09:52,949 [INFO] DTLS Full Handshake initiated by client : SUCCEED
DefaultRegistrationEngine 2021-09-30 19:09:52,990 [INFO] Registered with location '/rd/vXMGfVFgQi'.
...
2. حالت کلید عمومی خام (RPK)
حالت کلید عمومی خام ویژگیهایی را ارائه میدهد که بین حالت کلید از پیشاشتراکی و حالت مبتنی بر گواهی قرار دارند و مزایای هر دو حالت را ترکیب میکنند. استفاده از رمزنگاری نامتقارن امنیت بهتری را فراهم میکند، اما از سربار مرتبط با گواهیها و زیرساخت کلید عمومی جلوگیری میکند.
برای پیکربندی ارتباط، باید مراحل زیر را انجام دهید:
- کلیدهای مشتری را تولید کرده و کلید عمومی مشتری را در بخش "Device Credentials - Client Key" در پلتفرم ThingsConnect کپی کنید.
- کلیدهای سرور را تولید کرده و آنها را در فایل ذخیرهسازی کلید سرور lwm2mserver.jks اضافه کنید، سپس فایل را به پوشه نصب سرور بازگردانید.
- اتصال مشتری خود را پیکربندی کنید.
ما از ابزار OpenSSL استفاده خواهیم کرد و راهنمای مربوط به آن از Leshan را دنبال میکنیم: اینجا
توجه: این مرحله به سیستمعامل مبتنی بر لینوکس و نصب Java نیاز دارد.
- یک پوشه جداگانه ایجاد کنید که در آن تمام کلیدهای تولید شده را نگهداری خواهیم کرد.
- ThingsConnect کلیدهای سرور را در فایل ذخیرهسازی کلید lwm2mserver.jks نگه میدارد، لطفاً این فایل را پیدا کرده و آن را به پوشه خود کپی کنید. محل پیشفرض فایل کلید:
/common/transport/lwm2m/src/main/resources/credentials/lwm2mserver.jks
3. برای تولید تمام کلیدهای مورد نیاز، از اسکریپت زیر استفاده خواهیم کرد. کافی است یک فایل متنی با هر ویرایشگری ایجاد کرده، اسکریپت را در آن کپی کنید و فایل را با پسوند *.sh ذخیره کنید، به عنوان مثال ‘generate-rpk.sh’:
generate-rpk.sh
#!/bin/bash
#
# Copyright © 2016-2021 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.
#
# RPK. Generation of the keys.
echo "====START RPK ========"
echo "Generating client keys..."
# Create EC key pair (private and public) using default openssl pem encoding:
openssl ecparam -out keysClient.pem -name prime256v1 -genkey
# Convert Client Private Key to PKCS#8 format (DER encoding):
openssl pkcs8 -topk8 -inform PEM -outform DER -in keysClient.pem -out cprik.der -nocrypt
# Output Client Public Key portion in SubjectPublicKeyInfo format (DER encoding):
openssl ec -in keysClient.pem -pubout -outform DER -out cpubk.der
echo "Client public key in base64 format. Copy this key to the Thingsboard - Client Key field in Device Credentials"
base64 cpubk.der
# get server keys
# Importing keystore lwm2mserver.jks alias="server" to scertServer.p12
keytool -importkeystore -srckeystore lwm2mserver.jks -alias server -destkeystore scertServer.p12 -deststoretype PKCS12
# Importing keystore lwm2mserver.jks to scert.p12...
# Enter destination keystore password: server_ks_password
# Re-enter new password: server_ks_password
# Enter source keystore password: server_ks_password
# Generating scertServer.pem:
openssl pkcs12 -in scertServer.p12 -nodes -nocerts -out scertServer.pem
echo Enter Import Password: server_ks_password
# Server public key in base64 format (spubk.pem):
openssl ec -in scertServer.pem -pubout -outform DER -out spubk.der
لطفاً توجه داشته باشید که اسکریپت از رمز عبور پیشفرض برای فایل "lwm2mserver.jks" استفاده میکند. اگر قصد دارید از رمز عبور دیگری استفاده کنید، لطفاً آن را در فایل پیکربندی "thingsboard.yml" نیز بهروزرسانی کنید:
...
lwm2m:
...
server:
...
security:
...
key_alias: "${LWM2M_SERVER_KEY_ALIAS:server}"
key_password: "${LWM2M_SERVER_KEY_PASSWORD:server_ks_password}"
...
برای اجرای اسکریپت، از دستورات زیر استفاده کنید:
chmod +x generate-rpk.sh
sudo ./generate-rpk.sh
- lwm2mserver.jks - فایل ذخیرهسازی کلید سرور (Keystore)
- keysClient.pem - جفت کلید عمومی و خصوصی کلاینت
- cprik.der - کلید خصوصی کلاینت به فرمت DER با رمزگذاری Base64
- cpubk.der - کلید عمومی کلاینت به فرمت DER
- spubk.der - کلید عمومی سرور به فرمت DER
- scertServer.pem - کلید عمومی سرور بدون رمزگذاری
5. پیکربندی دستگاه در پلتفرم ThingsConnect:
- نام نقطه انتهایی: یک رشته متنی منحصر به فرد که برای شناسایی دستگاه کلاینت استفاده میشود.
- کلید کلاینت: در ترمینال، فایل cprik.der را با استفاده از دستور Base64 باز کنید و کد را به فیلد کلید کلاینت کپی کنید:
#command:
$ Base64 cpubk.der
#Output:
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEdvBZZ2vQRK9wgDhctj6B1c7bxR3Z0wYg1+YdoYFnVUKWb+rIfTTyYK9tmQJx5Vlb5fxdLnVv1RJOPiwsLIQbAA==
6. دستور مثال برای راهاندازی "کلاینت دموی Leshan" در حالت RPK:
#command:
$ java -jar leshan-client-demo.jar -u localhost:5686 -lh 0.0.0.0 -lp 10004 -n ClientRpk -cpubk cpubk.der -cprik cprik.der -spubk spubk.der
#Output:
Leshan Client Demo Interactive Console :
Commands:
help Displays help information about the specified command
create Enable a new Object
delete Disable a new object
update Trigger a registration update.
send Send data to server
move Simulate client mouvement.
Press Ctl-C to exit.
LeshanClient 2021-10-27 10:37:21,196 [INFO] Starting Leshan client ...
CaliforniumEndpointsManager 2021-10-27 10:37:21,470 [INFO] New endpoint created for server coaps://18.184.200.162:5686 at coaps://[0:0:0:0:0:0:0:0]:10004
LeshanClient 2021-10-27 10:37:21,472 [INFO] Leshan client[endpoint:leshan-rpkz] started.
DefaultRegistrationEngine 2021-10-27 10:37:21,474 [INFO] Trying to register to coaps://18.184.200.162:5686 ...
LeshanClientDemo 2021-10-27 10:37:21,549 [INFO] DTLS Full Handshake initiated by client : STARTED ...
LeshanClientDemo 2021-10-27 10:37:21,729 [INFO] DTLS Full Handshake initiated by client : SUCCEED
DefaultRegistrationEngine 2021-10-27 10:37:21,771 [INFO] Registered with location '/rd/yyIIQFyg6H'.
DefaultRegistrationEngine 2021-10-27 10:37:21,773 [INFO] Next registration update to coaps://18.184.200.162:5686 in 53s...