Blue Dot API¶
BlueDot¶
-
class
bluedot.
BlueDot
(device='hci0', port=1, auto_start_server=True, power_up_device=False, print_messages=True, cols=1, rows=1)[source]¶ Interacts with a Blue Dot client application, communicating when and where a button has been pressed, released or held.
This class starts an instance of
btcomm.BluetoothServer
which manages the connection with the Blue Dot client.This class is intended for use with a Blue Dot client application.
The following example will print a message when the Blue Dot button is pressed:
from bluedot import BlueDot bd = BlueDot() bd.wait_for_press() print("The button was pressed")
Multiple buttons can be created, by changing the number of columns and rows. Each button can be referenced using its [col, row]:
bd = BlueDot(cols=2, rows=2) bd[0,0].wait_for_press() print("Top left button pressed") bd[1,1].wait_for_press() print("Bottom right button pressed")
Parameters: - 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, and under normal use this should never need to change.
- auto_start_server (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. - 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
- print_messages (bool) – If
True
(the default), server status messages will be printed stating when the server has started and when clients connect / disconnect. - cols (int) – The number of columns in the grid of buttons. Defaults to
1
. - rows (int) – The number of rows in the grid of buttons. Defaults to
1
.
-
allow_pairing
(timeout=60)[source]¶ Allow a Bluetooth device to pair with your Raspberry Pi by putting 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.
-
resize
(cols, rows)[source]¶ Resizes the grid of buttons.
Parameters: Note
Existing buttons will retain their state (color, border, etc) when resized. New buttons will be created with the default values set by the
BlueDot
.
-
set_when_client_connects
(callback, background=False)[source]¶ Sets the function which is called when a Blue Dot connects.
Parameters: - callback (Callable) – The function to call, setting to None will stop the callback.
- background (bool) – If set to True the function will be run in a separate thread and it will return immediately. The default is False.
-
set_when_client_disconnects
(callback, background=False)[source]¶ Sets the function which is called when a Blue Dot disconnects.
Parameters: - callback (Callable) – The function to call, setting to None will stop the callback.
- background (bool) – If set to True the function will be run in a separate thread and it will return immediately. The default is False.
-
start
()[source]¶ Start the
btcomm.BluetoothServer
if it is not already running. By default the server is started at initialisation.
-
wait_for_connection
(timeout=None)[source]¶ Waits until a Blue Dot client connects. Returns
True
if a client connects.Parameters: timeout (float) – Number of seconds to wait for a wait connections, if None
(the default), it will wait indefinetly for a connection from a Blue Dot client.
-
adapter
¶ The
btcomm.BluetoothAdapter
instance that is being used.
-
border
¶ When set to True adds a border to the dot. Default is False.
Note
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
A list of
BlueDotButton
objects in the “grid”.
-
color
¶ Sets or returns the color of the button. Defaults to BLUE.
An instance of
colors.Color
is returned.Value can be set as a
colors.Color
object, a hex color value in the format #rrggbb or #rrggbbaa, a tuple of (red, green, blue) or (red, green, blue, alpha) values between 0 & 255 or a text description of the color, e.g. “red”.A dictionary of available colors can be obtained from bluedot.COLORS.
Note
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
-
cols
¶ Sets or returns the number of columns in the grid of buttons.
-
device
¶ The Bluetooth device the server is using. This defaults to “hci0”.
-
double_press_time
¶ Sets or returns the time threshold in seconds for a double press. Defaults to 0.3.
Note
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
-
interaction
¶ Returns an instance of
BlueDotInteraction
representing the current or last interaction with the Blue Dot.Note
If the Blue Dot is released (and inactive),
interaction
will return the interaction when it was released, until it is pressed again. If the Blue Dot has never been pressedinteraction
will returnNone
.If there are multiple buttons, the interaction will only be returned for button [0,0]
Deprecated since version 2.0.0.
-
is_connected
¶ Returns
True
if a Blue Dot client is connected.
-
is_pressed
¶ Returns
True
if the button is pressed (or held).Note
If there are multiple buttons, if any button is pressed, True will be returned.
-
paired_devices
¶ Returns a sequence of devices paired with this adapter
[(mac_address, name), (mac_address, name), ...]
:bd = BlueDot() devices = bd.paired_devices for d in devices: device_address = d[0] device_name = d[1]
-
port
¶ The port the server is using. This defaults to 1.
-
print_messages
¶ When set to
True
messages relating to the status of the Bluetooth server will be printed.
-
rotation_segments
¶ Sets or returns the number of virtual segments the button is split into for rotating. Defaults to 8.
Note
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
-
rows
¶ Sets or returns the number of rows in the grid of buttons.
-
running
¶ Returns a
True
if the server is running.
-
server
¶ The
btcomm.BluetoothServer
instance that is being used to communicate with clients.
-
square
¶ When set to True the ‘dot’ is made square. Default is False.
Note
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
-
visible
¶ When set to False the dot will be hidden. Default is True.
Note
Events (press, release, moved) are still sent from the dot when it is not visible.
If there are multiple buttons in the grid, the ‘default’ value will be returned and when set all buttons will be updated.
-
when_client_connects
¶ Sets or returns the function which is called when a Blue Dot application connects.
The function will be run in the same thread and block, to run in a separate thread use set_when_client_connects(function, background=True)
-
when_client_disconnects
¶ Sets or returns the function which is called when a Blue Dot disconnects.
The function will be run in the same thread and block, to run in a separate thread use set_when_client_disconnects(function, background=True)
BlueDotButton¶
-
class
bluedot.
BlueDotButton
(bd, col, row, color, square, border, visible)[source]¶ Represents a single button on the button client applications. It keeps tracks of when and where the button has been pressed and processes any events.
This class is intended for use via
BlueDot
and should not be instantiated “manually”.A button can be interacted with individually via
BlueDot
by stating its position in the grid e.g.from bluedot import BlueDot bd = BlueDot() first_button = bd[0,0].wait_for_press first_button.wait_for_press() print("The first button was pressed")
Parameters: - :param string color
The color of the button.
Can be set as a
colors.Color
object, a hex color value in the format #rrggbb or #rrggbbaa, a tuple of (red, green, blue) or (red, green, blue, alpha) values between 0 & 255 or a text description of the color, e.g. “red”.A dictionary of available colors can be obtained from bluedot.COLORS.
Parameters: -
get_rotation
()[source]¶ Returns an instance of
BlueDotRotation
if the last interaction with the button was a rotation. Returns None if the button was not rotated.
-
get_swipe
()[source]¶ Returns an instance of
BlueDotSwipe
if the last interaction with the button was a swipe. Returns None if the button was not swiped.
-
is_double_press
(position)[source]¶ Returns True if the position passed represents a double press.
i.e. The last interaction was the button was to release it, and the time to press is less than the double_press_time.
Parameters: position (BlueDotPosition) – The BlueDotPosition where the Dot was pressed.
-
move
(position)[source]¶ Processes any “released” events associated with this button.
Parameters: position (BlueDotPosition) – The BlueDotPosition where the Dot was pressed.
-
press
(position)[source]¶ Processes any “pressed” events associated with this button.
Parameters: position (BlueDotPosition) – The BlueDotPosition where the dot was pressed.
-
release
(position)[source]¶ Processes any “released” events associated with this button.
Parameters: position (BlueDotPosition) – The BlueDotPosition where the Dot was pressed.
-
border
¶ When set to True adds a border to the dot. Default is False.
-
color
¶ Sets or returns the color of the dot. Defaults to BLUE.
An instance of
colors.Color
is returned.Value can be set as a
colors.Color
object, a hex color value in the format #rrggbb or #rrggbbaa, a tuple of (red, green, blue) or (red, green, blue, alpha) values between 0 & 255 or a text description of the color, e.g. “red”.A dictionary of available colors can be obtained from bluedot.COLORS.
-
interaction
¶ Returns an instance of
BlueDotInteraction
representing the current or last interaction with the button.Note
If the button is released (and inactive),
interaction
will return the interaction when it was released, until it is pressed again. If the button has never been pressedinteraction
will returnNone
.
-
modified
¶ Returns True if the button’s appearance has been modified [is different] from the default.
-
square
¶ When set to True the ‘dot’ is made square. Default is False.
-
visible
¶ When set to False the dot will be hidden. Default is True.
Note
Events (press, release, moved) are still sent from the dot when it is not visible.
BlueDotPosition¶
-
class
bluedot.
BlueDotPosition
(col, row, x, y)[source]¶ Represents a position of where the blue dot is pressed, released or held.
Parameters: -
angle
¶ The angle from centre of where the Blue Dot is pressed, held or released. 0 degrees is up, 0..180 degrees clockwise, -180..0 degrees anti-clockwise.
-
bottom
¶ Returns
True
if the Blue Dot is pressed, held or released at the bottom.
-
col
¶ The column.
-
distance
¶ The distance from centre of where the Blue Dot is pressed, held or released. The radius of the Blue Dot is 1.
-
left
¶ Returns
True
if the Blue Dot is pressed, held or released on the left.
-
middle
¶ Returns
True
if the Blue Dot is pressed, held or released in the middle.
-
right
¶ Returns
True
if the Blue Dot is pressed, held or released on the right.
-
row
¶ The row.
-
time
¶ The time the blue dot was at this position.
Note
This is the time the message was received from the Blue Dot app, not the time it was sent.
-
top
¶ Returns
True
if the Blue Dot is pressed, held or released at the top.
-
x
¶ The x position of the Blue Dot, 0 being centre, -1 being far left and 1 being far right.
-
y
¶ The y position of the Blue Dot, 0 being centre, -1 being at the bottom and 1 being at the top.
-
BlueDotInteraction¶
-
class
bluedot.
BlueDotInteraction
(pressed_position)[source]¶ Represents an interaction with the Blue Dot, from when it was pressed to when it was released.
A
BlueDotInteraction
can be active or inactive, i.e. it is active because the Blue Dot has not been released, or inactive because the Blue Dot was released and the interaction finished.Parameters: pressed_position (BlueDotPosition) – The BlueDotPosition when the Blue Dot was pressed. -
moved
(moved_position)[source]¶ Adds an additional position to the interaction, called when the position the Blue Dot is pressed moves.
-
released
(released_position)[source]¶ Called when the Blue Dot is released and completes a Blue Dot interaction
Parameters: released_position (BlueDotPosition) – The BlueDotPosition when the Blue Dot was released.
-
active
¶ Returns
True
if the interaction is still active, i.e. the Blue Dot hasnt been released.
-
current_position
¶ Returns the current position for the interaction.
If the interaction is inactive, it will return the position when the Blue Dot was released.
-
distance
¶ Returns the total distance of the Blue Dot interaction
-
duration
¶ Returns the duration in seconds of the interaction, i.e. the amount time between when the Blue Dot was pressed and now or when it was released.
-
positions
¶ A sequence of
BlueDotPosition
instances for all the positions which make up this interaction.The first position is where the Blue Dot was pressed, the last is where the Blue Dot was released, all position in between are where the position Blue Dot changed (i.e. moved) when it was held down.
-
pressed_position
¶ Returns the position when the Blue Dot was pressed i.e. where the interaction started.
-
previous_position
¶ Returns the previous position for the interaction.
If the interaction contains only 1 position, None will be returned.
-
released_position
¶ Returns the position when the Blue Dot was released i.e. where the interaction ended.
If the interaction is still active it returns
None
.
-
BlueDotSwipe¶
-
class
bluedot.
BlueDotSwipe
(interaction)[source]¶ Represents a Blue Dot swipe interaction.
A
BlueDotSwipe
can be valid or invalid based on whether the Blue Dot interaction was a swipe or not.Parameters: interaction (BlueDotInteraction) – The BlueDotInteraction object to be used to determine whether the interaction was a swipe. -
angle
¶ Returns the angle of the swipe (i.e. the angle between the pressed and released positions)
-
col
¶ The column.
-
direction
¶ Returns the direction (“up”, “down”, “left”, “right”) of the swipe. If the swipe is not valid None is returned.
-
distance
¶ Returns the distance of the swipe (i.e. the distance between the pressed and released positions)
-
down
¶ Returns
True
if the Blue Dot was swiped down.
-
interaction
¶ The
BlueDotInteraction
object relating to this swipe.
-
left
¶ Returns
True
if the Blue Dot was swiped left.
-
right
¶ Returns
True
if the Blue Dot was swiped right.
-
row
¶ The row.
-
speed
¶ Returns the speed of the swipe in Blue Dot radius / second.
-
up
¶ Returns
True
if the Blue Dot was swiped up.
-
valid
¶ Returns
True
if the Blue Dot interaction is a swipe.
-
BlueDotRotation¶
-
class
bluedot.
BlueDotRotation
(interaction, no_of_segments)[source]¶ -
anti_clockwise
¶ Returns
True
if the Blue Dot was rotated anti-clockwise.
-
clockwise
¶ Returns
True
if the Blue Dot was rotated clockwise.
-
col
¶ The column.
-
interaction
¶ The
BlueDotInteraction
object relating to this rotation.
-
row
¶ The row.
-
valid
¶ Returns
True
if the Blue Dot was rotated.
-
value
¶ Returns 0 if the Blue Dot wasn’t rotated, -1 if rotated anti-clockwise and 1 if rotated clockwise.
-