Bluetooth Comm API¶
Blue Dot also contains a useful btcomm
API for sending and
receiving data over Bluetooth.
For normal use of Blue Dot, this API doesn’t need to be used, but its included in the documentation for info and for those who might need a simple Bluetooth communication library.
BluetoothServer¶
-
class
bluedot.btcomm.
BluetoothServer
(data_received_callback, auto_start=True, device='hci0', port=1, encoding='utf-8', power_up_device=False, when_client_connects=None, when_client_disconnects=None)[source]¶ Creates a Bluetooth server which will allow connections and accept incoming RFCOMM serial data.
When data is received by the server it is passed to a callback function which must be specified at initiation.
The following example will create a Bluetooth server which will wait for a connection and print any data it receives and send it back to the client:
from bluedot.btcomm import BluetoothServer from signal import pause def data_received(data): print(data) s.send(data) s = BluetoothServer(data_received) pause()
Parameters: - data_received_callback – A function reference should be passed, this function will be called when
data is received by the server. The function should accept a single parameter
which when called will hold the data received. Set to
None
if received data is not required. - auto_start (bool) – If
True
(the default), the Bluetooth server will be automatically started on initialisation, ifFalse
, the methodstart
will need to be called before connections will be accepted. - device (str) – The Bluetooth device the server should use, the default is “hci0”, if your device only has 1 Bluetooth adapter this shouldn’t need to be changed.
- port (int) – The Bluetooth port the server should use, the default is 1.
- encoding (str) – The encoding standard to be used when sending and receiving byte data. The default is
“utf-8”. If set to
None
no encoding is done and byte data types should be used. - power_up_device (bool) –
If
True
, the Bluetooth device will be powered up (if required) when the server starts. The default isFalse
.Depending on how Bluetooth has been powered down, you may need to use rfkill to unblock Bluetooth to give permission to bluez to power on Bluetooth:
sudo rfkill unblock bluetooth
- when_client_connects – A function reference which will be called when a client connects. If
None
(the default), no notification will be given when a client connects - when_client_disconnects – A function reference which will be called when a client disconnects. If
None
(the default), no notification will be given when a client disconnects
-
disconnect_client
()[source]¶ Disconnects the client if connected. Returns True if a client was disconnected.
-
send
(data)[source]¶ Send data to a connected Bluetooth client
Parameters: data (str) – The data to be sent.
-
start
()[source]¶ Starts the Bluetooth server if its not already running. The server needs to be started before connections can be made.
-
adapter
¶ A
BluetoothAdapter
object which represents the Bluetooth device the server is using.
-
client_address
¶ The MAC address of the client connected to the server. Returns
None
if no client is connected.
-
client_connected
¶ Returns
True
if a client is connected.
-
data_received_callback
¶ Sets or returns the function which is called when data is received by the server.
The function should accept a single parameter which when called will hold the data received. Set to
None
if received data is not required.
-
device
¶ The Bluetooth device the server is using. This defaults to “hci0”.
-
encoding
¶ The encoding standard the server is using. This defaults to “utf-8”.
-
port
¶ The port the server is using. This defaults to 1.
-
running
¶ Returns a
True
if the server is running.
-
server_address
¶ The MAC address of the device the server is using.
-
when_client_connects
¶ Sets or returns the function which is called when a client connects.
-
when_client_disconnects
¶ Sets or returns the function which is called when a client disconnects.
- data_received_callback – A function reference should be passed, this function will be called when
data is received by the server. The function should accept a single parameter
which when called will hold the data received. Set to
BluetoothClient¶
-
class
bluedot.btcomm.
BluetoothClient
(server, data_received_callback, port=1, device='hci0', encoding='utf-8', power_up_device=False, auto_connect=True)[source]¶ Creates a Bluetooth client which can send data to a server using RFCOMM Serial Data.
The following example will create a Bluetooth client which will connect to a paired device called “raspberrypi”, send “helloworld” and print any data is receives:
from bluedot.btcomm import BluetoothClient from signal import pause def data_received(data): print(data) c = BluetoothClient("raspberrypi", data_received) c.send("helloworld") pause()
Parameters: - server (str) – The server name (“raspberrypi”) or server MAC address (“11:11:11:11:11:11”) to connect to. The server must be a paired device.
- data_received_callback – A function reference should be passed, this function will be called when
data is received by the client. The function should accept a single parameter
which when called will hold the data received. Set to
None
if data received is not required. - port (int) – The Bluetooth port the client should use, the default is 1.
- device (str) – The Bluetooth device to be used, the default is “hci0”, if your device only has 1 Bluetooth adapter this shouldn’t need to be changed.
- encoding (str) – The encoding standard to be used when sending and receiving byte data. The default is
“utf-8”. If set to
None
no encoding is done and byte data types should be used. - power_up_device (bool) –
If
True
, the Bluetooth device will be powered up (if required) when the server starts. The default isFalse
.Depending on how Bluetooth has been powered down, you may need to use rfkill to unblock Bluetooth to give permission to Bluez to power on Bluetooth:
sudo rfkill unblock bluetooth
- auto_connect (bool) – If
True
(the default), the Bluetooth client will automatically try to connect to the server at initialisation, ifFalse
, theconnect()
method will need to be called.
-
adapter
¶ A
BluetoothAdapter
object which represents the Bluetooth device the client is using.
-
client_address
¶ The MAC address of the device being used.
-
connected
¶ Returns
True
when connected.
-
data_received_callback
¶ Sets or returns the function which is called when data is received by the client.
The function should accept a single parameter which when called will hold the data received. Set to
None
if data received is not required.
-
device
¶ The Bluetooth device the client is using. This defaults to “hci0”.
-
encoding
¶ The encoding standard the client is using. The default is “utf-8”.
-
port
¶ The port the client is using. This defaults to 1.
-
server
¶ The server name (“raspberrypi”) or server MAC address (“11:11:11:11:11:11”) to connect to.
BluetoothAdapter¶
-
class
bluedot.btcomm.
BluetoothAdapter
(device='hci0')[source]¶ Represents and allows interaction with a Bluetooth Adapter.
The following example will get the Bluetooth adapter, print its powered status and any paired devices:
a = BluetoothAdapter() print("Powered = {}".format(a.powered)) print(a.paired_devices)
Parameters: device (str) – The Bluetooth device to be used, the default is “hci0”, if your device only has 1 Bluetooth adapter this shouldn’t need to be changed. -
allow_pairing
(timeout=60)[source]¶ Put the adapter into discoverable and pairable mode.
Parameters: timeout (int) – The time in seconds the adapter will remain pairable. If set to None
the device will be discoverable and pairable indefinetly.
-
address
¶ The MAC address of the Bluetooth adapter.
-
device
¶ The Bluetooth device name. This defaults to “hci0”.
-
discoverable
¶ Set to
True
to make the Bluetooth adapter discoverable.
-
pairable
¶ Set to
True
to make the Bluetooth adapter pairable.
-
paired_devices
¶ Returns a sequence of devices paired with this adapater
[(mac_address, name), (mac_address, name), ...]
:a = BluetoothAdapter() devices = a.paired_devices for d in devices: device_address = d[0] device_name = d[1]
-
powered
¶ Set to
True
to power on the Bluetooth adapter.Depending on how Bluetooth has been powered down, you may need to use rfkill to unblock Bluetooth to give permission to bluez to power on Bluetooth:
sudo rfkill unblock bluetooth
-