Overview

Save Subscribe

In this guide we'll show you how you can create a fun little physics based hourglass gadget. Hourglasses are used to track time, and this one ends up being sort of triangle shaped, so...yah, it's a Time Triangle Thing. This project was inspired by this awesome Instagram post by @david_proyectos.

We'll go over the underlying simplified physics model also. It could be a useful approach for some other gadgets. It's all written in CircuitPython.

Hardware Items

Below we link to the specific hardware items used in this guide. However, the key ingredients are:

  • A reasonably powerful main board that can run CircuitPython and has I2C
  • LED matrix or matrices
  • Accelerometer

Therefore it's possible to come up with potentially different arrangements. For example, an accelerometer breakout could be used with a non-Feather board. Or smaller LED matrices could be used, etc. Also, the battery can be whatever size you want.

Angled shot of Adafruit Feather.
The Adafruit Feather Bluefruit Sense takes our popular Feather nRF52840 Express and adds a smorgasbord of sensors...
Out of Stock
Out of Stock
Adafruit Small 1.2" 8x8 Green LED Matrix w/I2C Backpack assembled and powered on. A yellow-green graphic smiley is displayed.
What's better than a single LED? Lots of LEDs! A fun way to make a small display is to use an 8x8 matrix or a
$10.95
In Stock
Add to Cart
Angled shot of a rectangular lipo battery with a 2-pin JST connector. The battery specs are listed on the body: 3.7V 250mAh.
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This...
$6.95
In Stock
Add to Cart

The Physics Model

led_matrices_raspberry_pi_hero_timer.jpg

The physics model used here is really a simplification of the one used in the LED Matrix Sand Toy shown above. That project runs on a fairly large 64x64 LED matrix. It uses a Raspberry Pi for the processing, which gives it the computational power required. The code was written in C++, which also helps with the execution speed.

With the continued use of C++ (ala Arduino), a smaller version was even able to run on a Feather 32u4 in the Animated LED Sand project show below.

led_matrices_3d_printing_gimbal-attach3.jpg

That code was ported to CircuitPython (with some effort) and the results are covered in the CircuitPython Digital Sand guide and shown below:

led_matrices_key_shot.jpg

From that guide there is this commentary:

The first version of the python code could barely move 5 grains around in anything approaching a smooth speed. The current version does a reasonable job with 10 grains.

That was the motivation to try and see if things could be simplified even further to improve performance when using CircuitPython. First, let's review the "complex" model used on the projects mentioned above.

LED Sand Physics

Physics may be too strong a term. This is really just kinematics - how things move without worrying about the specifics of the forces involved. In our case, "force" comes from acceleration. That can be used to update the velocity of a given particle (code):

led_matrices_equation2.png

And then the updated velocity can be used to update position (code):

led_matrices_equation1.png

The LED Matrix Sand projects above are based on these basic equations.

The value for acceleration comes from the accelerometer, and everything else is computed from there, sand particle by sand particle, one time step at a time. The concept of terminal velocity is used as a way set a maximum upper bound on velocity. Additionally, collisions are accounted for by having particles "bounce" off each other. This is even done inelastically to provide more realism.

In summary, the key items of the "complex" physics model are:

  • Proper acceleration / velocity kinematics
  • Enforcing terminal velocity
  • Modeling inelastic collisions

All of that of course requires code and CPU cycle time to process. Which, if you have the processing power, is great. What if you don't?

Simplified Physics

So are all those kinematic details necessary? To provide realistic motion, yes. However, to actually appreciate the effects of that realism, the simulation needs to play out on a reasonably sized display, like a 64x64 matrix. For a smaller display, like an 8x8, there really isn't enough space for the realism to be seen. So what if we make some fairly sweeping and hand wavy simplifications?

  • Just move one pixel in direction of current acceleration
  • Attempt diagonal move for any collision

And that's it.

Move one pixel in direction of current acceleration - one of the red arrows.

For diagonal collisions, attempt to move left/right.

Will that work? Well...we weren't sure either. So we coded it up and tried it out. Let's see how it works with some basic breadboard examples.

Examples

Each code example is broken into two general parts:

  • matrixsand.py - This contains a class which has the physics engine. You can't use it stand alone, you need to use it your application code. Also, you generally don't change anything in here.
  • examplecode.py - This is your application code. This is what you write.

The name examplecode.py is notional. Replace that with whatever you want. And remember that naming it code.py will allow it to run automatically when powered.

Simplified Matrix Sand Code

Here is the code for the simplified matrix sand physics. Save this as matrixsand.py into your CIRCUITPY folder. After that, just leave it alone. It will be used by application code examples which we we'll cover next.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

class MatrixSand:
    """Class to simulate simplified sand physics."""

    def __init__(self, width, height):
        self._width = width
        self._height = height
        self._grains = [False] * width * height

    def __getitem__(self, value):
        if isinstance(value, tuple):
            value = value[0] + self._width * value[1]
        return self._grains[value]

    def __setitem__(self, value, key):
        if isinstance(value, tuple):
            value = value[0] + self._width * value[1]
        self._grains[value] = key

    def _side_count(self, upside_down=False):
        left = right = 0
        for x in range(self._width):
            for y in range(self._height):
                if x != y and self[x, y]:
                    if x > y:
                        right += 1
                    else:
                        left += 1
        if upside_down:
            return right, left
        else:
            return left, right

    def iterate(self, acceleration):
        """Update sand based on supplied acceleration tuple. Returns True if
        any motion occurred, otherwise False."""
        #pylint: disable=too-many-locals,too-many-nested-blocks,too-many-branches

        ax, ay, az = acceleration

        # if z dominates, don't do anything
        if abs(az) > abs(ax) and abs(az) > abs(ay):
            return False

        # unit vectors for accelo
        ix = iy = 0
        if abs(ax) > 0.01:
            ratio = abs(ay / ax)
            if ratio < 2.414: # tan(67.5deg)
                ix = 1 if ax > 0 else -1
            if ratio > 0.414: # tan(22.5deg)
                iy = 1 if ay > 0 else -1
        else:
            iy = 1 if ay > 0 else -1

        # buffer
        new_grains = self._grains[:]

        # flag to indicate change
        updated = False

        # loop through the grains
        for x in range(self._width):
            for y in range(self._height):
                # is there a grain here?
                if self[x, y]:
                    moved = False
                    # compute new location
                    newx = x + ix
                    newy = y + iy
                    # bounds check
                    newx = max(min(self._width-1, newx), 0)
                    newy = max(min(self._height-1, newy), 0)
                    # wants to move?
                    if x != newx or y != newy:
                        moved = True
                        # is it blocked?
                        if new_grains[newx + self._width * newy]:
                            # can we move diagonally?
                            if not new_grains[x + self._width * newy] and \
                               not new_grains[newx + self._width * y]:
                                # can move either way
                                # move away from fuller side
                                left, right = self._side_count(ax < 0 and ay < 0)
                                if left >= right:
                                    newy = y
                                elif right > left:
                                    newx = x
                            elif not new_grains[x + self._width * newy]:
                                # move in y only
                                newx = x
                            elif not new_grains[newx + self._width * y]:
                                # move in x only
                                newy = y
                            else:
                                # nope, totally blocked
                                moved = False
                    # did it move?
                    if moved:
                        new_grains[x + self._width * y] = False
                        new_grains[newx + self._width * newy] = True
                        updated = True

        # did things change?
        if updated:
            self._grains = new_grains

        return updated
View on GitHub

Single Matrix Example

Let's start simple and just use a single 8x8 LED matrix. Wire up a matrix with address set to the default 0x70 as shown:

led_matrices_single_matrix_bb.png

And then save the following code as code.py in your CIRCUITPY folder.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import time
import board
import adafruit_lsm6ds.lsm6ds33
from adafruit_ht16k33 import matrix
import matrixsand

DELAY = 0.00 # add some delay if you want

# setup i2c
i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

# the accelo
accelo = adafruit_lsm6ds.lsm6ds33.LSM6DS33(i2c)

# the matrix
matrix = matrix.Matrix8x8(i2c, 0x70)

# the sand
sand = matrixsand.MatrixSand(8, 8)

# simple helper
def update_matrix():
    for x in range(8):
        for y in range(8):
            matrix[x,y] = sand[x,y]

# add some initial sand
for sx in range(4):
    for sy in range(4):
        sand[sx, sy] = 1
update_matrix()

# loop forever
while True:
    # read accelo
    ax, ay, az = accelo.acceleration

    # rotate coord sys
    xx = ay
    yy = ax
    zz = az

    # iterate the sand
    updated = sand.iterate((xx, yy, zz))

    # update matrix if needed
    if updated:
        update_matrix()

    # sleep
    time.sleep(DELAY)
View on GitHub

Now move the breadboard around and watch the grains of sand go!

Double Matrix Example

OK, now let's try two 8x8 matrices to create a 16x8 area. Since the class that takes care of the physics is general purpose, we can set it up for different sizes. So adapting the code for different sizes is easy.

Wire up the two matrices as shown below, with address 0x71 on the left and address 0x70 on the right.

led_matrices_double_matrix_bb.png

And then save the following code as code.py in your CIRCUITPY folder.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import time
import board
import adafruit_lsm6ds.lsm6ds33
from adafruit_ht16k33 import matrix
import matrixsand

DELAY = 0.00 # add some delay if you want

# setup i2c
i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

# the accelo
accelo = adafruit_lsm6ds.lsm6ds33.LSM6DS33(i2c)

# the matrix
matrix1 = matrix.Matrix8x8(i2c, 0x70)
matrix2 = matrix.Matrix8x8(i2c, 0x71)

# the sand
sand = matrixsand.MatrixSand(8, 16)

# simple helper
def update_matrix():
    for x in range(8):
        for y in range(16):
            if y < 8:
                matrix1[x, y] = sand[x, y]
            else:
                matrix2[x, y-8] = sand[x, y]

# add some initial sand
for sx in range(4):
    for sy in range(4):
        sand[sx, sy] = 1

update_matrix()

# loop forever
while True:
    # read accelo
    ax, ay, az = accelo.acceleration

    # rotate coord sys
    xx = ay
    yy = ax
    zz = az

    # iterate the sand
    updated = sand.iterate((xx, yy, zz))

    # update matrix if needed
    if updated:
        update_matrix()

    # sleep
    time.sleep(DELAY)
View on GitHub

Now move the breadboard around and watch the grains of sand go!

Does This Work?

So...does this approach work? Well, as you can see from running the examples above, it's not perfect. Things move in sort of a klunky fashion and they can stack up in odd ways. Also, the lack of true kinematics seems to start to become apparent with 16 pixels to move.

But it does provide a general sense of the actual physics. It's reasonably fun to move the examples above around and watch the "sand" move about. So, sure, it works. Just not perfectly. But it's a good option for smaller displays where the full physics are not necessarily warranted.

Let's now use it to make the Time Triangle Thing.

 

Build It

Here are the details for building the Time Triangle Thing.

Prepare the LED Matrices

Follow this guide for the general assembly of the 8x8 LED matrices:

You'll also need to change the I2C address of one of the matrices. See this part of the guide:

and solder the A0 jumper on one of the LEDs matrices to set the address to 0x71. That way we will end up with these addresses for our matrices:

  • Matrix 1 = 0x70 (default, no solder)
  • Matrix 2 = 0x71

Wiring Diagram

Here's how everything gets wired together. The 0x70 address matrix in on top and the 0x71 address matrix in on the bottom. Also reference the photos below in the general build.

led_matrices_hourglass_bb.png

Making the Triangle

Let's use some paper craft skills to make our Time Triangle Thing. You'll need a piece of cardboard that is 9" x 6". The bottom of an Adafruit shipping box can be used, which is what is shown here. But any scrap cardboard should do.

Gather the items you'll need:

  • A source for the cardboard
  • A pencil and a ruler
  • Something to cut with
  • Some tape
  • Cut the cardboard into a 9" wide by 6" tall rectangle.
  • Mark vertical lines at 3", 6", and 7.5" from the left edge.
  • Mark a horizontal line 3" up from the bottom as shown in the far right area.
  • Place the components down and use them to mark the cut outs.
  • Use the LEDs themselves (not the PCB edges) to mark square cut outs.
  • Use the Feather to mark cut outs for the headers to poke through.
  • This is how the markings should end up looking.
  • The small circle by the Feather is for passing through the battery cable.
Neatness counts for the LED cut outs. So take your time with those.
  • CAREFULLY cut out the areas.
  • Bend the cardboard at the 3" and 6" lines using the edge of the ruler to help make it nice and sharp.
  • It should look something like this.
  • Tape the components in place.
  • Note the orientation of the LED matrices. The top one should be 0x70 and the bottom one should be 0x71.
  • The Feather is on the outside and pokes through the slots.
  • Wire everything together. Consult the wiring diagram.
  • Now close everything up into the eponymous triangle.
  • Tape along the edge to close it up.

DONE!

led_matrices_final.jpg

Now move on to loading the code...

Hourglass Code

Now let's get the Feather setup with CircuitPython, the necessary libraries, and the hourglass code.

Prepare the Feather Sense

Follow this guide for setting up CircuitPython on the Feather nRF52840 Sense:

Install Libraries

Follow this guide for installing libraries:

This guide has specifics on the libraries used with the LED matrices:

Make sure these libraries are in your CIRCUITPY/lib folder:

led_matrices_Screenshot_from_2020-06-06_09-32-43.png

Hourglass Code

And here is the hourglass code. If you haven't already, also make sure to have matrixsand.py copied to your CIRCUITPY folder. If you worked through the examples in the previous section, then that should already have been done.

Then save the code below as code.py and the hourglass should start.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import time
import board
import adafruit_lsm6ds.lsm6ds33
from adafruit_ht16k33 import matrix
import matrixsand

DELAY = 0.05 # overall update rate

# setup i2c
i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller

# the accelo
accelo = adafruit_lsm6ds.lsm6ds33.LSM6DS33(i2c)

# the matrices
m1 = matrix.Matrix8x8(i2c, 0x70)
m2 = matrix.Matrix8x8(i2c, 0x71)

# the sand
sand1 = matrixsand.MatrixSand(8, 8)
sand2 = matrixsand.MatrixSand(8, 8)

# simple helper
def update_matrix(m, s):
    for x in range(8):
        for y in range(8):
            m[x,y] = s[x,y]

# fill up some sand
for sx in range(8):
    for sy in range(8):
        sand1[sx, sy] = True
sand1[0,0] = sand1[0,1] = sand1[1,0] = False
sand1[0,2] = sand1[1,1] = sand1[2,0] = False

update_matrix(m1, sand1)
update_matrix(m2, sand2)

updated1 = updated2 = False

while True:
    # read accelo
    ax, ay, az = accelo.acceleration
    # rotate coords
    xx = -ax - ay
    yy = -ax + ay
    zz = az

    # move grain of sand from upper to lower?
    if yy > 0 and sand1[7,7] and not sand2[0,0] and not updated2:
        sand1[7,7] = False
        sand2[0,0] = True
        updated1 = updated2 = True
    # move grain of sand from lower to upper?
    elif yy <= 0 and sand2[0,0] and not sand1[7,7] and not updated1:
        sand2[0,0] = False
        sand1[7,7] = True
        updated1 = updated2 = True
    # nope, just a regular update
    else:
        updated1 = sand1.iterate((xx, yy, zz))
        updated2 = sand2.iterate((xx, yy, zz))

    # update matrices if needed
    if updated1:
        update_matrix(m1, sand1)
    if updated2:
        update_matrix(m2, sand2)

    time.sleep(DELAY)
View on GitHub

This guide was first published on Jun 06, 2020. It was last updated on Jun 06, 2020.