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: 802
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 TBA]




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 4MHz"
BOD:				"BOD 2.7V"
EEPROM:			"EEPROM Retained"
Complier LTO:		"LTO Disabled"
Variant:			This will depend on version of device shipped with you 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.

Post Reply

Return to “Arduino”