bluetoothctl-gatt(1) Linux System Administration bluetoothctl-gatt(1)

bluetoothctl-gatt - زیرمنوی ویژگی‌های عمومی (Generic Attribute Submenu)

bluetoothctl [--options] [gatt.commands]

این زیرمنو با خدمات (services)، مشخصه‌ها (characteristics) و توصیف‌گرهای (descriptors) مربوط به GATT با استفاده از رابط‌های org.bluez.GattService(5)، org.bluez.GattCharacteristic(5)، org.bluez.GattDescriptor(5) و org.bluez.GattManager(5) تعامل برقرار می‌کند.

ویژگی‌های دستگاه محلی یا دستگاه دوردست را فهرست می‌کند که شامل خدمات، مشخصه‌ها و دستگیره‌ها (handles) می‌شود. این دستور نمای کلی جامعی از ویژگی‌های بلوتوث موجود را فراهم می‌آورد که می‌توان بعداً با سایر دستورها با آن‌ها تعامل داشت.

کاربرد (Usage)
> list-attributes [dev/local]
[dev/local]
نشانی MAC دستگاه، مسیر شیء، یا "local" برای فهرست کردن ویژگی‌های ثبت‌شده محلی (اختیاری؛ در صورت حذف، همه موارد فهرست می‌شوند)
مثال فهرست کردن ویژگی‌ها برای یک خدمت مشخص
> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a
مثال فهرست کردن ویژگی‌ها برای یک مشخصه خاص
> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
مثال فهرست کردن ویژگی‌ها برای یک خدمت در دستگاهی دیگر
> list-attributes /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0020
مثال فهرست کردن تمام ویژگی‌های خدمت Generic Access
> list-attributes 0x1800
مثال فهرست کردن تمام ویژگی‌های خدمت باتری (Battery Service)
> list-attributes 0x180F
مثال فهرست کردن تمام ویژگی‌های مشخصه نام دستگاه (Device Name)
> list-attributes 0x2A00
مثال فهرست کردن ویژگی‌ها با استفاده از شناسه یکتای کامل (UUID)
> list-attributes 00001801-0000-1000-8000-00805f9b34fb
مثال فهرست کردن ویژگی‌ها برای UUID سفارشی یک خدمت
> list-attributes 12345678-1234-5678-9abc-123456789abc

یک ویژگی خاص را روی دستگاه محلی یا دوردست برای عملیات بعدی انتخاب می‌کند. پیش از خواندن یا نوشتن روی یک ویژگی، باید آن را با این دستور انتخاب کنید. این کار زمینه کاری (context) را برای بسیاری از دستورهای دیگر (مانند read، write، notify و غیره) تعیین می‌کند و مشخص می‌سازد کدام ویژگی باید تحت تأثیر قرار گیرد.

کاربرد (Usage)
> select-attribute <attribute/UUID/local> [attribute/UUID]
<attribute/UUID/local>
مسیر ویژگی GATT، شناسه یکتا (UUID)، یا "local" برای انتخاب از ویژگی‌های محلی
[attribute/UUID]
مسیر ویژگی یا UUID اضافی هنگام استفاده از "local" (اختیاری)
مثال انتخاب یک مشخصه خاص
> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
مثال انتخاب یک توصیف‌گر خاص
> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service0020/char0022/desc0024
مثال انتخاب خدمت در دستگاهی دیگر
> select-attribute /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service001a
مثال انتخاب مشخصه نام دستگاه (Device Name)
> select-attribute 0x2A00
مثال انتخاب مشخصه سطح باتری (Battery Level)
> select-attribute 0x2A19
مثال انتخاب توصیف‌گر پیکربندی مشخصه کارخواه (CCCD)
> select-attribute 0x2902
مثال انتخاب مشخصه دما با استفاده از UUID کامل
> select-attribute 00002a6e-0000-1000-8000-00805f9b34fb
مثال انتخاب مشخصه سفارشی
> select-attribute 12345678-1234-5678-9abc-123456789abc

اطلاعات تفصیلی درباره یک ویژگی را نمایش می‌دهد. اگر ویژگی یا UUID مشخص نشده باشد، اطلاعات ویژگی انتخاب‌شده فعلی را نمایش می‌دهد. این دستور برای درک ویژگی‌ها و قابلیت‌های یک خصیصه مفید است.

کاربرد (Usage)
> attribute-info [attribute/UUID]
[attribute/UUID]
مسیر ویژگی GATT یا UUID برای دریافت اطلاعات آن (اختیاری؛ در صورت حذف، مورد فعلی استفاده می‌شود)
مثال نمایش اطلاعات ویژگی انتخاب‌شده فعلی
> attribute-info
مثال نمایش اطلاعات مشخصه خاص
> attribute-info /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
مثال نمایش اطلاعات مشخصه سطح باتری
> attribute-info 0x2A19
مثال نمایش اطلاعات مشخصه نام دستگاه
> attribute-info 0x2A00
مثال نمایش اطلاعات مشخصه دما
> attribute-info 00002a6e-0000-1000-8000-00805f9b34fb

مقدار یک ویژگی را می‌خواند. نیازمند آن است که پیش‌تر یک ویژگی با select-attribute انتخاب شده باشد. پارامتر اختیاری offset می‌تواند برای ویژگی‌هایی که اجازه خواندن جزئی را می‌دهند استفاده شود.

کاربرد (Usage)
> read [offset]
استفاده‌ها (Uses)
متد ReadValue از رابط org.bluez.GattCharacteristic(5)
[offset]
انحراف بایتی برای شروع خواندن (اختیاری؛ پیش‌فرض 0 است)
مثال خواندن مقدار ویژگی از انحراف ۰
> read
مثال خواندن مقدار ویژگی از انحراف ۰ (صریح)
> read 0
مثال خواندن مقدار ویژگی با شروع از انحراف ۴
> read 4
مثال خواندن مقدار ویژگی با شروع از انحراف ۱۰
> read 10
مثال خواندن مقدار ویژگی با شروع از انحراف ۱۶
> read 16

مقداری را در یک ویژگی می‌نویسد. این دستور ایجاب می‌کند که یک ویژگی از قبل با استفاده از select-attribute انتخاب شده باشد. داده‌ها باید در قالب هگزادسیمال (شانزده‌شانزدهی) ارائه شوند. پارامترهای اختیاری offset و type می‌توانند نیازهای خاص نوشتن را برآورده کنند.

کاربرد (Usage)
> write <data="xx xx ..."> [offset] [type]
استفاده‌ها (Uses)
متد WriteValue از رابط org.bluez.GattCharacteristic(5)
<xx xx ...>
بایت‌های داده در قالب هگزادسیمال برای نوشتن در ویژگی
[offset]
انحراف بایتی برای شروع نوشتن (اختیاری؛ پیش‌فرض 0 است)
[type]
نوع نوشتن - request، command یا reliable (اختیاری؛ پیش‌فرض request است)
مثال نوشتن "Hello" در ویژگی (بایت‌های اسکی)
> write "48 65 6C 6C 6F"
مثال نوشتن داده‌های باینری در ویژگی
> write "01 02 03 04"
مثال نوشتن مقدار تک‌بایتی
> write "FF"
مثال نوشتن ۲ بایت با شروع از انحراف ۴
> write "01 02" 4
مثال نوشتن با درخواست نوشتن (پیش‌فرض)
> write "48 65 6C 6C 6F" 0 request
مثال نوشتن با دستور نوشتن (بدون پاسخ)
> write "01 02 03" 0 command
مثال نوشتن با نوشتن قابل‌اطمینان (reliable)
> write "FF EE DD" 0 reliable

یک توصیف‌گر پرونده نوشتن (Write file descriptor) برای ویژگی از پیش انتخاب‌شده دریافت می‌کند. این کار برای برنامه‌هایی مفید است که برای انجام عملیات نوشتن به یک توصیف‌گر پرونده نیاز دارند.

کاربرد (Usage)
> acquire-write
استفاده‌ها (Uses)
متد AcquireWrite از رابط org.bluez.GattCharacteristic(5)
مثال دریافت توصیف‌گر پرونده نوشتن برای ویژگی فعلی
> acquire-write

توصیف‌گر پرونده نوشتن را که با acquire-write به دست آمده بود، آزاد می‌کند. این دستور برای پاک‌سازی منابع پس از پایان عملیات نوشتن ضروری است.

کاربرد (Usage)
> release-write
مثال آزادسازی توصیف‌گر پرونده نوشتن برای ویژگی فعلی
> release-write

یک توصیف‌گر پرونده اعلان (Notify file descriptor) برای ویژگی از پیش انتخاب‌شده به دست می‌آورد. این امکان را به برنامه‌ها می‌دهد تا برای آگاهی از تغییرات مقدار ویژگی گوش به زنگ باشند.

کاربرد (Usage)
> acquire-notify
استفاده‌ها (Uses)
متد AcquireNotify از رابط org.bluez.GattCharacteristic(5)
مثال دریافت توصیف‌گر پرونده اعلان برای ویژگی فعلی
> acquire-notify

توصیف‌گر پرونده اعلانی را که با acquire-notify به دست آمده بود، آزاد می‌کند. این تضمین می‌کند که به محض عدم نیاز به گوش دادن به اعلان‌ها، منابع آزاد شوند.

کاربرد (Usage)
> release-notify
مثال آزادسازی توصیف‌گر پرونده اعلان برای ویژگی فعلی
> release-notify

اعلان‌ها را برای تغییرات مقدار ویژگی فعال یا غیرفعال می‌کند. پیش از استفاده از این دستور، ویژگی مربوطه باید انتخاب شده باشد. این دستور به برنامه‌ها اجازه می‌دهد بدون نیاز به نظرسنجی مداوم (polling)، از تغییرات ویژگی مطلع شوند.

کاربرد (Usage)
> notify <on/off>
استفاده‌ها (Uses)
متدهای StartNotify و StopNotify از رابط org.bluez.GattCharacteristic(5)
<on/off>
فعال‌سازی یا غیرفعال‌سازی اعلان‌ها برای ویژگی فعلی
مثال فعال‌سازی اعلان‌ها برای ویژگی فعلی
> notify on
مثال غیرفعال‌سازی اعلان‌ها برای ویژگی فعلی
> notify off

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

کاربرد (Usage)
> clone [dev/attribute/UUID]
[dev/attribute/UUID]
نشانی MAC دستگاه، مسیر ویژگی، یا UUID برای کلون کردن (اختیاری؛ در صورت حذف، مورد فعلی کلون می‌شود)
مثال همتاسازی کل پایگاه داده GATT دستگاه
> clone 00:11:22:33:44:55
مثال همتاسازی دستگاهی دیگر
> clone AA:BB:CC:DD:EE:FF
مثال همتاسازی یک خدمت مشخص
> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a
مثال همتاسازی یک مشخصه خاص
> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
مثال همتاسازی خدمت Generic Access
> clone 0x1800
مثال همتاسازی خدمت باتری
> clone 0x180F
مثال همتاسازی مشخصه سطح باتری
> clone 0x2A19

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

کاربرد (Usage)
> register-application [UUID ...]
استفاده‌ها (Uses)
متد RegisterApplication از رابط org.bluez.GattManager(5)
[UUID ...]
فهرست اختیاری از UUIDهای خدمت برای ثبت به همراه برنامه
مثال ثبت برنامه GATT بدون UUIDهای مشخص
> register-application
مثال ثبت برنامه با خدمت باتری
> register-application 0x180F
مثال ثبت به همراه خدمت‌های Generic Access و باتری
> register-application 0x1800 0x180F
مثال ثبت برنامه با UUID سفارشی خدمت
> register-application 12345678-1234-5678-9abc-123456789abc
مثال ثبت با چند خدمت استاندارد
> register-application 0x1800 0x180F 0x180A

برنامه‌ای را که پیش‌تر ثبت شده است از سامانه بلوتوث حذف می‌کند.

کاربرد (Usage)
> unregister-application
استفاده‌ها (Uses)
متد UnregisterApplication از رابط org.bluez.GattManager(5)
مثال لغو ثبت برنامه GATT فعلی
> unregister-application

یک خدمت جدید را ذیل یک برنامه ثبت‌شده اضافه می‌کند. این دستور برای تعریف خدمات جدیدی که دستگاه‌ها می‌توانند ارائه دهند بسیار حیاتی است.

کاربرد (Usage)
> register-service <UUID> [handle]
<UUID>
شناسه یکتای (UUID) خدمت برای ثبت (در قالب‌های ۱۶ بیتی، ۳۲ بیتی یا ۱۲۸ بیتی)
[handle]
دستگیره خصیصه مشخص برای انتساب (اختیاری؛ در صورت حذف به طور خودکار منتسب می‌شود)
مثال ثبت خدمت Generic Access (دستگیره خودکار)
> register-service 0x1800
مثال ثبت خدمت باتری (دستگیره خودکار)
> register-service 0x180F
مثال ثبت خدمت اطلاعات دستگاه (دستگیره خودکار)
> register-service 0x180A
مثال ثبت خدمت Generic Access روی دستگیره ۱
> register-service 0x1800 0x0001
مثال ثبت خدمت باتری روی دستگیره ۱۶
> register-service 0x180F 0x0010
مثال ثبت خدمت اطلاعات دستگاه روی دستگیره ۳۲
> register-service 0x180A 0x0020
مثال ثبت خدمت سفارشی (دستگیره خودکار)
> register-service 12345678-1234-5678-9abc-123456789abc
مثال ثبت خدمت سفارشی روی دستگیره مشخص
> register-service 12345678-1234-5678-9abc-123456789abc 0x0050

یک خدمت را از برنامه ثبت‌شده حذف می‌کند و در نتیجه دسترسی به آن متوقف می‌شود.

کاربرد (Usage)
> unregister-service <UUID/object>
<UUID/object>
شناسه یکتای خدمت یا مسیر شیء مربوط به خدمتی که باید لغو ثبت شود
مثال لغو ثبت خدمت Generic Access
> unregister-service 0x1800
مثال لغو ثبت خدمت باتری
> unregister-service 0x180F
مثال لغو ثبت خدمت سفارشی
> unregister-service 12345678-1234-5678-9abc-123456789abc
مثال لغو ثبت خدمت از طریق مسیر شیء
> unregister-service /org/bluez/example/service0
مثال لغو ثبت خدمتی دیگر
> unregister-service /org/bluez/example/service1

یک خدمت را به عنوان گنجانده‌شده (included) درون خدمتی دیگر علامت‌گذاری می‌کند که این امر ساختارهای سلسله‌مراتبی و پیچیده خدمات را امکان‌پذیر می‌سازد.

کاربرد (Usage)
> register-includes <UUID> [handle]
<UUID>
شناسه یکتای خدمت برای ثبت به عنوان خدمت گنجانده‌شده
[handle]
دستگیره خصیصه مشخص برای انتساب (اختیاری؛ در صورت حذف به طور خودکار منتسب می‌شود)
مثال ثبت Generic Access به عنوان خدمت گنجانده‌شده
> register-includes 0x1800
مثال ثبت خدمت باتری به عنوان گنجانده‌شده روی دستگیره ۲۱
> register-includes 0x180F 0x0015
مثال ثبت خدمت سفارشی به عنوان گنجانده‌شده
> register-includes 12345678-1234-5678-9abc-123456789abc

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

کاربرد (Usage)
> unregister-includes <Service-UUID> <Inc-UUID>
<Service-UUID>
شناسه یکتای خدمت والد که شامل خدمت گنجانده‌شده است
<Inc-UUID>
شناسه یکتای خدمت گنجانده‌شده برای حذف از خدمت والد
مثال لغو گنجاندن خدمت باتری از Generic Access
> unregister-includes 0x1800 0x180F
مثال لغو گنجاندن اطلاعات دستگاه از خدمت سفارشی
> unregister-includes 12345678-1234-5678-9abc-123456789abc 0x180A

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

کاربرد (Usage)
> register-characteristic <UUID> <Flags=read,write,notify...> [handle]
<UUID>
شناسه یکتای مشخصه برای ثبت (در قالب‌های ۱۶ بیتی، ۳۲ بیتی یا ۱۲۸ بیتی)
<Flags=read,write,notify...>
فهرست جداشده با ویرگول از خصیصه‌ها و مجوزهای مشخصه
[handle]
دستگیره خصیصه مشخص برای انتساب (اختیاری؛ در صورت حذف به طور خودکار منتسب می‌شود)
مثال ثبت نام دستگاه (فقط‌خواندنی)
> register-characteristic 0x2A00 read
مثال ثبت سطح باتری (خواندن + اعلان‌ها)
> register-characteristic 0x2A19 read,notify
مثال ثبت سنجش ضربان قلب (فقط اعلان)
> register-characteristic 0x2A37 notify
مثال ثبت نام دستگاه (خواندن + نوشتن)
> register-characteristic 0x2A00 read,write
مثال ثبت سطح باتری (خواندن + نوشتن + اعلان)
> register-characteristic 0x2A19 read,write,notify
مثال ثبت دما (خواندن + نشانه‌ها/indications)
> register-characteristic 0x2A6E read,indicate
مثال ثبت نام دستگاه روی دستگیره ۳
> register-characteristic 0x2A00 read 0x0003
مثال ثبت سطح باتری روی دستگیره ۱۹
> register-characteristic 0x2A19 read,notify 0x0013
مثال ثبت مشخصه سفارشی با قابلیت‌های کامل
> register-characteristic 12345678-1234-5678-9abc-123456789abc read,write,notify
مثال ثبت مشخصه سفارشی فقط‌نوشتنی
> register-characteristic ABCD1234-ABCD-1234-ABCD-123456789ABC write-without-response
مثال ثبت با تمام پرچم‌ها
> register-characteristic 0x2A00 read,write,write-without-response,notify,indicate

یک مشخصه را از یک خدمت حذف می‌کند و کارکرد آن را برمی‌دارد.

کاربرد (Usage)
> unregister-characteristic <UUID/object>
<UUID/object>
شناسه یکتای مشخصه یا مسیر شیء مربوط به مشخصه‌ای که باید لغو ثبت شود
مثال لغو ثبت مشخصه نام دستگاه
> unregister-characteristic 0x2A00
مثال لغو ثبت مشخصه سطح باتری
> unregister-characteristic 0x2A19
مثال لغو ثبت مشخصه سفارشی
> unregister-characteristic 12345678-1234-5678-9abc-123456789abc
مثال لغو ثبت مشخصه از طریق مسیر شیء
> unregister-characteristic /org/bluez/example/service0/char0
مثال لغو ثبت مشخصه‌ای دیگر
> unregister-characteristic /org/bluez/example/service1/char1

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

کاربرد (Usage)
> register-descriptor <UUID> <Flags=read,write...> [handle]
<UUID>
شناسه یکتای توصیف‌گر برای ثبت (در قالب‌های ۱۶ بیتی، ۳۲ بیتی یا ۱۲۸ بیتی)
<Flags=read,write...>
فهرست جداشده با ویرگول از خصیصه‌ها و مجوزهای توصیف‌گر
[handle]
دستگیره خصیصه مشخص برای انتساب (اختیاری؛ در صورت حذف به طور خودکار منتسب می‌شود)
مثال ثبت پیکربندی مشخصه کارخواه (CCCD)
> register-descriptor 0x2902 read,write
مثال ثبت توضیحات کاربر مشخصه
> register-descriptor 0x2901 read
مثال ثبت قالب ارائه مشخصه
> register-descriptor 0x2904 read
مثال ثبت CCCD روی دستگیره ۵
> register-descriptor 0x2902 read,write 0x0005
مثال ثبت توضیحات کاربر روی دستگیره ۲۱
> register-descriptor 0x2901 read 0x0015
مثال ثبت توصیف‌گر سفارشی
> register-descriptor 12345678-1234-5678-9abc-123456789abc read,write
مثال ثبت توصیف‌گر سفارشی فقط‌خواندنی
> register-descriptor ABCD1234-ABCD-1234-ABCD-123456789ABC read
مثال ثبت توصیف‌گر محدوده معتبر
> register-descriptor 0x2906 read
مثال ثبت ارجاع گزارش خارجی
> register-descriptor 0x2907 read
مثال ثبت ارجاع گزارش
> register-descriptor 0x2908 read

یک توصیف‌گر را از یک مشخصه حذف می‌کند و رفتار آن را ساده می‌سازد.

کاربرد (Usage)
> unregister-descriptor <UUID/object>
<UUID/object>
شناسه یکتای توصیف‌گر یا مسیر شیء مربوط به توصیف‌گری که باید لغو ثبت شود
مثال لغو ثبت پیکربندی مشخصه کارخواه (CCCD)
> unregister-descriptor 0x2902
مثال لغو ثبت توضیحات کاربر مشخصه
> unregister-descriptor 0x2901
مثال لغو ثبت توصیف‌گر سفارشی
> unregister-descriptor 12345678-1234-5678-9abc-123456789abc
مثال لغو ثبت توصیف‌گر از طریق مسیر شیء
> unregister-descriptor /org/bluez/example/service0/char0/desc0
مثال لغو ثبت توصیف‌گری دیگر
> unregister-descriptor /org/bluez/example/service1/char1/desc1

http://www.bluez.org

<linux-bluetooth@vger.kernel.org>

استفاده رایگان از این نرم‌افزار تحت شرایط پروانه عمومی همگانی کاهش‌یافته گنو (LGPL) اعطا می‌شود.

November 2022 BlueZ