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 the following development boards:
ATMega328 Arduinos such as the Uno, Nano, 5V Pro Mini
ATMega25060 based Arduinos such as the Mega
ATmega32U4 based Arduinos such as the Leonardo and 5V pro mini.
ESP8266 development boards such as the Lolin D1 min & Hobby Components ESP8266 Development Board
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.
14/07/23 version 1.0: Updated to allow user to specify the output pin
22/02/24 version 2.0: Implemented output code into in-line assembly for 8bit AVR
microcontrollers for better timing.
Removed option for setting output pin via library constructor
as 8bit AVRs are not fast enough to support - Uncomment
#define DOUT_PIN line HCMAX7219.h file and set pin there.
A few considerations when using this library
1) The library defaults to using Arduino pin 3 on AVR based boards and D4 on ESP8266 Lolin boards. If you need to change this open the HCWS2812.h file in a text editor (do not use Windows text pad), uncomment the #define DOUT_PIN 2 line in the user configuration section and then change the number to the pin you require.
2) 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
3) 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.
4) 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
5) 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.
- /* 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 2 (D4 on ESP8266 Lolin based boards) 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);
- }
- }
- /* 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 2 (D4 on ESP8266 Lolin based boards) 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);
- }
- /* 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);
- }
- }
HCWS2812 latest version (V2.0):
HCWS2812 version (V1.0):
Older versions:
Libraries, example code, and diagrams are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no 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.