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: HCKITS0050Green: TBARed: TBAWhite 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:

#include "HC8x8x8Cube.h"

To initialise the library place the following line in the Setup() loop at the top of the sketch:

Code:

CubeInit();

One the library has been initiliased you can control the states of the LEDs on the cube with the following library functions:

Code:

CubeClearBuffer();

Clears all LED data in the matrix buffer (turns off all LEDs).

Code:

Base_LED(State);

Used to set the state of the 10mm base LEDs where: 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:

SetVoxel(x, y, z);

Sets (turns on) the state of a single LED (Voxel) where: 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:

SetVoxel(x, y, z, View, Direction);

Sets (turns on) the state of a single LED (Voxel) where: 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:

ClearVoxel(x, y, z);

Clears (turns off) the state of a single LED (Voxel) where: 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:

ClearVoxel(x, y, z, View, Direction);

Clears (turns off) the state of a single LED (Voxel) where: 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:

State = GetVoxel(x, y, z);

Gets the current state of a single LED (Voxel) where: 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:

boolean GetVoxel(x, y, z, View, Direction)

Gets the current state of a single LED (Voxel) where: 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:

Shift_Cube(Axis, Direction);

Shifts the entire grid of LEDs in one direction where 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:

printString(TextString[], Offset, Axis, Layer, Direction);

Prints a string of alphanumeric text to the cube on a specified axis and layer where: 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:

printWrap(TextString[], Offset, IncludeBack);

Uses the PrintString function to wrap a string of text around the outside of the cube where: 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:

Scroll_Text(TextString[], Mode, Speed);

Automatically scrolls a string of text in one of 26 ways. Where: 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:

Cube(x1, y1, z1, x2, y2, z2, Solid);

Used to display a 3D cube primitive where: 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

Used to draw a single Voxel width line in 3D: 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:

Bitmap(Bitmap[], Offset, Axis, Layer, Direction);

Displays an array containing a binary 8x8 bitmap image where: 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:

WrapBitmap(bitmap[], Offset, IncludeBack);

Uses the Bitmap() function to wrap a bitmap on the outside of the cube where: 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:

State = ModeButtonState();

Gets the current state of the mode button

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:

Clear_Mode_Button_State();

Clears the current status (MODE_NOT_PRESSED) of the mode button.

Code:

State = Mode_Repeat();

Checks if the mode button has been pressed for longer than 1 second and if so toggles the repeat mode flag

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:

#include "HC8x8x8_Cube_Patterns.h"

The following patterns are available:

Code:

Pattern_Frame(Cycles, Speed);

Display a sweeping 8x8 grid of LEDs where: 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:

Pattern_All_Flash(Cycles, Speed);

Flash all the LEDs where: 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:

Pattern_Random_Slide(Speed, Axis, Direction)

Shifts an 8x8 grid of LEDs from one sides of the cube to the other by one 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:

Pattern_Rain(Cycles, Speed, Intensity, Direction);

Random rain effect pattern where: 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:

Pattern_StarField(Cycles, Speed, Intensity, Direction);

Random star field pattern where: 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:

Pattern_Blizzard(Cycles, Speed, Intensity, Direction);

Random blizzard field pattern where: 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:

Pattern_Random_Fill(byte Speed);

Tuns on each LED in a random pattern until all LEDs are on. Where: Speed is the speed at which to turn each LED on specified in 1ms increments. Valid values are from 1 to 254

Code:

Pattern_Random_Clear(byte Speed);

Tuns off each LED in a random pattern until all LEDs are off. Where: Speed is the speed at which to turn each LED off specified in 1ms increments. Valid values are from 1 to 254

Code:

Pattern_Random_Clear(byte Speed);

Bounces a number of 4x4x4 cubes in 3 dimensions where: 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:

Pattern_SineWave( Cycles, Speed);

Displays a scrolling sine wave on all layers where: 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:

Pattern_LineDance(Cycles, Speed);

Bounces a line within the cube in a 3d motion where: 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:

Pattern_PlasmaBall(Cycles, Speed);

Uses the line function to create a plasma ball effect where: 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:

Pattern_PM(Cycles, Speed);

Uses the bitmap function to play an animation around the outside edges of the cube where: 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:

Pattern_WireCube(Cycles, Speed);

Draws an expanding wire frame cube from one corner to another where: 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:

Pattern_CubeSlide(Cycles, Speed);

Slides an 8x8x8 cube from the right side to the left side where: 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:

Pattern_CubeSwap(Cycles, Speed);

Moves four 4x4x4 LED cubes in a pattern where: 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:

Pattern_CubeBounce(Cycles, Speed, Objects);

Bounces a number of 4x4x4 cubes in 3 dimensions where: 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:

Pattern_TextWrap(Cycles, Speed);

Scrolls the text '8x8x8LEDCube' around the outside of the cube where: 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:

Pattern_Text3D(Cycles, Speed);

Scrolls the text '8x8x8LEDCube' through the middle 4 layers of the cube to create a 3D text effect where: 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:

Pattern_Countdown();

Scrolls the numbers 5 to 1 from the front of the cube to the back to create a countdown effect.

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 leavereference to HobbyComponents.com in your comments if you redistribute this code.This software may not be used directly for the purpose of selling products thatdirectly compete with Hobby Components Ltd's own range of products.

THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHEREXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OFMERCHANTABILITY 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 ANYREASON 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);

Who is online

Users browsing this forum: No registered users and 1 guest

You cannot post new topics in this forumYou cannot reply to topics in this forumYou cannot edit your posts in this forumYou cannot delete your posts in this forumYou cannot post attachments in this forum