Customization and Use

Customizing Images and Sounds

This line in the code (around line 40) specifies what image to load…it’s mario.bmp by default:

Download: file
IMAGEFILE = 'mario.bmp'       # BMP image to display

Change this to badge.bmp to use the other example image we provide:

Download: file
IMAGEFILE = 'badge.bmp'       # BMP image to display

led_pixels_mario.bmp

led_pixels_badge.bmp

If you can create or convert other images to 128x128 pixel 24-bit color BMP files, copy them to the CIRCUITPY drive and modify the value of IMAGEFILE to match the name. There are some other examples shown in this guide.

Sound files can also be customized. 16-bit mono PCM WAV files (22,050 sample rate or less) are ideal. These are specified just a few lines up in the code, around line 37:

Download: file
TOUCH_WAV = load_wav('touch') # WAV file to play when capacitive pads touched
JUMP_WAV = load_wav('jump')   # WAV file to play when jumping

No need to specify the complete filename on these lines; the “.wav” is implied. (e.g. 'touch' will load the file touch.wav).

One line down, you can specify how sensitive the jump detection will be:

Download: file
JUMP_THRESHOLD = 4.0          # Higher number = triggers more easily

This isn’t any particular type of real-world units…just try higher or lower numbers if you even find it’s necessary. Larger numbers will trigger more easily (i.e. you might get some false triggers when walking or moving around), smaller numbers are more strict about jumps.

Changing Behavior

One last thing…you might find it silly that the code does both types of sounds…touching and jumping. Maybe with your own sound files you have an idea that could make use of both. But otherwise, it’s unbecoming of a starship captain to be making beepy jumping noises, and vice-versa for Italian plumbers. Let’s look at the last few lines of code...

Download: file
    if A2 < JUMP_THRESHOLD:
        # Freefall (or very close to it) detected, play a sound:
        play_wav(JUMP_WAV)
    elif TOUCH1.value or TOUCH2.value or TOUCH3.value or TOUCH4.value:
        # One of the capacitive pads was touched, play other sound:
        play_wav(TOUCH_WAV)

This first checks the accelerometer reading to see if we’ve jumped…and if not, it then proceeds to check the capacitive touch pads. If you just want one or the other, how might you change the code?

If you just want jumping, simply delete the latter three lines, so it’s now just this:

Download: file
    if A2 < JUMP_THRESHOLD:
        # Freefall (or very close to it) detected, play a sound:
        play_wav(JUMP_WAV)

And if you only want the touch pads, delete the prior three lines, and change the “elif” to an “if”:

Download: file
    if TOUCH1.value or TOUCH2.value or TOUCH3.value or TOUCH4.value:
        # One of the capacitive pads was touched, play sound:
        play_wav(TOUCH_WAV)

You can probably see how the code might be modified to load multiple sounds and have each touch pad trigger a different one. I’ll leave that to you as homework if you like. But I will recommend…don’t over-do it! The sounds are funny but can quickly become tiresome…use your gags sparingly and get on with being a good party guest, don’t drag it out into a whole PowerPoint slideshow.

Math (or the lack thereof)

I thought detecting jumps was going to be quite complicated and would lag well behind reality. But it turns out to be one of the simplest things. Using the onboard accelerometer, we just have to check if the board is in free fall and play a sound accordingly.

Funny thing about free fall…the “fall” part makes us think of things on the way down, but that’s not necessarily true. Anything following a ballistic trajectory…that is, without propulsion and influenced only by gravity…is in free fall, even on the way up. Throw a ball, and the moment it leaves your hand (its source of propulsion), it’s on a ballistic trajectory. Jump, and the moment your feet leave the ground, it’s the same thing. (We can disregard air resistance as negligible here.) So we don’t have to sift through the accelerometer readings looking for spikes of acceleration…quite the opposite, just look for zero (or close to it):

Download: file
    X, Y, Z = ACCEL.acceleration
    A2 = X * X + Y * Y + Z * Z  # Acceleration^2 in 3space (no need for sqrt)
    if A2 < JUMP_THRESHOLD:
        # Freefall (or very close to it) detected, play a sound:
        play_wav(JUMP_WAV)

X, Y, Z refer to the three axes of the accelerometer. The orientation of the board completely doesn’t matter in this application, we just want the magnitude of the acceleration, in any direction…that’s what the multiplications and additions on the next line do…mostly…

Many situations would require taking the square root of that result to get the actual acceleration magnitude, in actual meters-per-second-squared real-world units. Square roots are relatively slow to calculate. Since we’re just comparing against a number, we can speed things up by leaving out the square root, and instead square the value we’re comparing against (JUMP_THRESHOLD). The default value of JUMP_THRESHOLD is 4.0, which means we’re really looking for an acceleration magnitude less than 2.0 meters/second² (normal acceleration due to gravity is 9.8 m/s², and perfect free fall would be 0.0…given our readings and our jumping may be a little sloppy, this is “close enough” to free fall with hopefully not too many false positives from just energetic walking around). It’s that simple.

This guide was first published on Oct 02, 2018. It was last updated on Oct 02, 2018. This page (Customization and Use) was last updated on Jan 02, 2020.