Peripheral([deviceAddr=None[, addrType=ADDR_TYPE_PUBLIC[, iface=None]]])

اگر deviceAddr برابر با None نباشد، یک شیء Peripheral ایجاد کرده و به دستگاه مشخص‌شده توسط deviceAddr متصل می‌شود. deviceAddr باید یک رشته شامل شش بایت هگزادسیمال باشد که با دونقطه از هم جدا شده‌اند، مانند "11:22:33:ab:cd:ed".

اگر deviceAddr برابر با None باشد، یک شیء Peripheral متصل‌نشده ایجاد می‌کند. برای این‌که این شیء قابل استفاده باشد، باید پیش از هر کاری متد connect() را روی آن فراخوانی کرده و آدرس دستگاه را به آن ارسال کنید.

پارامتر addrType می‌تواند برای انتخاب میان انواع آدرس‌های ثابت (btle.ADDR_TYPE_PUBLIC) و تصادفی (btle.ADDR_TYPE_RANDOM)، بسته به نیازمندی دستگاه جانبی هدف، استفاده شود. برای جزئیات بیشتر به بخش ۱۰.۸ از مشخصات فنی Bluetooth 4.0 مراجعه کنید.

پارامتر iface امکان تعیین رابط بلوتوثی که اتصال روی آن برقرار می‌شود را فراهم می‌کند. در لینوکس، مقدار 0 به معنای /dev/hci0، مقدار 1 به معنای /dev/hci1 و به همین ترتیب است.

deviceAddr می‌تواند یک شیء ScanEntry نیز باشد. در این حالت، آدرس دستگاه، نوع آدرس و شماره رابط همگی از مقادیر ScanEntry گرفته می‌شوند و پارامترهای addrType و iface نادیده گرفته خواهند شد.

در صورتی که اتصال به دستگاه ناموفق باشد، سازنده یک خطای BTLEException صادر خواهد کرد.

connect(addr[, addrType=ADDR_TYPE_PUBLIC[, iface=None]])

یک اتصال به دستگاه مشخص‌شده توسط addr، با نوع آدرس addrType و شماره رابط iface برقرار می‌کند (برای جزئیات به سازندهٔ Peripheral مراجعه کنید). این متد را تنها زمانی باید فراخوانی کنید که Peripheral متصل نباشد (یعنی مقداری برای addr به سازنده ارسال نکرده باشید)؛ یک شیء دستگاه جانبی پس از متصل شدن، نمی‌تواند مجدداً متصل شود.

disconnect()

اتصال به دستگاه را قطع کرده و منابع مرتبط با آن در سیستم‌عامل را پاک‌سازی می‌کند. گرچه مخرب (destructor) پایتون برای Peripheral تلاش می‌کند این متد را فراخوانی کند، اما نباید بر رخ دادن این امر در زمانی مشخص تکیه کنید. بنابراین، اگر کار شما با یک دستگاه به پایان رسیده است، همواره disconnect() را به صورت صریح فراخوانی کنید.

getState()

رشته‌ای را برمی‌گرداند که وضعیت دستگاه را نشان می‌دهد. وضعیت‌های ممکن عبارتند از: "conn" - متصل، "disc" - قطع‌شده، "scan" - در حال پایش (اسکن) و "tryconn" - در حال اتصال.

getServices()

فهرستی از اشیاء Service را برمی‌گرداند که نمایانگر سرویس‌های ارائه‌شده توسط دستگاه جانبی هستند. اگر کشف سرویس بلوتوث قبلاً انجام نشده باشد، این عملیات انجام خواهد شد؛ در غیر این صورت، بلافاصله فهرست کش‌شدهٔ سرویس‌ها را برمی‌گرداند.

در پایتون 3.x، این متد به جای یک لیست، یک شیء dictionary view برمی‌گرداند.

getServiceByUUID(uuidVal)

نمونه‌ای از یک شیء Service را برمی‌گرداند که دارای UUID مشخص‌شده است. uuidVal می‌تواند یک شیء UUID، یا هر رشته یا عدد صحیحی باشد که برای ساخت یک شیء UUID به کار می‌رود. اگر سرویس قبلاً کشف شده باشد (مثلاً توسط getServices())، این متد بی‌درنگ مقدار را برمی‌گرداند، و در غیر این صورت از دستگاه جانبی استعلام می‌کند. چنانچه سرویس یافت نشود، یک استثنای BTLEEException صادر خواهد شد.

getCharacteristics(startHnd=1, endHnd=0xFFFF, uuid=None)

فهرستی حاوی اشیاء Characteristic برای دستگاه جانبی برمی‌گرداند. اگر هیچ آرگومانی داده نشود، همهٔ مشخصه‌ها را برمی‌گرداند. اگر startHnd و/یا endHnd داده شوند، فهرست به مشخصه‌هایی محدود می‌شود که دستگیره‌های (handles) آن‌ها در محدودهٔ داده‌شده قرار دارند - توجه داشته باشید که معمولاً برای دریافت مشخصه‌های مربوط به یک سرویس خاص، استفاده از Service.getCharacteristics() راحت‌تر است. علاوه بر این، می‌توان uuid را برای یافتن مشخصه‌ای با یک مقدار UUID مشخص تعیین کرد. uuid می‌تواند هر رشته، عدد صحیح یا نوع UUID باشد که بتواند برای ساخت یک شیء UUID به کار رود.

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

getDescriptors(startHnd=1, endHnd=0xFFFF)

فهرستی حاوی اشیاء Descriptor برای دستگاه جانبی برمی‌گرداند. اگر هیچ آرگومانی داده نشود، همهٔ توصیف‌کننده‌ها را برمی‌گرداند. اگر startHnd و/یا endHnd داده شوند، فهرست به توصیف‌کننده‌هایی محدود می‌شود که دستگیره‌های آن‌ها در محدودهٔ داده‌شده قرار دارند. در اینجا نیز معمولاً استفاده از Service.getDescriptors() برای دریافت توصیف‌کننده‌های مرتبط با یک سرویس خاص راحت‌تر است.

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

withDelegate(delegate)

این متد ارجاعی به یک شیء «نماینده» ("delegate") ذخیره می‌کند که هنگام وقوع رویدادهای ناهمگام مانند دریافت اعلان‌های بلوتوث فراخوانی می‌شود. این شیء باید زیرکلاسی از کلاس DefaultDelegate باشد. برای اطلاعات بیشتر به بخش کار با اعلان‌ها در <#notifications> مراجعه کنید. این متد شیء Peripheral را برمی‌گرداند.

setDelegate(delegate)

(از نسخه 0.9.10 منسوخ شده است) مشابه withDelegate().

waitForNotifications(timeout)

تا زمان دریافت یک اعلان از دستگاه جانبی، یا تا زمانی که مهلت زمانی داده‌شده (timeout بر حسب ثانیه) به پایان برسد، مسدود می‌شود. اگر اعلانی دریافت شود، متد handleNotification() شیء نماینده فراخوانی شده و سپس waitForNotifications() مقدار True را برمی‌گرداند.

اگر پیش از به پایان رسیدن مهلت زمانی چیزی دریافت نشود، مقدار False برگردانده خواهد شد.

writeCharacteristic(handle, val, withResponse=False)

دادهٔ val (از نوع str در پایتون 2.x و byte در 3.x) را روی مشخصه‌ای که با دستگیرهٔ handle شناسایی می‌شود می‌نویسد؛ این دستگیره باید یک عدد صحیح در بازهٔ 1 تا 65535 باشد. این قابلیت زمانی مفید است که هندل GATT یک مشخصه را می‌دانید، اما شیء Characteristic مربوط به آن را در اختیار ندارید.

اگر withResponse برابر با true باشد، منتظر دریافت تأیید موفقیت‌آمیز بودن نوشتن از سوی دستگاه می‌ماند.

readCharacteristic(handle)

مقدار فعلی مشخصهٔ شناسایی‌شده با handle را می‌خواند. این متد زمانی مفید است که دستگیرهٔ مشخصه را می‌دانید اما شیء Characteristic مناسبی در اختیار ندارید.

تمامی ویژگی‌های فهرست‌شده در زیر فقط‌خواندنی هستند.

Scanner([index=0])

یک شیء اسکنر جدید ایجاد و مقداردهی اولیه می‌کند. آرگومان index رابط Bluetooth مورد استفاده را مشخص می‌کند (که در آن 0 معادل /dev/hci0 و غیره است). اسکن تا زمانی که متدهای start() یا scan() فراخوانی نشوند آغاز نمی‌شود - برای جزئیات به بخش زیر مراجعه کنید.

withDelegate(delegate)

ارجاعی به یک شیء delegate را ذخیره می‌کند که هنگام دریافت انتشارها از دستگاه‌ها، فراخوانی‌های بازگشتی (callbacks) را دریافت می‌نماید. برای جزئیات به مستندات DefaultDelegate مراجعه کنید.

scan([timeout = 10])

برای یافتن دستگاه‌ها به مدت زمان مشخص‌شده در timeout (به ثانیه) اسکن می‌کند. در طول این دوره، فراخوانی‌های بازگشتی به شیء delegate فراخوانده می‌شوند. هنگامی که مهلت زمانی پایان یابد، اسکن متوقف شده و این متد فهرستی (یا یک view در Python 3.x) از اشیاء ScanEntry را برای تمام دستگاه‌های کشف‌شده در این بازه زمانی بازمی‌گرداند.

متد scan() معادل فراخوانی متدهای clear()، start()، process() و stop() به ترتیب است.

clear()

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

start()

دریافت انتشارهای تبلیغاتی را از دستگاه‌های جانبی (peripherals) فعال می‌کند. باید پیش از فراخوانی process() فراخوانی شود.

process([timeout = 10])

منتظر انتشارهای تبلیغاتی می‌ماند و هنگام دریافت آن‌ها شیء delegate را فراخوانی می‌کند. پس از پایان دوره زمانی مشخص‌شده در timeout (به ثانیه) بازمی‌گردد. این متد ممکن است چندین بار (بین فراخوانی‌های start() و stop()) فراخوانی شود.

stop()

دریافت انتشارهای تبلیغاتی را غیرفعال می‌کند. باید پس از بازگشت متد process() فراخوانی شود.

getDevices()

فهرستی (یک view در Python 3.x) از اشیاء ScanEntry را برای تمام دستگاه‌هایی که کشف شده‌اند (از زمان آخرین فراخوانی clear()) بازمی‌گرداند.

کد پایه برای اجرای پویش دستگاه LE به مدت ۱۰ ثانیه در این مثال آمده است:

# 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's MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print "Discovered device", dev.addr
        elif isNewData:
            print "Received new data from", 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's MAC address, its address type,
    # and Received Signal Strength Indication that shows how strong the signal was when the script received the broadcast.
    print "Device %s (%s), RSSI=%d dB" % (dev.addr, dev.addrType, dev.rssi)
    # For each of the device's 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 "  %s = %s" % (desc, value)

برای پویش مداوم، این مثال را دنبال کنید:

# 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's MAC address
    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print "Discovered device", dev.addr
        elif isNewData:
            print "Received new data from", 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 "Still running..."
    scanner.process()

توجه داشته باشید که (۱) پویش LE باید با دسترسی ریشه (root) اجرا شود و (۲) کد پویش مداوم هرگز به پایان نمی‌رسد، بنابراین لازم است کارهای مورد نظر را در متد handleDiscovery() شیء delegate خود انجام دهید.

برای مشاهده اطلاعات موجود از طریق پارامتر dev ارسال‌شده به delegate، مستندات ScanEntry را ببینید..SH "کلاس SCANENTRY (THE SCANENTRY CLASS)"

یک شیء ScanEntry شامل اطلاعاتی است که در طول کارکرد Scanner از یک دستگاه Bluetooth LE دریافت شده است. این اطلاعات پارامترهای لازم برای اتصال به دستگاه (آدرس MAC، نوع آدرس) و داده‌های تبلیغاتی (مانند نام آن یا سرویس‌های دردسترس) ارائه‌شده در مخابره‌های (broadcasts) دستگاه را در بر می‌گیرد.

getDescription(adtype)

یک توضیح خوانا برای انسان از کد نوع ('type') داده تبلیغاتی adtype برمی‌گرداند. برای نمونه، مقدار adtype برابر ۹ رشته "Complete Local Name" را برمی‌گرداند. برای مشاهده فهرست کامل، شماره‌های تخصیص‌یافته در Generic Access Profile را در https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile ببینید.

getValueText(adtype)

یک نمایش متنی خوانا برای انسان از داده تبلیغاتی مربوط به کد adtype برمی‌گرداند. مقادیری مانند 'local name' مستقیماً به عنوان رشته بازگردانده می‌شوند؛ مقادیر دیگر به رشته‌های هگزادسیمال تبدیل می‌شوند. اگر داده درخواستی موجود نباشد، مقدار None بازگردانده می‌شود.

getScanData()

فهرستی از تاپل‌های (adtype, description, value) شامل کد نوع AD، توضیحات خوانا برای انسان و مقدار (همان‌طور که توسط getDescription() و getValueText() گزارش می‌شود) برای تمامی بخش‌های داده تبلیغاتی موجود برمی‌گرداند.

addr

آدرس MAC دستگاه (به صورت رشته هگزادسیمال که با دو‌نقطه جدا شده است).

addrType

نوع آدرس دستگاه - یکی از مقادیر ADDR_TYPE_PUBLIC یا ADDR_TYPE_RANDOM.

iface

شماره رابط بلوتوث (0 = /dev/hci0) که اطلاعات تبلیغاتی روی آن مشاهده شده است.

rssi

شاخص قدرت سیگنال دریافتی (RSSI) برای آخرین پخش (broadcast) دریافت شده از دستگاه. این یک مقدار عدد صحیح است که بر حسب dB اندازه‌گیری می‌شود؛ 0 dB حداکثر توان سیگنال (نظری) است و اعداد منفی‌تر نشان‌دهنده سیگنال ضعیف‌تر هستند.

connectable

مقدار بولی - در صورتی که دستگاه از اتصال پشتیبانی کند True، و در غیر این صورت False (معمولاً برای 'beacons' تبلیغاتی استفاده می‌شود).

updateCount

تعداد بسته‌های تبلیغاتی دریافت شده از این دستگاه تا این لحظه (از زمان فراخوانی clear() روی شیء Scanner که آن را یافته است) به صورت یک عدد صحیح.

handleNotification(cHandle, data)

زمانی که یک اعلان (notification) یا نشانه (indication) از یک شیء متصل Peripheral دریافت شود فراخوانی می‌گردد. cHandle هندل (عدد صحیح) برای مشخصه است - می‌توان از این مقدار برای تمایز میان اعلان‌ها از چندین منبع روی همان peripheral استفاده کرد. data داده‌های مشخصه است (نوع str در Python 2.x و bytes در 3.x).

handleDiscovery(scanEntry, isNewDev, isNewData)

زمانی که داده‌های تبلیغاتی (advertising data) از یک دستگاه LE در هنگام فعال بودن یک شیء Scanner دریافت شود فراخوانی می‌گردد. scanEntry حاوی اطلاعات دستگاه و داده‌های تبلیغاتی است - برای جزئیات به کلاس ScanEntry مراجعه کنید. اگر دستگاه (که با نشانی MAC شناسایی می‌شود) قبلاً توسط اسکنر دیده نشده باشد مقدار isNewDev برابر با True و در غیر این صورت False خواهد بود. اگر داده‌های تبلیغاتی جدید یا به‌روزرسانی‌شده در دسترس باشد مقدار isNewData برابر با True است.

UUID(value)

یک شیء UUID با مقدار value داده‌شده می‌سازد. این مقدار می‌تواند موارد زیر باشد:

getCommonName()

رشته‌ای در توصیف آن UUID برمی‌گرداند. اگر UUID در «شماره‌های اختصاص‌یافته» <#assignednumbers> فهرست شده باشد، این مقدار نامی خوانا برای انسان خواهد بود؛ مانند "Cycling Speed and Cadence". در غیر این صورت، یک رشتهٔ هگزادسیمال خواهد بود.

binVal

مقدار UUID در قالب دودویی (یک شیء str در Python 2.x و bytes در 3.x).

getCharacteristics([forUUID=None])

فهرستی از اشیاء Characteristic مرتبط با سرویس را برمی‌گرداند. اگر این کار قبلاً انجام نشده باشد، از peripheral استعلام می‌شود؛ در غیر این صورت فهرستی از حافظهٔ موقت بازگردانده می‌شود. در صورت مشخص شدن forUUID، می‌تواند یک شیء UUID یا مقداری باشد که برای ساختن آن به کار رفته است. در این حالت، فهرست بازگردانده‌شده (که ممکن است خالی باشد)، شامل هر مشخصهٔ مرتبط با سرویس است که با آن UUID تطابق دارد.

تمام ویژگی‌های فهرست‌شده در زیر فقط-خواندنی هستند.

read()

مقدار فعلی یک مشخصه را به عنوان رشته‌ای از بایت‌ها می‌خواند. در پایتون 2.x این مقدار از نوع str است و در پایتون 3.x از نوع bytes می‌باشد. این متد می‌تواند به همراه ماژول struct برای استخراج مقادیر عدد صحیح از داده‌ها استفاده شود.

write(data[, withResponse=False])

دادهٔ مشخص‌شده در data را روی مشخصه می‌نویسد. آرگومان data در پایتون 2.x باید از نوع str و در پایتون 3.x از نوع bytes باشد. استاندارد Bluetooth LE به فرستنده اجازه می‌دهد از دستگاه جانبی درخواست کند پاسخی برای تأیید دریافت داده‌ها ارسال کند. تنظیم پارامتر withResponse بر روی True این درخواست را ارسال خواهد کرد. در صورت شکست فرایند تأیید، یک استثنای BTLEException صادر می‌شود.

supportsRead()

اگر مشخصه قابل خواندن باشد (طبق آنچه ویژگی‌های آن نشان می‌دهند)، مقدار True و در غیر این صورت مقدار False را برمی‌گرداند.

propertiesToString()

رشته‌ای را برمی‌گرداند که ویژگی‌های مشخصه را توصیف می‌کند ('READ'، 'WRITE' و غیره).

getHandle()

مقدار عدد صحیح ۱۶ بیتی را که برای شناسایی مشخصه در پروتکل زیربنایی GATT به کار می‌رود، برمی‌گرداند. این مقدار ممکن است برای تمایز بین اعلان‌های مشخصه‌های مختلف مفید باشد (برای اطلاعات بیشتر به بخش کار با اعلان‌ها <#notifications> مراجعه کنید).

uuid

شناسهٔ بلوتوث UUID برای این مشخصه.

peripheral

شیء Peripheral مربوط به دستگاهی که این مشخصه به آن تعلق دارد.

properties

یک ماسک بیتی (bitmask) از ویژگی‌های این مشخصه.