| org.bluez.Device(5) | مدیریت سیستم لینوکس | org.bluez.Device(5) |
نام (NAME)
org.bluez.Device - مستندات واسط D-Bus دستگاه در BlueZ
واسط (INTERFACE)
- سرویس (Service)
- org.bluez
- واسط (Interface)
- org.bluez.Device1
- مسیر شیء (Object path)
- [variable prefix]/{hci0,hci1,...}/dev_{BDADDR}
- مورد استفاده توسط (Used by)
- bluetoothctl(1)
متدها (Methods)
void Connect()
تمام پروفایلهایی را که دستگاه دوردست پشتیبانی میکند، امکان اتصال به آنها وجود دارد و بهعنوان دارای قابلیت اتصال خودکار (auto-connectable) نشانهگذاری شدهاند، متصل میکند. اگر تنها زیرمجموعهای از پروفایلها در حال حاضر متصل باشند، برای اتصال پروفایلهایی که هماکنون قطع هستند تلاش خواهد شد.
اگر دستکم یک پروفایل با موفقیت متصل شود، این متد وضعیت موفقیت را گزارش میدهد.
برای دستگاههای دومنظوره (dual-mode) در هر زمان تنها یک حامل (bearer) متصل میشود؛ شرایط به ترتیب زیر هستند:
- 1.
- اتصال حامل قطعشده در صورتی که از قبل متصل بوده باشد.
- 2.
- ابتدا اتصال حامل پیوندیافته (bonded). اگر هیچ حاملی پیوند نخورده باشد یا هر دو پیوند خورده باشند، نادیده گرفته شده و آخرین حامل دیدهشده بررسی میشود.
- 3.
- اتصال آخرین حامل استفادهشده؛ در صورتی که برچسبهای زمانی یکسان باشند، BR/EDR اولویت دارد، یا در صورتی که PreferredBearer روی یک حامل خاص تنظیم شده باشد، از آن استفاده میشود.
خطاهای ممکن:
مثالها:
- bluetoothctl
- > connect <dev> [uuid]
void Disconnect()
تمام پروفایلهای متصل را قطع کرده و سپس اتصال سطحپایین ACL را پایان میدهد.
اتصال ACL حتی اگر برخی از پروفایلها به درستی قطع نشده باشند (مثلاً به دلیل عملکرد نادرست دستگاه) پایان خواهد یافت.
این متد همچنین میتواند برای لغو فراخوانی قبلی متد Connect پیش از دریافت پاسخ آن استفاده شود.
برای دستگاههای غیرقابلاعتماد (non-trusted) که از طریق حامل LE متصل شدهاند، فراخوانی این متد اتصالات ورودی را تا زمان فراخوانی مجدد متد Connect غیرفعال میکند.
خطاهای ممکن:
مثالها:
- bluetoothctl
- > disconnect [dev] [uuid]
void ConnectProfile(string uuid)
یک پروفایل خاص از این دستگاه را متصل میکند. شناسه یکتا (UUID) ارائهشده، UUID سرویس دوردست برای آن پروفایل است.
خطاهای ممکن:
void DisconnectProfile(string uuid)
یک پروفایل خاص از این دستگاه را قطع میکند. پروفایل باید یک پروفایل کلاینت ثبتشده باشد.
هیچ ردیابی اتصالی برای یک پروفایل وجود ندارد، بنابراین تا زمانی که پروفایل ثبت شده باشد، این متد همواره با موفقیت انجام میشود.
خطاهای ممکن:
void Pair()
به دستگاه دوردست متصل شده و فرایند جفتسازی (pairing) را آغاز میکند و سپس با کشف سرویس (service discovery) ادامه میدهد.
اگر برنامه عامل (agent) اختصاصی خود را ثبت کرده باشد، از همان عامل استفاده خواهد شد. در غیر این صورت از عامل پیشفرض استفاده میشود.
داشتن عامل اختصاصی تنها برای برنامههایی مانند جادوگر جفتسازی (pairing wizard) منطقی است. در تقریباً تمام موارد دیگر، عامل پیشفرض این کار را به خوبی مدیریت میکند.
در صورتی که هیچ عامل برنامهای و همچنین هیچ عامل پیشفرضی وجود نداشته باشد، این متد با شکست مواجه خواهد شد.
خطاهای ممکن:
مثالها:
- bluetoothctl
- > pair [dev]
void CancelPairing()
یک عملیات جفتسازی را که توسط متد Pair آغاز شده است لغو میکند.
خطاهای ممکن:
مثالها:
- bluetoothctl
- > cancel-pairing [dev]
array{array{byte}} GetServiceRecords() [experimental]
تمام رکوردهای سرویس BR/EDR شناختهشده فعلی برای دستگاه را بازمیگرداند. هر آرایه بایت مجزا نشاندهنده یک رکورد خام SDP است، همانطور که در مشخصات پروتکل کشف سرویس بلوتوث (Service Discovery Protocol) تعریف شده است.
این متد صرفاً برای استفاده توسط لایههای سازگاری مانند Wine در نظر گرفته شده است که برای پشتیبانی از رابطهای برنامهنویسی (API) بلوتوث خارجی نیاز به دسترسی به رکوردهای خام SDP دارند.
برنامههای عمومی باید در عوض از واسط کاربری Profile برای قابلیتهای مرتبط با سرویسها استفاده کنند.
خطاهای ممکن:
سیگنالها (Signals)
void Disconnected(string reason, string message)
این سیگنال هنگام قطع اتصال یک دستگاه، همراه با علت قطع اتصال ارسال میشود.
این سیگنال میتواند توسط برنامه کلاینت (بسته به سیاست داخلی آن) استفاده شود تا در صورت اتمام مهلت زمانی (timeout) یا قطع اتصال نامشخص، برای اتصال مجدد به دستگاه یا تلاش برای اتصال به دستگاهی دیگر اقدام نماید.
علتهای ممکن:
- org.bluez.Reason.Unknown
- org.bluez.Reason.Timeout
- اتمام مهلت
زمانی
اتصال.
مهلت نظارت بر پیوند (link supervision timeout) برای یک اتصال منقضی شده است یا مهلت همگامسازی برای یک برودکست به پایان رسیده است.
- org.bluez.Reason.Local
- اتصال توسط
میزبان
محلی پایان
یافته است.
دستگاه محلی اتصال را قطع کرده، همگامسازی با یک پخشکننده (broadcaster) را خاتمه داده یا ارسال بستههای پخش همگانی را متوقف کرده است.
- org.bluez.Reason.Remote
- اتصال توسط
میزبان
دوردست
پایان
یافته است.
این قطع اتصال میتواند به دلایل زیر باشد:
- کاربر در دستگاه دوردست یا اتصال را قطع کرده یا ارسال بستههای پخش همگانی را متوقف نموده است،
- دستگاه دوردست اتصال را به دلیل کمبود منابع قطع کرده است،
- دستگاه دوردست اتصال را به این دلیل قطع کرده است که دستگاه در حال خاموش شدن است.
- org.bluez.Reason.Authentication
- اتصال به دلیل شکست در فرایند احراز هویت پایان یافته است.
- org.bluez.Reason.Suspend
- اتصال توسط میزبان محلی به دلیل تعلیق سیستم (suspend) پایان یافته است.
ویژگیها (Properties)
string Address [readonly]
آدرس دستگاه بلوتوثِ دستگاه دوردست.
string AddressType [readonly]
نوع آدرس دستگاه بلوتوث. برای دستگاههای دومنظوره (dual-mode) و دستگاههای منحصراً BR/EDR، مقدار پیشفرض آن "public" است. دستگاههای تکحالته LE ممکن است هر یک از این مقادیر را داشته باشند.
اگر دستگاه دوردست از حریم خصوصی (privacy) استفاده کند، قبل از جفتسازی این ویژگی نوع آدرس استفادهشده برای اتصال، و پس از جفتسازی «آدرس هویت» (Identity Address) را نشان میدهد.
مقادیر ممکن:
- "public"
- آدرس عمومی (Public address)
- "random"
- آدرس تصادفی (Random address)
string Name [readonly, optional]
نام بلوتوثِ دستگاه دوردست.
این مقدار صرفاً جهت کامل بودن ارائه شده است. بهتر است هنگام نمایش نام دستگاه همواره از ویژگی Alias استفاده شود.
اگر ویژگی Alias تنظیم نشده باشد، این مقدار را منعکس خواهد کرد که کار را راحتتر میکند.
string Icon [readonly, optional]
نام آیکون پیشنهادی بر اساس مشخصات نامگذاری آیکون freedesktop.org.
uint32 Class [readonly, optional]
کلاس دستگاه بلوتوثِ دستگاه دوردست.
uint16 Appearance [readonly, optional]
ظاهر بیرونی دستگاه، همانطور که در سرویس GAP یافت میشود.
array{string} UUIDs [readonly, optional]
فهرستی از شناسههای یکتای (UUID) ۱۲۸ بیتی که نمایانگر سرویسهای دوردستِ دردسترس هستند.
boolean Paired [readonly]
نشان میدهد که آیا دستگاه دوردست جفت شده است یا خیر. جفتشده بدین معناست که فرایند جفتسازی (که در آن دستگاهها اطلاعات لازم برای برقراری یک اتصال رمزگذاریشده را تبادل میکنند) تکمیل شده است.
boolean Bonded [readonly]
نشان میدهد که آیا دستگاه دوردست پیوند یافته (bonded) است یا خیر. پیوندیافته بدین معناست که اطلاعات تبادلشده در فرایند جفتسازی ذخیره شده و ماندگار خواهد بود.
boolean Connected [readonly]
نشان میدهد که آیا دستگاه دوردست در حال حاضر متصل است یا خیر.
سیگنال PropertiesChanged تغییرات این وضعیت را اعلام میکند.
boolean Trusted [readwrite]
نشان میدهد که آیا دستگاه دوردست بهعنوان قابلاعتماد (trusted) شناخته میشود یا خیر.
این تنظیم میتواند توسط برنامه تغییر داده شود.
مثالها:
- bluetoothctl
- > trust [dev]
- bluetoothctl
- > untrust [dev]
boolean Blocked [readwrite]
در صورت تنظیم روی true، هرگونه اتصال ورودی از سوی این دستگاه بلافاصله رد خواهد شد.
همچنین تا زمانی که دستگاه مسدود (blocked) باشد، تمام درایورهای دستگاه حذف میشوند و هیچ درایور جدیدی بررسی و بارگذاری نخواهد شد.
مثالها:
- bluetoothctl
- > block [dev]
- bluetoothctl
- > unblock [dev]
boolean WakeAllowed [readwrite]
در صورت تنظیم روی true، این دستگاه مجاز خواهد بود میزبان را از حالت تعلیق سیستم (suspend) بیدار کند.
مثالها:
- bluetoothctl
- > wake [dev] [on/off]
string Alias [readwrite]
نام مستعار دستگاه دوردست. از نام مستعار میتوان برای تعیین یک نام دوستانه و متفاوت برای دستگاه دوردست استفاده کرد.
در صورتی که هیچ نام مستعاری تنظیم نشده باشد، نام دستگاه دوردست را بازمیگرداند. تنظیم یک رشته خالی بهعنوان نام مستعار، آن را مجدداً به نام دستگاه دوردست بازمیگرداند.
هنگام بازنشانی نام مستعار با یک رشته خالی، این ویژگی به نام اصلی دستگاه دوردست بازمیگردد.
مثالها:
- bluetoothctl
- > set-alias <alias>
object Adapter [readonly]
مسیر شیءِ آداپتوری که دستگاه به آن تعلق دارد.
boolean LegacyPairing [readonly]
اگر دستگاه تنها از سازوکار جفتسازی پیش از بلوتوث ۲.۱ (pre-2.1) پشتیبانی کند، روی true تنظیم میشود.
این ویژگی در حین کشف دستگاه مفید است تا بتوان پیشبینی کرد که در صورت شروع جفتسازی، جفتسازی سنتی (legacy) یا ساده رخ خواهد داد.
توجه داشته باشید که این ویژگی ممکن است در مورد دستگاههای بلوتوث ۲.۱ (یا جدیدتر) که پشتیبانی از پاسخ استعلام گسترده (Extended Inquiry Response) را غیرفعال کردهاند، موارد مثبت کاذب (false-positives) نشان دهد.
boolean CablePairing [readonly]
اگر دستگاه از طریق کابل جفت شده باشد و از پیوند استاندارد همراه با رمزگذاری پشتیبانی نکند (مانند گیمپد Sixaxis)، روی true تنظیم میشود.
در صورت true بودن، BlueZ بدون اجبار به رمزگذاری اتصال را برقرار خواهد کرد.
string Modalias [readonly, optional]
اطلاعات شناسه دستگاه دوردست در قالب modalias که توسط هسته (kernel) و udev استفاده میشود.
int16 RSSI [readonly, optional]
شاخص قدرت سیگنال دریافتی (RSSI) دستگاه دوردست (استعلام یا تبلیغ).
int16 TxPower [readonly, optional]
سطح توان ارسال تبلیغشده (استعلام یا تبلیغ).
dict ManufacturerData [readonly, optional]
دادههای تبلیغاتی مخصوص سازنده (Manufacturer specific). کلیدها شناسه ۱۶ بیتی سازنده هستند که به دنبال آن مقدار آرایه بایت مربوطه قرار میگیرد.
dict ServiceData [readonly, optional]
دادههای تبلیغاتی سرویس. کلیدها شناسههای UUID در قالب رشته هستند که به دنبال آنها مقدار آرایه بایت مربوطه قرار میگیرد.
bool ServicesResolved [readonly]
نشان میدهد که آیا کشف سرویس (service discovery) به پایان رسیده و حل شده است یا خیر.
array{byte} AdvertisingFlags [readonly]
فلگهای دادههای تبلیغاتی (Advertising Data Flags) دستگاه دوردست.
dict AdvertisingData [readonly]
دادههای تبلیغاتی دستگاه دوردست. کلیدها نوع AD با طول ۱ بایت هستند که به دنبال آن دادهها بهصورت آرایه بایت قرار میگیرند.
نکته: تنها نوعهایی در دسترس قرار میگیرند که برای پردازش توسط برنامه ایمن تلقی شوند.
مقادیر ممکن:
- <type>
- <byte array>
مثال:
<Transport Discovery> <Organization Flags...> 0x26 0x01 0x01...
array{object, dict} Sets [readonly, experimental]
مسیرهای شیءِ مجموعههایی که دستگاه به آنها تعلق دارد، همراه با یک دیکشنری که میتواند شامل موارد زیر باشد:
- byte Rank
- رتبه دستگاه در مجموعه (Set).
string PreferredBearer [readwrite, optional, experimental]
حامل ترجیحی را هنگام برقراری اتصال مشخص میکند؛ این ویژگی تنها برای دستگاههای دومنظوره (dual-mode) در دسترس است.
هنگام تغییر از "bredr" به "le"، دستگاه از فهرست 'auto-connect' (اتصال خودکار) حذف خواهد شد تا در زمان انتشار تبلیغات بهطور خودکار متصل نشود.
نکته: تغییرات تنها زمانی اعمال میشوند که اتصال دستگاه قطع باشد.
مقادیر ممکن:
- "last-used"
- ابتدا به آخرین حامل استفادهشده متصل شود. پیشفرض.
- "bredr"
- ابتدا به BR/EDR متصل شود.
- "le"
- ابتدا به LE متصل شود.
- "last-seen"
- ابتدا به آخرین حامل دیدهشده متصل شود.
مثالها:
- bluetoothctl
- > bearer <dev> [last-seen/bredr/le]
| اکتبر 2023 | BlueZ |