HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

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

HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by admin » Tue Nov 23, 2021 11:56 am

Image




This Arduino library is for the Hobby Components range of 4x4x4 LED cube kits. It can be used to create your own cube animations or to restore the default animation supplied with the kit.

This library is compatible with all versions (V1, V.1 & V2) cube kit. See notes about using this library with various versions of the kit.

To upload sketches to your cube you will also need a USB to serial adaptor. If you do not already have an adapter we currently sell two suitable versions:

https://hobbycomponents.com/usb-interfa ... al-adaptor

https://hobbycomponents.com/usb-interfa ... rt-adapter




STEP 1: Installing the Arduino IDE

To use this library you will need to install the Arduino integrated development environment (IDE) which can be freely downloaded from the software section of the Arduino website here:

https://www.arduino.cc/en/software

Arduino IDE Install instructions are available here:

https://www.arduino.cc/en/Guide




STEP 2: Installing the HC4x4x4 library

Download the HC4x4x4 zip file here:
HC4x4x4.zip

Next open the Arduino IDE and click the Sketch menu option at the top of the IDE window.

In the sketch menu navigate to Include Library->Add .Zip Library

A file navigation window will now open. Navigate to wherever you downloaded the HC4x4x4.zip file , select it and click the open button.

This library should now be automatically added to your Arduino IDE. Alternatively you can just unzip the library into your Arduino library folder usually found in the following location:

On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/


Once the library has been installed you can access the example sketches by clicking the File menu and navigating to Examples->HC4x4x4



STEP 3: Configuring the IDE for your version of cube


Version 2 cube:

Version 2 cubes are supplied pre-flashed with the MiniCore bootloader. You must first add support for this bootloader to your Arduino IDE via the Arduino board manager feature before sketches can be uploaded.

To do this go to the MiniCore github page and follow 'How to install' -> 'Boars manager' section. A direct link to this section is available here:

https://github.com/MCUdude/MiniCore#boa ... stallation

Once you have followed the steps in the link above your Arduino IDE should now have support for the MiniCore bootloader and you can configure the board settings under the 'Tools' menu as follows:


Board:			"ATMega328"
Clock:			"Internal 8MHz"
BOD:				"BOD 2.7V"
EEPROM:			"EEPROM Retained"
Complier LTO:		"LTO Disabled"
Variant:			This will depend on version of device shipped with your kit but is normally "328P / 328PA"
Bootloader:		"Yes (UART0)"
Port:				The COM port of your USB to serial adapter




Version 1 & 1.1 cubes:

Version 1 & 1.1 cubes are currently shipped with the Arduino Nano bootloader installed. To upload sketches configure the board settings under the 'Tools' menu as follows:

Board:			"Arduino Nano"
Processor:			"ATMega328p (old bootloader)"
Port:				The COM port of your USB to serial adapter


Next you will need tell the library what version of cube you have (library defaults to version 2). To do this you will need to open the version.h file in a text editor and uncomment the version of your cube:
  1. /****************************************************************************/
  2. //      UNCOMMENT ONE OF THE FOLLOWING DEPENDING ON YOUR CUBE VERSION
  3. /****************************************************************************/
  4.  
  5. #define CUBE_VERSION_1               //<-- Version 1 & 1.1 Users uncomment this line
  6. //#define CUBE_VERSION_1_NO_XTAL  
  7. //#define CUBE_VERSION_2
  8.  
  9. /****************************************************************************/



Using the library:


To use the library include the HC4x4x4.h header file in your sketch, create an instance of the library, and initialise it in the startup() section of your sketch as follows:

  1. // Step 1: Include the library
  2. #include "HC4x4x4.h"
  3.  
  4. // Step 2: Create an instance of the library
  5. HC4x4x4 HC4x4x4;
  6.  
  7. void setup()
  8. {
  9.   // Step 3: Initialise the library
  10.   HC4x4x4.init();
  11. }
  12.  
  13. void loop()
  14. {
  15. }




HC4x4x4 Library Functions:


HC4x4x4.plot(x, y, z, mode);

Sets the state of one of the cubes LEDS where:

x, y, & z are signed integer values containing the coordinates of the LED.
Valid values are 0 to 3. Note values outside this range are ignored.

mode specifies the state to set the LED to. Valid values for mode are:
ON Turns the LED on
OFF Turns the LED off
INVERT Inverts the current state of the LED

Note if the mode parameter is omitted the LED will be tuned on

Returns: void



HC4x4x4.get(x, y, z);

Gets the current state of the LED where:

x, y, & z are signed integer values containing the coordinates of the LED.

Returns: A boolean value representing the current state of the LED



HC4x4x4.line(x1, y1, z1, x2, y2, z2, mode);

Draws a line of 1 LED thickness in 3d where:

x1, y1, z1 is the x,y,z coordinate of the start of the line
x2, y2, z2 is the x,y,z coordinate of the end of the line

mode specifies the state to set the LED to. Valide values for mode are:
ON Turns the LED on
OFF Turns the LED off
INVERT Inverts the current state of the LED

Note if the mode parameter is omitted the LED will be tuned on

Returns: void



HC4x4x4.printChar(c, col, layer);

Prints an alphanumeric character where:

c is a char variable containing the character to print

col is the column position on the cube from where to start displaying the character from

layer is the z axis layer to print the character on



HC4x4x4.print(*text, col, layer);

Prints a string of text to the cube where:

*text is a pointer to the start of a null terminated character array containing the text

col is the column position on the cube from where to start displaying the text from

layer is the z axis layer to print the text on



HC4x4x4.printScroll(*text, delay, layer);

Automatically scrolls a string of text across the cube where:

*text is a pointer to the start of a null terminated character array containing the text

length is a integer value containing length of the string in bytes

Returns: void



HC4x4x4.cube(x1, y1, z1, x2, y2, z2, solid, mode);

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

solid specifies whether the cube should be drawn solid (filled in) or wire frame */

mode specifies the state to set the LED to. Valid values for mode are:
ON Turns the LED on
OFF Turns the LED off
INVERT Inverts the current state of the LED

Note if the mode parameter is omitted the LED will be tuned on

Returns: void



HC4x4x4.shift(dir);

Shifts the entire grid of LEDs in one direction where:

dir is the direction to shift. Valide values for dir are:
LEFT Shifts all the LEDs +1 position in the x axis
RIGHT Shifts all the LEDs -1 position in the x axis
UP Shifts all the LEDs +1 position in the y axis
DOWN Shifts all the LEDs -1 position in the y axis
FORWARD Shifts all the LEDs +1 position in the z axis
BACKWARD Shifts all the LEDs -1 position in the z axis

Returns: void



HC4x4x4.setDrawDir(dir);

Sets the drawing orientation where:

dir is the required direction. Valid values for dir are
TOP_0
TOP_90
TOP_180
TOP_270
BOTTOM_0
BOTTOM_90
BOTTOM_180
BOTTOM_270
FRONT_0
FRONT_90
FRONT_180
FRONT_270
LEFT_0
LEFT_90
LEFT_180
LEFT_270
BACK_0
BACK_90
BACK_180
BACK_270
RIGHT_0
RIGHT_90
RIGHT_180
RIGHT_270

Returns: void



HC4x4x4.baseLEDs(state);

Turns on or off the base LEDs where:

state is the required state of the LEDs. Valid values for state are
OFF
ON

Returns: void

Note: THIS COMMAND IS NOT SUPPORTED IN V1 & V1.1 CUBES



Example Sketch:
  1. /* FILE:    HC4x4x4_Library_Examples
  2.    DATE:    19/11/21
  3.    VERSION: 1.0
  4.    AUTHOR:  Andrew Davies
  5.    
  6. 19/11/21 version 1.0: Original version
  7. */
  8.  
  9. #include "HC4x4x4.h"
  10.  
  11. // Create an instance of the HC4x4x4 library
  12. HC4x4x4 HC4x4x4;
  13.  
  14. void setup()
  15. {
  16.   // Initialise the library
  17.   HC4x4x4.init();
  18. }
  19.  
  20. void loop()
  21. {
  22.  
  23. /****************************************************************************/
  24. //                            PLOT EXAMPLES
  25. /****************************************************************************/
  26.   // Turn on LED at x,y,z coordinate 0,0,0
  27.   HC4x4x4.plot(0,0,0, ON);
  28.   delay(4000);
  29.  
  30.   // Plot across x axis
  31.   HC4x4x4.plot(1,0,0, ON);
  32.   HC4x4x4.plot(2,0,0, ON);
  33.   HC4x4x4.plot(3,0,0, ON);
  34.   delay(4000);
  35.  
  36.   // Plot across y axis
  37.   HC4x4x4.plot(0,1,0, ON);
  38.   HC4x4x4.plot(0,2,0, ON);
  39.   HC4x4x4.plot(0,3,0, ON);
  40.   delay(4000);
  41.  
  42.   // Plot across z axis
  43.   HC4x4x4.plot(0,0,1, ON);
  44.   HC4x4x4.plot(0,0,2, ON);
  45.   HC4x4x4.plot(0,0,3, ON);
  46.   delay(4000);
  47.  
  48.  
  49.   // Turn off LED at x,y,z coordinate 0,0,0
  50.   HC4x4x4.plot(0,0,0, OFF);
  51.   delay(4000);
  52.  
  53.   // Toggle the state of the LED at 0,0,0
  54.   for(byte i = 0; i < 10; i++)
  55.   {
  56.     HC4x4x4.plot(0,0,0, INVERT);
  57.     delay(500);
  58.   }
  59.  
  60.  
  61. /****************************************************************************/
  62. //                            LINE EXAMPLE
  63. /****************************************************************************/
  64.   // Draw a line
  65.   HC4x4x4.line(0,0,0, 3,3,3, ON);
  66.   delay(4000);
  67.  
  68.  
  69. /****************************************************************************/
  70. //                            CUBE EXAMPLES
  71. /****************************************************************************/
  72.   // Draw a cube with opposite corners at 1,1,1 & 2,2,2, make it solid (true)
  73.   HC4x4x4.cube(1,1,1, 2,2,2, true);
  74.   delay(4000);
  75.  
  76.    // Draw a bigger cube but make it hollow
  77.   HC4x4x4.cube(0,0,0, 3,3,3, false);
  78.   delay(4000);
  79.  
  80.  
  81. /****************************************************************************/
  82. //                            SHIFT EXAMPLE
  83. /****************************************************************************/
  84.   // Shift left
  85.   for(byte i = 0; i < 4; i++)
  86.   {
  87.     HC4x4x4.shift(LEFT);
  88.     delay(1000);
  89.   }
  90. /****************************************************************************/
  91.  
  92.  
  93. /****************************************************************************/
  94. //                            TEXT EXAMPLES
  95. /****************************************************************************/
  96.   // Print an 'A' starting a x axis column 0 and z axis layer 0
  97.   HC4x4x4.print("X", 0, 0);
  98.   delay(4000);
  99.  
  100.   // Print it on the left of the cube
  101.   HC4x4x4.clear();
  102.   HC4x4x4.setDrawDir(LEFT_0);
  103.   HC4x4x4.print("X", 0, 0);
  104.   delay(4000);
  105.  
  106.   // Print it on the right of the cube
  107.   HC4x4x4.clear();
  108.   HC4x4x4.setDrawDir(RIGHT_0);
  109.   HC4x4x4.print("X", 0, 0);
  110.   delay(4000);
  111.  
  112.   // Print it on the right of the cube
  113.   HC4x4x4.clear();
  114.   HC4x4x4.setDrawDir(TOP_0);
  115.   HC4x4x4.print("X", 0, 0);
  116.   delay(4000);
  117.  
  118.   // Turn off all LEDs and put the reference back to the bottom left corner
  119.   HC4x4x4.clear();
  120.   HC4x4x4.setDrawDir(FRONT_0);
  121.  
  122.   // Scroll some text with a 200ms delay on z axis layer 0
  123.   HC4x4x4.printScroll("Hello World!", 200, 0);
  124.   delay(4000);
  125.  /****************************************************************************/
  126. }


Disclaimer: Libraries, example code, and diagrams within this forum thread are provided as an additional free service by Hobby Components and are not sold as part of any product. We do not provide any guarantees or warranties as to their accuracy or fitness for purpose.

Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.
You do not have the required permissions to view the files attached to this post.

jcampbel2
Posts: 3
Joined: Sun Jul 10, 2022 2:59 pm

Re: HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by jcampbel2 » Mon Dec 19, 2022 12:07 pm

I have a 4x4x4 cube (the version 2 i'm assuming, the 2 chips are inline, not side by side) and I have a DTR pin on board if that helps. Cube works fine and seems to go throught the preload program fine but now trying to reprogram it using this post

But I can't upload anything to the chip through the Ardunio IDE . Everytime I try to upload anything I get the error

avrdude: stk500_getsync() attempt 1 of 10: not in sync: resp=0x00

have tried
2 different USB to serial boards (bought one direct from hobbycomponents in end).
Upgraded the Arduino IDE to latest version,
tried any number of combos between TxD/RxD/DTR
gone through the different vaiants (eg 328P/328PB etc)

have checked a text upload to a vanila UNOR3 and its fine.

Any ideas welcome.

As alternative, Is it possible to swap the chip onto my UNO R3 board and download the code that way?

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

Re: HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by andrew » Mon Dec 19, 2022 4:50 pm

I have a 4x4x4 cube (the version 2 i'm assuming, the 2 chips are inline, not side by side)
Yes that sounds like you have the V2 kit

But I can't upload anything to the chip through the Ardunio IDE . Everytime I try to upload anything I get the error

avrdude: stk500_getsync() attempt 1 of 10: not in sync: resp=0x00

That error is just a generic ‘I can’t talk to the device for some reason’ error which could be for a number of reasons. First thing is to confirm that you have connected your USB adapter to the cube correctly…

Can you confirm that you have it connected as follows:

ADAPTER…............….CUBE
GND……….…............….GND
5V(or VBUS)..........5V
RX……………..............…..TX
TX……………..............……RX
DTR………..............………DTR

Note that Tx connects to Rx and vice versa


If you have it connected as above and it still doesn’t program then the next thing I need to confirm is that you have installed the minicore board files into the Arduino IDE as per STEP 3 in the first post of this thread? If you have any issues doing this just let me know.


As alternative, Is it possible to swap the chip onto my UNO R3 board and download the code that way?


This should be possible but the cube uses a different bootloader to the UNO so you’d still have to add mincore support to your Arduino IDE anyway. It would help rule out a physical connection problem between the serial header pins and the IC socket but I think you’d be better off trying to get it to program via the cube first.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

jcampbel2
Posts: 3
Joined: Sun Jul 10, 2022 2:59 pm

Re: HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by jcampbel2 » Mon Dec 19, 2022 5:39 pm

Thanks for answer Andrew
I have checked wiring and there is a RX/TX crossover (tried both ways around tbh as wasnt sure).

Download the minicore as advised on this forum (reinstalled today after upgrading the Arduino IDE to 2.0.3)
Am using these settings
board: ATmega328
BOD 2.7V
Bootloader UART0 (also tried UART1)
Clock Internal 4MHz
EEPROM retained
LTO disabled
variant : tried all 3

What I do notice is that when it tries to download it seems to reset the chip as the preloaded displat program immediately restarts so guess something is getting through? Should I also have the separate power cable in?
Addition- tried with separate powercable in but still resets itself. Seems to be at start of download attempt (just after successful compile message on IDE console)

jcampbel2
Posts: 3
Joined: Sun Jul 10, 2022 2:59 pm

Re: HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by jcampbel2 » Mon Dec 19, 2022 6:27 pm

Hi Andrew
I think I just got it to work!

Changed the clock speed to 8MHz internal and it then gave me this warning regards chip type

avrdude: Expected signature for ATmega328P is 1E 95 0F
Double check chip, or use -F to override this check.
Failed uploading: uploading error: exit status 1

swapped variant to 328A and seems to work :)

Would this make sense? Assuming it has its own clock, could that variant be 8Mhz rather than 4Mhz??

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

Re: HC4x4xx4 Version 2 Library for 4x4x4 LED Cube kits

Post by andrew » Tue Dec 20, 2022 3:13 pm

Hi Andrew
I think I just got it to work!

Changed the clock speed to 8MHz internal
My apologies, the setting for the clock speed in the first post is incorrect. The bootloader was originally 4MHz but it got updated to 8MHz so it's out of date. I'll get that updated shortly.

As for the variant, currently that could be any of the 3 options as due to the current chip shortages it's dependant on what variant we can source.

Glad you got it working anyway.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Post Reply

Return to “Arduino”