Getting Started with Digital Outputs: Lighting LEDs

A typical use for output pins is to control an indicator such as an LED or light bulb, or some actuator or motor. Usually an electronic circuit is needed to transform the Raspberry Pi output into something that will control the desired device. For a small LED all that is needed is a series resistor; its purpose is to reduce the current that will flow through the LED in order to protect both the LED and the Raspberry Pi. Not a lot of current can be supplied by the output pins, and LEDs will be damaged by too high current. Furthermore LEDs are non-linear and will not light at all if too low a voltage is applied across them. Small LEDs (particularly red, yellow and green ones) will work fine with the Raspberry Pi outputs provided a resistor is attached in series. The exact resistance doesn’t matter; anything between 100 ohms and 1kohm should allow for sufficient output brightness when the output is set to logic ‘1’.

As a quick exercise the photo here (click on it to zoom in) shows the Raspberry Pi connected up to an LED using jumper wiresjumper wires. To prevent accidental shorts and for convenience the Raspberry Pi was bolted onto a piece of wood (2mm or 2.5mm diameter bolts; 3mm will not fit) and a bread board glued next to it.

A bread board, a single resistor and an LED were connected up to the Raspberry Pi. The GND (also known as 0V) connection was taken from pin 6 on the Raspberry Pi header, and the GPIO pin used was GPIO22 (see the diagram earlier) which is pin 15. Any GPIO pin could be used; they are marked in pink on the earlier diagram. Another way of representing this is shown in the schematic below.

Once you’ve connected up the LED, a program or script can be written to control it. The choice of language is up to you. One (popular) example is Python; here is some code that will light up the LED.

# Connect LED to GPIO22 (pin 15)
import time
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(22, GPIO.OUT)
GPIO.output(22, True)
time.sleep(3)
GPIO.cleanup()

     

Save the code to a file called led-test.py and then to run it, type

sudo python led-test.py

Here is another example in Python. It flashes the LED 10 times (Note: if you're new to Python, unlike other programming languages the line indentations in the code are important):

# connect LED to GPIO22 (pin 15)
import time
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
for x in range(0,10):
  GPIO.setup(22, GPIO.OUT)
  GPIO.output(22, True)
  time.sleep(0.05)
  GPIO.output(22, False)
  time.sleep(0.45)

GPIO.cleanup()
     

Another way to control the output pins is to use a shell script. This appears slightly more complex (unless you enjoy writing shell scripts) but is a good thing just for reference because often other programming languages allow you to run shell scripts, and therefore if needed this can be a quick approach to using GPIO with other languages. Furthermore the method described here is standard across different platforms so your code can be ported to boards other than the Raspberry Pi too. If you're a beginner to programming, stick with Python for now and move on to the next example; shell scripts can be revisited at a much later stage.

#!/bin/sh
GPIO_PATH=/sys/class/gpio
LED_PIN=22 #GPIO 22 is pin 15
echo "$LED_PIN" > $GPIO_PATH/export
echo "out" > $GPIO_PATH/gpio$LED_PIN/direction
echo "1" > $GPIO_PATH/gpio$LED_PIN/value
sleep 1
echo "$LED_PIN" > $GPIO_PATH/unexport
     

The first line of the shell script looks like a comment line, but is needed to make it easy for the Linux shell to know what to do with the script upon execution, so don’t modify that. The remainder script lines are used to take control of a GPIO pin, set it to become an output, set it to a logic high value, and then wait for 1 second. Finally control of the GPIO pin is released so other programs can make use of it if desired.

Another programming language that may be encountered is C or its (far) bigger brother C++. An example using C or C++ is given further below in the ‘Voltmeter’ section where the code is used for input from a circuit, and output to an LED.

Another Output Example: Tone Generator

A more interesting example than an LED is to use a couple of GPIO pins to control a tone generator circuit. The Raspberry Pi has a headphone connector for audio but sometimes just a simple tone or alarm is needed to signal events (such as for an alarm clock project).

The photo below shows a very simple single integrated circuit (IC) project that can generate various sounds. By adjusting resistor and capacitor values, different tones and sounds could be created.

The circuit connects to two outputs from the Raspberry Pi. One output is used to switch the tone on or off, and the other is used to alternate between two tones. One of the capacitors in the circuit is used to create a sweeping tone transition when tones are alternated. The circuit diagram is shown below; it uses an ICM7555 timer integrated circuitICM7555 timer integrated circuit. GPIO22 was used to switch the tone on and off, and GPIO27 modifies the tone. C1, R1 and R2 can be adjusted to select the desired tones.

The Python code below plays some alarm tone effects. To use the code, save the code to a file called tone-test.py and then type

sudo python tone-test.py

import time
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(22, GPIO.OUT)  # TONE_ENABLE
GPIO.setup(27, GPIO.OUT)  # TONE_CHANGE


GPIO.output(22, True)
for x in range(0,5):
  GPIO.output(27, True)
  time.sleep(0.1)
  GPIO.output(27, False)
  time.sleep(0.2)
GPIO.output(22, False)
time.sleep(0.5)


for x in range(0,5):
  GPIO.output(22, True)
  time.sleep(0.1)
  GPIO.output(22, False)
  time.sleep(0.2)
GPIO.output(27, True)
time.sleep(0.2)


for x in range(0,5):
  GPIO.output(22, True)
  time.sleep(0.05)
  GPIO.output(22, False)
  time.sleep(0.05)


for x in range(0,10):
  GPIO.output(22, True)
  time.sleep(0.1)
  GPIO.output(22, False)
  time.sleep(0.1)
time.sleep(1)


GPIO.cleanup()
     

Note that the circuit uses the 3.3V supply (pin 1) available from the Raspberry Pi. Only use this supply if you know your circuit doesn’t consume much power. More than a few tens of milliamps of current consumption would require your own external power supply. Another approach would be to build a 5V to 3.3V regulator circuit and connect it to the 5V supply available on pin 2 from the Raspberry Pi.

Output Design Tips

All the circuits described so far have involved low current and low voltage but sometimes higher power devices need to be controlled or monitored. There are some typical methods to achieve this, and they are described here.

Connecting to 5V Logic

When the Raspberry Pi is used to output a signal to 5V devices, usually (not always) no additional circuit is needed; many 5V logic device inputs will function just fine with the 3.3V logic output signals from the Raspberry Pi. You can confirm by checking the datasheet for the 5V device.

Low Power, Low Voltage LEDs (red, yellow, green)

A single LED can be controlled using a series resistor between around 100 ohms and 1kohm. No other considerations are required.

Any Color Low Power LED

Blue and white LEDs may require a voltage higher than 3.3V. The easiest way to control a single LED is to use a transistor circuit to switch the 5V supply rail. The value of R1 should be increased if using an LED of any color other than blue or white. In general consult the LED data sheet. Any NPN transistor should work for this circuit.

Higher Power AC or DC Devices (but not mains!)

A relay is useful for this scenario. Virtually any NPN transistor can be used. Popular devices include BC547BBC547B, 2N39042N3904 and BC549BC549. If the connected device can function from 5V DC then the Raspberry Pi's 5V connection on pin 2 of the 40-pin header could be connected to the relay switch as long as the required current is not too high (use 100mA as a very conservative guideline) otherwise the relay switch can be connected to an external supply (take care it doesn't accidentally short to the 5V supply or any other connection on the Raspberry Pi - keep it totally isolated). Check the relay datasheet to confirm that it is suitable for your needs.

A small relay with pins convenient for breadboard layout is Finder 32.21.7.005.200032.21.7.005.2000 and it can switch up to 6A. Note that just because a relay is rated for (say) 250V does not mean it can be used for this. Breadboards and stripboards are designed for far lower voltages. Even with a custom PCB the project should not be used at mains voltages because there are legal requirements for conductor spacing, temperature, types of enclosure material, connection type, conductor clamping method and so on. It is easy to create a product that will fail and cause personal injury or an electrical fire or harm others at some point in time.

Mains Powered Devices

Treat any circuit or product that directly controls mains devices from a Raspberry Pi with extreme suspicion. Most do not meet safety standards (even though some firms self-certify that they do meet safety standards when clearly their products do not). Instead, a reasonably safe method is to find a reputable remote control product from a reputable manufacturer and a reputable supplier that uses infra-red or wireless (radio) technology to control the mains device. In the UK, the Energenie RF controlled mains socketsEnergenie RF controlled mains sockets appear suitable and they provide a small radio transmitter board that directly plugs onto the Raspberry Pi 40-pin connector and they also supply example Python code for it. For an examination of the hardware and software click to see Energenie Experiments - Remote Power Control for the Home.

Some products for non-UK regions are mentioned at that link too.

Multiple Relays, LEDs or Devices that require less than 200mA Current at 12V

The ancient (>25 years in production!) yet useful ULN2803AULN2803A integrated circuit can be employed for this scenario. Several hundred milliamps can be supplied by each output pin (there are 8 of them).

Driving small DC Motors (the most common motors, also known as ‘Brushed DC’ Motors) and Stepper Motors

For small motors consider the Gertbot motor control boardGertbot motor control board. It can drive several brushed DC motors if needed, and can also be used for stepper motors.

Driving Brushed DC Motors (Medium to High Power) in either Direction

Use the  Infineon Motor Control board  Infineon Motor Control board. It can control one motor in both directions, or two motors in one direction. If more motors are needed, add more of the boards.

Push Button Switch Input

The connections on the Raspberry Pi can be converted into inputs under software control. The example here is about the simplest; a push button switch is wired up to the 40-pin connector:

The circuit diagram is shown below. Note that the LED circuit from the exercises before is still left wired up but is not shown in the diagram below.

As can be seen from the circuit diagram, when the switch is not pressed the input pin is connected to +3.3V through a resistor. The input pin has a high resistance inside the Raspberry Pi, and so the voltage at the input pin is close to the 3.3V that the resistor is connected to. This means that the Raspberry Pi will detect a logic ‘1’ condition when the switch is not pressed.

When the switch is pressed, there is a direct path between the input pin and 0V and so the voltage at the input pin becomes 0V which is a logic ‘0’ condition.

For this simple switch circuit, the value of resistor R1 is not critical and can be any resistance from around 1k to 47k, but avoid low values since that increases current consumption when the switch is pressed.

Here is some example Python code that can detect the push button switch status. To use the code, save the code in a file called button-test.py and then to run it type:

sudo python button-test.py

# Connections:
# GPIO5 (pin 29) is button input
# GPIO22 (pin 15) is LED


import time
import curses
import sys
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(5, GPIO.IN)
GPIO.setup(22, GPIO.OUT)
tc=curses.initscr()
tc.nodelay(1)
old_button_status=GPIO.input(5)
count=0


tc.addstr(1, 0, "Press SPACE to quit:\n")
tc.addstr(2, 0, str(count))


while 1:
  button_status=GPIO.input(5)
  kbval=tc.getch()
  GPIO.output(22, button_status)
  if old_button_status != button_status:
    if button_status == True:
      tc.addstr(2, 10, "-") # pin is high, button unpressed
      count=count+1
    else:
      tc.addstr(2, 10, "_") # pin is low, button pressed
    old_button_status=button_status
    tc.addstr(2, 0, str(count))
  if kbval==0x20:
    break


time.sleep(1)
GPIO.cleanup()
curses.endwin()
print "Goodbye"

     

The code displays the button status on the screen, along with a count of how many times the button was pressed. You’ll notice that occasionally the count increases more than the number of times the button was thought to be pressed and this happens because of ‘contact bounce’; as the switch is pressed, the contacts connect together and release many times rapidly before finally making contact. A similar thing happens when the switch is released. The solution is to have ‘debouncing’ functionality. It can be implemented in hardware or in software (the software method is very common). The code below implements debouncing and will more accurately register the correct number of button presses. The only difference with the earlier code is that this time the input status is checked a second time delayed by about 20msec – this provides time for contact bounce to have completed.

# Connections:
# GPIO5 (pin 29) is button input
# GPIO22 (pin 15) is LED


import time
import curses
import sys
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(5, GPIO.IN)
GPIO.setup(22, GPIO.OUT)
tc=curses.initscr()
tc.nodelay(1)
old_button_status=GPIO.input(5)
count=0


tc.addstr(1, 0, "Press SPACE to quit:\n")
tc.addstr(2, 0, str(count))


while 1:
  button_status=GPIO.input(5)
  kbval=tc.getch()
  GPIO.output(22, button_status)
  if old_button_status != button_status:
    time.sleep(0.02) # debounce period
    button_status=GPIO.input(5) # re-read the input
    if old_button_status != button_status:


      if button_status == True:
        tc.addstr(2, 10, "-") # pin is high, button unpressed
        count=count+1
      else:
        tc.addstr(2, 10, "_") # pin is low, button pressed
      old_button_status=button_status
      tc.addstr(2, 0, str(count))


  if kbval==0x20:
    break


time.sleep(1)
GPIO.cleanup()
curses.endwin()
print "Goodbye"

     

Another Input Example: A Voltmeter

The Raspberry Pi has digital inputs and outputs but the real world has analog quantities that may need to be measured or controlled. The example here converts analog values into a digital signal that can be read using a Raspberry Pi input connection.

The example is an extremely simple voltmeter; it can measure voltages between 0 and 1V with good precision. Note that this won’t replace a handheld multimeter! It doesn’t have the requisite safety protection and could damage itself or persons or property if used for anything beyond the scope of the examples described here.

This is the circuit diagram:

The circuit uses an AD654 integrated circuitAD654 integrated circuit which generates a square wave with frequency dependant on an input voltage. The square wave output is connected to a Raspberry Pi input (GPIO5 in this example). The square wave has a frequency of up to 10kHz and so some accurate timing is needed to determine the voltmeter input. The code here uses the C programming language and a library called wiringpi written by Gordon Henderson. First off, install the wiringpi library:

mkdir development
cd development
git clone git://git.drogon.net/wiringPi
cd wiringPi
./build
     

Next, save the following code into a file called voltmeter.c

// AD654 Voltmeter
// Ver 1.0 Shabaz August 2015
// GPIO5 (pin 29) connects to AD654
// GPIO22 (pin 15) connects to LED


#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <wiringPi.h>

#define INREF 5
#define LEDREF 22
#define INVAL (digitalRead(INREF))
#define INVAL_IS_HIGH (digitalRead(INREF)==1)
#define INVAL_IS_LOW (digitalRead(INREF)==0)
#define LED_ON digitalWrite(LEDREF, 1)
#define LED_OFF digitalWrite(LEDREF, 0)


struct timespec ts_zero;


void
get_tzero(void)
{
  clock_gettime(CLOCK_MONOTONIC, &ts_zero);
}


long
get_time(void)
{
  long nsec, sec;
  struct timespec tts;
  clock_gettime(CLOCK_MONOTONIC, &tts);
  sec=tts.tv_sec-ts_zero.tv_sec;
  nsec=tts.tv_nsec-ts_zero.tv_nsec;
  if (sec>0)
  {
    nsec=nsec+1E9; // we don't expect times greater than 1 sec
  }
  ts_zero=tts;
  return(nsec);
}


int
main(int argc, char *argv[])
{
  int i;
  long avg;
  double mv, v;
  long nsec[65];
  wiringPiSetupGpio();
  pinMode(INREF, INPUT);
  pinMode(LEDREF, OUTPUT);


  while(1)
  {
    LED_ON;
    while(INVAL_IS_LOW);
    get_tzero();
    for (i=0; i<64; i++)
    {
      while(INVAL_IS_HIGH);
      nsec[i]=get_time();
      while(INVAL_IS_LOW);
    }
    avg=0;
    for(i=1; i<65; i++)
    {
      avg=avg+nsec[i];
    }
    avg=avg/64;
    v=1.0E5/((double)avg);
    mv=v*1000;
    printf("Voltage is %fV\n", v);
    LED_OFF;
    sleep(1);
  }


  return(0);
}
     

The code can be compiled by typing:

gcc -o voltmeter -lrt -lwiringPi voltmeter.c

To run the code, type:

sudo ./voltmeter

The code uses an averaging method to get high precision. It rapidly measures the width of the incoming square wave 64 times, and then sums the values and divides by 64 to get the average value. Then it sleeps for a second to allow other processes to do their thing, and then repeats.

The circuit also needs a few things for high precision. The 10nF timing capacitor10nF timing capacitor for the AD564 is selected to be a polypropylene part for better accuracy. The 1k timing resistor1k timing resistor can be a 1% part or alternatively a variable trimming resistor can be used. The circuit runs from the 5V supply from the Raspberry Pi 40-pin connector but this is only approximately 5V and so the circuit would benefit from a dedicated and more accurate 5V supply circuit.

As a quick check, the circuit shown above had the voltmeter input subjected to a potential divider circuit consisting of two resistors. The calculated voltage (if the resistors were precisely the correct values and the supply was exactly 5V) out of the potential divider is 0.04950V. When the software was run, it reported measurements of 0.04991V in the short test. Not bad for such a simple project!

Diodes D1 and D2 in the circuit above are optional but highly recommended because they will provide some protection to the integrated circuit if the input is accidentally subjected to a voltage outside the 0-1V range.

Input Design Tips

Protected Inputs

The Raspberry Pi can be protected from accidental connections to higher than expected voltages by adding an additional circuit to the inputs in use. A very good option in some situations is to use an optocoupler alternatively a low-cost method such as the circuit below will tolerate voltages as high as 60V without damaging the Raspberry Pi, and will cope with reversed connections too. The BC547BBC547B transistor in the circuit can be replaced with another type such as 2N39042N3904 or BC549BC549 if more convenient to obtain. R1 can be a (normal) 0.25W resistor for inputs up to around 50V, and will need to be a 0.5W part otherwise.

The output of this circuit is inverted, and an input voltage higher than about 2V will pull the output low.

Connecting to 5V Logic

A direct connection of a 5V logic output to a Raspberry Pi input could cause damage. Different approaches can be taken depending on the specific need.

If the 5V logic output changes slowly then you could consider using a potential divider circuit (i.e. two resistors) but it is not a great method (it doesn’t work for fast circuits). A far better method is to use a 5V tolerant buffer integrated circuit. A mid-way approach adequate for up to 100kHz switching speed is shown below, using a ZVN2110AZVN2110A N-channel MOSFET. The output is inverted.

Alternative MOSFETs that are suitable include ZVNL120AZVNL120A and VN10LPVN10LP.

MOSFETs are easy to damage when unsoldered in a circuit due to a very delicate gate structure (it is made of a thin layer internally that can be destroyed with high voltage). Take electrostatic precautions and another good practice is to first connect R3 into your circuit (either on a circuit board or breadboard) and then remove the MOSFET from its safe packaging and connect it into the circuit. The resistor R3 will provide some protection.

Advanced Topic: Speed and Jitter

Beginners: Skip to the next section! Advanced users, read on.

Button-presses and LED outputs are slow events measured in tens or hundreds of milliseconds. Sometimes much higher speed signals are encountered. For example, a TV remote emits infra-red light pulses around 40k times per second. Although the core CPU in the Raspberry Pi runs at speeds approaching 1GHz, input and output signals at that rate are not supported for several reasons that are hardware, electrical and software related. We will consider some of the software factors for the scope of this blog post.

The Raspberry Pi runs Linux which is a multi-tasking OS. It can (at any time) pre-emptively take control away from your software program in order to service other tasks. It all happens relatively quickly, so it looks like the mouse still works while your program is running, but really the Linux OS is providing short time-slices to your program and to the mouse driver code.

Ordinarily this doesn’t matter, but when you need short or high precision events this can become an issue revealed (for example) as jitter.

Furthermore choice of programming language has an effect too, because some libraries are more suitable than others. Interpreted code may run at a different speed compared to compiled code. In short if very precise timing is needed then either a Linux driver needs to be written or external hardware (such as another microcontroller, or logic circuits and clock) may be needed.

One good question for more advanced use of the Raspberry Pi capabilities is approximately how fast can output signals be toggled using the Python and C libraries and the script method described earlier?

To find out, code was written to repeatedly toggle an output pin and an oscilloscope was connected up. The results are shown below.

However, it is always important to remember there is jitter that will be present due to the use of the Linux OS. This is not an issue for general LED toggling of course. The oscilloscope capture below shows part of the nature of the jitter by overlaying multiple traces triggered at the same time. Notice that the jitter can take on many values, although they are all discretely spaced 4nsec apart (250MHz) which is due to internal hardware inside the Raspberry Pi.

Summary

If you've read this far then by now it should be clear that the 40-pin connector on the Raspberry Pi can be used for many diverse projects from driving LEDs and relays to creating voltmeters or generating alarms. With little circuitry the 3.3V logic compatible Raspberry Pi connections can interface to circuits. Using Python it is very easy to control outputs, and reading inputs is not too difficult either. For C programmers the wiringpi library makes control easy.

Next Steps

If you have a few basic components (an LED, some resistors and a breadboard and jumper wires) you can begin exploring.

Rather than just buy a single resistor or capacitor as you need it, consider purchasing a small pack of resistors, capacitors and a few transistors (bipolar and MOSFET), diodes, and a multimeter.

As you dive into deeper projects you'll also be interested in learning about the serial interface connections available on the 40-pin connector. The serial interfaces are used to send and receive multiple bits of data in a standard method between the Raspberry Pi and other integrated circuits. However there are also many integrated circuits that are very easy to connect to the GPIO connections and several were covered in this blog post. Consider obtaining a few ICM7555 devices - there are a lot of fun and interesting experiments possible with them.