Bluetooth Comm API

Blue Dot also contains a useful API bluedot.btcomm 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)

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 (string) – 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 (string) – 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
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.

send(data)

Send data to a connected bluetooth client

Parameters:data (string) – The data to be sent.
server_address

The mac address of the device the server is using.

start()

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

stop()

Stops the Bluetooth server if its running.

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)

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 (string) –

    The server name (“raspberrypi”) or server mac address (“11:11:11:11:11:11”) to connect too.

    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 (string) – 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 (string) – 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 method connect 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.

connect()

Connect to a bluetooth server.

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.

disconnect()

Disconnect from a bluetooth server.

encoding

The encoding standard the client is using. The default is utf-8.

port

The port the client is using. This defaults to 1.

send(data)

Send data to a bluetooth server

Parameters:data (string) – The data to be sent.
server

The server name (“raspberrypi”) or server mac address (“11:11:11:11:11:11”) to connect too.

BluetoothAdapter

class bluedot.btcomm.BluetoothAdapter(device='hci0')

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 (string) – 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.
address

The mac address of the bluetooth adapter.

allow_pairing(timeout=60)

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.
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 list of devices paired with this adapater ((device_mac_address, device_name), (device_mac_address, device_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