.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.3 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BLUEPY" "1" "Dec 14, 2025" "0.9" "bluepy"
.SH "نام (NAME)"
bluepy \- مستندات bluepy
.sp
\fBbluepy\fP یک ماژول پایتون است که امکان برقراری ارتباط با دستگاه‌های بلوتوث کم‌مصرف (Bluetooth Low Energy) را فراهم می‌کند. پیاده‌سازی فعلی روی لینوکس اجرا می‌شود (در لایه‌های درونی از کدهای پروژهٔ BlueZ به نشانی \%<http://\:www\:.bluez\:.org> استفاده می‌کند)، اگرچه قابلیت پورت شدن به پلتفرم‌های دیگر را نیز دارد.
.sp
برای مرور مستندات API، توصیه می‌شود از کلاس Peripheral به نشانی \%<#\:peripheral>\& شروع کنید.
.sp
فهرست مطالب:
.SH "کلاس PERIPHERAL (THE PERIPHERAL CLASS)"
.sp
کلاس \fBPeripheral\fP در bluepy یک اتصال به یک دستگاه جانبی (peripheral) بلوتوث LE را کپسوله‌سازی می‌کند. شما یک شیء \fBPeripheral\fP را مستقیماً با تعیین آدرس MAC آن ایجاد می‌کنید؛ هنگامی که اتصال برقرار شد، سرویس‌ها و مشخصه‌های (characteristics) ارائه‌شده توسط آن دستگاه می‌توانند کشف شده و خوانده یا نوشته شوند.
.SS "سازنده (Constructor)"
.INDENT 0.0
.TP
.B Peripheral([deviceAddr=None[, addrType=ADDR_TYPE_PUBLIC[, iface=None]]])
اگر \fIdeviceAddr\fP برابر با \fBNone\fP نباشد، یک شیء \fBPeripheral\fP ایجاد کرده و به دستگاه مشخص‌شده توسط \fIdeviceAddr\fP متصل می‌شود. \fIdeviceAddr\fP باید یک رشته شامل شش بایت هگزادسیمال باشد که با دونقطه از هم جدا شده‌اند، مانند \fB\(dq11:22:33:ab:cd:ed\(dq\fP\&.
.sp
اگر \fIdeviceAddr\fP برابر با \fBNone\fP باشد، یک شیء \fBPeripheral\fP متصل‌نشده ایجاد می‌کند. برای این‌که این شیء قابل استفاده باشد، باید پیش از هر کاری متد \fBconnect()\fP را روی آن فراخوانی کرده و آدرس دستگاه را به آن ارسال کنید.
.sp
پارامتر \fIaddrType\fP می‌تواند برای انتخاب میان انواع آدرس‌های ثابت (\fBbtle.ADDR_TYPE_PUBLIC\fP) و تصادفی (\fBbtle.ADDR_TYPE_RANDOM\fP)، بسته به نیازمندی دستگاه جانبی هدف، استفاده شود. برای جزئیات بیشتر به بخش ۱۰.۸ از مشخصات فنی Bluetooth 4.0 مراجعه کنید.
.sp
پارامتر \fIiface\fP امکان تعیین رابط بلوتوثی که اتصال روی آن برقرار می‌شود را فراهم می‌کند. در لینوکس، مقدار 0 به معنای \fI/dev/hci0\fP، مقدار 1 به معنای \fI/dev/hci1\fP و به همین ترتیب است.
.sp
\fIdeviceAddr\fP می‌تواند یک شیء \fBScanEntry\fP نیز باشد. در این حالت، آدرس دستگاه، نوع آدرس و شماره رابط همگی از مقادیر \fBScanEntry\fP گرفته می‌شوند و پارامترهای \fIaddrType\fP و \fIiface\fP نادیده گرفته خواهند شد.
.sp
در صورتی که اتصال به دستگاه ناموفق باشد، سازنده یک خطای \fBBTLEException\fP صادر خواهد کرد.
.UNINDENT
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B connect(addr[, addrType=ADDR_TYPE_PUBLIC[, iface=None]])
یک اتصال به دستگاه مشخص‌شده توسط \fIaddr\fP، با نوع آدرس \fIaddrType\fP و شماره رابط \fIiface\fP برقرار می‌کند (برای جزئیات به سازندهٔ \fBPeripheral\fP مراجعه کنید). این متد را تنها زمانی باید فراخوانی کنید که \fBPeripheral\fP متصل نباشد (یعنی مقداری برای \fIaddr\fP به سازنده ارسال نکرده باشید)؛ یک شیء دستگاه جانبی پس از متصل شدن، نمی‌تواند مجدداً متصل شود.
.UNINDENT
.INDENT 0.0
.TP
.B disconnect()
اتصال به دستگاه را قطع کرده و منابع مرتبط با آن در سیستم‌عامل را پاک‌سازی می‌کند. گرچه مخرب (destructor) پایتون برای \fBPeripheral\fP تلاش می‌کند این متد را فراخوانی کند، اما نباید بر رخ دادن این امر در زمانی مشخص تکیه کنید. بنابراین، اگر کار شما با یک دستگاه به پایان رسیده است، همواره \fBdisconnect()\fP را به صورت صریح فراخوانی کنید.
.UNINDENT
.INDENT 0.0
.TP
.B getState()
رشته‌ای را برمی‌گرداند که وضعیت دستگاه را نشان می‌دهد. وضعیت‌های ممکن عبارتند از: \(dqconn\(dq \- متصل، \(dqdisc\(dq \- قطع‌شده، \(dqscan\(dq \- در حال پایش (اسکن) و \(dqtryconn\(dq \- در حال اتصال.
.UNINDENT
.INDENT 0.0
.TP
.B getServices()
فهرستی از اشیاء \fBService\fP را برمی‌گرداند که نمایانگر سرویس‌های ارائه‌شده توسط دستگاه جانبی هستند. اگر کشف سرویس بلوتوث قبلاً انجام نشده باشد، این عملیات انجام خواهد شد؛ در غیر این صورت، بلافاصله فهرست کش‌شدهٔ سرویس‌ها را برمی‌گرداند.
.sp
در پایتون 3.x، این متد به جای یک لیست، یک شیء \fIdictionary view\fP برمی‌گرداند.
.UNINDENT
.INDENT 0.0
.TP
.B getServiceByUUID(uuidVal)
نمونه‌ای از یک شیء \fBService\fP را برمی‌گرداند که دارای UUID مشخص‌شده است. \fBuuidVal\fP می‌تواند یک شیء \fBUUID\fP، یا هر رشته یا عدد صحیحی باشد که برای ساخت یک شیء \fBUUID\fP به کار می‌رود. اگر سرویس قبلاً کشف شده باشد (مثلاً توسط \fIgetServices()\fP)، این متد بی‌درنگ مقدار را برمی‌گرداند، و در غیر این صورت از دستگاه جانبی استعلام می‌کند. چنانچه سرویس یافت نشود، یک استثنای \fIBTLEEException\fP صادر خواهد شد.
.UNINDENT
.INDENT 0.0
.TP
.B getCharacteristics(startHnd=1, endHnd=0xFFFF, uuid=None)
فهرستی حاوی اشیاء \fBCharacteristic\fP برای دستگاه جانبی برمی‌گرداند. اگر هیچ آرگومانی داده نشود، همهٔ مشخصه‌ها را برمی‌گرداند. اگر \fIstartHnd\fP و/یا \fIendHnd\fP داده شوند، فهرست به مشخصه‌هایی محدود می‌شود که دستگیره‌های (handles) آن‌ها در محدودهٔ داده‌شده قرار دارند \- توجه داشته باشید که معمولاً برای دریافت مشخصه‌های مربوط به یک سرویس خاص، استفاده از \fBService.getCharacteristics()\fP راحت‌تر است. علاوه بر این، می‌توان \fIuuid\fP را برای یافتن مشخصه‌ای با یک مقدار UUID مشخص تعیین کرد. \fIuuid\fP می‌تواند هر رشته، عدد صحیح یا نوع \fBUUID\fP باشد که بتواند برای ساخت یک شیء \fBUUID\fP به کار رود.
.sp
اگر هیچ مشخصهٔ منطبقی یافت نشود، یک فهرست خالی برمی‌گرداند.
.UNINDENT
.INDENT 0.0
.TP
.B getDescriptors(startHnd=1, endHnd=0xFFFF)
فهرستی حاوی اشیاء \fBDescriptor\fP برای دستگاه جانبی برمی‌گرداند. اگر هیچ آرگومانی داده نشود، همهٔ توصیف‌کننده‌ها را برمی‌گرداند. اگر \fIstartHnd\fP و/یا \fIendHnd\fP داده شوند، فهرست به توصیف‌کننده‌هایی محدود می‌شود که دستگیره‌های آن‌ها در محدودهٔ داده‌شده قرار دارند. در اینجا نیز معمولاً استفاده از \fBService.getDescriptors()\fP برای دریافت توصیف‌کننده‌های مرتبط با یک سرویس خاص راحت‌تر است.
.sp
اگر هیچ توصیف‌کنندهٔ منطبقی یافت نشود، یک فهرست خالی برمی‌گرداند.
.UNINDENT
.INDENT 0.0
.TP
.B withDelegate(delegate)
این متد ارجاعی به یک شیء «نماینده» (\(dqdelegate\(dq) ذخیره می‌کند که هنگام وقوع رویدادهای ناهمگام مانند دریافت اعلان‌های بلوتوث فراخوانی می‌شود. این شیء باید زیرکلاسی از کلاس \fBDefaultDelegate\fP باشد. برای اطلاعات بیشتر به بخش کار با اعلان‌ها در \%<#\:notifications> مراجعه کنید. این متد شیء \fBPeripheral\fP را برمی‌گرداند.
.UNINDENT
.INDENT 0.0
.TP
.B setDelegate(delegate)
\fI(از نسخه 0.9.10 منسوخ شده است)\fP مشابه \fIwithDelegate()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B waitForNotifications(timeout)
تا زمان دریافت یک اعلان از دستگاه جانبی، یا تا زمانی که مهلت زمانی داده‌شده (\fItimeout\fP بر حسب ثانیه) به پایان برسد، مسدود می‌شود. اگر اعلانی دریافت شود، متد \fBhandleNotification()\fP شیء نماینده فراخوانی شده و سپس \fBwaitForNotifications()\fP مقدار \fBTrue\fP را برمی‌گرداند.
.sp
اگر پیش از به پایان رسیدن مهلت زمانی چیزی دریافت نشود، مقدار \fBFalse\fP برگردانده خواهد شد.
.UNINDENT
.INDENT 0.0
.TP
.B writeCharacteristic(handle, val, withResponse=False)
دادهٔ \fIval\fP (از نوع \fBstr\fP در پایتون 2.x و \fBbyte\fP در 3.x) را روی مشخصه‌ای که با دستگیرهٔ \fIhandle\fP شناسایی می‌شود می‌نویسد؛ این دستگیره باید یک عدد صحیح در بازهٔ 1 تا 65535 باشد. این قابلیت زمانی مفید است که هندل GATT یک مشخصه را می‌دانید، اما شیء \fBCharacteristic\fP مربوط به آن را در اختیار ندارید.
.sp
اگر \fIwithResponse\fP برابر با true باشد، منتظر دریافت تأیید موفقیت‌آمیز بودن نوشتن از سوی دستگاه می‌ماند.
.UNINDENT
.INDENT 0.0
.TP
.B readCharacteristic(handle)
مقدار فعلی مشخصهٔ شناسایی‌شده با \fIhandle\fP را می‌خواند. این متد زمانی مفید است که دستگیرهٔ مشخصه را می‌دانید اما شیء \fBCharacteristic\fP مناسبی در اختیار ندارید.
.UNINDENT.SS "ویژگی‌ها (Properties)"
.sp
تمامی ویژگی‌های فهرست‌شده در زیر فقط‌خواندنی هستند.
.INDENT 0.0
.TP
.B addr
آدرس MAC دستگاه (به‌صورت یک رشته هگزادسیمال جداشده با دونقطه).
.UNINDENT
.INDENT 0.0
.TP
.B addrType
نوع آدرس دستگاه \- یکی از \fIADDR_TYPE_PUBLIC\fP یا \fIADDR_TYPE_RANDOM\fP؛ این یک رشته قابل‌چاپ خواهد بود.
.UNINDENT
.INDENT 0.0
.TP
.B iface
شماره رابط Bluetooth (مانند 0 = \fB/dev/hci0\fP) که برای اتصال استفاده می‌شود.
.UNINDENT
.SH "کلاس اسکنر (THE SCANNER CLASS)"
.sp
یک شیء \fBScanner\fP برای اسکن دستگاه‌های LE که در حال انتشار داده‌های تبلیغاتی (advertising data) هستند استفاده می‌شود. در بیشتر موقعیت‌ها، این کار مجموعه‌ای از دستگاه‌های در دسترس برای اتصال را ارائه می‌دهد. (البته توجه داشته باشید که ممکن است دستگاه‌های Bluetooth LE اتصالات را بدون انتشار داده‌های تبلیغاتی بپذیرند، یا ممکن است داده‌های تبلیغاتی را منتشر کنند اما هیچ اتصالی نپذیرند).
.SS "سازنده (Constructor)"
.INDENT 0.0
.TP
.B Scanner([index=0])
یک شیء اسکنر جدید ایجاد و مقداردهی اولیه می‌کند. آرگومان \fIindex\fP رابط Bluetooth مورد استفاده را مشخص می‌کند (که در آن 0 معادل \fB/dev/hci0\fP و غیره است). اسکن تا زمانی که متدهای \fIstart()\fP یا \fIscan()\fP فراخوانی نشوند آغاز نمی‌شود \- برای جزئیات به بخش زیر مراجعه کنید.
.UNINDENT
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B withDelegate(delegate)
ارجاعی به یک شیء \fIdelegate\fP را ذخیره می‌کند که هنگام دریافت انتشارها از دستگاه‌ها، فراخوانی‌های بازگشتی (callbacks) را دریافت می‌نماید. برای جزئیات به مستندات \fBDefaultDelegate\fP مراجعه کنید.
.UNINDENT
.INDENT 0.0
.TP
.B scan([timeout = 10])
برای یافتن دستگاه‌ها به مدت زمان مشخص‌شده در \fItimeout\fP (به ثانیه) اسکن می‌کند. در طول این دوره، فراخوانی‌های بازگشتی به شیء \fIdelegate\fP فراخوانده می‌شوند. هنگامی که مهلت زمانی پایان یابد، اسکن متوقف شده و این متد فهرستی (یا یک \fIview\fP در Python 3.x) از اشیاء \fBScanEntry\fP را برای تمام دستگاه‌های کشف‌شده در این بازه زمانی بازمی‌گرداند.
.sp
متد \fIscan()\fP معادل فراخوانی متدهای \fIclear()\fP، \fIstart()\fP، \fIprocess()\fP و \fIstop()\fP به ترتیب است.
.UNINDENT
.INDENT 0.0
.TP
.B clear()
مجموعه فعلی دستگاه‌های کشف‌شده را پاک می‌کند.
.UNINDENT
.INDENT 0.0
.TP
.B start()
دریافت انتشارهای تبلیغاتی را از دستگاه‌های جانبی (peripherals) فعال می‌کند. باید پیش از فراخوانی \fIprocess()\fP\& فراخوانی شود.
.UNINDENT
.INDENT 0.0
.TP
.B process([timeout = 10])
منتظر انتشارهای تبلیغاتی می‌ماند و هنگام دریافت آن‌ها شیء \fIdelegate\fP را فراخوانی می‌کند. پس از پایان دوره زمانی مشخص‌شده در \fItimeout\fP (به ثانیه) بازمی‌گردد. این متد ممکن است چندین بار (بین فراخوانی‌های \fIstart()\fP و \fIstop()\fP) فراخوانی شود.
.UNINDENT
.INDENT 0.0
.TP
.B stop()
دریافت انتشارهای تبلیغاتی را غیرفعال می‌کند. باید پس از بازگشت متد \fIprocess()\fP فراخوانی شود.
.UNINDENT
.INDENT 0.0
.TP
.B getDevices()
فهرستی (یک \fIview\fP در Python 3.x) از اشیاء \fBScanEntry\fP را برای تمام دستگاه‌هایی که کشف شده‌اند (از زمان آخرین فراخوانی \fIclear()\fP) بازمی‌گرداند.
.UNINDENT.SS "کد نمونه (Sample code)"
.sp
کد پایه برای اجرای پویش دستگاه LE به مدت ۱۰ ثانیه در این مثال آمده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# import the necessary parts of the bluepy library
from bluepy.btle import Scanner, DefaultDelegate

# create a delegate class to receive the BLE broadcast packets
class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    # when this python script discovers a BLE broadcast packet, print a message with the device\(aqs MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print \(dqDiscovered device\(dq, dev.addr
        elif isNewData:
            print \(dqReceived new data from\(dq, dev.addr

# create a scanner object that sends BLE broadcast packets to the ScanDelegate
scanner = Scanner().withDelegate(ScanDelegate())

# create a list of unique devices that the scanner discovered during a 10\-second scan
devices = scanner.scan(10.0)

# for each device  in the list of devices
for dev in devices:
    # print  the device\(aqs MAC address, its address type,
    # and Received Signal Strength Indication that shows how strong the signal was when the script received the broadcast.
    print \(dqDevice %s (%s), RSSI=%d dB\(dq % (dev.addr, dev.addrType, dev.rssi)

    # For each of the device\(aqs advertising data items, print a description of the data type and value of the data itself
    # getScanData returns a list of tupples: adtype, desc, value
    # where AD Type means “advertising data type,” as defined by Bluetooth convention:
    # https://www.bluetooth.com/specifications/assigned\-numbers/generic\-access\-profile
    # desc is a human\-readable description of the data type and value is the data itself
    for (adtype, desc, value) in dev.getScanData():
        print \(dq  %s = %s\(dq % (desc, value)
.EE
.UNINDENT
.UNINDENT
.sp
برای پویش مداوم، این مثال را دنبال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# import the necessary parts of the bluepy library
from bluepy.btle import Scanner, DefaultDelegate

# create a delegate class to receive the BLE broadcast packets
class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    # when this python script discovers a BLE broadcast packet, print a message with the device\(aqs MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print \(dqDiscovered device\(dq, dev.addr
        elif isNewData:
            print \(dqReceived new data from\(dq, dev.addr

# create a scanner object that sends BLE broadcast packets to the ScanDelegate
scanner = Scanner().withDelegate(ScanDelegate())

# start the scanner and keep the process running
scanner.start()
while True:
    print \(dqStill running...\(dq
    scanner.process()
.EE
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که (۱) پویش LE باید با دسترسی ریشه (root) اجرا شود و (۲) کد پویش مداوم هرگز به پایان نمی‌رسد، بنابراین لازم است کارهای مورد نظر را در متد \fIhandleDiscovery()\fP شیء delegate خود انجام دهید.
.sp
برای مشاهده اطلاعات موجود از طریق پارامتر \fIdev\fP ارسال‌شده به delegate، مستندات \fBScanEntry\fP را ببینید..SH "کلاس SCANENTRY (THE SCANENTRY CLASS)"
.sp
یک شیء \fBScanEntry\fP شامل اطلاعاتی است که در طول کارکرد \fBScanner\fP از یک دستگاه Bluetooth LE دریافت شده است. این اطلاعات پارامترهای لازم برای اتصال به دستگاه (آدرس MAC، نوع آدرس) و داده‌های تبلیغاتی (مانند نام آن یا سرویس‌های دردسترس) ارائه‌شده در مخابره‌های (broadcasts) دستگاه را در بر می‌گیرد.
.SS "سازنده (Constructor)"
.sp
اشیاء \fBScanEntry\fP توسط کلاس \fBScanner\fP ساخته می‌شوند و نباید توسط کاربر ایجاد شوند.
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B getDescription(adtype)
یک توضیح خوانا برای انسان از کد نوع (\(aqtype\(aq) داده تبلیغاتی \fIadtype\fP برمی‌گرداند. برای نمونه، مقدار \fIadtype\fP برابر ۹ رشته \fB\(dqComplete Local Name\(dq\fP را برمی‌گرداند. برای مشاهده فهرست کامل، شماره‌های تخصیص‌یافته در Generic Access Profile را در \%<https://\:www\:.bluetooth\:.org/\:en-us/\:specification/\:assigned-numbers/\:generic-access-profile> ببینید.
.UNINDENT
.INDENT 0.0
.TP
.B getValueText(adtype)
یک نمایش متنی خوانا برای انسان از داده تبلیغاتی مربوط به کد \fIadtype\fP برمی‌گرداند. مقادیری مانند \(aqlocal name\(aq مستقیماً به عنوان رشته بازگردانده می‌شوند؛ مقادیر دیگر به رشته‌های هگزادسیمال تبدیل می‌شوند. اگر داده درخواستی موجود نباشد، مقدار \fBNone\fP بازگردانده می‌شود.
.UNINDENT
.INDENT 0.0
.TP
.B getScanData()
فهرستی از تاپل‌های \fI(adtype, description, value)\fP شامل کد نوع AD، توضیحات خوانا برای انسان و مقدار (همان‌طور که توسط \fBgetDescription()\fP و \fBgetValueText()\fP گزارش می‌شود) برای تمامی بخش‌های داده تبلیغاتی موجود برمی‌گرداند.
.UNINDENT
.SS "ویژگی‌ها (Properties)"
.sp
تمامی ویژگی‌های فهرست‌شده در زیر فقط‌خواندنی (read\-only) هستند.
.INDENT 0.0
.TP
.B addr
آدرس MAC دستگاه (به صورت رشته هگزادسیمال که با دو‌نقطه جدا شده است).
.UNINDENT
.INDENT 0.0
.TP
.B addrType
نوع آدرس دستگاه \- یکی از مقادیر \fIADDR_TYPE_PUBLIC\fP یا \fIADDR_TYPE_RANDOM\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B iface
شماره رابط بلوتوث (0 = \fB/dev/hci0\fP) که اطلاعات تبلیغاتی روی آن مشاهده شده است.
.UNINDENT
.INDENT 0.0
.TP
.B rssi
شاخص قدرت سیگنال دریافتی (RSSI) برای آخرین پخش (broadcast) دریافت شده از دستگاه. این یک مقدار عدد صحیح است که بر حسب dB اندازه‌گیری می‌شود؛ 0 dB حداکثر توان سیگنال (نظری) است و اعداد منفی‌تر نشان‌دهنده سیگنال ضعیف‌تر هستند.
.UNINDENT
.INDENT 0.0
.TP
.B connectable
مقدار بولی \- در صورتی که دستگاه از اتصال پشتیبانی کند \fBTrue\fP، و در غیر این صورت \fBFalse\fP (معمولاً برای \(aqbeacons\(aq تبلیغاتی استفاده می‌شود).
.UNINDENT
.INDENT 0.0
.TP
.B updateCount
تعداد بسته‌های تبلیغاتی دریافت شده از این دستگاه تا این لحظه (از زمان فراخوانی \fIclear()\fP روی شیء \fBScanner\fP که آن را یافته است) به صورت یک عدد صحیح.
.UNINDENT
.SH "کلاس DEFAULTDELEGATE (THE DEFAULTDELEGATE CLASS)"
.sp
توابع \fBbluepy\fP که پیام‌های بلوتوث را به صورت ناهمگام (asynchronous) دریافت می‌کنند \- مانند اعلان‌ها (notifications)، نشانه‌ها (indications) و داده‌های تبلیغاتی \- این اطلاعات را با فراخوانی متدها روی یک شیء \(aqdelegate\(aq به کاربر ارسال می‌کنند.
.sp
برای کاربردی بودن، شیء delegate باید از کلاسی باشد که توسط کاربر ایجاد شده است. کلاس \fBDefaultDelegate\fP در bluepy یک کلاس پایه برای این منظور است \- شما باید برخی یا تمام متدهای موجود در آن را با کدهای اختصاصی برنامه خود بازنویسی (override) کنید..SS "سازنده (Constructor)"
.INDENT 0.0
.TP
.B DefaultDelegate()
نمونهٔ شیء را مقداردهی اولیه می‌کند.
.UNINDENT
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B handleNotification(cHandle, data)
زمانی که یک اعلان (notification) یا نشانه (indication) از یک شیء متصل
\fBPeripheral\fP دریافت شود فراخوانی می‌گردد. \fIcHandle\fP هندل (عدد صحیح) برای
مشخصه است \- می‌توان از این مقدار برای تمایز میان اعلان‌ها از چندین منبع
روی همان peripheral استفاده کرد. \fIdata\fP داده‌های مشخصه است
(نوع \fBstr\fP در Python 2.x و \fBbytes\fP در 3.x).
.UNINDENT
.INDENT 0.0
.TP
.B handleDiscovery(scanEntry, isNewDev, isNewData)
زمانی که داده‌های تبلیغاتی (advertising data) از یک دستگاه LE در هنگام فعال بودن یک
شیء \fBScanner\fP دریافت شود فراخوانی می‌گردد. \fIscanEntry\fP حاوی اطلاعات دستگاه
و داده‌های تبلیغاتی است \- برای جزئیات به کلاس \fBScanEntry\fP مراجعه کنید. اگر دستگاه
(که با نشانی MAC شناسایی می‌شود) قبلاً توسط اسکنر دیده نشده باشد مقدار \fIisNewDev\fP
برابر با \fBTrue\fP و در غیر این صورت \fBFalse\fP خواهد بود. اگر داده‌های تبلیغاتی جدید یا
به‌روزرسانی‌شده در دسترس باشد مقدار \fIisNewData\fP برابر با \fBTrue\fP است.
.UNINDENT
.SH "کلاس UUID (THE UUID CLASS)"
.SS "سازنده (Constructor)"
.INDENT 0.0
.TP
.B UUID(value)
یک شیء \fBUUID\fP با مقدار \fIvalue\fP داده‌شده می‌سازد. این مقدار می‌تواند موارد زیر باشد:
.INDENT 7.0
.IP \(bu 2
یک مقدار \fIint\fP در محدودهٔ 0 تا 0xFFFFFFFF
.IP \(bu 2
یک مقدار \fIstr\fP
.IP \(bu 2
یک شیء \fIUUID\fP دیگر
.IP \(bu 2
هر مقدار دیگری که بتوان با استفاده از \fBstr()\fP آن را به ارقام هگزادسیمال تبدیل کرد
.UNINDENT
.UNINDENT
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B getCommonName()
رشته‌ای در توصیف آن UUID برمی‌گرداند. اگر UUID در «شماره‌های اختصاص‌یافته»
\%<#\:assignednumbers> فهرست شده باشد، این مقدار نامی خوانا برای انسان خواهد بود؛
مانند \(dqCycling Speed and Cadence\(dq. در غیر این صورت، یک رشتهٔ هگزادسیمال خواهد بود.
.UNINDENT
.SS "ویژگی‌ها (Properties)"
.sp
تمام ویژگی‌های فهرست‌شده در زیر فقط‌خواندنی (read\-only) هستند.
.INDENT 0.0
.TP
.B binVal
مقدار UUID در قالب دودویی (یک شیء \fBstr\fP در Python 2.x و \fBbytes\fP در 3.x).
.UNINDENT
.SH "کلاس SERVICE (THE SERVICE CLASS)"
.sp
یک شیء \fBService\fP در Bluetooth LE نمایانگر مجموعه‌ای از مشخصه‌ها (\fIcharacteristics\fP) و
توصیف‌کننده‌ها (\fIdescriptors\fP) است که همگی با یک عملکرد خاص در جانبی (peripheral) در ارتباط هستند.
این ساختار امکان شناسایی مشخصه‌های خاص را بدون نیاز به فهرست کردن تمام قابلیت‌های ارائه‌شده توسط peripheral فراهم می‌کند.
.sp
اطلاعات بیشتر دربارهٔ سرویس‌های استاندارد را می‌توانید در نشانی زیر بیابید:
\%<https://\:www\:.bluetooth\:.org/\:en-us/\:specification/\:adopted-specifications>
.SS "سازنده (Constructor)"
.sp
نباید اشیاء \fBService\fP را مستقیماً بسازید؛ بلکه از متدهای
\fBgetServices()\fP یا \fBgetServiceByUUID()\fP یک شیء متصل \fBPeripheral\fP استفاده کنید.
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B getCharacteristics([forUUID=None])
فهرستی از اشیاء \fBCharacteristic\fP مرتبط با سرویس را برمی‌گرداند. اگر این کار
قبلاً انجام نشده باشد، از peripheral استعلام می‌شود؛ در غیر این صورت فهرستی از حافظهٔ
موقت بازگردانده می‌شود. در صورت مشخص شدن \fIforUUID\fP، می‌تواند یک شیء \fBUUID\fP
یا مقداری باشد که برای ساختن آن به کار رفته است. در این حالت، فهرست بازگردانده‌شده
(که ممکن است خالی باشد)، شامل هر مشخصهٔ مرتبط با سرویس است که با آن UUID تطابق دارد.
.UNINDENT.SS "ویژگی‌ها (Properties)"
.sp
تمام ویژگی‌های فهرست‌شده در زیر فقط\-خواندنی هستند.
.INDENT 0.0
.TP
.B uuid
شناسهٔ بلوتوث \fBUUID\fP برای این سرویس.
.UNINDENT
.INDENT 0.0
.TP
.B peripheral
شیء \fBPeripheral\fP مربوط به دستگاهی که این سرویس به آن تعلق دارد.
.UNINDENT
.SH "کلاس مشخصه (THE CHARACTERISTIC CLASS)"
.sp
یک «مشخصه» (\(dqcharacteristic\(dq) در Bluetooth LE بیانگر یک قلم دادهٔ کوتاه است که می‌تواند خوانده یا نوشته شود. این داده‌ها می‌توانند ثابت باشند (مانند رشته‌ای که نام سازنده را نشان می‌دهد) یا به صورت پویا تغییر کنند (مانند دمای فعلی یا وضعیت یک کلید). بیشتر تعاملات با دستگاه‌های جانبی Bluetooth LE از طریق خواندن یا نوشتن مشخصه‌ها انجام می‌شود.
.SS "سازنده (Constructor)"
.sp
شما نباید اشیاء \fBCharacteristic\fP را مستقیماً بسازید. در عوض، از متد \fBgetCharacteristics()\fP یک شیء متصل \fBPeripheral\fP استفاده کنید.
.SS "متدهای نمونه (Instance Methods)"
.INDENT 0.0
.TP
.B read()
مقدار فعلی یک مشخصه را به عنوان رشته‌ای از بایت‌ها می‌خواند. در پایتون 2.x این مقدار از نوع \fIstr\fP است و در پایتون 3.x از نوع \fIbytes\fP\& می‌باشد. این متد می‌تواند به همراه ماژول \fIstruct\fP برای استخراج مقادیر عدد صحیح از داده‌ها استفاده شود.
.UNINDENT
.INDENT 0.0
.TP
.B write(data[, withResponse=False])
دادهٔ مشخص‌شده در \fIdata\fP را روی مشخصه می‌نویسد. آرگومان \fIdata\fP در پایتون 2.x باید از نوع \fIstr\fP و در پایتون 3.x از نوع \fIbytes\fP باشد. استاندارد Bluetooth LE به فرستنده اجازه می‌دهد از دستگاه جانبی درخواست کند پاسخی برای تأیید دریافت داده‌ها ارسال کند. تنظیم پارامتر \fIwithResponse\fP بر روی \fITrue\fP این درخواست را ارسال خواهد کرد. در صورت شکست فرایند تأیید، یک استثنای \fIBTLEException\fP صادر می‌شود.
.UNINDENT
.INDENT 0.0
.TP
.B supportsRead()
اگر مشخصه قابل خواندن باشد (طبق آنچه ویژگی‌های آن نشان می‌دهند)، مقدار \fITrue\fP و در غیر این صورت مقدار \fIFalse\fP را برمی‌گرداند.
.UNINDENT
.INDENT 0.0
.TP
.B propertiesToString()
رشته‌ای را برمی‌گرداند که ویژگی‌های مشخصه را توصیف می‌کند (\(aqREAD\(aq، \(aqWRITE\(aq و غیره).
.UNINDENT
.INDENT 0.0
.TP
.B getHandle()
مقدار عدد صحیح ۱۶ بیتی را که برای شناسایی مشخصه در پروتکل زیربنایی GATT به کار می‌رود، برمی‌گرداند. این مقدار ممکن است برای تمایز بین اعلان‌های مشخصه‌های مختلف مفید باشد (برای اطلاعات بیشتر به بخش کار با اعلان‌ها \%<#\:notifications> مراجعه کنید).
.UNINDENT
.SS "ویژگی‌ها (Properties)"
.sp
تمام ویژگی‌های فهرست‌شده در زیر فقط\-خواندنی هستند.
.INDENT 0.0
.TP
.B uuid
شناسهٔ بلوتوث \fBUUID\fP برای این مشخصه.
.UNINDENT
.INDENT 0.0
.TP
.B peripheral
شیء \fBPeripheral\fP مربوط به دستگاهی که این مشخصه به آن تعلق دارد.
.UNINDENT
.INDENT 0.0
.TP
.B properties
یک ماسک بیتی (bitmask) از ویژگی‌های این مشخصه.
.UNINDENT
.SH "کلاس توصیف‌گر (THE DESCRIPTOR CLASS)"
.sp
کلاس Descriptor یک جای‌نگه‌دار (placeholder) است. \fBbluepy\fP در حال حاضر از هیچ عملیات کاربردی با توصیف‌گرها پشتیبانی نمی‌کند.
.SH "کار با اعلان‌ها (WORKING WITH NOTIFICATIONS)"
.sp
در \fBbluepy\fP، پردازش اعلان‌ها با ایجاد یک شیء نماینده (\(dqdelegate\(dq) و ثبت آن در \fBPeripheral\fP صورت می‌گیرد. هر زمان که اعلانی از دستگاه جانبی دریافت شود، متدی در نماینده فراخوانی خواهد شد، همان‌طور که در زیر نشان داده شده است:
.INDENT 0.0
.TP
.B handleNotification(cHandle, data)
هنگامی فراخوانی می‌شود که اعلانی از یک \fBPeripheral\fP دریافت شده باشد. معمولاً برای فراهم شدن این امکان، متد \fBwaitForNotifications()\fP دستگاه جانبی را فراخوانی می‌کنید؛ اما توجه داشته باشید که یک دستگاه Bluetooth LE ممکن است در هر زمان اعلانی ارسال کند. این بدان معناست که متد \fIhandleNotification()\fP بالقوه می‌تواند هنگام اجرای هر فراخوانی BluePy فراخوانده شود.
.sp
پارامتر \fIcHandle\fP همان \(aqhandle\(aq مربوط به پروتکل GATT برای مشخصه‌ای است که اعلان را ارسال می‌کند. اگر یک دستگاه جانبی برای بیش از یک مشخصه اعلان بفرستد، می‌توان از این مقدار برای تمایز آن‌ها استفاده کرد. مقدار \(aqhandle\(aq با فراخوانی متد \fBgetHandle()\fP مربوط به یک شیء \fBCharacteristic\fP قابل دستیابی است.
.sp
پارامتر \fIdata\fP مقداری از نوع \fBstr\fP (در پایتون 2.x) یا \fBbytes\fP (در پایتون 3.x) حاوی داده‌های اعلان است. توصیه می‌شود برای حفظ قابلیت حمل و سازگاری میان نسخه‌های مختلف پایتون، از ماژول \fBstruct\fP پایتون جهت باز کردن (unpack) داده‌ها استفاده نمایید.
.UNINDENT
.sp
توصیه می‌شود کلاسی که برای شیء delegate استفاده می‌شود از \fBbtle.DefaultDelegate\fP مشتق شده باشد. این کار تضمین می‌کند که یک متد پیش‌فرض مناسب برای هرگونه فراخوانی احتمالی در آینده که ممکن است به رابط delegate افزوده شود، وجود داشته باشد..SS "کد نمونه (Example code)"
.sp
کد دریافت اعلان‌ها از یک دستگاه جانبی می‌تواند از طرح کلی زیر پیروی کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import btle

class MyDelegate(btle.DefaultDelegate):
    def __init__(self, params):
        btle.DefaultDelegate.__init__(self)
        # ... initialise here

    def handleNotification(self, cHandle, data):
        # ... perhaps check cHandle
        # ... process \(aqdata\(aq


# Initialisation  \-\-\-\-\-\-\-

p = btle.Peripheral( address )
p.setDelegate( MyDelegate(params) )

# Setup to turn notifications on, e.g.
#   svc = p.getServiceByUUID( service_uuid )
#   ch = svc.getCharacteristics( char_uuid )[0]
#   ch.write( setup_data )

# Main loop \-\-\-\-\-\-\-\-

while True:
    if p.waitForNotifications(1.0):
        # handleNotification() was called
        continue

    print \(dqWaiting...\(dq
    # Perhaps do something else here
.EE
.UNINDENT
.UNINDENT
.SH "شماره‌های تخصیص‌یافته (ASSIGNED NUMBERS)"
.sp
شیء \fBAssignedNumbers\fP روشی آسان برای ارجاع به شماره‌های تخصیص‌یافته رایج مرتبط با Bluetooth از طریق نام‌های متنی است. بنابراین، برای نمونه \fBAssignedNumbers.firmwareRevisionString\fP یک شیء \fBUUID\fP برای شناسه مشخصه \fIFirmware Revision String\fP (0x2A26) است.
.sp
فهرست کامل شماره‌های تخصیص‌یافته Bluetooth در \%<https://\:www\:.bluetooth\:.org/\:en-us/\:specification/\:assigned-numbers> آورده شده است.
.sp
نسخه فعلی \fIbluepy\fP شامل مقادیر تعریف‌شده زیر است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
alertNotificationService
batteryLevel
batteryService
bloodPressure
currentTimeService
cyclingPower
cyclingSpeedAndCadence
deviceInformation
deviceName
firmwareRevisionString
genericAccess
genericAttribute
glucose
hardwareRevisionString
healthThermometer
heartRate
humanInterfaceDevice
immediateAlert
linkLoss
locationAndNavigation
manufacturerNameString
modelNumberString
nextDstChangeService
phoneAlertStatusService
referenceTimeUpdateService
runningSpeedAndCadence
scanParameters
serialNumberString
softwareRevisionString
txPower
txPowerLevel
userData
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
نمایه \%<>
.IP \(bu 2
نمایه ماژول \%<>
.IP \(bu 2
صفحه جستجو \%<>
.UNINDENT.SH "نویسنده (AUTHOR)"
Ian Harvey
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2014, Ian Harvey
.\" End of generated man page.