Tethering Codebug And Colour Tail With Python


Reach the full potential of your CodeBug with Tethered mode. You can make programs that will be able to:

  • Respond to Minecraft

  • Control CodeBug from the web

  • Display alerts and the time on CodeBug

  • Turn CodeBug into an Internet of Things device

To use CodeBug Tether you will need to load it with a special project file. Once this is done you can control CodeBug and Colour tails with Python over a USB connection.

You will need
CodeBug CodeBug
Micro USB cable
ColourStar ColourStar

  • Ask a new question:

Set up Tethered mode

For tethered mode you need to load your CodeBug with a special project file. This is done in the same way as a regular CodeBug program (refer to the download guide for details).

Download the CodeBug tether project file and load it onto your CodeBug.

Next, you need to install some Python modules.

  • Ask a new question:

Python libraries for Raspberry Pi & Linux

You must now install the Python libraries that will talk to your CodeBug. Python should already be installed but for good measure:

sudo apt-get install python3

To install pip, securely download get-pip.py, then run the following:

python get-pip.py

To install codebug_tether, open up a terminal and type:

pip install codebug_tether

1 Question
  • deleted

    Answer this question:

  • I have Python 3 on a Windows 7 laptop - can I install these libraries on there? — mamvcivm @ April 6, 2016, 10:50 p.m.

    You should be able to install on windows with pip http://codebug-tether.readthedocs.org/en/latest/installation.html#installing-with-pip we are working on Windows based instructions Thomas Macpherson-Pope @ April 7, 2016, 8:30 a.m.

    Answer this question:

  • Ask a new question:

Python libraries for Windows

Download and install the latest version of Python 3 from here. Make sure you tick the Add Python 3 to environment variables checkbox.

To install codebug_tether, open up a command prompt and type:

pip install codebug_tether

2 Questions
  • why wont it work sonic_iron @ Aug. 1, 2016, 3:27 p.m.

    Answer this question:

  • Please clean up the Linux documentation to reflect reality -or- delete it all and point to the github page. This worked for me on a Debian-type Linux: sudo apt-get update sudo apt-get upgrade sudo apt-get install python3 ( Download https://bootstrap.pypa.io/get-pip.py to get pip3 source code ) sudo python3 get-pip.py sudo pip3 install codebug_tether sudo apt-get install python3-serial ( Verify ) python3 >>> import codebug_tether >>> codebug = codebug_tether.CodeBug() >>> codebug.set_pixel(2, 2, 1) Richard Elkins @ Oct. 26, 2016, 7:49 p.m.

    Answer this question:

  • Ask a new question:

Python libraries for MaxOSX

Download and install Xcode (if you haven’t already) and then enable the command line tools by running (in a terminal):

xcode-select --install

Now install Homebrew (a package manager for OSX):

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

The script will explain what changes it will make and prompt you before the installation begins. Once you’ve installed Homebrew, insert the Homebrew directory at the top of your PATH environment variable. You can do this by adding the following line at the bottom of your ~/.profile file:

export PATH=/usr/local/bin:/usr/local/sbin:$PATH

Now, we can install Python 3:

brew install python3

This will take a minute or two.

To install codebug_tether, open up a terminal and type:

pip install codebug_tether

1 Question
  • For "pip install codebug_tether", Terminal says "pip install codebug_tether -bash: pip: command not found" How can I fix this? Charlie McMahon @ June 5, 2017, 6:08 a.m.

    Please Help Charlie McMahon @ June 5, 2017, 6:14 a.m.

    Answer this question:

  • Ask a new question:

Connecting your tail

It is recommended that you connect your Colour Tail after plugging in the Micro USB cable into CodeBug and disconnect your Colour Tail before unplugging the Micro USB from your CodeBug to avoid damaging the devices. Take care when plugging in or unplugging devices from CodeBug.

To fit a Colour Tail to CodeBug, place the Colour Tail on a table with the LEDs facing upwards, then with CodeBug with LEDs side up, gently slide CodeBug’s expansion socket onto the 6 pin connector on the Colour Tail.

  • Ask a new question:

Your own tethered CodeBug programs

You can write your own tethered CodeBug programs using Python and a few simple commands to control your CodeBug. In the next steps you will start an interactive Python session and enter commands to interact with your tethered CodeBug. Don’t forget you need the tethered mode project installed on your CodeBug for them to work.

Open a Terminal and type:

sudo python3

You will see the python prompt appear >>> Now type:

import codebug_tether

import codebug_tether.colourtail

cb = codebug_tether.CodeBug()

cb.set_pixel(2, 2, 1)

You will see the center LED - at position (2, 2) - light up on CodeBug.

NB: On some computers, or if you have multiple CodeBugs you will have to put the address of your CodeBug in brackets. More details are in the section Addressing Your CodeBug.

To set up the colour tail

colourtail = codebug_tether.colourtail.CodeBugColourTail(cb)


Now try setting a Colour tail pixel:

colourtail.set_pixel(0, 255, 0, 0)


You will see the first pixel on your colour tail light up red. You passed this function 4 numbers. The first number was the number of the pixel, and the other 3 were red, green and blue. Note: The colour numbers need to be between 0 and 255. The update() function pushes any changes to pixel colours you have made, to the physical colour tail, so you can run multiple set_pixel() commands and then run update() so the pixels all change at the same time.

Try setting multiple Colour tail pixels:

colourtail.set_pixel(0, 0, 0, 255)

colourtail.set_pixel(1, 0, 100, 200)

colourtail.set_pixel(3, 255, 255, 0)


All 3 pixels change at once right?! Try different combinations of colours and pixel numbers to get comfortable using this function.

You can use variables and for loops to create amazing patterns with colour tail.

    for red in range(0,255):
        for green in reversed(range(0,255):

            for pixel in range(0,9):

            colourtail.set_pixel(pixel, red, green, 0)


Get a full list of the commands available by typing:

 help(colourtail) or


You can write longer programs for tethered mode CodeBug by writing commands in your text editor and then saving and running the file in the way you did with the examples earlier.

Tethered mode gives your CodeBug access to the full processing power, functionality and network connectivity of your computer! You can use variety of powerful yet easy to use Python modules allow your CodeBug to generate random numbers, react to emails or even respond to Twitter activity.

1 Question
  • I have followed the instructions above but get the following when I enter import codebug_tether.colourtail. I have downloaded the tethered project available on this site and my RPi2 cis using Jessie. What is wrong ? Python 3.4.2 (default, Oct 19 2014, 13:31:11) [GCC 4.9.1] on linux Type "copyright", "credits" or "license()" for more information. >>> import codebug_tether >>> import codebug_tether.colourtail Traceback (most recent call last): File "<pyshell#1>", line 1, in <module> import codebug_tether.colourtail ImportError: No module named 'codebug_tether.colourtail' >>> Kevin Hainsworth @ Dec. 13, 2015, 12:46 a.m.

    I think our latest tethered software hasn't been pushed . try 'sudo pip3 install codebug-tether' Thomas Macpherson-Pope @ Dec. 14, 2015, 12:36 p.m.

    Answer this question:

  • Ask a new question:

Addressing Your CodeBugs

The CodeBug tether library has a default address for CodeBug. In most cases this will work, however if you have multiple CodeBugs connected you may need to change the address you’re using.

To do this, first open a Terminal and type the commands:

ls /dev/tty*

Plug the CodeBug back into your computer’s USB port and wait a couple of seconds. Then type the command:

ls /dev/tty*

See what address has been added to the list (you should see something like ttyACM0 for Raspberry Pi or tty.usbmodemfd141 for Mac). You may find it easier if you unplug your other USB devices first.

When you initiliase CodeBug in your Python programs, you must pass it the address you have found.


cb = CodeBug(‘/dev/tty.usbmodemfa141’)

  • Ask a new question:

What next?

Add responses to Minecraft or email to your program to make a cool notification lamp.

  • Ask a new question:

Back to top