HC8x8x8Cube library for H.C. 8x8x8 LED Cube Kit (HCKITS0050)
Arduino library to control the Hobby Components 8x8x8 LED cube kit (HCKITS0050). If you are interested in building an 8x8x8 LED cube the please take a look at our very own and easy to build (through-hold components) 8x8x8 LED cube kits. They available in the following colours:
Blue: HCKITS0050
Green: TBA
Red: TBA
White TBA
This library will handle the automatic refreshing of the cube and provides a set of library functions for controlling the LED on the cube, and displaying text and graphic animations. Additionally the library also comes with a set of predefined patters and that can be played back to the cube with just one command.
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:
Documents/Arduino/libraries/
Linux:
Usually found within the users home area under /Arduino/libraries/
Using the HC8x8x8Cube library
To use the library just include the HC8x8x8Cube.h header file in your own sketch:
Code: Select all
#include "HC8x8x8Cube.h"
To initialise the library place the following line in the Setup() loop at the top of the sketch:
Code: Select all
CubeInit();
Code: Select all
CubeClearBuffer();
Code: Select all
Base_LED(State);
State is the state the LEDs will be set to. Valid values are
ON (All 4 LED are turned on)
OFF (All 4 LEDs are turned off)
Code: Select all
SetVoxel(x, y, z);
x is the x coordinate of the LED to set. Valid values are 0 to 7
y is the y coordinate of the LED to set. Valid values are 0 to 7
z is the z coordinate of the LED to set. Valid values are 0 to 7
Code: Select all
SetVoxel(x, y, z, View, Direction);
x is the x coordinate of the LED to set. Valid values are 0 to 7
y is the y coordinate of the LED to set. Valid values are 0 to 7
z is the z coordinate of the LED to set. Valid values are 0 to 7
View is the perspective from which the x, y, and z coordiantes are referenced from. Valid values are
FRONT (coordiantes are referenced from the front of the cube)
BACK (coordiantes are referenced from the back of the cube)
LEFT (coordiantes are referenced from the left side of the cube)
RIGHT (coordiantes are referenced from the right side of the cube)
TOP (coordiantes are referenced from the top of the cube)
BOTTOM (coordiantes are referenced from the bottom of the cube)
Direction specifies side of the cube coordates are referenced from. Valid values are
FORWARD (Coordiantes are referenced from the bottom left corner)
REVERSE (Coordiantes are referenced from the bottom right corner
Code: Select all
ClearVoxel(x, y, z);
x is the x coordinate of the LED to clear. Valid values are 0 to 7
y is the y coordinate of the LED to clear. Valid values are 0 to 7
z is the z coordinate of the LED to set. Valid values are 0 to 7
Code: Select all
ClearVoxel(x, y, z, View, Direction);
x is the x coordinate of the LED to clear. Valid values are 0 to 7
y is the y coordinate of the LED to clear. Valid values are 0 to 7
z is the z coordinate of the LED to set. Valid values are 0 to 7
View is the perspective from which the x, y, and z coordiantes are referenced from. Valid values are
FRONT (coordiantes are referenced from the front of the cube)
BACK (coordiantes are referenced from the back of the cube)
LEFT (coordiantes are referenced from the left side of the cube)
RIGHT (coordiantes are referenced from the right side of the cube)
TOP (coordiantes are referenced from the top of the cube)
BOTTOM (coordiantes are referenced from the bottom of the cube)
Direction specifies side of the cube coordates are referenced from. Valid values are
FORWARD (Coordiantes are referenced from the bottom left corner)
REVERSE (Coordiantes are referenced from the bottom right corner)
Code: Select all
State = GetVoxel(x, y, z);
x is the x coordinate of the LED. Valid values are 0 to 7
y is the y coordinate of the LED. Valid values are 0 to 7
z is the z coordinate of the LED. Valid values are 0 to 7
Returns the current state of the LED where
true = LED at coordinate x,y,z is currently ON
false = LED at coordinate x, y, z is currently OFF
Code: Select all
boolean GetVoxel(x, y, z, View, Direction)
x is the x coordinate of the LED. Valid values are 0 to 7
y is the y coordinate of the LED. Valid values are 0 to 7
z is the z coordinate of the LED. Valid values are 0 to 7
View is the perspective from which the x, y, and z coordiantes are referenced from. Valid values are
FRONT (coordiantes are referenced from the front of the cube)
BACK (coordiantes are referenced from the back of the cube)
LEFT (coordiantes are referenced from the left side of the cube)
RIGHT (coordiantes are referenced from the right side of the cube)
TOP (coordiantes are referenced from the top of the cube)
BOTTOM (coordiantes are referenced from the bottom of the cube)
Direction specifies side of the cube coordates are referenced from. Valid values are
FORWARD (Coordiantes are referenced from the bottom left corner)
REVERSE (Coordiantes are referenced from the bottom right corner)
Returns the current state of the LED where
true = LED at coordinate x,y,z is currently ON
false = LED at coordinate x, y, z is currently OFF
Code: Select all
Shift_Cube(Axis, Direction);
Axis is the x, y, or z axis to shift the LEDs in. Valid values are
X_Axis (Shifts the LEDs one place in the x axis)
Y_Axis (Shifts the LEDs one place in the y axis)
Z_Axis (Shifts the LEDs one place in the z axis)
Direction is the direction in which to shift the LEDs. Valid values are
FORWARD (Shifts the LEDs by one position in the forward direction)
REVERSE (Shifts the LEDs by one position in the reverse direction)
Code: Select all
printString(TextString[], Offset, Axis, Layer, Direction);
TextString[] is a string array containing the text to be displayed.
Offset is the column position on the cube from where to start displaying the text from
Axis is which axis (x, y, or z) to display the text on. Valid values are
X_Axis (Displays the text on the vertical x axis)
Y_Axis (Displays the text on the vertical y axis)
Z_Axis (Displays the text on the horizontal z axis)
Layer is the on which to display the text. Valid values are from 0 to 7
Direction specifies in which direction to print the text to the cube. Valid values are
FORWARD (Prints the text in the forward direction. I.e. left to right)
REVERSE (Prints the text in the reverse direction. I.e. right to left)
Code: Select all
printWrap(TextString[], Offset, IncludeBack);
TextString[] is a string array containing the text to be displayed
Offset is the column position on the cube from where to start displaying the text from
IncludeBack specifies whether to include the rear side of the cube when wrapping the text around it. Valid values are
true (include the back when wrapping the text)
false (do not include the back when wrapping the text)
Code: Select all
Scroll_Text(TextString[], Mode, Speed);
TextString[] is a string array containing the text to be displayed.
Mode specifies how the text will be scrolled. Valid values are:
Scroll_X_Layer0 (Scrolls the text in the x axis on layer 0)
Scroll_X_Layer1 (Scrolls the text in the x axis on layer 1)
Scroll_X_Layer2 (Scrolls the text in the x axis on layer 2)
Scroll_X_Layer3 (Scrolls the text in the x axis on layer 3)
Scroll_X_Layer4 (Scrolls the text in the x axis on layer 4)
Scroll_X_Layer5 (Scrolls the text in the x axis on layer 5)
Scroll_X_Layer6 (Scrolls the text in the x axis on layer 6)
Scroll_X_Layer7 (Scrolls the text in the x axis on layer 7)
Scroll_Y_Layer0 (Scrolls the text in the y axis on layer 0)
Scroll_Y_Layer1 (Scrolls the text in the y axis on layer 1)
Scroll_Y_Layer2 (Scrolls the text in the y axis on layer 2)
Scroll_Y_Layer3 (Scrolls the text in the y axis on layer 3)
Scroll_Y_Layer4 (Scrolls the text in the y axis on layer 4)
Scroll_Y_Layer5 (Scrolls the text in the y axis on layer 5)
Scroll_Y_Layer6 (Scrolls the text in the y axis on layer 6)
Scroll_Y_Layer7 (Scrolls the text in the y axis on layer 7)
Scroll_z_Layer0 (Scrolls the text in the z axis on layer 0)
Scroll_z_Layer1 (Scrolls the text in the z axis on layer 1)
Scroll_z_Layer2 (Scrolls the text in the z axis on layer 2)
Scroll_z_Layer3 (Scrolls the text in the z axis on layer 3)
Scroll_z_Layer4 (Scrolls the text in the z axis on layer 4)
Scroll_z_Layer5 (Scrolls the text in the z axis on layer 5)
Scroll_z_Layer6 (Scrolls the text in the z axis on layer 6)
Scroll_z_Layer7 (Scrolls the text in the z axis on layer 7)
Scroll_Wrap (Scrolls the text around the outside of the cube)
Scroll_Full_Wrap (Scrolls the text around the outside of the cube including the back of the cube)
Speed specifies how fast in millisecond steps to scroll the text. Valid values are 1ms to 1023ms per step.
Code: Select all
Cube(x1, y1, z1, x2, y2, z2, Solid);
x1 is the x axis coordinate for the first corner of the cube.
y1 is the y axis coordinate for the first corner of the cube.
z1 is the z axis coordinate for the first corner of the cube.
x2 is the x axis coordinate for the opposite corner of the cube.
y2 is the y axis coordinate for the opposite corner of the cube.
z2 is the z axis coordinate for the opposite corner of the cube.
valid values for x1, y1, z1, x2, y2, z2 are from 0 to 7
Solid specifies whether the cube should be drawn solid (filled in) or wire frame
Code: Select all
Line(x1, y1, z1, x2, y2, z2);
x1 is the x axis coordinate for the first end of the line.
y1 is the y axis coordinate for the first end of the line.
z1 is the z axis coordinate for the first end of the line.
x2 is the x axis coordinate for the opposite end of the line.
y2 is the y axis coordinate for the opposite end of the line.
z2 is the z axis coordinate for the opposite end of the line.
valid values for x1, y1, z1, x2, y2, z2 are from 0 to 7
Code: Select all
Bitmap(Bitmap[], Offset, Axis, Layer, Direction);
Bitmap[] is a 1 dimensional array of 8 bytes containing the bitmap image to displayed. This must be stored in program memory and of type byte (const byte).
Offset is the column position on the cube from where to start displaying the bitmap from
Axis is which axis (x, y, or z) to display the bitmap on. Valid values are
X_Axis (Displays the bitmap on the vertical x axis)
Y_Axis (Displays the bitmap on the vertical y axis)
Z_Axis (Displays the bitmap on the horizontal z axis)
Layer is the on which to display the bitmap. Valid values are from 0 to 7
Direction specifies in which direction to print the bitmap to the cube. Valid values are
FORWARD (Prints the bitmap in the forward direction. I.e. left to right)
REVERSE (Prints the bitmap in the reverse direction. I.e. right to left)
Code: Select all
WrapBitmap(bitmap[], Offset, IncludeBack);
Bitmap[] is a 1 dimensional array of 8 bytes containing the bitmap image to displayed. This must be stored in program memory and of type byte (const byte).
Offset is the column position on the cube from where to start displaying the bitmap from
IncludeBack specifies whether to include the rear side of the cube when wrapping the bitmap around it. Valid values are
true (include the back when wrapping the bitmap)
false (do not include the back when wrapping the bitmap)
Code: Select all
State = ModeButtonState();
Returns the current state where
MODE_NOT_PRESSED = The mode button has not been pressed
MODE_SHORT_PRESS = The mode button has been pressed for between 100 to 500ms
MODE_LONG_PRESS = The mode button has been pressed for longer than 1 second.
The mode state is not automatically cleared. Once you have read the state you must clear
it with the Clear_Mode_Button_State() function.
Code: Select all
Clear_Mode_Button_State();
Code: Select all
State = Mode_Repeat();
Returns a boolean value that will toggle state each time the mode button has been pressed for longer than 1 second
This function can be used in a loop to give the user the option of continually repeating a pattern.
Using the pre-defined patterns
The library also provides a set of pre-defined patterns what can be written to the cube with just one command. These patterns are also pre-programmed into ATMega328 device provided with the 8x8x8 cube kit. To use this patterns you will need to include the HC8x8x8_Cube_Patterns.h header file at the top of your sketch:
Code: Select all
#include "HC8x8x8_Cube_Patterns.h"
The following patterns are available:
Code: Select all
Pattern_Frame(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 254
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023
Code: Select all
Pattern_All_Flash(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 254
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023
Code: Select all
Pattern_Random_Slide(Speed, Axis, Direction)
random LED at a time. Where:
Speed is the speed at which to move each LED in 1ms increments.
Axis is the x, y, or z axis to shift the LEDs in. Valid values are
X_Axis
Y_Axis
Z_Axis
Direction is the direction in which to animate the movement of the LEDs. Valid values are
FORWARD
REVERSE
Code: Select all
Pattern_Rain(Cycles, Speed, Intensity, Direction);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023
Intensity is how many 'drops' of rain to animate. Valid values are 1 to 254
Direction is the direction in which to animate the rain drops. Valid values are
FORWARD (Rain drops will move from the top layer to the bottom layer of the cube)
REVERSE (Rain drops will move from the bottom layer to the top layer of the cube)
Code: Select all
Pattern_StarField(Cycles, Speed, Intensity, Direction);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023
Intensity is how many 'stars' to animate. Valid values are 1 to 254
Direction is the direction in which to animate the movement of the stars. Valid values are
FORWARD (stars will move from the rear layer to the front layer of the cube)
REVERSE (stars will move from the front layer to the rear layer of the cube)
Code: Select all
Pattern_Blizzard(Cycles, Speed, Intensity, Direction);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023
Intensity is how many 'snow flakes' to animate. Valid values are 1 to 254
Direction is the direction in which to animate the movement of the snow. Valid values are
FORWARD (snow will move from the right layer to the left layer of the cube)
REVERSE (stars will move from the left layer to the right layer of the cube)
Code: Select all
Pattern_Random_Fill(byte Speed);
Speed is the speed at which to turn each LED on specified in 1ms increments. Valid values are from 1 to 254
Code: Select all
Pattern_Random_Clear(byte Speed);
Speed is the speed at which to turn each LED off specified in 1ms increments. Valid values are from 1 to 254
Code: Select all
Pattern_Random_Clear(byte Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Objects is the number if 4x4x4 cubes to animate. valid values are from 1 to 254.
Code: Select all
Pattern_SineWave( Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_LineDance(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_PlasmaBall(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_PM(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_WireCube(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_CubeSlide(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_CubeSwap(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_CubeBounce(Cycles, Speed, Objects);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Objects is the number if 4x4x4 cubes to animate. valid values are from 1 to 254.
Code: Select all
Pattern_TextWrap(Cycles, Speed);
Cycles is the number of repetitions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_Text3D(Cycles, Speed);
Cycles is the number of repititions. Valid values are from 1 to 1023
Speed is the speed at which to step though each frame of the animation in 1ms increments. Valid values are from 1 to 1023.
Code: Select all
Pattern_Countdown();
- /* FILE: HC8x8x8_Play_Patterns
- DATE: 14/03/16
- VERSION: 0.1
- AUTHOR: Andrew Davies
- 14/03/16 version 0.1: Original version
- This is the default sketch that comes pre-programmed into the cube. It will
- sequence through each of the patterns available in the HC8x8_Cube_Patterns_library.
- 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 LED cube and patterns library */
- #include "HC8x8x8Cube.h"
- #include "HC8x8x8_Cube_Patterns.h"
- /* Set the animation speed for each pattern */
- #define SPEED 100
- void setup()
- {
- /* Initialises the cube library */
- CubeInit();
- }
- /* Main loop */
- void loop()
- {
- byte index1, index2;
- /* Play the start animation only when the cube is first turned on */
- Scroll_Text("8x8x8LEDCubeDemo", Scroll_X_Layer0, SPEED / 2);
- Pattern_Countdown();
- Pattern_All_Flash(10, SPEED);
- /* Play the patterns in a continuous loop */
- while(1)
- {
- /* Display a sweeping 8x8 grid of LEDs */
- do
- {
- Pattern_Frame(5, SPEED);
- }while(Mode_Repeat());
- /* Random rain effect */
- do
- {
- Pattern_Rain(100, SPEED, 20, FORWARD);
- }while(Mode_Repeat());
- /* Random rain effect in reverse direction */
- do
- {
- Pattern_Rain(100, SPEED, 20, REVERSE);
- }while(Mode_Repeat());
- /* Random star field pattern */
- do
- {
- Pattern_StarField(100, SPEED, 5, FORWARD);
- }while(Mode_Repeat());
- /* Random star field pattern in reverse direction */
- do
- {
- Pattern_StarField(100, SPEED, 5, REVERSE);
- }while(Mode_Repeat());
- /* Random blizzard field pattern */
- do
- {
- Pattern_Blizzard(100, SPEED, 5, FORWARD);
- }while(Mode_Repeat());
- /* Random blizzard field pattern in reverse direction*/
- do
- {
- Pattern_Blizzard(100, SPEED, 5, REVERSE);
- }while(Mode_Repeat());
- CubeClearBuffer();
- /* Scrolls the text '8x8x8LEDCube' through the middle 4 layers of the cube to create a 3D text effect */
- do
- {
- Pattern_Text3D(1, SPEED);
- }while(Mode_Repeat());
- CubeClearBuffer();
- /* Randomly turn on then off all the LEDs */
- do
- {
- for(index1 = 0; index1 < 3; index1++)
- {
- Pattern_Random_Fill(SPEED / 10);
- Pattern_Random_Clear(SPEED / 10);
- }
- }while(Mode_Repeat());
- /* Randomly bounce ten 4x4x4 cubes */
- do
- {
- Pattern_CubeBounce(1023, SPEED / 5, 10);
- }while(Mode_Repeat());
- /* Displays a scrolling sine wave on all layers */
- Pattern_SineWave(300, SPEED * 0.7);
- /* Bounces a line within the cube in a 3d motion */
- Pattern_LineDance(500, SPEED / 2);
- /* Uses the line function to create a plasma ball */
- Pattern_PlasmaBall(200, SPEED / 2);
- /* Uses the bitmap function to play an animation around the outside edges of the cube */
- Pattern_PM(3, SPEED * 1.5 /*130*/);
- /* Draws an expanding wire frame cube from one corner to another */
- Pattern_WireCube(5, SPEED / 2);
- /* Slides an 8x8x8 cube from the right side to the left side */
- Pattern_CubeSlide(5, SPEED / 2);
- CubeClearBuffer();
- /* Scrolls the text '8x8x8LEDCube' around the outside of the cube */
- Pattern_TextWrap(1, SPEED);
- /* Moves four 4x4x4 LED cubes in a pattern */
- Pattern_CubeSwap(5, SPEED);
- /* Bounces a single 4x4x4 cube in 3 dimensions */
- Pattern_CubeBounce(1023, SPEED / 10 , 1);
- }
- }
The HC8x8x8Cube library (V0.2) can be downloaded here (please log in to download):