# T³ Time Triangle Thing
## Overview
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](https://www.instagram.com/p/B_fP8ygjlBN/?igshid=1x72j8gdue7e) 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](https://circuitpython.org/).
## 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.
### Adafruit Feather nRF52840 Sense
[Adafruit Feather nRF52840 Sense](https://www.adafruit.com/product/4516)
The **Adafruit Feather Bluefruit Sense** takes our popular [Feather nRF52840 Express](https://www.adafruit.com/product/4062) and adds a smorgasbord of sensors to make a great wireless sensor platform. This Feather microcontroller comes with Bluetooth® Low Energy and...
In Stock
[Buy Now](https://www.adafruit.com/product/4516)
[Related Guides to the Product](https://learn.adafruit.com/products/4516/guides)
### Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Yellow-Green
[Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Yellow-Green](https://www.adafruit.com/product/1051)
What's better than a single LED? Lots of LEDs! A fun way to make a small display is to use an [8x8 matrix](https://www.adafruit.com/category/37_88) or a [4-digit 7-segment display](https://www.adafruit.com/category/37_103). Matrices like these are...
In Stock
[Buy Now](https://www.adafruit.com/product/1051)
[Related Guides to the Product](https://learn.adafruit.com/products/1051/guides)
### Lithium Ion Polymer Battery - 3.7V 350mAh
[Lithium Ion Polymer Battery - 3.7V 350mAh](https://www.adafruit.com/product/2750)
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 battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/2750)
[Related Guides to the Product](https://learn.adafruit.com/products/2750/guides)
# T³ Time Triangle Thing
## The Physics Model
The physics model used here is really a simplification of the one used in the [LED Matrix Sand Toy](https://learn.adafruit.com/matrix-led-sand) 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](https://github.com/adafruit/Adafruit_PixelDust) 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](https://learn.adafruit.com/animated-led-sand) project show below.
That code was ported to [CircuitPython](https://circuitpython.org/) (with some effort) and the results are covered in the [CircuitPython Digital Sand](https://learn.adafruit.com/digital-sand-dotstar-circuitpython-edition) guide and shown below:
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](https://en.wikipedia.org/wiki/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](https://github.com/adafruit/Adafruit_PixelDust/blob/6e5e4058dd4ed099a269af90932a4ef9fc1f2943/Adafruit_PixelDust.cpp#L204)):
And then the updated velocity can be used to update position ([code](https://github.com/adafruit/Adafruit_PixelDust/blob/6e5e4058dd4ed099a269af90932a4ef9fc1f2943/Adafruit_PixelDust.cpp#L239)):
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](https://en.wikipedia.org/wiki/Inelastic_collision) 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.
# T³ Time Triangle Thing
## 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.**
- **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**.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_LED_Sand_Hourglass/single_matrix/code.py
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.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_LED_Sand_Hourglass/double_matrix/code.py
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.
# T³ 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:
[LED Matrix Assembly](https://learn.adafruit.com/adafruit-led-backpack/1-2-8x8-matrix-assembly)
You'll also need to change the I2C address of one of the matrices. See this part of the guide:
[Changing I2C Address](https://learn.adafruit.com/adafruit-led-backpack/changing-i2c-address#changing-addresses-706265-1)
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.
## 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.
Info:
- **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!**
Now move on to loading the code...
# T³ Time Triangle Thing
## 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:
[CircuitPython on Feather Sense](https://learn.adafruit.com/adafruit-feather-sense/circuitpython-on-feather-sense)
## Hourglass Code
Click the **Download Project Bundle** button in the code listing below to get a zip file with the project code and necessary libraries. Copy **code.py** and **matrixsand.py** to the **CIRCUITPY** folder.
Also copy the libraries to **CIRCUITPY/lib**. For quick reference, the **CIRCUITPY/lib** folder should have these contents (having more is OK):
Here is the main code listing for **code.py**. The **matrixsand.py** file will be found in the zip, along with everything else. Click the **Download Project Bundle** to get the zip.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CircuitPython_LED_Sand_Hourglass/hourglass/code.py
The code handles both of the accelerometers that may appear on the Adafruit Feather nRF52840 Sense.
## Featured Products
### Adafruit Feather nRF52840 Sense
[Adafruit Feather nRF52840 Sense](https://www.adafruit.com/product/4516)
The **Adafruit Feather Bluefruit Sense** takes our popular [Feather nRF52840 Express](https://www.adafruit.com/product/4062) and adds a smorgasbord of sensors to make a great wireless sensor platform. This Feather microcontroller comes with Bluetooth® Low Energy and...
In Stock
[Buy Now](https://www.adafruit.com/product/4516)
[Related Guides to the Product](https://learn.adafruit.com/products/4516/guides)
### Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Yellow-Green
[Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Yellow-Green](https://www.adafruit.com/product/1051)
What's better than a single LED? Lots of LEDs! A fun way to make a small display is to use an [8x8 matrix](https://www.adafruit.com/category/37_88) or a [4-digit 7-segment display](https://www.adafruit.com/category/37_103). Matrices like these are...
In Stock
[Buy Now](https://www.adafruit.com/product/1051)
[Related Guides to the Product](https://learn.adafruit.com/products/1051/guides)
### Lithium Ion Polymer Battery - 3.7V 350mAh
[Lithium Ion Polymer Battery - 3.7V 350mAh](https://www.adafruit.com/product/2750)
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 battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/2750)
[Related Guides to the Product](https://learn.adafruit.com/products/2750/guides)
## Related Guides
- [Adafruit Feather nRF52840 Sense](https://learn.adafruit.com/adafruit-feather-sense.md)
- [Animating Multiple LED Backpacks](https://learn.adafruit.com/animating-multiple-led-backpacks.md)
- [Using the Bluefruit Dashboard with Web Bluetooth in Chrome](https://learn.adafruit.com/bluefruit-dashboard-web-bluetooth-chrome.md)
- [Mini LED Matrix Audio Visualizer](https://learn.adafruit.com/mini-led-matrix-audio-visualizer.md)
- [How to Fuse Motion Sensor Data into AHRS Orientation (Euler/Quaternions)](https://learn.adafruit.com/how-to-fuse-motion-sensor-data-into-ahrs-orientation-euler-quaternions.md)
- [Wearable Continuous Temperature Monitor with Adafruit IO](https://learn.adafruit.com/wearable-temperature-monitor.md)
- [Programmable Wireless BLE Gesture Mouse](https://learn.adafruit.com/ble-wireless-gesture-mouse.md)
- [LED Bullwhip with Motion & Sound Reactivity](https://learn.adafruit.com/led-bullwhip.md)
- [CircuitPython BLE Libraries on Any Computer](https://learn.adafruit.com/circuitpython-ble-libraries-on-any-computer.md)
- [Adafruit LED Backpacks](https://learn.adafruit.com/adafruit-led-backpack.md)
- [BLE Buzzy Box](https://learn.adafruit.com/ble-buzzy-box.md)
- [Light-Up Reactive Ukulele](https://learn.adafruit.com/light-up-reactive-ukulele.md)
- [Introducing Adafruit Feather](https://learn.adafruit.com/adafruit-feather.md)
- [BLE Vibration Bracelet](https://learn.adafruit.com/ble-vibration-bracelet.md)
- [CircuitPython Hardware: LED Backpacks & FeatherWings](https://learn.adafruit.com/micropython-hardware-led-backpacks-and-featherwings.md)
- [Adafruit LSM6DS33 6-DoF IMU Breakout](https://learn.adafruit.com/lsm6ds33-6-dof-imu-accelerometer-gyro.md)