The Circuit Playground Express and Bluefruit both come with an accelerometer near the center of the board. This sensor can provide acceleration values for the x, y and z axes in addition to taps and shakes. The values returned are in m/s2 (meters per second-squared). An axis is an invisible line going through the center of the accelerometer in the center of your board. The x axis is across the board, left to right. The y axis is across the board, top to bottom. The z axis is straight through the board front to back. The values can be grouped together in a Python tuple: (x, y, z).

An accelerometer measures acceleration. You can read more about acceleration here. When the board is held still in any given position, it is still being affected by gravity. Gravity is -9.8m/s2. So, at any given point in time, that value is being applied downward. For example, the values returned if the board is laying flat, facing up, are (0, 0, 9.8), because gravity is pulling on the sensor along the z axis. If you were to pick up the board and shake it, you'll find that you get much higher values. This is because the force with which you are shaking the board causes increased acceleration to be applied to the sensor along whichever axes you are shaking it.

Add the following code to your code.py. Remember, if you need help with this, check here.

"""
This example uses the accelerometer on the Circuit Playground. It prints the values. Try moving
the board to see the values change. If you're using Mu, open the plotter to see the values plotted.
"""
import time
from adafruit_circuitplayground import cp

while True:
    x, y, z = cp.acceleration
    print((x, y, z))

    time.sleep(0.1)

Open the serial console to see the x, y and z values printed out. Try moving the board around to see the values change!

Let's take a look at the code. First, we import time and cp.

Inside our loop, we assign x, y, z = cp.acceleration. Since acceleration values are a 3-member tuple (x, y, z), you need to assign three variables to cp.acceleration to get those three values. We've chosen x, y and z because those are the three axes represented by cp.acceleration.

Then we print((x, y, z)). We include a time.sleep(0.1) to slow down the printed values - if they print too quickly it's difficult to read.

Since (x, y, z) is already a tuple, and we aren't printing any labels for the values, we can use the Mu plotter with the code without any changes. Click on the Plotter button on the top of Mu to see the plotter. Try moving the board around to watch the plotter lines change!

Color Glow Accelerometer

You can use the acceleration values to make a fun light up project with the NeoPixels. There are three acceleration values, and the LEDs have three color values. Let's see what we can do with that!

Add the following code to your code.py.

"""If the switch is to the right, it will appear that nothing is happening. Move the switch to the
left to see the NeoPixels light up in colors related to the accelerometer! The Circuit Playground
has an accelerometer in the center that returns (x, y, z) acceleration values. This program uses
those values to light up the NeoPixels based on those acceleration values."""
from adafruit_circuitplayground import cp

# Main loop gets x, y and z axis acceleration, prints the values, and turns on
# red, green and blue, at levels related to the x, y and z values.
while True:
    if not cp.switch:
        # If the switch is to the right, it returns False!
        print("Slide switch off!")
        cp.pixels.fill((0, 0, 0))
        continue
    R = 0
    G = 0
    B = 0
    x, y, z = cp.acceleration
    print((x, y, z))
    cp.pixels.fill(((R + abs(int(x))), (G + abs(int(y))), (B + abs(int(z)))))

Move the slide switch to the right if it isn't already. Lights! Now move the board in different directions to see the colors change!

Let's take a look at the code. First we import cp.

Inside our loop, we start by checking to see if the switch is to the left. If it is, we print Slide switch off! and turn off all the LEDs. This creates an "off switch" for the project in case you'd like to leave it sitting around but not have the lights on. continue tells the code to keep checking the switch until the state changes, i.e. you move the switch to the right. Once that happens, we move on to the rest of the code.

Next we have the else block. First, we create three variables, R, G and B. We're going to use these to set the colors. We assign them to 0 to start. Then, we assign x, y, z = cp.acceleration and print the values. If you look at the serial output, you'll see how fast the values are scrolling. This is why we typically include a time.sleep() in the code, to slow those values down to a readable speed. However, this project works best without a sleep, so we've left it out.

The last line fills the LEDs with RGB values based on acceleration using the following line:

cp.pixels.fill(((R + abs(int(x))), (G + abs(int(y))), (B + abs(int(z)))))

This involves some special math to work. Let's take a look!

First we'll look at the red value. We start with R which we created at the beginning of our loop. We're going to add the x value to R. However, there's a lot about the basic acceleration value that won't work for adding to color values, such as it potentially being a decimal or negative number. Luckily, Python has some easy ways to deal with this.

You'll notice that our value of x is modified a little with abs(int(x)). This returns the absolute value of the whole number value of x. Absolute values are explained here. Since color values are all whole numbers, we use int(x) to return only the nearest whole number value of x, instead of a long decimal which is often what acceleration returns. Since color values are all positive, we take the absolute value of int(x) to remove any potential negative numbers from the mix.

We add abs(int(x)) to R and we have our R value to use for red! Then we do the same thing for y and z, except abs(int(y)) is added to G and abs(int(z)) is added to B. This gives us our three color values!

As you move the board around, the acceleration values change, and that causes each of our color values to be different. Now, depending on what angle you hold the board, you'll get a different color combination!

Remember the earlier example, where we explained that if the board is laying flat, the returned values are (0, 0, 9.8). This means, if the board is laying flat, facing up, while this code is running, the color values are (0, 0, 9.8). So, you'll see if it's laying flat on your desk, it's blue!

If you hold it so the USB cable is on the top and pointed downwards, the values are, (0, 9.8, 0), so the LEDs are green.

If you hold it so the USB cable is sideways, pointing left or right, the values are (9.8, 0, 0) so the LEDs are red.

As you move the board around at different angles, you'll find every color between!

We also explained that if you shake the board, you'll get back higher values from the accelerometer. This means that the LEDs will be brighter if you shake it. Give it a try!

This guide was first published on Jun 05, 2018. It was last updated on Jun 05, 2018.

This page (Acceleration) was last updated on Nov 06, 2020.