.. note::

    Hello, welcome to the SunFounder Raspberry Pi & Arduino & ESP32 Enthusiasts Community on Facebook! Dive deeper into Raspberry Pi, Arduino, and ESP32 with fellow enthusiasts.

    **Why Join?**

    - **Expert Support**: Solve post-sale issues and technical challenges with help from our community and team.
    - **Learn & Share**: Exchange tips and tutorials to enhance your skills.
    - **Exclusive Previews**: Get early access to new product announcements and sneak peeks.
    - **Special Discounts**: Enjoy exclusive discounts on our newest products.
    - **Festive Promotions and Giveaways**: Take part in giveaways and holiday promotions.

    👉 Ready to explore and create with us? Click [|link_sf_facebook|] and join today!

.. _1.3.3_py_pi5:

1.3.3 Relay
===========

Introduction
------------

In this project, we will learn to use a relay. It is one of the commonly
used components in automatic control system. When the voltage, current,
temperature, pressure, etc., reaches, exceeds or is lower than the
predetermined value, the relay will connect or interrupt the circuit, to
control and protect the equipment.

Required Components
------------------------------

In this project, we need the following components. 

.. image:: ../python_pi5/img/1.3.3_relay_list.png

It's definitely convenient to buy a whole kit, here's the link: 

.. list-table::
    :widths: 20 20 20
    :header-rows: 1

    *   - Name	
        - ITEMS IN THIS KIT
        - LINK
    *   - Raphael Kit
        - 337
        - |link_Raphael_kit|

You can also buy them separately from the links below.

.. list-table::
    :widths: 30 20
    :header-rows: 1

    *   - COMPONENT INTRODUCTION
        - PURCHASE LINK

    *   - :ref:`cpn_gpio_board`
        - |link_gpio_board_buy|
    *   - :ref:`cpn_breadboard`
        - |link_breadboard_buy|
    *   - :ref:`cpn_wires`
        - |link_wires_buy|
    *   - :ref:`cpn_resistor`
        - |link_resistor_buy|
    *   - :ref:`cpn_led`
        - |link_led_buy|
    *   - :ref:`cpn_transistor`
        - |link_transistor_buy|
    *   - :ref:`cpn_relay`
        - |link_relay_buy|
    *   - :ref:`cpn_diode`
        - |link_diode_buy|

Schematic Diagram
-----------------

.. image:: ../python_pi5/img/1.3.3_relay_schematic.png


Experimental Procedures
-----------------------

**Step 1:** Build the circuit.

.. image:: ../python_pi5/img/1.3.3_relay_circuit.png

**Step 2:** Open the code file.

.. raw:: html

   <run></run>

.. code-block::

    cd ~/raphael-kit/python-pi5


**Step 3:** Run.

.. raw:: html

   <run></run>

.. code-block::

    sudo python3 1.3.3_Relay_zero.py

While the code is running, the LED lights up. In addition, you can hear
a ticktock caused by breaking normally close contact and closing
normally open contact.

.. warning::

    If there is an error prompt  ``RuntimeError: Cannot determine SOC peripheral base address``, please refer to :ref:`faq_soc` 

**Code**

.. note::

    You can **Modify/Reset/Copy/Run/Stop** the code below. But before that, you need to go to  source code path like ``raphael-kit/python-pi5``. After modifying the code, you can run it directly to see the effect.


.. raw:: html

    <run></run>

.. code-block:: python

   #!/usr/bin/env python3
   from gpiozero import OutputDevice  # Import the class for controlling GPIO pins
   from time import sleep  # Import the sleep function for delay

   # Initialize the relay connected to GPIO pin 17, starting in the 'off' state
   relay = OutputDevice(17, initial_value=False)

   try:
       # Loop to continuously toggle the relay's state every second
       while True:
           print('Relay open...')  # Inform that the relay is being activated
           relay.on()  # Turn on the relay (assuming active low configuration)
           sleep(1)   # Maintain the relay in the on state for 1 second

           print('...Relay close')  # Inform that the relay is being deactivated
           relay.off()  # Turn off the relay
           sleep(1)   # Maintain the relay in the off state for 1 second

   except KeyboardInterrupt:
       # Handle a keyboard interrupt (Ctrl+C) to exit the loop
       relay.off()  # Ensure the relay is turned off before exiting
       pass


**Code Explanation**

#. It imports ``OutputDevice`` from ``gpiozero`` for controlling GPIO pins and ``sleep`` from ``time`` for adding delays.

   .. code-block:: python

       #!/usr/bin/env python3
       from gpiozero import OutputDevice  # Import the class for controlling GPIO pins
       from time import sleep  # Import the sleep function for delay

#. Initializes an ``OutputDevice`` object for the relay connected to GPIO pin 17. The ``initial_value=False`` sets the relay to the ``off`` state initially (assuming active low configuration).

   .. code-block:: python

       # Initialize the relay connected to GPIO pin 17, starting in the 'off' state
       relay = OutputDevice(17, initial_value=False)

#. Inside the ``try`` block, a ``while True`` loop continuously toggles the relay's state. The relay is turned on and off with a 1-second delay between each state, accompanied by console print statements.

   .. code-block:: python

       try:
           # Loop to continuously toggle the relay's state every second
           while True:
               print('Relay open...')  # Inform that the relay is being activated
               relay.on()  # Turn on the relay (assuming active low configuration)
               sleep(1)   # Maintain the relay in the on state for 1 second

               print('...Relay close')  # Inform that the relay is being deactivated
               relay.off()  # Turn off the relay
               sleep(1)   # Maintain the relay in the off state for 1 second

#. Catches a KeyboardInterrupt (like Ctrl+C) to allow for graceful script termination. The relay is turned off before exiting the script.

   .. code-block:: python
      
      except KeyboardInterrupt:
        # Handle a keyboard interrupt (Ctrl+C) to exit the loop
        relay.off()  # Ensure the relay is turned off before exiting
        pass