BlueDot API

BlueDot

class bluedot.BlueDot(device='hci0', port=1, auto_start_server=True, power_up_device=False, print_messages=True)

Interacts with a Blue Dot client application, communicating when and where it has been pressed, released or held.

This class starts an instance of a bluetooth server (btcomm.BluetoothServer) which manages the connection with the Blue Dot client.

This class is intended for use with the Blue Dot client application.

The following example will print a message when the Blue Dot is pressed:

from bluedot import BlueDot
bd = BlueDot()
bd.wait_for_press()
print("The blue dot was pressed")
Parameters:
  • 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, 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 use 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 / disconect.
allow_pairing(timeout=60)

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

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.

is_connected

Returns True if a Blue Dot client is connected.

is_pressed

Returns True if the Blue Dot is pressed (or held).

port

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

position

Returns an instance of BlueDotPosition representing the current or last position the Blue Dot was pressed, held or released.

Note - if the Blue Dot is released (and inactive), position will return position when it was released, until it is pressed again. If the Blue Dot has never been pressed position will return None.

print_messages

When set to True results in messages relating to the status of the bluetooth server to be printed.

server

The btcomm.BluetoothServer instance that is being used to communicate with clients.

start()

Start the BluetoothServer if it is not already running. By default the server is started at initialisation.

stop()

Stop the bluetooth server.

value

Returns a 1 if the Blue Dot is pressed, 0 if released.

values

Returns an infinite generator constantly yielding the current value

wait_for_connection(timeout=None)

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.
wait_for_double_press(timeout=None)

Waits until a Blue Dot is double pressed. Returns True if the Blue Dot was double pressed.

Parameters:timeout (float) – Number of seconds to wait for a Blue Dot to be double pressed, if None (the default), it will wait indefinetly.
wait_for_move(timeout=None)

Waits until the position where the Blue Dot is pressed is moved. Returns True if the position pressed on the Blue Dot was moved.

Parameters:timeout (float) – Number of seconds to wait for the position that the Blue Dot is pressed to move, if None (the default), it will wait indefinetly.
wait_for_press(timeout=None)

Waits until a Blue Dot is pressed. Returns True if the Blue Dot was pressed.

Parameters:timeout (float) – Number of seconds to wait for a Blue Dot to be pressed, if None (the default), it will wait indefinetly.
wait_for_release(timeout=None)

Waits until a Blue Dot is released. Returns True if the Blue Dot was released.

Parameters:timeout (float) – Number of seconds to wait for a Blue Dot to be released, if None (the default), it will wait indefinetly.
wait_for_swipe(timeout=None)

Waits until the Blue Dot is swiped. Returns True if the Blue Dot was swiped.

Parameters:timeout (float) – Number of seconds to wait for the Blue Dot to be swiped, if None (the default), it will wait indefinetly.
when_client_connects

Sets or returns the function which is called when a Blue Dot connects.

when_client_disconnects

Sets or returns the function which is called when a Blue Dot disconnects.

when_double_pressed

Sets or returns the function which is called when the Blue Dot is double pressed.

The function should accept 0 or 1 parameters, if the function accepts 1 parameter an instance of BlueDotPosition will be returned representing where the Blue Dot was pressed the second time.

Note - the double press event is fired before the 2nd press event e.g. events would be appear in the order, pressed, released, double pressed, pressed.

when_moved

Sets or returns the function which is called when the position the Blue Dot is pressed is moved.

The function should accept 0 or 1 parameters, if the function accepts 1 parameter an instance of BlueDotPosition will be returned representing the new position of where the Blue Dot is held.

when_pressed

Sets or returns the function which is called when the Blue Dot is pressed.

The function should accept 0 or 1 parameters, if the function accepts 1 parameter an instance of BlueDotPosition will be returned representing where the Blue Dot was pressed.

The following example will print a message to the screen when the button is pressed:

from bluedot import BlueDot

def dot_was_pressed():
    print("The Blue Dot was pressed")
    
bd = BlueDot()
bd.when_pressed = dot_was_pressed

This example shows how the position of where the dot was pressed can be obtained:

from bluedot import BlueDot

def dot_was_pressed(pos):
    print("The Blue Dot was pressed at pos x={} y={}".format(pos.x, pos.y))
    
bd = BlueDot()
bd.when_pressed = dot_was_pressed
when_released

Sets or returns the function which is called when the Blue Dot is released.

The function should accept 0 or 1 parameters, if the function accepts 1 parameter an instance of BlueDotPosition will be returned representing where the Blue Dot was held when it was released.

when_swiped

Sets or returns the function which is called when the Blue Dot is swiped.

The function should accept 0 or 1 parameters, if the function accepts 1 parameter an instance of BlueDotSwipe will be returned representing the how the Blue Dot was swiped.

BlueDotPosition

class bluedot.BlueDotPosition(x, y)

Represents a position of where the blue for 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 degress is up, 0 > 180 degrees clockwise, 0 > -180 degrees anti-clockwise.

bottom

Returns True if the Blue Dot is pressed, held or released at the bottom.

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.

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)

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

moved(moved_position)

Adds an additional position to the interaction, called when the position the Blue Dot is pressed moves.

positions

A list of BlueDotPositions 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.

released(released_position)

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

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)

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.

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.

MockBlueDot

class bluedot.MockBlueDot(device='hci0', port=1, auto_start_server=True, power_up_device=False, print_messages=True)

MockBlueDot inherits from BlueDot but overrides ._create_server, to create a MockBluetoothServer which can be used for testing and debugging.

launch_mock_app()

Launches a mock Blue Dot app.

The mock app reacts to mouse clicks and movement and calls the mock blue dot methods to simulates presses.

This is useful for testing, allowing you to interact with BlueDot without having to script mock functions.

The mock app uses pygame which will need to be installed.

mock_blue_dot_moved(x, y)

Simulates the blue dot being moved.

Parameters:
  • x (int) – The x position where the mock blue dot was moved too
  • y (int) – The y position where the mock blue dot was moved too
mock_blue_dot_pressed(x, y)

Simulates the blue dot being pressed.

Parameters:
  • x (int) – The x position where the mock blue dot was pressed
  • y (int) – The y position where the mock blue dot was pressed
mock_blue_dot_released(x, y)

Simulates the blue dot being released.

Parameters:
  • x (int) – The x position where the mock blue dot was released
  • y (int) – The y position where the mock blue dot was released
mock_client_connected(client_address='11:11:11:11:11:11')

Simulates a client connecting to the BlueDot.

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

Simulates a client disconnecting from the BlueDot.