Reply to topic  [ 1 post ] 
HCWS2812 Library For Serial RGB LEDs 
Author Message
Site Admin

Joined: Sun Aug 05, 2012 4:02 pm
Posts: 647
Post HCWS2812 Library For Serial RGB LEDs
Image


Image

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:
#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:
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)


To set the thirteenth LED to white you would do the following:

Code:
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:
HCWS2812.SetBG(R, G, B);


Sets the default background colour for the LEDs. This will be the colour the LEDs will default to when the RGBBuffer is cleared. Where:

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:
HCWS2812.ClearBuffer(void);

Clears the contents of the RGBBuffer with the background colour set by SetBG();


Code:
HCWS2812.Refresh();

Updates the LEDs by writing the contents of the RGBBuffer to them. Note that interrupts are disabled whilst this command is executed.



Additional commands for creating a message display:

Code:
HCWS2812.SetFontFG(R, G, B);

Sets the foreground colour of text written to the RGB buffer via the print command. Where:

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:
HCWS2812.SetFontBG(R, G, B);

Sets the background colour of text written to the RGBBuffer via the print command. Where:

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:
HCWS2812.print("TEXT STRING", Offset)

Writes a string of text to the RGBBuffer at position starting at Offset. A value of 1 for offset starts the text at column 1, 2 will start the text from column 2 etc. Offset numbers beyond the maximum column number can be set to allow for text to be positioned beyond the ends of the display.


Code:
HCWS2812.print(Value, Offset)

Writes a positive or negative integer to the display. If negative a '-' sign will be appended to the beginning of the number. See above of description of 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.




Image

Code:
/* 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:
/* 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:
/* 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); 
  }
}





Image

The library files can be downloaded from github here:

https://github.com/HobbyComponents/HCWS2812

Or directly from this forum:

Attachment:
HCWS2812.zip


You do not have the required permissions to view the files attached to this post.


Fri Mar 27, 2015 11:18 am
Profile
Display posts from previous:  Sort by  
Reply to topic   [ 1 post ] 

Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Thank you to phpBB.com & phpBB.ro.
Design created by Florea Cosmin Ionut.
© 2011 All contents of this site are © Hobby Components LTD