Example Python Code

Once your Circuit Playground is running the Firmata sketch you can use many different Firmata clients to control the board.  For example standard Firmata clients can control the digital pins on the board and even read some of the analog sensors like the thermistor and light sensor.  However to make full use of the Circuit Playground Firmata sketch you'll want to use a client that's specially modified to use custom Firmata commands that interact with Circuit Playground's on-board hardware like its accelerometer, NeoPixels, and more.

Included in the repository with the Circuit Playground Firmata sketch is a set of Python code to talk to Circuit Playground Firmata.  This code implements all of the custom Firmata extensions to control every component on the board.  You can write simple Python programs to light up the NeoPixels, read the accelerometer & tap detection, capacitive inputs, and much more.

If you're using a different Firmata client you might need to look into how it supports custom Firmata SysEx extensions.  See the Firmata Extension Reference page for details on the custom Firmata extensions for Circuit Playground.

Install Dependencies

To get started you'll first need to install a few dependencies to use the Python Firmata example code.  The Python code is based on the excellent PyMata library which implements most of the code to talk to Circuit Playground Firmata.

First make sure you've installed the latest version of Python, either 2.7.x or 3.4+.

Next you will want to install the pip Python package manager.  Some recent versions of Python include pip, however if you don't have pip installed (i.e. running the pip command at the command prompt fails with an unknown command error) follow the installation instructions to download and run get-pip.py.

After pip is installed you're ready to install the PyMata library.  Open a command prompt and run the following command to install the library:

Download: file
pip install pymata

Note on Linux and Mac OSX you might need to prefix the command with sudo so it runs as root and installs pymata globally:

Download: file
sudo pip install pymata

Make sure you see the PyMata installation succeeds, for example you might see text like:

Download: file
Collecting pymata
  Downloading PyMata-2.12.tar.gz
Collecting pyserial>=2.7 (from pymata)
  Downloading pyserial-3.0.1.tar.gz (134kB)
    100% |████████████████████████████████| 143kB 3.9MB/s 
Installing collected packages: pyserial, pymata
  Running setup.py install for pyserial ... done
  Running setup.py install for pymata ... done
Successfully installed pymata-2.12 pyserial-3.0.1

If you see the installation fail with an error go back and check you have both Python and pip installed and try again.

Once PyMata is installed you're ready to run the Python Circuit Playground Firmata code.

Python Circuit Playground Firmata Code

To run the Python Circuit Playground Firmata code first make sure you have a Circuit Playground board that is running the Circuit Playground Firmata sketch.  Check out the previous page if you haven't setup a Circuit Playground with the Firmata sketch yet.

Next make sure you've downloaded the Circuit Playground Firmata repository code.  You can use the button below to download this code:

Unzip the archive and notice the Python Examples subfolder.  Inside this folder is all the Python code to control Circuit Playground Firmata.

Before you run the example code first make sure the Circuit Playground board is plugged into the computer using its micro-USB port.  You'll also want to find the name of the serial port for Circuit Playground.  Check the Tools -> Port menu in the Arduino IDE and remember the name of the port that you see for Circuit Playground, like COM1, /dev/tty.usbmodem143431, /dev/ttyUSB0, etc.

Open a command prompt and navigate to the Python Examples folder.  Start by running a simple example to test the buttons on the Circuit Playground board:

Download: file
python buttons.py /dev/tty.usbmodem143431

Replace /dev/tty.usbmodem143431 with the name of the serial port for Circuit Playground on your computer.

You should see text like the following that shows PyMata connecting to the board and then the example code waiting for buttons to be pressed:

Download: file
Python Version 2.7.11 (default, Jan 22 2016, 08:29:18) 
[GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)]

PyMata version 2.12  Copyright(C) 2013-16 Alan Yorinks    All rights reserved.

Opening Arduino Serial port /dev/tty.usbmodem143431 

Please wait while Arduino is being detected. This can take up to 30 seconds ...
Board initialized in 0 seconds
Total Number of Pins Detected = 30
Total Number of Analog Pins Detected = 12
Press the left button, right button, or slide switch (Ctrl-C to quit)...
Switch is on the left!

Try pressing and releasing the left button, right button, and moving the slide switch between its left and right positions.  You should see text printed to the console:

Download: file
Left button pressed!
Left button released!
Right button pressed!
Right button released!
Switch is on the right!
Switch is on the left!

If you see an error check you have Python and the PyMata library successfully installed.  Also confirm Circuit Playground is connected to the serial port you specified when running the example.  Finally be sure the Circuit Playground board is running the Circuit Playground Firmata sketch--it doesn't hurt to reload the sketch if you're unsure.

As the buttons.py code runs you can see it listens for button presses on the Circuit Playground board and prints text when they are pressed.  This is a great example of using Circuit Playground to interact with Python code running on your computer.  When you're finished press Ctrl-C in the terminal to stop the program.

Try running other examples in the Python Examples directory.  Each example is run in the same way as buttons.py, you must specify a command line parameter with the name of the serial port for Circuit Playground.  

Note: If you see an error like IndexError: list out of range this means PyMata is a little confused about all the data being sent to it as it connects to the Circuit Playground board.  Usually this happens when a previous example was run and it turned on streaming of values to the host computer.  You can fix this by unplugging and plugging back in the Circuit Playground board.  This will reset it and make sure it isn't streaming any data that confuses PyMata.

Below is a description of each example:

  • accelerometer.py - This example will take a single reading from the accelerometer's X, Y, Z axis every 2 seconds and print it out.  This is a simple example of how to read the accelerometer with a function call, but you might want to look at the accelerometer_streaming.py example for a faster and more efficient way to use it.  The units for accelerometer data are meters per second squared.
  • accelerometer_streaming.py - This example uses fast streaming to quickly read and print the accelerometer's X, Y, Z axis acceleration.  The code will show how streaming can be turned on and off (for 5 seconds in the example) and then on again.  When accelerometer data is streamed you'll see much faster update rates, up to about 5 times a second, compared to the simpler accelerometer.py example.  This is great for quickly detecting when the acceleration and orientation of the Circuit Playground board changes.  The units for accelerometer data are meters per second squared.
  • buttons.py - This example will listen for button presses on the Circuit Playground (left button, right button, slide switch) and print them out.
  • cap_touch.py - This example will listen for capacitive touches on pin 10 of Circuit Playground.  Every two seconds the pin will be checked and if a large enough capacitance is found, like if a human is touching it, then a message will be printed.  This is a simple example of reading a capacitive touch input.  You can see a faster and more efficient way with the cap_streaming.py example.
  • cap_streaming.py - This example will listen for capacitive touches on both pins 3 and 10 of Circuit Playground.  The code shows how these changes are quickly streamed back to the host computer for fast responses.  In addition the code shows how streaming can be turned on and off and back on again.  Streaming the capacitive touch input is faster than the simple cap_touch.py example and will help programs quickly detect capacitive touches.
  • circuitplayground.py - This actually is not an example to run, instead it's a helper class to simplify talking to the Circuit Playground Firmata board.  You can copy this file and place it in the same directory as Python scripts you write yourself to control Circuit Playground!
  • light_sensor.py - This example will print out the light sensor value as it changes.  Note that you'll only see values printed when there is a change in light level--if the light level isn't changing then it won't print out.  The value has no units but is proportional to how bright the light is hitting the sensor.  Darkness will have a low value and bright light will have a very high value in the thousands.  Experiment to see what values appear with different levels of light!
  • pixels.py - This example will animate lighting the NeoPixels on Circuit Playground.  As the example runs you'll see a rainbow of colors move along the LEDs.
  • sound.py - This example will read the microphone and print out its readings as it changes. Note that these readings are raw samples from the microphone and don't necessarily relate to volume level or sound pressure--you might need to average out or apply other smoothing to find the volume of sound. 
  • tap.py - This example will read the tap detection on the LIS3DH accelerometer every two seconds and print out if the board has been tapped or double-tapped.  Note that this example is meant to show a simple way to check the tap detection state and isn't very accurate or fast at detecting taps.  Instead look at the tap_streaming.py example for a fast and efficient way to detect taps.
  • tap_streaming.py - This example will stream tap detection to the computer.  The code will turn on, off, and then on again streaming of tap detection.  Try tapping the LIS3DH accelerometer (tiny square in the exact middle of the Circuit Playground board) and you should see single and/or double tap events printed.  Note that tap detection is a little 'noisy' and you might see both a single and double tap or even multiple tap events so be aware in your own code that taps might occur multiple times in a short period.
  • temperature.py - This example will print the temperature from the thermistor every second.  In addition it will print the 'raw' analog to digital converter value for the thermistor in case you want to do your own processing on it.
  • tones.py - This example will play a music scale using the buzzer on Circuit Playground.  The code demonstrates simple tone playback at different frequencies and durations.

If you'd like to write your own Python code to control Circuit Playground you'll want to use the included circuitplayground.py file.  This file implements a class that simplifies talking to the Circuit Playground board and all of the examples above use this class to interact with Circuit Playground.

To use the class in your own code make sure you copy circuitplayground.py into the same directory as your code.  Then just import circuitplayground.py by adding to the top of your Python code:

Download: file
# Import CircuitPlayground class from the circuitplayground.py in the same directory.
from circuitplayground import CircuitPlayground

Check out the code for the examples above to see how they use the circuitplayground.py class to talk to the board.  There are simple functions to read sensors like the thermistor, light sensor, microphone, etc.  In addition there are functions to read the accelerometer, tap detection, capacitive touch inputs, and more.  Some of the components are actually read using PyMata's standard analog and digital input functions, while others use special Firmata extensions to control parts of the board like the NeoPixels.  The great thing is that your code doens't need to worry about how Circuit Playground Firmata works or is implemented--just call the functions in circuitplayground.py and you'll be controlling the board in no time!

That's all there is to using Circuit Playground Firmata with Python!  Let your imagination run wild as you write Python code to control Circuit Playground!

This guide was first published on Apr 27, 2016. It was last updated on Apr 27, 2016. This page (Example Python Code) was last updated on May 25, 2019.