ShiftPWM function reference

On this page you will find all functions that are provided by the ShiftPWM library. ShiftPWM relies on a few constants that should be declared before including ShiftPWM.h. Take a look at the examples that come with ShiftPWM to see how to properly set it up. The 'getting started' info page gives more information about these constants. You will find the rest of the documentation here.


Start (int ledFrequency, unsigned char max_Brightness)

Description

This function sets up and starts the timer interrupt for ShiftPWM. This is the last function that should be called after setting all the parameters. By default it uses timer 1. Timer 1 one is also used by the servo library. ShiftPWM checks for this (#ifndef _useTimer1) and automatically switches to timer2 when servo.h is included before ShiftPWM.h. If you want to force ShiftPWM to use timer 2, without including servo.h include it like this:
#define _useTimer1
#include <ShiftPWM.h>
This function can be called at run time to change the PWM frequency or brightness.

Parameters

int ledFrequency: This is the frequency of the PWM signal in Hz. ShiftPWM tries to approach this value as close as possible.
unsigned char ledBrightness: This is the brightness value that will correspond to fully on. So the number of brightness steps will be maxBrightness + 1.

Syntax

ShiftPWM.Start(pwmFrequency,maxBrightness);


SetAmountOfRegisters (unsigned char newAmount)

Description

This function sets how many 8 bit shift registers are controlled with ShiftPWM. If you are using 4 or 16 bit shift registers, still divide the number of outputs by 8 and round up. This function can be called at run time to change the number of registers on the fly. If the load will become too high, the old value is kept and an error is printed to the serial port.

Parameters

unsigned char newAmount: The new amount of 8 bit shift registers that should be driven.

Syntax

ShiftPWM.SetAmountOfRegisters(numRegisters);


SetPinGrouping (int grouping)

Description

With SetPinGrouping() you can tell ShiftPWM that the pins of your RGB LED's are connected in groups per color. By default, ShiftPWM assumes that RGB LED's are connected RGB RGB RGB... If you set the pin grouping to 4, ShiftPWM will work with RRRR GGGG BBBB RRRR GGGG BBBB... The RGB and HSV functions of ShiftPWM take this grouping into account: setting LED 0 to (255,255,255) will turn on pin 0, 4 and 8 when pin grouping is set to 4.

Parameters

int grouping: the number of pins of the same color that are next to each other.

Syntax

ShiftPWM.SetPinGrouping(4);


PrintInterruptLoad (void)

Description

This function runs the same delay loop twice: once with the interrupt disabled and once with the interrupt enabled. From the time difference it takes for the loop to complete, it computes how much CPU time is spent on ShiftPWM. This fraction is called the interrupt load. This is printed to the serial port together with information about the timer settings and interrupt frequency and duration.

Parameters

None

Syntax

ShiftPWM.printInterruptLoad();


SetOne (int pin, unsigned char value)

Description

This function sets one output the the duty cycle specified by value. If the value exceeds maxBrightness, the output is fully on. Otherwise the duty cycle is value/maxBrightness.

Parameters

int pin: This is the output number of the pin to set. Numbering starts at zero for output 0 of the first shift register. unsigned char value: This is the new duty cycle for the output.

Syntax

ShiftPWM.SetOne(ledNr, value);


SetAll (unsigned char value)

Description

This function sets all outputs to the same duty cycle, specified by value.

Parameters

unsigned char value: This is the new duty cycle for all outputs.

Syntax

ShiftPWM.SetAll(value);


SetRGB (int led, unsigned char r, unsigned char g, unsigned char b, int offset=0)

Description

This function sets one RGB LED to the value specified by r,g and b. The values are automatically scaled to maxBrightness. The default configuration is RGB RGB RGB, with output 0 of the first shift register being red of LED 0. You can change this with SetPinGrouping(). The offset parameter is optional. If you have your RGB LED's connected to groups of 2 shift registers and 5 RGB LED's, with the last pin of each group unused, you can give the second group and offset of 1 and the third group an offset of 2 to account for the gaps in your chain.

Parameters

int led: The LED to change. Numbering starts at zero.
unsigned char r: The value for red, 0-255.
unsigned char g: The value for green, 0-255.
unsigned char b: The value for blue, 0-255.
int offset (optional): All outputs can be shifted with the value provided here. Default is 0.

Syntax

ShiftPWM.SetRGB(lednr, red, green, blue);
ShiftPWM.SetRGB(lednr, red, green, blue, offset);


SetAllRGB (unsigned char r, unsigned char g, unsigned char b)

Description

This function is similar to SetRGB(), but sets all the LED's to the same value. It does not take gaps into account, so if you have gaps in your chain, you will have to use SetRGB() with the offset parameter.

Parameters

unsigned char r: The value for red, 0-255.
unsigned char g: The value for green, 0-255.
unsigned char b: The value for blue, 0-255.

Syntax

ShiftPWM.SetAllRGB(red, green, blue);


SetHSV (int led, unsigned int hue, unsigned int sat, unsigned int val, int offset=0)

Description

This function takes an HSV value and sets one LED to that HSV value. It first converts HSV to RGB and sets the RGB LED to that color. HSV is much more intuitive for color fades, because you can fade one value instead of having to fade 3 simultaneously.

Parameters

int led: The LED to change. Numbering starts at zero.
unsigned int char hue: The value for the hue, 0-360. This is the color.
unsigned int sat: The value for the saturation, 0-255. 0 is white, 255 is full color
unsigned int val: The value for the brightness, 0-255. 0 is off, 255 is fully on.
int offset (optional): All outputs can be shifted with the value provided here. Default is 0.

Syntax

ShiftPWM.SetHSV(lednr, hue, saturation, brightness);
ShiftPWM.SetHSV(lednr, hue, saturation, brightness, offset);


SetAllHSV (unsigned int hue, unsigned int sat, unsigned int val)

Description

This function takes an HSV value and sets all RGB LED's to that HSV value.

Parameters

unsigned int char hue: The value for the hue, 0-360. This is the color.
unsigned int sat: The value for the saturation, 0-255. 0 is white, 255 is full color
unsigned int val: The value for the brightness, 0-255. 0 is off, 255 is fully on.

Syntax

ShiftPWM.SetAllHSV(hue, saturation, brightness);


SetGroupOf2 (int group, unsigned char v0, unsigned char v1, int offset=0)
SetGroupOf3 (int group, unsigned char v0, unsigned char v1, unsigned char v2, int offset=0)
SetGroupOf4 (int group, unsigned char v0, unsigned char v1, unsigned char v2, unsigned char v3, int offset=0)
SetGroupOf5 (int group, unsigned char v0, unsigned char v1, unsigned char v2, unsigned char v3, unsigned char v4, int offset=0)

Description

These functions can set a group of output pins that are next to each other. It is the multiple pin equivalent of SetOne(). If you are using RGB LED's, you are probably better off with SetRGB and SetHSV.

Parameters

int group: The group to change. If you are using SetGroupOf4, the first group will be pin 0-3, the second pin 4-7, etc.
unsigned char v#: The value that the pin should be set to, from 0 to maxBrightness.
int offset (optional): All outputs can be shifted with the value provided here. Default is 0.

Syntax

ShiftPWM.SetGroupOf2(group, value0, value1);
ShiftPWM.SetGroupOf3(group, value0, value1, value2);
ShiftPWM.SetGroupOf4(group, value0, value1, value2, value3);
ShiftPWM.SetGroupOf5(group, value0, value1, value2, value3, value4);
 
ShiftPWM.SetGroupOf2(group, value0, value1, offset);
ShiftPWM.SetGroupOf3(group, value0, value1, value2, offset);
ShiftPWM.SetGroupOf4(group, value0, value1, value2, value3, offset);
ShiftPWM.SetGroupOf5(group, value0, value1, value2, value3, value4, offset);


OneByOneSlow (void)
OneByOneFast (void)

Description

These are test functions that fade in and out each output. Their purpose is only to check your hardware. They just loop over all outputs, fade in, fade out and go to the next output.

Parameters

None.

Syntax

ShiftPWM.OneByOneSlow();
ShiftPWM.OneByOneFast();

31 Comments

  1. I can’t seem to figure out how to replicate the demo functions for rainbow fading on just one LED? Is it possible you could help?

    • Use SetHSV, with saturation on 255, value on 255 and loop the hue from 0 to 359.
      Hue is the color. 0 is red, 120 is green, 240 is blue and 360 is red again.
      Saturation is from grey to full color.
      Value is from off to fully on.

      See http://en.wikipedia.org/wiki/HSL_and_HSV

      Something like this (not tested):

      unsigned int ledNr = 0;
      for(unsigned int hue=0; hue<360; hue++){
          ShiftPWM.SetHSV(ledNr, hue, 255, 255);
          delay(10);
      }
      • Did you remove “ShiftPWM.SetRGB(lednr, red, green, blue);”?
        I get a compile error, and “SetGroupOf3” doesn’t yield the results I expected?

        • On the teensy++, I am getting
          “class CShiftPWM’ has no member named ‘SetRGB'”

          • I got a compile error the first time (couldn’t find Serial?), switched board to teensy, then back to teensy++. Now the ShiftPWM examples compile without errors.

            Can you compile the examples?

          • Ah wait a minute. I know what the problem is. The Teensy installer includes a very old version of ShiftPWM. I have e-mailed Paul about it, but apparently he has not had the time to update it. SetRGB has been added later, so please remove the library directory and get the latest version from GitHub.

        • No? Can you post the compile error?
          SetGroupOf3 doesn’t scale your input to the number of brightness levels. SetRGB takes 0-255 as input and scales it.

          If you are trying to do a color fade, wouldn’t HSV be easier?

          • http://pastebin.com/Cv2GQsC5
            Here is all of my code so far, I have many more modes planned… I just switched from TLC5940, to your library, because your work is absolutely amazing!

        • As I said in my other comment, update to the latest version and you will have no problems. I have e-mailed Paul again to update the teensy installer.

          Also start out with one of the updated examples and continue to write your own code from them.

  2. I am using the version from this site. At the bottom of my code link is all of the compiler errors.

  3. sketch_oct25b.cpp.o: In function `ShiftPWM_handleInterrupt’:
    C:\Users\HTPC\Documents\arduino-1.0.1\libraries\ShiftPWM/ShiftPWM.h:124: undefined reference to `ShiftPWM_balanceLoad’

    deleting, replacing, closing and reopening changed my compiler error to this…

    • Great, it sounds like you do have the newest version now.
      ShiftPWM_balanceLoad was introduced in one of the latest updates. It allows you to distribute the PWM zero crossing moment for each shift register.

      It should be defined in your main file, take a look at one of the examples, like this:

       const bool ShiftPWM_balanceLoad = false;

      Since you wrote your code from an older example, it is missing. So just do the following:
      – Open one of the ShiftPWM examples from the file menu to see that everything is all right now.
      – Update the first few lines that set up ShiftPWM to match one of the examples.

  4. Very nice, thanks for your library, and taking the time to support it!

  5. Hi,

    first of all, thank’s for your library!! It’s really really nice!!

    But I have a question, I have buy this product http://dx.com/p/spi-rgb-5v-4xsmd-5050-led-light-module-for-arduino-white-146940 and I can’t change the hardware.
    The problem is that the function SetAllRGB(r,g,b) is inverted when I try. The R is the B and the B is R… I can chage this paramater in your library whit one parameter? I have created 2 new function that invert this but for HSV it’s more complicated…

    Thank’s for your help!

    Gtkow

    • You can change the functions in CShiftPWM.h and change the order there.
      SetHSV uses SetRGB, so you only have to change lines 119-121 in https://github.com/elcojacobs/ShiftPWM/blob/master/CShiftPWM.cpp
      Just swap r, g and b.

      Btw, is there another shift register on the bottom of that thing? 4xRGB=12 outputs and I only see one shift register.

      • Hi, thank’s for your answer.
        I’ll try today. I have also seen on line 128 and 130 the same code but for the function “SetAllRGB”. I need also swap the variables r and b?

        For your question, there is only one shift register. but the leds are connected two by two. In onther word I can drive only two leds and with this, only 6 output are used. 2xRGb = 6.

        Gtkow

        • Yes, swap them there as well.
          If you have multiple of these modules in series, you can use the offset function arguments to account for the 2 pin gap before the next module.

  6. Hi Eelco,

    nice, library! I had it running on an Leonardo via the Arduino software version 1.0.1. I updated it to version 1.0.2 in order to use it on an Arduino Mirco. But now it gives compile errors at both Leonardo and Micro board….

    Arduino/libraries/ShiftPWM/CShiftPWM.cpp: In member function ‘void CShiftPWM::InitTimer2()’: ->and more….

    any ideas?

    UP

    • Hi,

      This was something that was on my to do list. Finally made some time today and just pushed a big upgrade to support 1.02 and the Atmega32u4 better.
      Download the newest version from GitHub and I think you will be fine.

      Elco

      • Thank you so much! It works. You are quick. What else is on your list 😉

  7. Hi Elco, I’m willing to buy a shiftPWM driver board from your shop. I will use it for my DIY aquarium LED lightning. it’s made by a combination of RGB and white led strips (cut by peaces of 6 leds for optimal lighning). I made an wire diagram from it:

    My question, I will use 18 PWM connections for RGB leds (with RGBRGBRGB layout) and 6 for the White leds. Can I made groups with the SETGROUPOF function for it or do I use SETRGB with an offset?

    • Hi,
      Your image link doesn’t work for me. So I cannot see the order of your LED strips.
      I think you can use the SetRGB and SetHSV functions for the RGB LED strips and SetOne for the white LED’s.
      Elco

      • Hi Eelco, (nice name btw. looks like my name hihi)

        I replaced it on tinypic: http://tinypic.com/r/33w0hzr/6

        The aquarium hood has 6 spots (at 3 bars) for the leds. so I have 10 segments of RGB leds and 14 of white leds. I will made some serial-wire connections between the leds strips for reducing the amount of PWM ports needed. It’s 6xRGB and 6x white on the PWM ports.

        • It’s Elco, I corrected your comment the first time 😉
          I don’t know what you mean by serial wire, but you can just connect multiple led strips in parallel.

          You will not even need the offset functions because your white LED’s are last in the row. Just use ShiftPWM.SetOne(18, brightness).
          I saw that you just ordered. It will ship tomorrow (Monday).

          • Sorry I didn’t write it down right. it’s parallel wired indeed. I just cut the whole strip into 10cm parts so I can make RGB-white-RGB bars for the right photosenthese of my aquarium plants.

            Yes, I just made the order in your small shop 🙂 and I will make a howto/progress blog on my website from the build!

  8. Hi Elco,

    First of all can i say this is a great library! It is awesome for controlling RGB led’s. My question is how could i use it to run RGBW led’s in a RGBWRGBWRGBW config? As i am currently looking at using it to run about 700 leds to backlight a project of mine.

    Thanks in advance,
    Mack

    • I do have a function called SetGroupOf4. It does not automatically scale 0-255 to 0-maxBrightness, like the SetRGB function.
      The SetRGB function is not complicated though, check the source in CShiftPWM.cpp. It might be easier to just add your own function to the library.

  9. Hello Elco,

    thanks for tutorial. Everything works well? No 🙁

    I cant use ShiftPWM.SetPinGrouping(4), i has no influence. I connected the pins:
    ShiftRegister1:0 -> Red
    ShiftRegister1:1 -> Red
    ShiftRegister1:2 -> Red
    ShiftRegister1:3 -> Red
    ShiftRegister1:4 -> Green
    ShiftRegister1:5 -> Green
    ShiftRegister1:6 -> Green
    ShiftRegister1:7 -> Green

    ShiftRegister2:0 -> Blue
    ShiftRegister:1 -> Blue
    ShiftRegister2:2 -> Blue
    ShiftRegister2:3 -> Blue
    ShiftRegister2:4 -> Red
    ShiftRegister2:5 -> Red
    ShiftRegister2:6 -> Red
    ShiftRegister2:7 -> Red

    ShiftRegister3:0 -> Green
    ShiftRegister3:1 -> Green
    ShiftRegister3:2 -> Green
    ShiftRegister3:3 -> Green
    ShiftRegister3:4 -> Blue
    ShiftRegister3:5 -> Blue
    ShiftRegister3:6 -> Blue
    ShiftRegister3:7 -> Blue

    You see, i use 3 Register that are already configured
    int numRegisters = 3;
    int numRGBleds = numRegisters*8/3;

    But when I started for example OneByeOne,

    so the first 4 RGB Leds shine one by one. First round Red, than Green and Blue. After this, die last 4 RGB Leds start shining one bye one. First round Red, ….

    Can you help me?

    • Hi Stefan,
      The OneByOne function is a test function that just goes through all output pins.
      If you use SetRGB the pin grouping is taken into account.
      Elco

  10. Hi Elco,

    thank you for your fast answer. After i postet the reply i saw that rainbow works fine 😉

Leave a Reply

Your email address will not be published. Required fields are marked *