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.
• code.py - This is your application code. This is what you write. It relies on matrixsand.py.

Both files should be placed in the CIRCUITPY folder. Clicking the Download Project Bundle link for the code listing below will provide a .zip file that contains everything needed. Not only the two .py files, but also any require libraries - to be placed in CIRCUITPY/lib.

## 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:

Click the Download Project Bundle buttoon and save the .zip file. Then from the zip file, copy code.py  and matrixsand.py to the CIRCUITPY folder. Also copy any libraries from the zip to CIRCUITPY/lib.

```# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#

import time
import board
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

# 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]

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

# loop forever
while True:
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)
```

Once the code files and libraries have been copied over, the example should run. 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.

Same as above, click the Download Project Bundle button to get the .zip and copy the files as needed to the CIRCUITPY folder.

```# SPDX-FileCopyrightText: 2020 Carter Nelson for Adafruit Industries
#

import time
import board
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

# 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]

for sx in range(4):
for sy in range(4):
sand[sx, sy] = 1

update_matrix()

# loop forever
while True:
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)
```

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.

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