An Arduino library to drive 4x4x4 LED cubes. This library is designed to work with an ATMega328p based Arduino.
If you are interested in building an LED cube the please take a look at our very inexpensive and easy to build 4x4x4 kits that will work great with this library. They available in the following colours:
Blue: HCKITS0040
Green: HCKITS0042
Red: HCKITS0043
White HCKITS0044
This library will handle the automatic refreshing of the cube and will allow you to individually control the state of each LED simply by saving a bit pattern to a predefined array. Additionally the library also comes with predefined animation sequences and an example sketch demonstrating their use.
You will need to download (please log in to download the library) and unzip this library to the Arduino development environments library area.
On Windows:
My Documents\Arduino\libraries\
On Mac:
Docments/Arduino/libraries/
or similarly for Linux.
Using the library
To use the library just include the HC4x4x4Cube.h header file in your own sketch.
To initialise the library place the following line in the Setup() loop at the top of the sketch:
Code: Select all
CubeInit();Once the library is initialised you can then control the state of each LED by saving a bit pattern to the libraries LED buffer Matrix_Buffer[]. This buffer is simply an array containing four 16 bit integer numbers. Each of the 4 numbers represent the bit pattern for each layer of the cube as follows:
Matrix_Buffer[0] = [BOTTOM LAYER]
Matrix_Buffer[1] = [2nd LAYER]
Matrix_Buffer[2] = [3rd LAYER]
Matrix_Buffer[3] = [TOP LAYER]
The bit pattern for each layer is a 16 bit number where each bit of the number represents the state of an LED on that layer (there are 16 LEDs on each layer). Setting each bit to a 1 will turn the appropriate LED on and setting it to a 0 will turn it off. In the line below we are turning on the first and last LED for the first layer:
Code: Select all
Matrix_Buffer[0] = 0b1000000000000001;Code: Select all
Matrix_Buffer[3] = 0b0000001111000000;When any pattern is written to this buffer the library will automatically update the cube to display the new pattern. This is done in the background an no further code is required in your sketch. We can then put all the above steps together to create the following example sketch:
/* Include the cube library */
#include "HC4x4x4Cube.h"
Code: Select all
void setup()
{
/* Initialise the cube */
CubeInit();
}
/* Main sketch */
void loop()
{
/* Turn on all LEDs in the first and 3rd layers */
Matrix_Buffer[3] = 0b0000000000000000;
Matrix_Buffer[2] = 0b1111111111111111;
Matrix_Buffer[1] = 0b0000000000000000;
Matrix_Buffer[0] = 0b1111111111111111;
/* Wait 5 seconds */
delay(5000);
/* Turn on the corner LEDs */
Matrix_Buffer[3] = 0b1001000000001001;
Matrix_Buffer[2] = 0b0000000000000000;
Matrix_Buffer[1] = 0b0000000000000000;
Matrix_Buffer[0] = 0b1001000000001001;
/* Wait 5 seconds */
delay(5000);
/* Turn on a different block of 4 LED for each layer */
Matrix_Buffer[3] = 0b1100110000000000;
Matrix_Buffer[2] = 0b0000000011001100;
Matrix_Buffer[1] = 0b0011001100000000;
Matrix_Buffer[0] = 0b0000000000110011;
/* Wait 5 seconds */
delay(5000);
}Also included in the library is a number of predefined animation sequences. These can be automatically 'played' to the cube using the libraries CubePlayPattern() function:
Code: Select all
CubePlayPattern(PatternName, Delay, Cycles);PatternName is the name of the pattern to play. See below for a list of patterns.
Delay is the delay time in millisecond to wait between each step of the animation. A lower value will make the animation step faster.
Cycles is the number of times to play the entire animation before moving on.
The following predefined patterns are available:
- LayerBounce
LayerRotate;
Spiral
BorderLoop
BorderFlash
BorderWipe
Block4Random
Block4Corners
Rise
FourRotate
SpiralLayers
Snake
Upright
RandomFill
Cube
The example sketch to demonstrate how to use these animation is also included with the library:
/* FILE: HC4x4x4Cube_Animation.ino
DATE: 24/06/15
VERSION: 0.1
AUTHOR: Andrew Davies
24/06/15 version 0.1: Original version
This sketch uses the HC4x4x4Cube library to step though the predefined LED
patterns found in the HC4x4x4_Cube_Patterns.h file. The sketch makes use of the
CubePlayPattern() function to automatically play each pattern. This function has 3
parameters (arguments). The first is the name of the predefined LED pattern.
The second specifies the delay in milliseconds between each step of the sequence.
The final parameter specifies how many times to loop though the animation before
moving on.
You may copy, alter and reuse this code in any way you like, but please leave
reference to HobbyComponents.com in your comments if you redistribute this code.
This software may not be used directly for the purpose of selling products that
directly compete with Hobby Components Ltd's own range of products.
THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHER
EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR LACK OF NEGLIGENCE.
HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR ANY DAMAGES,
INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR ANY
REASON WHATSOEVER.
*/
/* Include the cube library */
#include "HC4x4x4Cube.h"
/* Include the predefined patterns */
#include "HC4x4x4_Cube_Patterns.h"
/* Set the default speed for all animations in ms */
#define SPEED 200
void setup()
{
/* Initialise the cube */
CubeInit();
}
/* Main sketch */
void loop()
{
/* Step through each predefined LED pattern */
CubePlayPattern(LayerBounce, SPEED, 2);
CubePlayPattern(LayerRotate, SPEED, 10);
CubePlayPattern(Spiral, SPEED, 1);
CubePlayPattern(BorderLoop, SPEED, 3);
CubePlayPattern(BorderFlash, SPEED, 5);
CubePlayPattern(BorderWipe, SPEED, 1);
CubePlayPattern(Block4Random, SPEED, 5);
CubePlayPattern(Block4Corners, SPEED, 3);
CubePlayPattern(Rise, SPEED, 5);
CubePlayPattern(FourRotate, SPEED, 5);
CubePlayPattern(SpiralLayers, SPEED, 2);
CubePlayPattern(Snake, SPEED, 5);
CubePlayPattern(Upright, SPEED, 5);
CubePlayPattern(RandomFill, SPEED, 5);
CubePlayPattern(Cube, SPEED, 5);
}
The library files can be downloaded from our forum here:
Version 0.2:
Older version 0.1:
.