Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
270 lines (174 sloc) 7.3 KB


The recipes provide examples of how you can use Blue Dot. Don't be restricted by these ideas and be sure to have a look at the :doc:`dotapi` as there is more to be discovered.


The simplest way to use the Blue Dot is as a wireless button.

Hello World

.. currentmodule:: bluedot

Let's say "Hello World" by creating the :class:`BlueDot` object then waiting for the Blue Dot app to connect and be pressed:

.. literalinclude:: examples/

Alternatively you can also use :attr:`~BlueDot.when_pressed` to call a function:

.. literalinclude:: examples/

:attr:`~BlueDot.wait_for_release` and :attr:`~BlueDot.when_released` also allow you to interact when the Blue Dot is released:

.. literalinclude:: examples/

Double presses can also be used with :attr:`~BlueDot.wait_for_double_press` and :attr:`~BlueDot.when_double_pressed`:

.. literalinclude:: examples/

Flash an LED

Using Blue Dot in combination with :mod:`gpiozero` you can interact with electronic components, such as LEDs, connected to your Raspberry Pi.

When the Blue Dot is pressed, the LED connected to GPIO 27 will turn on; when released it will turn off:

.. literalinclude:: examples/

You could also use :attr:`~BlueDot.when_pressed` and :attr:`~BlueDot.when_released`:

.. literalinclude:: examples/

Alternatively use :attr:`~gpiozero.SourceMixin.source` and :attr:`~BlueDot.values`:

.. literalinclude:: examples/

Remote Camera

Using a Raspberry Pi camera module, :class:`picamera.PiCamera` and :class:`BlueDot`, you can really easily create a remote camera:

.. literalinclude:: examples/


The Blue Dot can also be used as a joystick when the middle, top, bottom, left or right areas of the dot are touched.


Using the position the Blue Dot was pressed you can work out whether it was pressed to go up, down, left, right like the D-pad on a joystick:

.. literalinclude:: examples/

At the moment the D-pad only registers when it is pressed. To get it work when the position is moved you should add the following line above pause():

bd.when_moved = dpad


These recipes assume your robot is constructed with a pair of H-bridges. The forward and backward pins for the H-bridge of the left wheel are 17 and 18 respectively, and the forward and backward pins for H-bridge of the right wheel are 22 and 23 respectively.

Using the Blue Dot and :class:`gpiozero.Robot`, you can create a bluetooth controlled robot which moves when the dot is pressed and stops when it is released:

.. literalinclude:: examples/

Variable Speed Robot

You can change the robot to use variable speeds, so the further towards the edge you press the Blue Dot, the faster the robot will go.

The :attr:`~BlueDotPosition.distance` attribute returns how far from the centre the Blue Dot was pressed, which can be passed to the robot's functions to change its speed:

.. literalinclude:: examples/

Alternatively you can use a generator and yield (x, y) values to the :attr:`gpiozero.Robot.source` property (courtesy of Ben Nuttall):

.. literalinclude:: examples/


By holding down the Blue Dot and moving the position you can use it as an analogue slider.

Centre Out

Using the :attr:`BlueDotPosition.distance` property which is returned when the position is moved you can create a slider which goes from the centre out in any direction:

.. literalinclude:: examples/

Left to Right

The :attr:`BlueDotPosition.x` property returns a value from -1 (far left) to 1 (far right). Using this value you can create a slider which goes horizontally through the middle:

.. literalinclude:: examples/

To make a vertical slider you could change the code above to use :attr:`BlueDotPosition.y` instead.

Dimmer Switch

Using the :class:`gpiozero.PWMLED` class and :class:`BlueDot` as a vertical slider you can create a wireless dimmer switch:

.. literalinclude:: examples/


You can interact with the Blue Dot by swiping across it, like you would to move between pages in a mobile app.


Detecting a single swipe is easy using :attr:`~BlueDot.wait_for_swipe`:

.. literalinclude:: examples/

Alternatively you can also use :attr:`~BlueDot.when_swiped` to call a function:

.. literalinclude:: examples/


You can tell what direction the Blue Dot is swiped by using the :class:`BlueDotSwipe` object passed to the function assigned to :attr:`~BlueDot.when_swiped`:

.. literalinclude:: examples/

Speed, Angle, and Distance

:class:`BlueDotSwipe` returns more than just the direction. It also includes the speed of the swipe (in Blue Dot radius per second), the angle, and the distance between the start and end positions of the swipe:

.. literalinclude:: examples/


You can use Blue Dot like a rotary encoder or "iPod classic click wheel" - rotating around the outer edge of the Blue Dot will cause it to "tick". The Blue Dot is split into a number of virtual segments (the default is 8), when the position moves from one segment to another, it ticks.


Using the :attr:`~BlueDot.when_rotated` callback you can create a counter which increments / decrements when the Blue Dot is rotated either clockwise or anti-clockwise. A :class:`BlueDotRotation` object is passed to the callback. Its :attr:`~BlueDotRotation.value` property will be -1 if rotated anti-clockwise and 1 if rotated clockwise:

.. literalinclude:: examples/

The rotation speed can be modified using the :attr:`BlueDot.rotation_segments` property which changes the number of segments the Blue Dot is split into:

bd.rotation_segments = 16


You can interact with the Bluetooth adapter using :class:`BlueDot`.


You can put your Raspberry Pi into pairing mode which will allow pairing from other devices for 60 seconds:

.. literalinclude:: examples/

Or connect up a physical button up to start the pairing (the button is assumed to be wired to GPIO 27):

.. literalinclude:: examples/

Paired Devices

You can iterate over the devices that your Raspberry Pi is paired too:

.. literalinclude:: examples/


Blue Dot includes a :class:`MockBlueDot` class to allow you to test and debug your program without having to use Bluetooth or a Blue Dot client.

:class:`MockBlueDot` inherits from :class:`BlueDot` and is used in the same way, but you have the option of launching a mock app which you can click with a mouse or writing scripts to simulate the Blue Dot being used.

Screenshot of the mock Blue Dot app

Mock App

Launch the mock Blue Dot app to test by clicking the on-screen dot with the mouse:

.. literalinclude:: examples/

Scripted Tests

Tests can also be scripted using :class:`MockBlueDot`:

.. literalinclude:: examples/