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; if False, the method start() 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 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
    
  • 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:
  • cols (int) – The number of columns in the grid of buttons.
  • rows (int) – The number of rows in the grid of buttons.

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.

stop()[source]

Stop the Bluetooth server.

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.

buttons

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 pressed interaction will return None.

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:
  • bd (BlueDot) – The BlueDot object this button belongs too.
  • col (int) – The column position for this button in the grid.
  • col – The row position for this button in the grid.
: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:
  • square (bool) – When set to True the button is made square.
  • border (bool) – When set to True adds a border to the button.
  • visible (bool) – When set to False the button will be hidden.
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 pressed interaction will return None.

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:
  • x (float) – The x position of the Blue Dot, 0 being centre, -1 being far left and 1 being far right.
  • y (float) – The y position of the Blue Dot, 0 being centre, -1 being at the bottom and 1 being at the top.
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.