This Arduino library is designed to work with WS2812 based serial RGB LED's such as our 8x serial RGB LED strip (HCMODU0075) or our Flexable RGB LED strips.
Additionally this library includes the ability to create full colour message displays by arranging the LEDs into multiple columns of 8 and with used of the built-in print functions you can easily display or scroll alphanumeric text.
The library currently supports ATMega328 Arduinos such as the Uno, Nano, 5V Pro Mini, ATMega25060 based Arduinos such as the Mega, and ATmega32U4 based Arduinos such as the Leonardo and 5V pro mini.
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/
or similarly for Linux.
Change log:
11/03/15 version 0.1: Original version
13/04/15 version 0.2: Updated timings to work with 1.x.x versions of Arduino IDE
30/11/16 version 0.3: Updated to support ESP8266
Text font moved to program memory to save ram.
A few considerations when using this library
1) Before using the library to save memory and processor cycles, you should edit the following lines in the HCWS2812.h header file found within the library folder:
#define NUMBEROFLEDS 200
2) By default this is set to 200. Change this to match the number of LED's you intend to drive. If you are a going using the print functions to drive an message display then you should make sure this number is a multiple of 8 otherwise your sketch will not work.
3) If you just want to drive a strip or LED's and don't need the print functions you can save some program memeort by commenting out the following line in the HCWS2812.h header file:
#define DOTMATRIX
Change to this:
//#define DOTMATRIX
4) Timing constraints for writing to the LEDs is very strict and so to ensure correct timing interrupts are disabled whilst the LEDs are being written to. Therefor anything relaying on interrupts will not work correctly whilst the Refresh function is executed.
Using the library
To use the library just include the HCWS2812.h header file and create an instance of the library. E.g:
Code: Select all
#include <HCWS2812.h>
HCWS2812 HCWS2812;The library will create an array called RGBBuffer[RED/GREEN/BLUE][INTENSITY] which stores the brightness settings (0 to 255) for each red, green, and blue element of each LED. Issuing a refresh command will write the contents of this buffer to the LEDs. So for example if you wish to set the first LED in the chain to red you would do the following:
Code: Select all
RGBBuffer[RED][0] = 255; // Sets first LEDs red element to maximum brightness (255)
RGBBuffer[GREEN][0] = 0; // Sets first LEDs green element to minimum brightness (0)
RGBBuffer[BLUE][0] = 0; // Sets first LEDs blue element to minimum brightness (0)Code: Select all
RGBBuffer[RED][12] = 255; // Sets first LEDs red element to maximum brightness (255)
RGBBuffer[GREEN][12] = 255; // Sets first LEDs green element to maximum brightness (255)
RGBBuffer[BLUE][12] = 255; // Sets first LEDs blue element to maximum brightness (255)The following functions are available with this library:
Code: Select all
HCWS2812.SetBG(R, G, B);R sets the intensity of the RED element. Valid values are between 0 (off) and 255 (maximum).
G sets the intensity of the GREEN element. Valid values are between 0 (off) and 255 (maximum).
B sets the intensity of the BLUE element. Valid values are between 0 (off) and 255 (maximum).
Code: Select all
HCWS2812.ClearBuffer(void);Code: Select all
HCWS2812.Refresh();Additional commands for creating a message display:
Code: Select all
HCWS2812.SetFontFG(R, G, B);R sets the intensity of the RED element. Valid values are between 0 (off) and 255 (maximum).
G sets the intensity of the GREEN element. Valid values are between 0 (off) and 255 (maximum).
B sets the intensity of the BLUE element. Valid values are between 0 (off) and 255 (maximum).
Code: Select all
HCWS2812.SetFontBG(R, G, B);R sets the intensity of the RED element. Valid values are between 0 (off) and 255 (maximum).
G sets the intensity of the GREEN element. Valid values are between 0 (off) and 255 (maximum).
B sets the intensity of the BLUE element. Valid values are between 0 (off) and 255 (maximum).
Code: Select all
HCWS2812.print("TEXT STRING", Offset)Code: Select all
HCWS2812.print(Value, Offset)HCWS2812.print(Value, Decimal_Position, Offset)
Writes a positive or negative integer to the display. If negative a '-' sign will be appended to the beginning of the number.
Decimal_Position allows the option to specify the position of a decimal point.
See above of description of Offset.
Code: Select all
/* FILE: HCWS2812_Cylon_Example
DATE: 26/03/15
VERSION: 0.1
AUTHOR: Andrew Davies
11/03/15 version 0.1: Original version
This is an example of how to use the HCMAX7219 library to control one or more
RGB LEDS. The example will set each LED to a random colour.
To use this example connect one or more LEDs in series (Dout --> Din) and connect
the first LED's Din pin to digital pin 8 of your Arduino.
By default the library is set to control 100 LEDs. You can change this by editing the
following line in the MCMAX7219.h header file:
#define NUMBEROFLEDS 200 <--- Change this number to match the number of LEDS connected
You can download the library from the software section of our support forum here:
http://forum.hobbycomponents.com/viewforum.php?f=58
Or from Github here:
https://github.com/HobbyComponents/HCWS2812
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 HCWS2812 library */
#include "HCWS2812.h"
/* Create an instance of the library */
HCWS2812 HCWS2812;
void setup()
{
/* Set the R,G,B background colours to zero */
HCWS2812.SetBG(0, 0, 0);
/* Clear the output buffer */
HCWS2812.ClearBuffer();
}
/* Main program */
void loop()
{
int index;
/* Step forward through each LED */
for(index = 0; index < NUMBEROFLEDS; index++)
{
HCWS2812.ClearBuffer();
RGBBuffer[RED][index] = 255;
HCWS2812.Refresh();
delay(100);
}
/* Step backward through each LED */
for(index = NUMBEROFLEDS; index; index--)
{
HCWS2812.ClearBuffer();
RGBBuffer[RED][index - 1] = 255;
HCWS2812.Refresh();
delay(100);
}
}
Code: Select all
/* FILE: HCWS2812_Random_Example
DATE: 26/03/15
VERSION: 0.1
AUTHOR: Andrew Davies
11/03/15 version 0.1: Original version
This is an example of how to use the HCMAX7219 library to control one or more
RGB LEDS. The example will set each LED to a random colour.
To use this example connect one or more LEDs in series (Dout --> Din) and connect
the first LED's Din pin to digital pin 8 of your Arduino.
By default the library is set to control 100 LEDs. You can change this by editing the
following line in the MCMAX7219.h header file:
#define NUMBEROFLEDS 200 <--- Change this number to match the number of LEDS connected
You can download the library from the software section of our support forum here:
http://forum.hobbycomponents.com/viewforum.php?f=58
Or from Github here:
https://github.com/HobbyComponents/HCWS2812
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 HCWS2812 library */
#include "HCWS2812.h"
/* Create an instance of the library */
HCWS2812 HCWS2812;
void setup()
{
/* Set the R,G,B background colours to zero */
HCWS2812.SetBG(0, 0, 0);
/* Clear the output buffer */
HCWS2812.ClearBuffer();
}
void loop()
{
int index;
/* Fill the output buffer with random colours */
for(index = 0; index < NUMBEROFLEDS; index++)
{
RGBBuffer[RED][index] = random(0,255);
RGBBuffer[GREEN][index] = random(0,255);
RGBBuffer[BLUE][index] = random(0,255);
}
/* Send the output buffer to the LEDs */
HCWS2812.Refresh();
/* Wait a moment before doing it again */
delay(100);
}
Code: Select all
/* FILE: HCWS2812_Message_Display_Example
DATE: 26/03/15
VERSION: 0.1
AUTHOR: Andrew Davies
11/03/15 version 0.1: Original version
This is an example of how to use the HCMAX7219 library to create a message display.
To use this example you will need to connect the LEDs in series (Dout --> Din) and
arrange them in columns of 8 to create your LED array. Connect the Din of the first
LED to digital pin of your Arduino.
You can create as many columns of 8 LEDs as you like but you will need to edit the
following line in the HCWS2812.h header file:
#define NUMBEROFLEDS 200 <--- Change this number to match the number of LEDS connected
This value must be an multiple of 8 otherwise the print functions will not work
You can download the library from the software section of our support forum here:
http://forum.hobbycomponents.com/viewforum.php?f=58
Or from Github here:
https://github.com/HobbyComponents/HCWS2812
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 HCWS2812 library */
#include "HCWS2812.h"
/* Create an instance of the library */
HCWS2812 HCWS2812;
void setup()
{
Serial.begin(9600);
/* Set the fonts R G B colour to white */
HCWS2812.SetFontFG(100, 100, 100);
/* Set the fonts R G B background colour to light red */
HCWS2812.SetBG(20, 0, 0);
}
/* Main program */
void loop()
{
byte index;
/* Scroll some text with random background colours */
for(index = 0; index < 160; index++)
{
/* Clear the output buffer */
HCWS2812.ClearBuffer();
/* Change the fonts background colour every 16 steps */
if (index % 16 == 0)
HCWS2812.SetFontBG(random(0,20), random(0,20), random(0,20));
/* Print some text to the output buffer */
HCWS2812.print("HOBBY COMPONENTS", index);
/* Send the contents of the output buffer to the LEDs */
HCWS2812.Refresh();
/* Wait a little before moving the text to the next position */
delay(80);
}
HCWS2812.ClearBuffer();
/* Set the fonts background colour to light green */
HCWS2812.SetFontBG(0, 20, 0);
/* Scroll an integer number */
for(index = 0; index < 64; index++)
{
HCWS2812.ClearBuffer();
HCWS2812.print(-1234, index);
HCWS2812.Refresh();
delay(80);
}
HCWS2812.ClearBuffer();
/* Set the fonts background colour to light green */
HCWS2812.SetFontBG(0, 20, 0);
/* Scroll an integer number with a decimal point
(notice a leading zero is added) */
for(index = 0; index < 80; index++)
{
HCWS2812.ClearBuffer();
HCWS2812.print(-1234, 4, index);
HCWS2812.Refresh();
delay(80);
}
}
The library files can be downloaded from github here:
https://github.com/HobbyComponents/HCWS2812
Or directly from this forum:
