DIY Flotilla-python Documentation


I’m a bit ‘old-school’ as I started teaching computer programming, or coding, in 1968 and I like DOCUMENTATION. I do not want to guess or try this to see if it will work if the guy I bought a device from hasn’t told me how to use it properly. I know that developing software takes time but documenting it is should be part of the package. As examples of good practice I suggest you look at the work of Alex Eames of and his documentation for Raspio-duino
or ProHAT
and Ben Nuttall’s gpiozero

I got a Mega Treasure Chest via Kickstarter. I was disappointed with the early versions of the software and gave up on it over the summer. Now that an improved version of the software is available and the nights are drawing in I’ve been giving it another try. Search as I might I still cannot find any useful documentation for ‘flotilla-python’ . There are a few examples, using some of the simplest commands, for the least complicated inputs and outputs but not enough details.

While we wait for the ‘official documentation’ I thought that I would post a few examples of what I have found out and hope that others will join in and add to the published body of knowledge. Unless teachers, who have little time, can easily access this information they will not be able to use Flotilla effectively in secondary schools. Its great physical kit, now working much better, so let’s pool what we have worked out so far.

My first contribution uses Touch, Rainbow, Dial and Number. Before you start using flotilla-python you must remember to turn off the flotilla service for Rockpool with the command ‘sudo service flotilla stop’ in terminal.

The script changes colours on the Rainbow, displays values on Number, inputs values from Dial and carries out a few simple calculations.
rainbow.set_pixel(pixel, r ,g, b).update()
pixel ( range: 0 to 4)
r, g, b (range: 0 to 255) colour mixing values
.update() this displays the changes immediately rather than with rainbow.update() later.

n is an integer (range: 0 to 9999)
number.update() displays the changed value (often forgotten)[0]
This reads the value from Dial (range: 0 to 1023) but returns a string. It must be converted to a number before you can carry out calculations or pass it on to Number. Use int([0]) to convert to integer and float([0]) for floating point.

#!/usr/bin/env python3
#Touch Rainbow Dial Number
# Tony Goodhew 18 Oct 2016
import flotilla
import time
client = flotilla.Client(

touch = client.first(flotilla.Touch)
dial = client.first(flotilla.Dial)
rainbow = client.first(flotilla.Rainbow)
number = client.first(flotilla.Number)

print("Touch the buttons and turn the dial\n")
print("    Use CTRL-C to stop")
    while True:
            rainbow.set_pixel(0,128,0,0).update() #red
        if touch.two:
            rainbow.set_pixel(0,0,128,0).update() #green
        if touch.three:
            rainbow.set_pixel(0,0,0,128).update() #blue
            dial_val = int([0]) #Read dial and change string to integer
        if touch.four:
            rainbow.set_pixel(0,100,0,100).update() #magenta
            dial_val = float([0]) # Changed to FP: range 0 to 1023
            percentage = int(dial_val * 1000.0 / 1023.0 / 10.0)
except KeyboardInterrupt:
    print("\nStopped with CTRL-C")

In an editor, like idle3, if you type a module name and full stop then press tab you get a list of possible commands. For example, “dial. “ gives the following list:
channel, channel_index, clamp, client, data, is_a, name, position, send, set_data, stop.
What do they do? Which are possibly dangerous?

I would like to take control of the LEDS on Touch to show which one was last pressed. Can anyone help?


Where did all the indents go?
If you would like an email copy of the program contact me at arduinolink(AT)


You can find the same program here as the indentations work on this forum.

while True:
    print("They do here, too...")

But you have to use three backticks ( ` ) to start and end your block of code.

We’re acutely aware of the documentation shortfall, and it’s one of the many Flotilla-related things we’re working on.

We’ve been focusing mostly on Rockpool/Cookbook, which are still being perfected. Unfortunately the Python API is still in flux, and will most-likely change to better support Python exports from Rockpool when we get those up and running. It’ll get its turn in good time, though.


Thanks for fixing the indents.
I’m not really getting at you about the docs, I know how long they take to write after teaching ‘A’ level Computing for many years, but I’m much more interested in using python than Rockpool. Many of us need some support. I’m hoping other users who have got further than me can provide help and a leg up to those still struggling to get started.


This second contribution uses the Joystick and Matrix modules. I used them orientated with the rope at the top of the modules.

The joystick consists of two potentiometers , like the Dial module, crossed at the centre. A push-button switch is also included and activated by pushing down in the centre of the joystick.
Reading the data from the joystick is accomplished with:
jsk =[n] where n = 0 gives the switch, n = 2 provides x and n = 3 the y results. They are all strings. If you need to do calculations you have to change them to integers or floats.

The Matrix consists of 64 white LEDS arranged in 8 rows of 8 with the origin (0,0) at the top left. The rows and columns are accessed with values of 0 to 7.
matrix.set_pixel(x, y, state) where state = 1 turns on a pixel and 0 turns it off. The display is not updated until .update() is executed, either as an extension or a separate command.

This script moves a pixel about the display until either the button is pushed or CTRL-C entered on the keyboard.

#!/usr/bin/env python3
#Joystick and Matrix - rope at the top
#Tony Goodhew 18 Oct 2016
import flotilla
import time
client = flotilla.Client(
matrix = client.first(flotilla.Matrix)
joystick = client.first(flotilla.Joystick)

old_x = 0
old_y = 0
    sw =[0] # string   Switch - press straight down
    swn = int(sw)         # integer
    while (swn == 0):
        x = int([1]) # range 0 to 1023
        y = int([2])
        x = 7 - int(x / 128)  # range 0 to 7
        y = int(y / 128)
        matrix.set_pixel(old_x, old_y, 0).update() # Turn old pixel off
        matrix.set_pixel(x, y, 1).update()   # Turn new pixel on
        old_x = x
        old_y = y
        swn = int([0])

    print("Stopped by joystick button")

except KeyboardInterrupt:
    print("Stopped by CTRL-C")


@Tonygo2 - thanks a lot for your examples.

I will be teaching a course with flotilla and hopefully python in the near future so this will be of great use!