HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Useful guides, libraries, and example sketches to support our Arduino based products.
admin
Site Admin
Posts: 865
Joined: Sun Aug 05, 2012 4:02 pm

HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by admin » Wed Jun 24, 2015 11:44 am

Image


Image

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;
In this example we are turning on the middle 4 LEDs for the 3rd layer:

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);
Where:
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);
}





Image

The library files can be downloaded from our forum here:

Version 0.2:
HC4x4x4Cube_V0_2.zip

Older version 0.1:
HC4x4x4Cube.zip
You do not have the required permissions to view the files attached to this post.

webac
Posts: 1
Joined: Sat Aug 27, 2016 12:22 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by webac » Sat Aug 27, 2016 3:10 pm

I tried this :

#include <HC4x4x4Cube.h>


void setup() {
// put your setup code here, to run once://
//*Initialize the cube *//
CubeInit();
}

void loop()
{
// put your main code here, to run repeatedly://
//* 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);
}

but resulted in the led`s remaining unlit for 10 seconds before the final pattern of four per layer lit up and remained on. I have now uploaded the demo HC4x4x4Cube_Animation.ino and all functions as expected. any ideas?

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by andrew » Tue Aug 30, 2016 10:02 am

I've checked the sketch is it is defiantly working as expected. It does imply that something is electrically wrong with your cube but it's odd that the demo animation works fine. A couple of things:

The cube comes pre-programmed with the demo animation. Does it still work fine when you re-flash it back in and does it defiantly go though all the animations? You can check them against the YouTube video.

For the demo sketch you have posted above, what happens if you swap the first pattern with the last? Does it do anything different?
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Mcrampvw
Posts: 1
Joined: Wed Sep 14, 2016 9:30 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by Mcrampvw » Thu Sep 15, 2016 12:11 am

I seem to be having the same problem as above! I have reflashed the demo on and that again works as it should with no problems.

When loading the matrix buffer sketch what ever pattern is at the is at the bottom works as it should after 10 blank seconds and remains on. If i just put one pattern on it works and remains on what ever pattern i try it just seems to not work correctly if i add more than one pattern.

Any ideas what i am doing wrong?

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by andrew » Thu Sep 15, 2016 7:55 am

This is strange, I can't replicate this problem. I've modified the sketch below to swap the first and last patterns and also reduced the delays to 1 second. Can you try it and let me know what happens:

Code: Select all

void setup() 
{
  /* Initialise the cube */
  CubeInit();
}


/* Main sketch */
void loop() 
{

  /* 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 1 seconds */
  delay(1000);
  
  /* Turn on the corner LEDs */
  Matrix_Buffer[3] = 0b1001000000001001;
  Matrix_Buffer[2] = 0b0000000000000000;
  Matrix_Buffer[1] = 0b0000000000000000;
  Matrix_Buffer[0] = 0b1001000000001001;
  
  /* Wait 1 seconds */
  delay(1000);
  
  /* 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 1 second */
  delay(1000);
}
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

tomd
Posts: 2
Joined: Sun Jan 01, 2017 8:27 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by tomd » Sun Jan 01, 2017 10:29 pm

Hi, I'm very pleased with this kit however I'm having issues trying to upload anything to the board. Firstly there was a problem with the prolific drivers which seems to have been solved by using version 3.3.2.102, so the arduino IDE is able to 'see' the device as I understand it, the compiling seems to go okay but then on uploading I get this error message:

Sketch uses 1,124 bytes (3%) of program storage space. Maximum is 30,720 bytes.
Global variables use 19 bytes (0%) of dynamic memory, leaving 2,029 bytes for local variables. Maximum is 2,048 bytes.
avrdude: stk500_getsync() attempt 1 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 2 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 3 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 4 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 5 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 6 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 7 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 8 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 9 of 10: not in sync: resp=0x00
avrdude: stk500_getsync() attempt 10 of 10: not in sync: resp=0x00

I assume this means it cannot communicate with the board. I have tried pressing the reset switch at every stage of the process to no avail. Could you offer any advice for solving this?

Many Thanks

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by andrew » Tue Jan 03, 2017 11:46 am

I assume the cube is running the default demo that's preloaded into the chip ok? If so this helps rule out some possibilities. Assuming it is running the demo there are four things that come to mind:

Firstly under 'Tools' menu in the Arduino IDE do you have 'Arduino Nano' selected as the board type and 'ATMega328' selected as the processor type?

Secondly check that you have the serial cable connected to the cube exactly as follows:

Black......GND
RED........5V
Green......Rx
White......Tx

Thirdly, when you upload the sketch you need to momentarily press the reset button on the cube at the exact moment the IDE changes from saying it's compiling the sketch to uploading it. At first it may take a few goes to get the timing right.

Finally there is not really much to go wrong between the connector and the IC. Have a look around that area for any lose or missing solder joints.
Last edited by andrew on Mon Apr 03, 2017 8:23 pm, edited 1 time in total.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

tomd
Posts: 2
Joined: Sun Jan 01, 2017 8:27 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by tomd » Thu Jan 05, 2017 7:01 pm

Hi Andrew, many thanks for your reply.

Turns out it was connected wrongly (RX and TX were reversed, must have been using an old diagram!). All working fine now :).

T3chn0h1ppy
Posts: 5
Joined: Tue Feb 07, 2017 12:21 am

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by T3chn0h1ppy » Tue Feb 07, 2017 10:20 pm

I've been working on my first sketch and have an issue similar to
Mcrampvw wrote:I seem to be having the same problem as above! I have reflashed the demo on and that again works as it should with no problems.

When loading the matrix buffer sketch what ever pattern is at the is at the bottom works as it should after 10 blank seconds and remains on. If i just put one pattern on it works and remains on what ever pattern i try it just seems to not work correctly if i add more than one pattern.

Any ideas what i am doing wrong?
like he says only the last pattern displays. interestingly, i took the first pattern, copied and pasted it and when I changed a couple of the layers it would switch from the first to the second but not loop them. once I had finished editing the second pattern however, it only displayed the second pattern.

I have uploaded the default pattern a couple of times with a couple of edits of the speed with no issues.

Any thoughts?

Code: Select all

#include <HC4x4x4Cube.h>

void setup() 
{
  /* Initialise the cube */
  CubeInit();
}


/* Main sketch */
void loop() 
{  
  /* tetrahedron 1 */
  Matrix_Buffer[3] = 0b1000010000100001;
  Matrix_Buffer[2] = 0b0100100000010010;
  Matrix_Buffer[1] = 0b0010000110000100;
  Matrix_Buffer[0] = 0b0001001001001000;
  
  /* Wait 1 seconds*/
  delay(500);

    /* tetrahedron 2 */
  Matrix_Buffer[3] = 0b0001001001001000;
  Matrix_Buffer[2] = 0b0010000110000100;
  Matrix_Buffer[1] = 0b0100100000010010;
  Matrix_Buffer[0] = 0b1000010000100001;
  
  /* Wait 1 seconds*/
  delay(500);
}

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: HC4x4x4Cube Arduino library for 4x4x4 LED cubes

Post by andrew » Wed Feb 08, 2017 12:08 pm

@T3chn0h1ppy

I've managed to replicate the problem using your posted sketch but interestingly only when I compile it with one of the latest versions of the Arduino IDE. If I use an older version (1.5.8) your sketch works fine. So something in the newer Arduino IDE has caused the library to break. My initial suspicion (I could be wrong) is that it's something to do with externally accessing the Matrix_Buffer[] array. Maybe whatever has changed is now causing an array overflow. This would explain the random weirdness.

I'll take a look into this to try and find out what exactly is causing the problem but if you need to quickly get your sketch working a temporary workaround would be to download one of the older Arduio IDE's in ZIP (non installer version) format (assuming you are using Windows). You can simply unzip it and run the IDE directly out of the unzipped folder and it shouldn't interfere with your installed version. The download link for older versions is below:

https://www.arduino.cc/en/Main/OldSoftw ... s#previous
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Post Reply

Return to “Arduino”