org.bluez.Adapter(5) Linux System Administration org.bluez.Adapter(5)

org.bluez.Adapter - مستندات واسط D-Bus آداپتور BlueZ

سرویس (Service)
org.bluez
واسط (Interface)
org.bluez.Adapter1
مسیر شیء (Object path)
[variable prefix]/{hci0,hci1,...}
مورد استفاده توسط (Used by)
bluetoothctl(1), bluetoothctl-scan(1)

نشست شناسایی دستگاه (device discovery session) را آغاز می‌کند که ممکن است شامل آغاز فرایندهای پرس‌وجو (inquiry) و/یا اسکن و حل نام دستگاه راه دور باشد.

برای آزادسازی نشست‌های دریافت‌شده از StopDiscovery استفاده کنید.

این فرایند هم‌زمان با شناسایی دستگاه‌های جدید، شروع به ایجاد اشیاء Device خواهد کرد.

در طول شناسایی، آستانه تغییرات RSSI (delta-threshold) اعمال می‌شود.

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

خطاهای ممکن:

مثال‌ها:

> scan <on/off/bredr/le>

نشست شناسایی دستگاه را که توسط StartDiscovery آغاز شده متوقف می‌کند.

توجه داشته باشید که فرایند شناسایی میان تمام نشست‌های شناسایی به اشتراک گذاشته می‌شود؛ بنابراین فراخوانی StopDiscovery تنها یک نشست را آزاد می‌کند و شناسایی زمانی متوقف می‌شود که تمام نشست‌های مربوط به همه کلاینت‌ها پایان یافته باشند.

خطاهای ممکن:

شیء دستگاه راه دور را در مسیر داده‌شده به همراه اطلاعات کش‌شده (مانند اطلاعات پیوند/bonding) حذف می‌کند.

خطاهای ممکن:

مثال‌ها:

> remove <dev>

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

مقادیر ممکن برای فیلتر:

فیلتر بر اساس UUIDهای سرویس؛ مقدار خالی به معنای تطابق با هر UUID است.

هنگامی که دستگاه راه دور یافت شود که هر یک از UUIDهای موجود در فهرست UUIDها را تبلیغ (advertise) کند، تحت شرایط زیر گزارش خواهد شد:

  • هر دو پارامتر Pathloss و RSSI خالی باشند.
  • فقط پارامتر Pathloss تنظیم شده باشد، دستگاه توان ارسال (TX power) را تبلیغ کند، و افت مسیر محاسبه‌شده کمتر از پارامتر Pathloss باشد.
  • فقط پارامتر RSSI تنظیم شده باشد، و RSSI دریافت‌شده بیشتر از پارامتر RSSI باشد.
مقدار آستانه RSSI.

سیگنال‌های PropertiesChanged برای اشیاء موجود Device با مقدار به‌روزشده RSSI ارسال خواهند شد. اگر یک یا چند فیلتر شناسایی تنظیم شده باشد، آستانه تغییرات RSSI (delta-threshold) که به‌طور پیش‌فرض توسط StartDiscovery اعمال می‌شود، اعمال نخواهد شد.

مقدار آستانه افت مسیر (Pathloss).

سیگنال‌های PropertiesChanged برای اشیاء موجود Device با مقدار به‌روزشده Pathloss ارسال خواهند شد.

پارامتر Transport نوع اسکن را تعیین می‌کند.

مقادیر ممکن:

"auto"
اسکن درهم‌تنیده (Interleaved)، استفاده از LE، BREDR، یا هر دو، بسته به آنچه هم‌اکنون فعال است.
"bredr"
فقط پرس‌وجوی BR/EDR (inquiry).
"le"
فقط اسکن LE.
تشخیص داده‌های تکراری تبلیغات را غیرفعال می‌کند.

در صورت فعال بودن، هر بار که ManufacturerData و ServiceData کشف شوند، سیگنال‌های PropertiesChanged برای آن‌ها ایجاد خواهد شد.

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

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

توجه: تطبیق الگو در صورتی که کلاینت‌های دیگری وجود داشته باشند که هیچ الگویی تنظیم نکرده باشند نادیده گرفته می‌شود زیرا عملکردی شبیه به OR منطقی دارد؛ همچنین تنظیم رشته خالی "" به عنوان الگو با هر دستگاه یافت‌شده‌ای مطابقت خواهد داشت.

در صورتی که الگو (Pattern) تنظیم شده باشد و با آدرس یا نام دستگاه مطابقت داشته باشد و دستگاه قابلیت اتصال داشته باشد، به طور خودکار به دستگاه‌های کشف‌شده متصل می‌شود.

هنگامی که فیلتر شناسایی تنظیم شود، اشیاء Device با کشف دستگاه‌های جدید دارای معیارهای منطبق ایجاد خواهند شد، صرف‌نظر از اینکه آن‌ها قابل اتصال یا قابل کشف باشند؛ این امر امکان شنود دستگاه‌های غیرقابل اتصال و غیرقابل کشف را فراهم می‌کند.

هنگامی که چند کلاینت SetDiscoveryFilter را فراخوانی کنند، فیلترهای آن‌ها در داخل ترکیب شده و اعلان‌های مربوط به دستگاه‌های جدید برای تمام کلاینت‌ها ارسال می‌شود. بنابراین، هر کلاینت باید بررسی کند که به‌روزرسانی‌های دستگاه واقعاً با فیلتر آن مطابقت دارد.

هنگامی که SetDiscoveryFilter چندین بار توسط یک کلاینت فراخوانی شود، آخرین فیلتر ارائه‌شده برای آن کلاینت فعال خواهد بود.

متد SetDiscoveryFilter می‌تواند پیش از StartDiscovery فراخوانی شود. این متد زمانی مفید است که کلاینت نخستین نشست شناسایی را ایجاد می‌کند تا اطمینان حاصل شود که اسکن مناسب بلافاصله پس از فراخوانی StartDiscovery آغاز می‌گردد.

خطاهای ممکن:

مثال‌ها:

[scan] > uuids [all/uuid1 uuid2 ...]
[scan] > rssi [rssi]
[scan] > pathloss [pathloss]
[scan] > transport [auto/bredr/le]
[scan] > duplicate-data [on/off]
[scan] > discoverable [on/off]
[scan] > pattern [value]
[scan] > clear [filter]

فیلترهای موجود را که می‌توان به SetDiscoveryFilter داد، بازمی‌گرداند.

خطاهای ممکن: هیچ (None)

بدون نیاز به انجام شناسایی عمومی (General Discovery)، به دستگاه متصل می‌شود.

مکانیسم اتصال مشابه متد Connect در واسط org.bluez.Device1(5) است، با این تفاوت که این متد پس از برقراری اتصال فیزیکی موفقیت را بازمی‌گرداند و می‌توانید حامل (bearer) مورد نظر را برای اتصال با استفاده از پارامتر تعیین کنید.

پس از بازگشت این متد، شناسایی سرویس‌ها ادامه خواهد یافت و هر پروفایل پشتیبانی‌شده متصل خواهد شد. نیازی به فراخوانی Connect در Device1 پس از این فراخوانی نیست. اگر اتصال موفقیت‌آمیز باشد، این متد مسیر شیء را به شیء دستگاه ایجادشده یا دستگاهی که از قبل وجود دارد بازمی‌گرداند.

مقادیر ممکن برای ویژگی‌ها (properties):

آدرس دستگاه بلوتوثِ دستگاه راه دور.
نوع آدرس دستگاه بلوتوث. این نوع آدرسی است که باید برای اتصال اولیه استفاده شود.

مقادیر ممکن:

"public"
آدرس عمومی (Public address)
"random"
آدرس تصادفی (Random address)

خطاهای ممکن:

آدرس دستگاه بلوتوث.

نوع آدرس بلوتوث. برای آداپتورهای دوحالته (dual-mode) و فقط BR/EDR، مقدار پیش‌فرض آن "public" است. آداپتورهای LE تک‌حالته ممکن است هر یک از این مقادیر را داشته باشند. در صورت فعال بودن حریم خصوصی (privacy)، این ویژگی حاوی نوع آدرس هویت (Identity Address) است و نه نوع آدرس مورد استفاده برای اتصال.

مقادیر ممکن:

"public"
آدرس عمومی (Public address).
"random"
آدرس تصادفی (Random address).

نام سیستمی بلوتوث (pretty hostname).

این ویژگی یا یک مقدار پیش‌فرض استاتیک سیستمی است یا توسط یک دیمن خارجی که دسترسی به پیکربندی pretty hostname را فراهم می‌کند، کنترل می‌شود.

نام دوستانه و کاربرپسند بلوتوث (friendly name). این مقدار قابل تغییر است.

در صورتی که نام مستعاری تنظیم نشده باشد، نام ارائه‌شده توسط سیستم بازگردانده می‌شود. تنظیم یک رشته خالی به عنوان نام مستعار، آن را به نام ارائه‌شده توسط سیستم بازمی‌گرداند.

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

در سیستمی با پیکربندی مناسب، هرگز نیازی به تغییر این ویژگی نیست زیرا به طور پیش‌فرض روی نام سیستم قرار دارد و pretty hostname را ارائه می‌دهد.

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

مثال‌ها:

> system-alias <name>
> reset-alias

کلاس دستگاه بلوتوث (Class of device).

این ویژگی نشان‌دهنده مقداری است که یا به طور خودکار توسط اطلاعات DMI/ACPI پیکربندی شده یا به عنوان پیکربندی استاتیک ارائه شده است.

آداپتور را در وضعیت قابل اتصال (connectable) یا غیرقابل اتصال قرار می‌دهد. این یک تنظیم سراسری است و فقط باید توسط برنامه تنظیمات استفاده شود.

تنظیم این ویژگی روی false، ویژگی Discoverable آداپتور را نیز روی false قرار می‌دهد که در صورت برگرداندن Connectable به true، به وضعیت قبل بازنمی‌گردد.

در صورت نیاز، برنامه باید به صورت دستی Discoverable را روی true تنظیم کند.

توجه داشته باشید که این ویژگی تنها بر اتصالات ورودی تأثیر می‌گذارد.

آداپتور را روشن یا خاموش می‌کند. این کار همچنین وضعیت اتصال‌پذیری مناسب کنترلر را تنظیم می‌کند.

مقدار این ویژگی ماندگار (persistent) نیست. پس از راه‌اندازی مجدد سیستم یا جدا کردن آداپتور، دوباره به false بازنشانی می‌شود.

مثال‌ها:

> power <on/off>

وضعیت توان (برق) آداپتور.

وضعیت توان مشخص می‌کند که آیا آداپتور در حال خاموش شدن است یا در حال روشن شدن، و همچنین روشن است یا خاموش.

مقادیر ممکن:

"on"
روشن (Powered on).
"off"
خاموش (Powered off).
"off-enabling"
در حال گذار از "off" به "on".
"on-disabling"
در حال گذار از "on" به "off".
"off-blocked"
مسدودشده توسط rfkill.

وضعیت آداپتور را برای مرئی کردن یا پنهان کردن آن به قابل کشف (discoverable) یا غیرقابل کشف تغییر می‌دهد. این یک تنظیم سراسری است و فقط باید توسط برنامه تنظیمات استفاده شود.

اگر DiscoverableTimeout روی یک مقدار غیر صفر تنظیم شده باشد، پس از انقضای زمان‌سنج، سیستم این مقدار را به false بازمی‌گرداند.

در صورتی که آداپتور خاموش باشد، تنظیم این مقدار با شکست مواجه می‌شود.

هنگام تغییر ویژگی Powered، وضعیت جدید این ویژگی از طریق سیگنال PropertiesChanged به‌روزرسانی می‌شود.

مثال‌ها:

> discoverable <on/off>

وضعیت آداپتور را به جفت‌پذیر (pairable) یا غیرقابل جفت‌سازی تغییر می‌دهد. این یک تنظیم سراسری است و فقط باید توسط برنامه تنظیمات استفاده شود.

توجه داشته باشید که این ویژگی تنها بر درخواست‌های جفت‌سازی ورودی تأثیر می‌گذارد.

مثال‌ها:

> pairable <on/off>

مدت‌زمان وقفه جفت‌پذیری بر حسب ثانیه. مقدار صفر یعنی مهلت زمانی غیرفعال است و آداپتور برای همیشه در حالت جفت‌پذیر باقی می‌ماند.

مدت‌زمان وقفه قابلیت کشف بر حسب ثانیه. مقدار صفر یعنی مهلت زمانی غیرفعال است و آداپتور برای همیشه در حالت قابل کشف/محدود باقی می‌ماند.

مثال‌ها:

> discoverable-timeout [value]

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

فهرستی از UUIDهای ۱۲۸ بیتی که سرویس‌های محلی موجود را نشان می‌دهند.

اطلاعات شناسه محلی دستگاه (Local Device ID) در قالب modalias که توسط هسته (kernel) و udev استفاده می‌شود.

فهرست نقش‌های پشتیبانی‌شده.

مقادیر ممکن:

"central"
از نقش مرکزی (central) پشتیبانی می‌کند.
"peripheral"
از نقش جانبی (peripheral) پشتیبانی می‌کند.
"central-peripheral"
از هر دو نقش به صورت هم‌زمان پشتیبانی می‌کند.

فهرستی از UUIDهای ۱۲۸ بیتی که ویژگی‌های آزمایشی فعال کنونی را نشان می‌دهند.

سازنده دستگاه، به عنوان شناسه شرکت از نوع uint16 تعریف‌شده در مشخصات هسته بلوتوث (Core Bluetooth Specification).

نسخه بلوتوث پشتیبانی‌شده توسط دستگاه، به عنوان کد نسخه هسته تعریف‌شده در مشخصات هسته بلوتوث (Core Bluetooth Specification).

October 2023 BlueZ