1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
import sys
import os
if sys.version < '3':
from .btcommon import *
else:
from bluetooth.btcommon import *
__version__ = 0.23
def _dbg(*args):
return
sys.stderr.write(*args)
sys.stderr.write("\n")
if sys.platform == "win32":
_dbg("trying widcomm")
have_widcomm = False
dll = "wbtapi.dll"
sysroot = os.getenv ("SystemRoot")
if os.path.exists (dll) or \
os.path.exists (os.path.join (sysroot, "system32", dll)) or \
os.path.exists (os.path.join (sysroot, dll)):
try:
from . import widcomm
if widcomm.inquirer.is_device_ready ():
# if the Widcomm stack is active and a Bluetooth device on that
# stack is detected, then use the Widcomm stack
from .widcomm import *
have_widcomm = True
except ImportError:
pass
if not have_widcomm:
# otherwise, fall back to the Microsoft stack
_dbg("Widcomm not ready. falling back to MS stack")
if sys.version < '3':
from .msbt import *
else:
from bluetooth.msbt import *
elif sys.platform.startswith("linux"):
if sys.version < '3':
from .bluez import *
else:
from bluetooth.bluez import *
elif sys.platform == "darwin":
from .macos import *
else:
raise Exception("This platform (%s) is currently not supported by pybluez." % sys.platform)
discover_devices.__doc__ = \
"""Perform a Bluetooth device discovery.
This function uses the first available Bluetooth resource to discover Bluetooth devices.
Parameters
----------
lookup_names : bool
When set to True :func:`discover_devices` also attempts to look up the display name of each
detected device. (the default is False).
lookup_class : bool
When set to True :func:`discover_devices` attempts to look up the class of each detected device.
(the default is False).
Returns
-------
list
Returns a list of device addresses as strings or a list of tuples. The content of the
tuples depends on the values of lookup_names and lookup_class as detailed below.
============ ============ =====================================
lookup_class lookup_names Return
============ ============ =====================================
False False list of device addresses
False True list of (address, name) tuples
True False list of (address, class) tuples
True True list of (address, name, class) tuples
============ ============ =====================================
"""
lookup_name.__doc__ = \
"""Look up the friendly name of a Bluetooth device.
This function tries to determine the friendly name (human readable) of the device with
the specified Bluetooth address.
Parameters
----------
address : str
The Bluetooth address of the device.
Returns
-------
str or None
The friendly name of the device on success, and None on failure.
Raises
------
BluetoothError
When the provided address is not a valid Bluetooth address.
"""
advertise_service.__doc__ = \
"""Advertise a service with the local SDP server.
Parameters
----------
sock : BluetoothSocket
The :class:`BluetoothSocket` to use for advertising a service. The socket must be a bound,
listening socket.
name : str
The name of the service and service_id (if specified). This should be a string
of the form "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", where each 'X' is a hexadecimal
digit.
service_classes : list
a list of service classes belonging to the advertised service.
Each service class is represented by a 16-bit or 128-bit UUID.
============ ====================================
UUID Type Format
------------ ------------------------------------
Short 16-bit XXXX
Full 128-bit XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
============ ====================================
where each 'X' is a hexadecimal digit.
There are some constants for standard services, e.g. SERIAL_PORT_CLASS that equals to
"1101". Some class constants provided by PyBluez are:
======================== ========================
SERIAL_PORT_CLASS LAN_ACCESS_CLASS
DIALUP_NET_CLASS HEADSET_CLASS
CORDLESS_TELEPHONY_CLASS AUDIO_SOURCE_CLASS
AUDIO_SINK_CLASS PANU_CLASS
NAP_CLASS GN_CLASS
======================== ========================
profiles : list
A list of service profiles that thie service fulfills. Each profile is a tuple with
(uuid, version). Most standard profiles use standard classes as UUIDs.
PyBluez offers a list of standard profiles, for example SERIAL_PORT_PROFILE. All standard profiles have
the same name as the classes, except that _CLASS suffix is replaced by _PROFILE.
provider : str
A text string specifying the provider of the service
description : str
A text string describing the service
protocols : list
A list of protocols
Note
----
A note on working with Symbian smartphones: bt_discover in Python for Series 60 will only
detect service records with service class SERIAL_PORT_CLASS and profile SERIAL_PORT_PROFILE
"""
stop_advertising.__doc__ = \
"""Try to stop advertising a bluetooth service.
This function instructs the local SDP server to stop advertising the service associated
with socket. You should typically call this right before you close socket.
Parameters
----------
sock : BluetoothSocket
The :class:`BluetoothSocket` to stop advertising the service on.
Raises
------
BluetoothError
When SDP fails to stop advertising for some reason.
""""""
"""
find_service.__doc__ = \
"""Use to find available Bluetooth services.
This function uses the service discovery protocol (SDP) to search for Bluetooth
services matching the specified criteria and returns the search results.
The search criteria are defined by passing one or more parameters to the function.
If no criteria are specified then a list of all nearby services detected is
returned. If more than one criteria is specified, then the search results will
match all the criteria specified.
Parameters
----------
name: str or None
The friendly name of a Bluetooth device.
uuid : str or None
A valid 16-bit or 128-bit UUID.
============ ====================================
UUID Type Format
------------ ------------------------------------
Short 16-bit XXXX
Full 128-bit XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
============ ====================================
where each 'X' is a hexadecimal digit.
address : str or None
The Bluetooth address of a device or "localhost".
If "localhost" is provided the function will search for Bluetooth services on the
local machine.
Returns
-------
list
The search results will be a list of dictionaries. Each dictionary represents a
search match having the following key/value pairs.
=============== ===========================================================
Key Value
=============== ===========================================================
host the bluetooth address of the device advertising the
service.
name the name of the service being advertised.
description a description of the service being advertised.
provider the name of the person/organization providing the service.
protocol either 'RFCOMM', 'L2CAP', None if the protocol was not specified,
or 'UNKNOWN' if the protocol was specified but unrecognized.
port the L2CAP PSM number if the protocol is 'L2CAP',
the RFCOMM channel number if the protocol is 'RFCOMM',
or None if the protocol wasn't specified.
service-classes a list of service class IDs (UUID strings). Possibly
empty
profiles a list of profiles the service claims to support.
a profile takes the form of (UUID, version) pairs.
Possibly empty.
service-id the Service ID of the service. None if it wasn't set
See the Bluetooth spec for the difference between
Service ID and Service Class ID List
=============== ===========================================================
"""
BluetoothSocket.__doc__ = \
""" A Bluetooth Socket representing one endpoint of a Bluetooth connection.
Parameters
----------
proto : int
The protocol the socket will use. The options are HCI, L2CAP, RFCOMM, or SCO.
The default is RFCOMM.
.. note:: RFCOMM is the only protocol available for Windows and macOS systems.
"""
BluetoothSocket.dup.__doc__ =\
"""Duplicate the socket
Returns
-------
BluetoothSocket
A new :class:`BluetoothSocket` connected to the same system resource.
"""
BluetoothSocket.accept.__doc__ = \
"""Accept a connection.
Returns
-------
tuple
A tuple containing a :class:`BluetoothSocket` and a Bluetooth address.
Raises
------
BluetoothError
When an attempt to accept a connection fails.
"""
BluetoothSocket.bind.__doc__ = \
"""Bind the socket to a local address and port.
Parameters
----------
addrport : tuple
A tuple of the form (address str, port int)
Raises
------
BluetoothError
When an attempt to bind the socket fails.
"""
#BluetoothSocket.get_l2cap_options.__doc__ =\
# """Get the L2CAP options for the specified L2CAP socket.
# Options are: omtu, imtu, flush_to, mode, fcs, max_tx, txwin_size.
# Returns
# -------
# list
# A list of L2CAP options available for the socket.
# """
BluetoothError.__doc__ = \
"""Raised when a bluetooth function or method fails for a Bluetooth I/O
related reason.
"""
|
