Pulse a LED

Skill Level: Beginner

by MikeGrusin October 31, 2011 | 18 comments

Anyone can blink a LED,

but you'll really impress your friends* if you can pulse a LED!

There are numerous ways you could go about this: use separate "for" loops to ramp the brightness up and down, retrieve values from a look-up table, etc. It turns out there's an easy and effective way to do this using trigonometry. If you don't know what that means, or DO know and are scared, don't worry - it's very simple. I used this technique on the Elevator TARDIS to generate the pulsing blue light on top of Doctor Who's time machine, but it's also great for warning lights, art projects, and just plain looking cool.

Instead of boring you with theory, let's jump right in with an example. Copy and paste this into the Arduino of your choice, and hook up a LED and resistor to pin 11: (This example requires a pin capable of PWM, hence pin 11)

const int LED = 11;

void setup()
{
}

void loop()
{
  float in, out;
  
  for (in = 0; in < 6.283; in = in + 0.001)
  {
    out = sin(in) * 127.5 + 127.5;
    analogWrite(LED,out);
  }
}

That's pretty neat! But that code's pretty weird... what's going on here?

Waves 101

If you ever had a trigonometry class, you probably learned (and may have forgotten) about the sine function. (If you haven't taken trigonometry yet, you'll be able to impress your teacher with this information).

Sine is a function (you put a number in, you get a number out) that generates sine waves. Sine waves appear in nature all the time (ocean waves, audio waves, radio waves, pendulum motion), and because they vary smoothly over time (and are easy to make, as we'll see below), we'll borrow them to make our LED vary smoothly between on and off.

In the Arduino, the sine function is named sin(). It takes a floating-point value (known as a "float") as an input and returns a float as an output. Unlike integers (whole numbers), which you use for most things, floating-point values give you the ability to use decimal points (such as 3.14159). The most basic equation for sin() is:

out = sin(in)

For reasons that we'll gloss over for the moment (see Wikipedia if you're curious), the input number is actually an angle. When you vary this angle from 0 to 360 degrees (all the way around a circle), the wave will complete one full circuit. If you step through a bunch of angles and graph the output of sin(), you'll get a sine wave:

In this graph, the numbers you put into the function are along the bottom, and the number the function returns are on the left. For example, if you put in 90 degrees, you'll get back 1.0. By stepping through the intermediate values between 0 and 360, you can generate a nice smooth wave.

Rule #1

Now's a good time to learn rule #1: sin() doesn't want the angle in degrees, it wants it in radians. Radians are angles based on pi. When you start from an angle of 0, halfway around a circle (180 degrees) is pi radians (3.141), and all the way around a circle (360 degrees) is 2 * pi radians (6.283). (If this sounds familiar, it is related to the circumference of a circle being 2 * pi * the radius. More at Wikipedia). So, to put angles into sin(), use numbers between 0 and 2 * pi like this:

This explains the weird numbers in the "for" loop in the above code:

for (in = 0; in < 6.283; in = in + 0.001)

What we're doing is stepping along the wave, with input values from 0 to 6.283 (2 * pi).  We're stepping by 0.001 so we get a lot of intermediate points which makes a very smooth curve, and incidentally slowing the computer down so the pulse isn't too fast. (More on modifying the speed in "Tips" below).

Home on the range

Next let's look at the output. The sine function will always return a floating-point number that ranges from -1 to +1. You can see this in the above graphs (look at the output numbers on the left side). This is a slight problem for us, since we want to use the analogWrite() function to drive the LED at various brightnesses; analogWrite() takes a value from 0 to 255, not -1 to +1.

To solve this problem, we'll add a bit more math to our equation:

out = sin(in) * range + offset

This will multiply and shift the -1 to +1 output to anything we want!

Here's a shortcut when picking range and offset: if you're trying to get to a number that ranges from 0 to n, use 1/2 n for both the range and offset. For example, we want our wave to range from 0 to 255 for analogWrite(), so we'll use 127.5 for both our range and offset (127.5 = 255 / 2). Multiplying -1 to +1 by 127.5 gives us a range from -127.5 to +127.5. (Multiplication always happens before addition when the computer is processing an equation.) Then when we add in the offset of 127.5, we get a range from 0 to 255!  This explains the other line of code:

out = sin(in) * 127.5 + 127.5;

Which gives us our final input-to-output graph:

Now when you step the input from 0 to 6.283, the output will vary from 0 to 255. Pretty neat, huh! Just pipe this into analogWrite(), and your LED will pulse away.

Tips

Varying the speed

The speed at which the LED pulses is controlled by the amount of time it takes you to step through a whole waveform (from 0 to 2 * pi).

We're stepping by 0.001 in the above code. Try changing that to 0.0001. The LED will pulse 10 times slower. Try changing it to 0.01. The LED will pulse 10 times faster. Often, you can find a pleasing value by modifying this number a few times until it's where you want it.

If you want (or need) greater control, you can add a precise time delay and be more formal about the values in the loop. For example, let's say you want to pulse your LED once per second. First, we want to decide how many samples we want to take of the waveform. Let's say 1000, which will make it easy to use a 1ms delay between samples. Next we'll divide 6.283 by 1000 to find our step size, which is 0.00628. Putting this value into the loop and adding the 1ms delay, we get this:

void loop()
{
  float in, out;
  
  for (in = 0; in < 6.283; in = in + 0.00628)
  {
    out = sin(in) * 127.5 + 127.5;
    analogWrite(LED,out);
    delay(1);
  }
}

This code pulses the LED exactly once per second by taking 1000 samples, and waiting 1ms between each one. You can easily change this to any speed you wish.

Starting from 0 brightness

If you start with an input angle of 0 as the above code does, you can see from the above graphs that the output will start with a value of 127.5, or 50% brightness. This may not look great if you want your LED to start pulsing from 0% brightness. Here's a way to fix that:

First, instead of starting from 0, we'll start from the point on the wave where we'll get an output of 0. From the above graph, we can see that the output value of 0 (on the left-hand side), corresponds with an input value of 4.712 (on the bottom edge). So, if we start our for loop from 4.712, we'll begin with an output of 0. Great - but if we just go from 4.712 to 6.283 and start over again, we won't be getting the whole wave, just the last quarter, which may look cool (try it!), but isn't what we're looking for.

Here's a trick. The sine wave actually repeats forever even after 6.283. In theory, you could keep increasing the angle to infinity and keep getting a sine wave back (though in practice you'll eventually run out of precision on the floating-point variable). So all we need to do is change the start and stop points of the "for" loop.

We've already got the new starting point, 4.712. To find our new end point, we'll add 2 * pi (the length of one wave) to 4.712. By adding one wavelength to any output value, we'll end up back there again when the wave has finished, or in other words, a full wavelength starts and stops at the same output value. Our new stopping point is 10.995 (4.712 + 6.283). Replace the "for" loop in the above example with the one below, and see what it does (you can hit the reset button on the Arduino whenever you want to restart the code and see that it really does start at zero brightness):

for (in = 4.712; in < 10.995; in = in + 0.001)

Now we're starting at 4.712, and tracing an entire wave from there (output = 0) to 10.995 (output = 0). The LED now nicely starts at 0% brightness!

Doing other things while pulsing a LED

The above code shows how to pulse a LED in a "for" loop. But sometimes you might want to do other things such as wait for input, sound an alarm, etc. while pulsing the LED. One way to do this is to break the for loop apart and to rely on the main loop() function to keep running your code:

void loop()
{
  static float in = 4.712;
  float out;
 
 // do input, etc. here - as long as you don't pause, the LED will keep pulsing
  
  in = in + 0.001;
  if (in > 10.995)
    in = 4.712;
  out = sin(in) * 127.5 + 127.5;
  analogWrite(LED,out);
}

As long as your other code doesn't pause and prevent the LED code from running, the LED will keep pulsing. (This is a great way to simulate "multitasking" on a small computer).

One thing to notice is the "static" modifier in the above declaration of "in". If we didn't use this, "in" would be initialized to 4.712 each time loop() loops, which would keep the LED output permanently at 0. By adding this modifier, you're telling the compiler to not keep initializing that variable every time we go through the loop.

Have fun!

We hope that this tutorial adds to your toolkit for making better looking Arduino programs. Let us know if you have any questions or comments, and we always love to hear about your projects!

-Your friends at SparkFun

* This statement strongly depends on the exact friends involved. But if your friends are anything like us, they'll definitely be impressed!