# 10. Migrating from RPi.GPIO

If you are familiar with the RPi.GPIO library, you will be used to writing code which deals with pins and the state of pins. You will see from the examples in this documentation that we generally refer to things like LEDs and Buttons rather than input pins and output pins.

GPIO Zero provides classes which represent devices, so instead of having a pin number and telling it to go high, you have an LED and you tell it to turn on, and instead of having a pin number and asking if it’s high or low, you have a button and ask if it’s pressed. There is also no boilerplate code to get started — you just import the parts you need.

GPIO Zero provides many device classes, each with specific methods and properties bespoke to that device. For example, the functionality for an HC-SR04 Distance Sensor can be found in the `DistanceSensor` class.

As well as specific device classes, we provide base classes `InputDevice` and `OutputDevice`. One main difference between these and the equivalents in RPi.GPIO is that they are classes, not functions, which means that you initialize one to begin, and provide its pin number, but then you never need to use the pin number again, as it’s stored by the object.

GPIO Zero was originally just a layer on top of RPi.GPIO, but we later added support for various other underlying pin libraries. RPi.GPIO is currently the default pin library used. Read more about this in Changing the pin factory.

## 10.1. Output devices

Turning an LED on in RPi.GPIO:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(2, GPIO.OUT)

    GPIO.output(2, GPIO.HIGH)

Turning an LED on in GPIO Zero:

    from gpiozero import LED

    led = LED(2)

    led.on()

The `LED` class also supports threaded blinking through the `blink()` method.

`OutputDevice` is the base class for output devices, and can be used in a similar way to output devices in RPi.GPIO.

See a full list of supported output devices. Other output devices have similar property and method names. There is commonality in naming at base level, such as `OutputDevice.is_active`, which is aliased in a device class, such as `LED.is_lit`.

## 10.2. Input devices

Reading a button press in RPi.GPIO:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(4, GPIO.IN, GPIO.PUD_UP)

    if not GPIO.input(4):
        print("button is pressed")

Reading a button press in GPIO Zero:

    from gpiozero import Button

    btn = Button(4)

    if btn.is_pressed:
        print("button is pressed")

Note that in the RPi.GPIO example, the button is set up with the option `GPIO.PUD_UP` which means “pull-up”, and therefore when the button is not pressed, the pin is high. When the button is pressed, the pin goes low, so the condition requires negation (`if not`). If the button was configured as pull-down, the logic is reversed and the condition would become `if GPIO.input(4)`:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(4, GPIO.IN, GPIO.PUD_DOWN)

    if GPIO.input(4):
        print("button is pressed")

In GPIO Zero, the default configuration for a button is pull-up, but this can be configured at initialization, and the rest of the code stays the same:

    from gpiozero import Button

    btn = Button(4, pull_up=False)

    if btn.is_pressed:
        print("button is pressed")

RPi.GPIO also supports blocking edge detection.

Wait for a pull-up button to be pressed in RPi.GPIO:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(4, GPIO.IN, GPIO.PUD_UP)

    GPIO.wait_for_edge(4, GPIO.FALLING):
    print("button was pressed")

The equivalent in GPIO Zero:

    from gpiozero import Buttons

    btn = Button(4)

    btn.wait_for_press()
    print("button was pressed")

Again, if the button is pulled down, the logic is reversed. Instead of waiting for a falling edge, we’re waiting for a rising edge:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(4, GPIO.IN, GPIO.PUD_UP)

    GPIO.wait_for_edge(4, GPIO.FALLING):
    print("button was pressed")

Again, in GPIO Zero, the only difference is in the initialization:

    from gpiozero import Buttons

    btn = Button(4, pull_up=False)

    btn.wait_for_press()
    print("button was pressed")

RPi.GPIO has threaded callbacks. You create a function (which must take one argument), and pass it in to `add_event_detect`, along with the pin number and the edge direction:

    import RPi.GPIO as GPIO

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    def pressed(pin):
        print("button was pressed")

    def released(pin):
        print("button was released")

    GPIO.setup(4, GPIO.IN, GPIO.PUD_UP)

    GPIO.add_event_detect(4, GPIO.FALLING, pressed)
    GPIO.add_event_detect(4, GPIO.RISING, released)

In GPIO Zero, you assign the `when_pressed` and `when_released` properties to set up callbacks on those actions:

    from gpiozero import Buttons

    def pressed():
        print("button was pressed")

    def released():
        print("button was released")

    btn = Button(4)

    btn.when_pressed = pressed
    btn.when_released = released

`when_held` is also provided, where the length of time considered a “hold” is configurable.

The callback functions don’t have to take any arguments, but if they take one, the button object is passed in, allowing you to determine which button called the function.

`InputDevice` is the base class for input devices, and can be used in a similar way to input devices in RPi.GPIO.

See a full list of input devices. Other input devices have similar property and method names. There is commonality in naming at base level, such as `InputDevice.is_active`, which is aliased in a device class, such as `Button.is_pressed` and `LightSensor.light_detected`.

## 10.3. Composite devices, boards and accessories

Some devices require connections to multiple pins, for example a distance sensor, a combination of LEDs or a HAT. Some GPIO Zero devices comprise multiple device connections within one object, such as `RGBLED`, `LEDBoard`, `DistanceSensor`, `Motor` and `Robot`.

With RPi.GPIO, you would have one output pin for the trigger, and one input pin for the echo. You would time the echo and calculate the distance. With GPIO Zero, you create a single `DistanceSensor` object, specifying the trigger and echo pins, and you would read the `DistanceSensor.distance` property which automatically calculates the distance within the implementation of the class.

The `Motor` class controls two output pins to drive the motor forwards or backwards. The `Robot` class controls four output pins (two motors) in the right combination to drive a robot forwards or backwards, and turn left and right.

The `LEDBoard` class takes an arbitrary number of pins, each controlling a single LED. The resulting `LEDBoard` object can be used to control all LEDs together (all on / all off), or individually by index. Also the object can be iterated over to turn LEDs on in order. See examples of this (including slicing) in the advanced recipes.

## 10.4. PWM (Pulse-width modulation)

Both libraries support software PWM control on any pin. Depending on the pin library used, GPIO Zero can also support hardware PWM (using `RPIOPin` or `PiGPIOPin`).

A simple example of using PWM is to control the brightness of an LED.

In RPi.GPIO:

    import RPi.GPIO as GPIO
    from time import sleep

    GPIO.setmode(GPIO.BCM)
    GPIO.setwarnings(False)

    GPIO.setup(2, GPIO.OUT)
    pwm = GPIO.PWM(2, 100)
    pwm.start(0)

    for dc in range(101):
        pwm.changeDutyCycle(dc)
        sleep(0.01)

In GPIO Zero:

    from gpiozero import PWMLED
    from time import sleep

    led = PWMLED(2)

    for b in range(101):
        led.value = b / 100.0
        sleep(0.01)

`PWMLED` has a `blink()` method which can be used the same was as `LED`’s `blink()` method, but its PWM capabilities allow for `fade_in` and `fade_out` options to be provided. There is also the `pulse()` method which provides a neat way to have an LED fade in and out repeatedly.

Other devices can make use of PWM, such as motors (for variable speed) and servos. See the `Motor`, `Servo` and `AngularServo` classes for information on those. `Motor` and `Robot` default to using PWM, but it can be disabled with `pwm=False` at initialization. Servos cannot be used without PWM. Devices containing LEDs default to not using PWM, but `pwm=True` can be specified and any LED objects within the device will be initialized as `PWMLED` objects.

## 10.5. Cleanup

Pin state cleanup is explicit in RPi.GPIO, and is done manually with `GPIO.cleanup()` but in GPIO Zero, cleanup is automatically performed on every pin used, at the end of the script. Manual cleanup is possible by use of the `close()` method on the device.

Note that cleanup only occurs at the point of normal termination of the script. If the script exits due to a program error, cleanup will not be performed. To ensure that cleanup is performed after an exception is raised, the exception must be handled, for example:

    from gpiozero import Button

    btn = Button(4)

    while True:
        try:
            if btn.is_pressed:
                print("Pressed")
        except KeyboardInterrupt:
            print("Ending program")

Read more in the relevant FAQ: What’s the gpiozero equivalent of GPIO.cleanup()?

## 10.6. Pi Information

RPi.GPIO provides information about the Pi you’re using. The equivalent in GPIO Zero is the function `pi_info()`:

    >>> from gpiozero import pi_info
    >>> pi = pi_info()
    >>> pi
    PiBoardInfo(revision='a02082', model='3B', pcb_revision='1.2', released='2016Q1', soc='BCM2837', manufacturer='Sony', memory=1024, storage='MicroSD', usb=4, ethernet=1, wifi=True, bluetooth=True, csi=1, dsi=1, headers=..., board=...)
    >>> pi.soc
    'BCM2837'
    >>> pi.wifi
    True

Read more about what `PiBoardInfo` provides.

## 10.7. More

GPIO Zero provides more than just GPIO device support, it includes some support for SPI devices including a range of analog to digital converters.

Device classes which are compatible with other GPIO devices, but have no relation to GPIO pins, such as `CPUTemperature`, `TimeOfDay`, `PingServer` and `LoadAverage` are also provided.

GPIO Zero features support for multiple pin libraries. The default is to use `RPi.GPIO` to control the pins, but you can choose to use another library, such as `pigpio`, which supports network controlled GPIO. See Changing the pin factory and Configuring Remote GPIO for more information.

It is possible to run GPIO Zero on your PC, both for remote GPIO and for testing purposes, using Mock pins.

Another feature of this library is configuring devices to be connected together in a logical way, for example in one line you can say that an LED and button are “paired”, i.e. the button being pressed turns the LED on. Read about this in Source/Values.

## 10.8. FAQs

Note the following FAQs which may catch out users too familiar with RPi.GPIO:

- How do I keep my script running?

- Why do I get PinFactoryFallback warnings when I import gpiozero?

- What’s the gpiozero equivalent of GPIO.cleanup()?