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, if False, the method start 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 is False.

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

stop()[source]

Stops the Bluetooth server if its running.

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.

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

    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, if False, the connect() method will need to be called.
connect()[source]

Connect to a Bluetooth server.

disconnect()[source]

Disconnect from a Bluetooth server.

send(data)[source]

Send data to a Bluetooth server.

Parameters:data (str) – The data to be sent.
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

MockBluetoothServer

class bluedot.mock.MockBluetoothServer(data_received_callback, auto_start=True, device='mock0', port=1, encoding='utf-8', power_up_device=False, when_client_connects=None, when_client_disconnects=None)[source]

MockBluetoothServer inherits from BluetoothServer but overrides __init__, start() and stop() to create a MockBluetoothServer which can be used for testing and debugging.

mock_client_connected(client_address='11:11:11:11:11:11')[source]

Simulates a client connected to the BluetoothServer.

Parameters:client_address (string) – The mock client mac address, defaults to ‘11:11:11:11:11:11’
mock_client_disconnected()[source]

Simulates a client disconnecting from the BluetoothServer.

mock_client_sending_data(data)[source]

Simulates a client sending data to the BluetoothServer.

start()[source]

Starts the Bluetooth server if its not already running. The server needs to be started before connections can be made.

stop()[source]

Stops the Bluetooth server if its running.