PyBluez

https://pybluez.readthedocs.io/en/latest/
Admin
PyBluez is a Python extension module that provides access to system Bluetooth resources for building...
Tokens:11,581
Snippets:144
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install PyBluez from source

Source: https://pybluez.readthedocs.io/en/latest/user/install.html

Install PyBluez by downloading the source code and running the setup script. This method is useful for development or when pip installation is not feasible.

```bash
python setup.py install

```

--------------------------------

### Install PyBluez from source

Source: https://pybluez.readthedocs.io/en/latest/install.html

Install PyBluez by downloading and compiling from the source code. Navigate to the extracted directory before running.

```bash
python setup.py install
```

--------------------------------

### Install PyBluez from source with BLE support (Linux)

Source: https://pybluez.readthedocs.io/en/latest/install.html

Install PyBluez from a local source directory with Bluetooth Low Energy support on Linux using an editable install.

```bash
pip install -e .[ble]
```

--------------------------------

### Install PyBluez using pip

Source: https://pybluez.readthedocs.io/en/latest/user/install.html

Use this command to install PyBluez directly from the Python Package Index. Ensure pip is installed and up-to-date.

```bash
pip install pybluez

```

--------------------------------

### Install PyBluez with BLE support (Linux)

Source: https://pybluez.readthedocs.io/en/latest/install.html

Install PyBluez with experimental Bluetooth Low Energy support on Linux. This requires additional dependencies.

```bash
pip install pybluez[ble]
```

--------------------------------

### Install PyBluez using pip

Source: https://pybluez.readthedocs.io/en/latest/install.html

Use this command to install the standard PyBluez package via pip. Ensure pip is updated.

```bash
pip install pybluez
```

--------------------------------

### pre_inquiry()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

This method is called just after `find_devices` is invoked, but just before the inquiry is started. It is intended to be overridden by subclasses.

```APIDOC
## pre_inquiry()

### Description
Called just after `find_devices` is invoked, but just before the inquiry is started.
This method exists to be overriden.

### Method
`pre_inquiry()`
```

--------------------------------

### inquiry_complete()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

This method is called when an inquiry started by `find_devices` has completed. It is intended to be overridden by subclasses.

```APIDOC
## inquiry_complete()

### Description
Called when an inquiry started by `find_devices` has completed.
This method exists to be overriden.

### Method
`inquiry_complete()`
```

--------------------------------

### accept()

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Accepts an incoming Bluetooth connection on the socket.

```APIDOC
## accept()

### Description
Accept a connection.

### Returns
* A tuple containing a `BluetoothSocket` and a Bluetooth address.

### Return Type
tuple

### Raises
* `BluetoothError` – When an attempt to accept a connection fails.
```

--------------------------------

### find_devices()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

Initiates the device discovery process. Allows configuration of name lookups, duration, and cache flushing.

```APIDOC
## find_devices(lookup_names=True, service_name=None, duration=8, flush_cache=True)

### Description
Call this method to initiate the device discovery process.

### Parameters
* **lookup_names** (bool) - Set to True if you want to lookup the user-friendly names for each device found. Defaults to True.
* **service_name** (string) - Set to the name of a service you’re looking for. Only devices with a service of this name will be returned in `device_discovered()`. NOT YET IMPLEMENTED.
* **duration** (int) - The number of 1.2 second units to spend searching for bluetooth devices. If `lookup_names` is True, then the inquiry process can take a lot longer. Defaults to 8.
* **flush_cache** (bool) - Return devices discovered in previous inquiries. Defaults to True.
```

--------------------------------

### Finding Bluetooth Services

Source: https://pybluez.readthedocs.io/en/latest/api.html

Demonstrates how to use the `find_service` function to discover available Bluetooth services.

```APIDOC
## Find Bluetooth Services

### Description
Use the `find_service` function to discover Bluetooth services. When `address` is set to `None`, it searches for services on nearby devices.

### Method
`bluetooth.find_service(address=None)`

### Parameters
#### Query Parameters
- **address** (string) - Optional - The address of the device to search for services on. If `None`, searches nearby devices.

### Request Example
```python
>>> import bluetooth as bt
>>> services = bt.find_service(address=None)
```

### Response
#### Success Response (200)
- **services** (list) - A list of dictionaries, where each dictionary represents a discovered service and contains details like 'host', 'name', 'port', and 'protocol'.

### Response Example
```json
[
  {
    "host": "XX:XX:XX:XX:XX:XX",
    "name": "My Bluetooth Service",
    "port": 1,
    "protocol": "RFCOMM"
  }
]
```
```

--------------------------------

### bluetooth.advertise_service

Source: https://pybluez.readthedocs.io/en/latest/api/advertise_service.html

Advertise a service with the local SDP server.

```APIDOC
## bluetooth.advertise_service

### Description
Advertise a service with the local SDP server.

### Parameters
#### Path Parameters
- **sock** (BluetoothSocket) – Required - The `BluetoothSocket` to use for advertising a service. The socket must be a bound, listening socket.
- **name** (str) – Required - 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.
#### Query Parameters
- **service_id** (str) – Optional - The service ID.
- **service_classes** (list) – Optional - A list of service classes belonging to the advertised service. Each service class is represented by a 16-bit or 128-bit UUID.
- **profiles** (list) – Optional - A list of service profiles that this service fulfills. Each profile is a tuple with (uuid, version).
- **provider** (str) – Optional - A text string specifying the provider of the service.
- **description** (str) – Optional - A text string describing the service.
- **protocols** (list) – Optional - 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
```

--------------------------------

### advertise_service

Source: https://pybluez.readthedocs.io/en/latest/api_bt_bluez.html

Advertises a service with the local SDP server. Requires a bound, listening socket.

```APIDOC
## advertise_service

### Description
Advertises a service with the local SDP server. The `sock` parameter must be a bound, listening socket. The `name` should be the service's name, and `service_id` (if provided) should be a UUID string.

`service_classes` is a list of service class UUIDs (16-bit or 128-bit). Constants like `SERIAL_PORT_CLASS` are available.

`profiles` is a list of service profiles, each as a tuple of (uuid, version). Constants like `SERIAL_PORT_PROFILE` are available.

`provider` and `description` are text strings for service provider and description, respectively.

### Parameters
- **sock** (socket) - A bound, listening socket.
- **name** (str) - The name of the service.
- **service_id** (str, optional) - The service UUID string (e.g., "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"). Defaults to ''.
- **service_classes** (list, optional) - A list of service class UUID strings. Defaults to [].
- **profiles** (list, optional) - A list of profile tuples (uuid, version). Defaults to [].
- **provider** (str, optional) - Text string specifying the service provider. Defaults to ''.
- **description** (str, optional) - Text string describing the service. Defaults to ''.
- **protocols** (list, optional) - A list of protocols. Defaults to [].

### Notes
On Symbian smartphones, `bt_discover` may only detect services with `SERIAL_PORT_CLASS` and `SERIAL_PORT_PROFILE`.
```

--------------------------------

### discover_devices Function

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Discovers available Bluetooth devices.

```APIDOC
## Function: discover_devices

### Description
Scans for and returns a list of discoverable Bluetooth devices.

### Parameters
(Details of parameters are not provided in the source text)

### Returns
(Details of return value are not provided in the source text)
```

--------------------------------

### discover_devices

Source: https://pybluez.readthedocs.io/en/latest/api_bt_bluez.html

Performs a Bluetooth device discovery using the first available Bluetooth resource.

```APIDOC
## discover_devices

### Description
Performs a Bluetooth device discovery using the first available Bluetooth resource. If `lookup_names` is False, it returns a list of Bluetooth addresses. If `lookup_names` is True, it returns a list of (address, name) tuples. If `lookup_class` is True, the class of the device is also included.

### Parameters
- **duration** (int, optional) - The duration of the discovery in seconds. Defaults to 8.
- **flush_cache** (bool, optional) - Whether to flush the cache before discovery. Defaults to True.
- **lookup_names** (bool, optional) - Whether to lookup device names. Defaults to False.
- **lookup_class** (bool, optional) - Whether to lookup device class. Defaults to False.
- **device_id** (int, optional) - The device ID to use. Defaults to -1.
- **iac** (int, optional) - The inquiry access code. Defaults to 10390323.
```

--------------------------------

### process_event()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

Waits for one event to happen and processes it. The event will be either a device discovery or an inquiry completion.

```APIDOC
## process_event()

### Description
Waits for one event to happen, and proceses it. The event will be either a device discovery, or an inquiry completion.

### Method
`process_event()`
```

--------------------------------

### Import PyBluez Package

Source: https://pybluez.readthedocs.io/en/latest/api.html

Import the PyBluez package for use in your application. This is the standard way to begin using PyBluez functionalities.

```python
>>> import bluetooth as bt
```

--------------------------------

### DeviceDiscoverer Class

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Handles the discovery of Bluetooth devices.

```APIDOC
## Class: DeviceDiscoverer

### Description
Used to discover nearby Bluetooth devices.

### Methods
(Details of methods are not provided in the source text)

### Attributes
(Details of attributes are not provided in the source text)
```

--------------------------------

### bluetooth.DeviceDiscoverer Methods

Source: https://pybluez.readthedocs.io/en/latest/genindex.html

Methods for discovering Bluetooth devices and services.

```APIDOC
## bluetooth.DeviceDiscoverer Methods

### Description
Provides methods for initiating and managing the process of discovering Bluetooth devices and their services.

### Methods
- `cancel_inquiry()`
- `device_discovered()`
- `find_devices(duration=8)`
- `fileno()`
- `inquiry_complete()`
- `pre_inquiry()`
- `process_event()`
- `process_inquiry()`

### Class
- `DeviceDiscoverer`
```

--------------------------------

### Importing the PyBluez Package

Source: https://pybluez.readthedocs.io/en/latest/api.html

This snippet shows the standard way to import the PyBluez package and access its functionalities.

```APIDOC
## Import PyBluez Package

### Description
This is the recommended way to import the PyBluez package for general use.

### Code
```python
>>> import bluetooth as bt
```
```

--------------------------------

### get_l2cap_options(sock, mtu)

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Retrieves L2CAP options for a given L2CAP socket.

```APIDOC
## get_l2cap_options(sock, mtu)

### Description
Gets L2CAP options for the specified L2CAP socket. Options are: omtu, imtu, flush_to, mode, fcs, max_tx, txwin_size.

### Parameters
* **sock** - The L2CAP socket.
* **mtu** - The Maximum Transmission Unit.
```

--------------------------------

### bind(addrport)

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Binds the Bluetooth socket to a local address and port.

```APIDOC
## bind(addrport)

### Description
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.
```

--------------------------------

### discover_devices Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Discovers available Bluetooth devices within range.

```APIDOC
## function bluetooth.msbt.discover_devices(_duration=8, _flush_cache=True, _lookup_names=False, _lookup_class=False, _device_id=-1)

### Description
Scans for nearby Bluetooth devices and returns a list of discovered devices.

### Parameters
- `_duration` (int, optional): The duration in seconds to scan for devices. Defaults to 8.
- `_flush_cache` (bool, optional): Whether to flush the device cache before scanning. Defaults to True.
- `_lookup_names` (bool, optional): Whether to look up the names of discovered devices. Defaults to False.
- `_lookup_class` (bool, optional): Whether to look up the class of discovered devices. Defaults to False.
- `_device_id` (int, optional): The ID of the Bluetooth adapter to use. Defaults to -1 (use default adapter).
```

--------------------------------

### Exceptions

Source: https://pybluez.readthedocs.io/en/latest/genindex.html

Custom exception class for Bluetooth related errors.

```APIDOC
## Exceptions

### Description
Provides a custom exception for handling errors specific to Bluetooth operations.

### Exception
- `BluetoothError`
```

--------------------------------

### advertise_service Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Advertises a Bluetooth service on macOS.

```APIDOC
## function bluetooth.macos.advertise_service(_sock, _name, _service_id='', _service_classes=None, _profiles=None, _provider='', _description='', _protocols=None)

### Description
Allows the device to advertise a specific Bluetooth service.

### Parameters
- **_sock** (object) - Required - The socket to use for advertising.
- **_name** (str) - Required - The name of the service.
- **_service_id** (str) - Optional - The unique identifier for the service.
- **_service_classes** (list) - Optional - A list of service classes.
- **_profiles** (list) - Optional - A list of service profiles.
- **_provider** (str) - Optional - The provider of the service.
- **_description** (str) - Optional - A description of the service.
- **_protocols** (list) - Optional - A list of supported protocols.
```

--------------------------------

### discover_devices

Source: https://pybluez.readthedocs.io/en/latest/api/discover_devices.html

Performs a Bluetooth device discovery using the first available Bluetooth resource. It can optionally look up device names and classes.

```APIDOC
## discover_devices

### Description
Perform a Bluetooth device discovery. This function uses the first available Bluetooth resource to discover Bluetooth devices.

### Parameters
* **duration** (int) - Optional - The duration of the discovery in seconds. Defaults to 8.
* **flush_cache** (bool) - Optional - Whether to flush the cache before discovery. Defaults to True.
* **lookup_names** (bool) - Optional - When set to True, `discover_devices()` also attempts to look up the display name of each detected device. Defaults to False.
* **lookup_class** (bool) - Optional - When set to True, `discover_devices()` attempts to look up the class of each detected device. Defaults to False.
* **device_id** (int) - Optional - The ID of the Bluetooth device to use. Defaults to -1.
* **iac** (int) - Optional - The Inquiry Access Code. Defaults to 10390323.

### Returns
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`:
- If `lookup_class` is False and `lookup_names` is False: list of device addresses.
- If `lookup_class` is False and `lookup_names` is True: list of (address, name) tuples.
- If `lookup_class` is True and `lookup_names` is False: list of (address, class) tuples.
- If `lookup_class` is True and `lookup_names` is True: list of (address, name, class) tuples.

### Return Type
list
```

--------------------------------

### discover_devices Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Discovers nearby Bluetooth devices on macOS.

```APIDOC
## function bluetooth.macos.discover_devices(duration=8, flush_cache=True, lookup_names=False, lookup_class=False, device_id=-1)

### Description
Scans for and returns a list of discoverable Bluetooth devices.

### Parameters
- **duration** (int) - Optional - The duration in seconds to scan for devices.
- **flush_cache** (bool) - Optional - Whether to flush the device cache before scanning.
- **lookup_names** (bool) - Optional - Whether to look up device names.
- **lookup_class** (bool) - Optional - Whether to look up device class information.
- **device_id** (int) - Optional - A specific device ID to look for.
```

--------------------------------

### dup()

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Creates a duplicate of the current Bluetooth socket.

```APIDOC
## dup()

### Description
Duplicate the socket

### Returns
* A new `BluetoothSocket` connected to the same system resource.

### Return Type
BluetoothSocket
```

--------------------------------

### set_l2cap_options(sock, options)

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Sets L2CAP options for a specified L2CAP socket.

```APIDOC
## set_l2cap_options(sock, options)

### Description
Sets L2CAP options for the specified L2CAP socket. The option list must be in the same format supplied by get_l2cap_options().

### Parameters
* **sock** - The L2CAP socket.
* **options** - A dictionary or list of L2CAP options.
```

--------------------------------

### process_inquiry()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

Repeatedly calls `process_event()` until the device inquiry has completed.

```APIDOC
## process_inquiry()

### Description
Repeatedly calls `process_event()` until the device inquiry has completed.

### Method
`process_inquiry()`
```

--------------------------------

### fileno()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

Returns the file descriptor associated with the discovery process.

```APIDOC
## fileno()

### Description
Returns the file descriptor associated with the discovery process.

### Method
`fileno()`
```

--------------------------------

### find_service

Source: https://pybluez.readthedocs.io/en/latest/api/find_service.html

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. 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.

```APIDOC
## find_service

### Description
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. 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.

### Method Signature
`bluetooth.find_service(name=None, uuid=None, address=None)`

### Parameters
#### Optional 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
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

### Return Type
list
```

--------------------------------

### advertise_service Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Advertises a Bluetooth service on the network.

```APIDOC
## function bluetooth.msbt.advertise_service(_sock_, _name, _service_id='', _service_classes=[], _profiles=[], _provider='', _description='', _protocols=[])

### Description
Advertises a specific Bluetooth service, making it discoverable by other devices.

### Parameters
- `_sock_` (object): The socket object to use for advertising.
- `_name` (str): The name of the service to advertise.
- `_service_id` (str, optional): The unique identifier for the service. Defaults to ''.
- `_service_classes` (list, optional): A list of service class identifiers. Defaults to [].
- `_profiles` (list, optional): A list of supported profiles. Defaults to [].
- `_provider` (str, optional): The provider of the service. Defaults to ''.
- `_description` (str, optional): A description of the service. Defaults to ''.
- `_protocols` (list, optional): A list of supported protocols. Defaults to [].
```

--------------------------------

### advertise_service Function

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Advertises a Bluetooth service.

```APIDOC
## Function: advertise_service

### Description
Allows a service to be advertised over Bluetooth.

### Parameters
(Details of parameters are not provided in the source text)

### Returns
(Details of return value are not provided in the source text)
```

--------------------------------

### DeviceDiscoverer Class

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Represents a class for discovering Bluetooth devices on Windows.

```APIDOC
## class bluetooth.msbt.DeviceDiscoverer

### Description
This class is used for discovering Bluetooth devices on the Windows platform.

### Usage
Instantiate this class to begin the device discovery process.
```

--------------------------------

### find_service Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Finds Bluetooth services on macOS.

```APIDOC
## function bluetooth.macos.find_service(name=None, uuid=None, address=None)

### Description
Searches for Bluetooth services based on provided criteria.

### Parameters
- **name** (str) - Optional - The name of the service to find.
- **uuid** (str) - Optional - The UUID of the service to find.
- **address** (str) - Optional - The address of the device hosting the service.
```

--------------------------------

### device_discovered()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

This method is called when a Bluetooth device is discovered. It is intended to be overridden by subclasses.

```APIDOC
## device_discovered(address, device_class, rssi, name)

### Description
Called when a bluetooth device is discovered.
This method exists to be overriden.

### Parameters
* **address** (string) - The bluetooth address of the device.
* **device_class** (string) - The Class of Device, as specified in [1], passed in as a 3-byte string.
* **rssi** (int) - The Received Signal Strength Indicator.
* **name** (string) - The user-friendly name of the device if `lookup_names` was set when the inquiry was started, otherwise None.
```

--------------------------------

### DeviceDiscoverer Class

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Represents a class for discovering Bluetooth devices on macOS.

```APIDOC
## class bluetooth.macos.DeviceDiscoverer

### Description
This class is used for discovering Bluetooth devices on macOS.

### Usage
Instantiate this class to begin the device discovery process.
```

--------------------------------

### Find Bluetooth Services

Source: https://pybluez.readthedocs.io/en/latest/api.html

Use the find_service function from the PyBluez package to discover available Bluetooth services. This function can search for services on any device if the address is set to None.

```python
>>> import bluetooth as bt
>>> services = bt.find_service(address=None)
```

--------------------------------

### lookup_name Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Resolves a Bluetooth device address to its name.

```APIDOC
## function bluetooth.msbt.lookup_name(_address, _timeout=10)

### Description
Attempts to resolve a given Bluetooth device address to its human-readable name.

### Parameters
- `_address` (str): The Bluetooth address of the device.
- `_timeout` (int, optional): The timeout in seconds for the lookup. Defaults to 10.
```

--------------------------------

### find_service

Source: https://pybluez.readthedocs.io/en/latest/api_bt_bluez.html

Searches for SDP services matching specified criteria.

```APIDOC
## find_service

### Description
Searches for SDP services that match the specified criteria and returns the search results. If no criteria are specified, it returns a list of all nearby services. If multiple criteria are specified, the results must match all of them. The `uuid` parameter must be a 16-bit or 128-bit UUID string. 'localhost' can be used for the `address` to search on the local machine.

The search results are a list of dictionaries, each containing details about the service.

### Parameters
- **name** (str, optional) - The name of the service to search for. Defaults to None.
- **uuid** (str, optional) - The UUID of the service to search for (16-bit or 128-bit). Defaults to None.
- **address** (str, optional) - The Bluetooth address of the device to search on, or 'localhost'. Defaults to None.

### Response Structure (each dictionary in the list)
- **host** (str) - The Bluetooth address of the device advertising the service.
- **name** (str) - The name of the service being advertised.
- **description** (str) - A description of the service.
- **provider** (str) - The name of the service provider.
- **protocol** (str) - The protocol used ('RFCOMM', 'L2CAP', None, or 'UNKNOWN').
- **port** (int or None) - The L2CAP PSM or RFCOMM channel number.
- **service-classes** (list) - A list of service class IDs (UUID strings).
- **profiles** (list) - A list of supported profiles as (UUID, version) pairs.
- **service-id** (str or None) - The Service ID of the service.
```

--------------------------------

### Module Level Functions

Source: https://pybluez.readthedocs.io/en/latest/genindex.html

Top-level functions available in the bluetooth module.

```APIDOC
## Module Level Functions

### Description
Functions directly available at the module level for Bluetooth operations.

### Functions
- `advertise_service()`
- `discover_devices(duration=8)`
- `find_service()`
- `lookup_name(address, timeout=8)`
- `stop_advertising()`
```

--------------------------------

### find_service Function

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Finds services offered by Bluetooth devices.

```APIDOC
## Function: find_service

### Description
Searches for specific services on Bluetooth devices.

### Parameters
(Details of parameters are not provided in the source text)

### Returns
(Details of return value are not provided in the source text)
```

--------------------------------

### find_service Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Searches for Bluetooth services on a remote device.

```APIDOC
## function bluetooth.msbt.find_service(name=None, uuid=None, address=None)

### Description
Searches for services offered by a specific Bluetooth device or services matching certain criteria.

### Parameters
- `name` (str, optional): The name of the service to find. Defaults to None.
- `uuid` (str, optional): The UUID of the service to find. Defaults to None.
- `address` (str, optional): The address of the device to search on. Defaults to None.
```

--------------------------------

### BluetoothError Exception

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Custom exception for Bluetooth-related errors.

```APIDOC
## Exception: BluetoothError

### Description
Raised when a Bluetooth function or method fails due to an I/O related reason.

### Bases
`OSError`
```

--------------------------------

### stop_advertising

Source: https://pybluez.readthedocs.io/en/latest/api/stop_advertising.html

This function instructs the local SDP server to stop advertising the service associated with a socket. It should typically be called right before closing the socket.

```APIDOC
## stop_advertising

### Description
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.

### Method
`bluetooth.stop_advertising`

### Parameters
#### Path Parameters
- **sock** (BluetoothSocket) - Required - The `BluetoothSocket` to stop advertising the service on.

### Raises
- **BluetoothError** - When SDP fails to stop advertising for some reason.
```

--------------------------------

### lookup_name

Source: https://pybluez.readthedocs.io/en/latest/api_bt_bluez.html

Tries to determine the friendly name of a device with a specified Bluetooth address.

```APIDOC
## lookup_name

### Description
Tries to determine the friendly, human-readable name of the device with the specified Bluetooth address. Returns the name on success, and None on failure.

### Parameters
- **address** (str) - The Bluetooth address of the device.
- **timeout** (int, optional) - The timeout in seconds for the lookup. Defaults to 10.
```

--------------------------------

### BluetoothSocket Class

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Represents a Bluetooth socket connection on Windows.

```APIDOC
## class bluetooth.msbt.BluetoothSocket(_proto=None, _sockfd=None)

### Description
Provides functionality for creating and managing Bluetooth sockets on Windows.

### Parameters
- `_proto` (object, optional): The protocol to use for the socket. Defaults to a mock object.
- `_sockfd` (int, optional): The socket file descriptor. Defaults to None.

### Methods
#### getpeername()
Used by autodoc_mock_imports.
```

--------------------------------

### bluetooth.BluetoothSocket Methods

Source: https://pybluez.readthedocs.io/en/latest/genindex.html

Methods available for BluetoothSocket objects, used for network communication over Bluetooth.

```APIDOC
## bluetooth.BluetoothSocket Methods

### Description
Provides methods for managing Bluetooth socket connections, including data transfer, connection management, and socket options.

### Methods
- `accept()`
- `bind(address)`
- `close()`
- `connect(address)`
- `connect_ex(address)`
- `dup()`
- `fileno()`
- `get_l2cap_options()`
- `getpeername()`
- `getsockname()`
- `getsockopt(level, optname)`
- `gettimeout()`
- `listen(backlog)`
- `makefile(mode='r', buffering=None)`
- `recv(bufsize, flags=0)`
- `recvfrom(bufsize, flags=0)`
- `send(data, flags=0)`
- `sendall(data, flags=0)`
- `sendto(data, flags=0, address=None)`
- `set_l2cap_mtu(mtu)`
- `set_l2cap_options(options)`
- `setblocking(flag)`
- `setl2capsecurity(level)`
- `setsockopt(level, optname, value)`
- `settimeout(value)`
- `shutdown(how)`

### Attributes
- `family`
- `proto`
- `timeout`
- `type`
```

--------------------------------

### lookup_name Function

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Looks up the Bluetooth name of a device.

```APIDOC
## Function: lookup_name

### Description
Retrieves the human-readable name associated with a Bluetooth device address.

### Parameters
(Details of parameters are not provided in the source text)

### Returns
(Details of return value are not provided in the source text)
```

--------------------------------

### lookup_name Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Looks up the name of a Bluetooth device by its address on macOS.

```APIDOC
## function bluetooth.macos.lookup_name(address, timeout=10)

### Description
Retrieves the human-readable name of a Bluetooth device given its address.

### Parameters
- **address** (str) - Required - The Bluetooth address of the device.
- **timeout** (int) - Optional - The time in seconds to wait for a response.
```

--------------------------------

### read_local_bdaddr Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Retrieves the Bluetooth address of the local machine.

```APIDOC
## function bluetooth.msbt.read_local_bdaddr()

### Description
Returns the Bluetooth Device Address (BD_ADDR) of the local machine.
```

--------------------------------

### BluetoothSocket Class

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Represents a Bluetooth socket connection on macOS.

```APIDOC
## class bluetooth.macos.BluetoothSocket(_proto=3, __sock=None)

### Description
Provides functionality for creating and managing Bluetooth sockets on macOS.

### Parameters
- **_proto** (int) - Optional - The protocol for the socket.
- **__sock** (object) - Optional - An existing socket object.
```

--------------------------------

### bluetooth.btcommon.to_full_uuid

Source: https://pybluez.readthedocs.io/en/latest/api_com.html

Converts a short 16-bit or 32-bit reserved UUID to a full 128-bit Bluetooth UUID.

```APIDOC
## bluetooth.btcommon.to_full_uuid

### Description
Converts a short 16-bit or 32-bit reserved UUID to its full 128-bit Bluetooth UUID representation.

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The short UUID (16-bit or 32-bit) to convert.

### Response
#### Success Response (string)
- **full_uuid** (string) - The converted 128-bit UUID.
```

--------------------------------

### stop_advertising Function

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Stops advertising a Bluetooth service.

```APIDOC
## Function: stop_advertising

### Description
Ceases the advertisement of a previously started Bluetooth service.

### Parameters
(Details of parameters are not provided in the source text)

### Returns
(Details of return value are not provided in the source text)
```

--------------------------------

### cancel_inquiry()

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

Call this method to cancel an inquiry in process. The `inquiry_complete` method will still be called.

```APIDOC
## cancel_inquiry()

### Description
Call this method to cancel an inquiry in process. `inquiry_complete` will still be called.

### Method
`cancel_inquiry()`
```

--------------------------------

### BluetoothSocket Class

Source: https://pybluez.readthedocs.io/en/latest/api/index.html

Represents a Bluetooth socket for communication.

```APIDOC
## Class: BluetoothSocket

### Description
Provides the interface for Bluetooth socket operations.

### Methods
(Details of methods are not provided in the source text)

### Attributes
(Details of attributes are not provided in the source text)
```

--------------------------------

### DeviceDiscoverer Class

Source: https://pybluez.readthedocs.io/en/latest/api/device_discoverer.html

The DeviceDiscoverer class is a skeleton for finer control of the device discovery process. Subclass this class to implement asynchronous device discovery.

```APIDOC
## class `bluetooth.DeviceDiscoverer`

### Description
Skeleton class for finer control of the device discovery process. To implement asynchronous device discovery (e.g. if you want to do something _as soon as_ a device is discovered), subclass DeviceDiscoverer and override `device_discovered()` and `inquiry_complete()`.

### Parameters
* **device_id** (int) - Optional - Defaults to -1.
```

--------------------------------

### stop_advertising Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_ms.html

Stops the advertisement of a Bluetooth service.

```APIDOC
## function bluetooth.msbt.stop_advertising(_sock_)

### Description
Stops the ongoing advertisement of a Bluetooth service associated with the provided socket.

### Parameters
- `_sock_` (object): The socket object whose service advertisement should be stopped.
```

--------------------------------

### read_local_bdaddr Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Reads the local Bluetooth device address on macOS.

```APIDOC
## function bluetooth.macos.read_local_bdaddr()

### Description
Returns the Bluetooth Device Address (BD_ADDR) of the local machine.
```

--------------------------------

### bluetooth.lookup_name

Source: https://pybluez.readthedocs.io/en/latest/api/lookup_name.html

Looks up the friendly name of a Bluetooth device using its address. It attempts to resolve the human-readable name for a device specified by its Bluetooth address.

```APIDOC
## bluetooth.lookup_name

### Description
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.

### Method
`bluetooth.lookup_name(_address_, _timeout_=10_)

### Parameters
#### Path Parameters
- **address** (str) - The Bluetooth address of the device.
- **timeout** (int) - Optional. Defaults to 10. The timeout in seconds for the lookup operation.

### 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.
```

--------------------------------

### stop_advertising Function

Source: https://pybluez.readthedocs.io/en/latest/api_bt_macos.html

Stops Bluetooth service advertising on macOS.

```APIDOC
## function bluetooth.macos.stop_advertising(_sock)

### Description
Stops the Bluetooth service advertising associated with the given socket.

### Parameters
- **_sock** (object) - Required - The socket used for advertising.
```

--------------------------------

### set_l2cap_mtu(sock, mtu)

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

Adjusts the Maximum Transmission Unit (MTU) for an L2CAP socket.

```APIDOC
## set_l2cap_mtu(sock, mtu)

### Description
Adjusts the MTU for the specified L2CAP socket. This method needs to be invoked on both sides of the connection for it to work! The default mtu that all L2CAP connections start with is 672 bytes.

### Parameters
* **sock** - The L2CAP socket.
* **mtu** - The Maximum Transmission Unit. Must be between 48 and 65535, inclusive.
```

--------------------------------

### bluetooth.btcommon.is_valid_address

Source: https://pybluez.readthedocs.io/en/latest/api_com.html

Checks if a given string is a valid Bluetooth address.

```APIDOC
## bluetooth.btcommon.is_valid_address

### Description
Returns True if the input string is a valid Bluetooth address. Valid addresses are in the format XX:XX:XX:XX:XX:XX where X is a hexadecimal character.

### Parameters
#### Path Parameters
- **s** (string) - Required - The string to validate as a Bluetooth address.

### Response
#### Success Response (True/False)
- **result** (boolean) - True if the address is valid, False otherwise.
```

--------------------------------

### bluetooth.btcommon.is_valid_uuid

Source: https://pybluez.readthedocs.io/en/latest/api_com.html

Checks if a given string is a valid 128-bit UUID.

```APIDOC
## bluetooth.btcommon.is_valid_uuid

### Description
Returns True if the input string is a valid 128-bit UUID. Valid UUIDs are strings in the format XXXX XXXXXXXX XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, where X is a hexadecimal digit (case insensitive).

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The string to validate as a UUID.

### Response
#### Success Response (True/False)
- **result** (boolean) - True if the UUID is valid, False otherwise.
```

--------------------------------

### BluetoothSocket Class

Source: https://pybluez.readthedocs.io/en/latest/api/bluetooth_socket.html

The BluetoothSocket class is the primary interface for Bluetooth communication. It supports various protocols like RFCOMM, L2CAP, SCO, and HCI.

```APIDOC
## class `bluetooth.BluetoothSocket`

### Description
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.
* **__sock** (optional) - Internal socket object.
```
Tokens:
Raw