Build a visual proximity alert with an ultrasonic sensor, RGB LED, and Raspberry Pi

Build a visual proximity alert with an ultrasonic sensor, RGB LED, and Raspberry Pi

1. Overview

Proximity alerts can be very useful, whether you're backing into a parking spot (and don't have a rearview camera), want to warn others that you're in a blind corner, or want to avoid getting too close to things. In this codelab, you'll build your own visual proximity alert that uses an RGB LED to indicate safe and dangerous distances and an ultrasonic sensor to determine those distances.

What You'll Build

Prerequisites

What You'll Need

What You'll Learn

Watch the video

See a demonstration of the visual proximity alert:

Visual proximity alert with ultrasonic sensor and RGB LED | DEMO

2. Set up your Raspberry Pi

The Raspberry Pi boots from a microSD card. You need to install Raspberry Pi OS on a microSD card that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.

Install Raspberry Pi OS

  1. Connect the microSD card to your computer.
  2. Launch the Raspberry Pi Imager.
  3. Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 4.
  4. Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
  5. Click CHOOSE STORAGE. From the list of devices, select the microSD card you intend to use in your Raspberry Pi.
  6. Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
  7. Check Set hostname and enter the name you would like to access the Pi by in that field, for example, test.
  8. Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). And specify a password.
  9. Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Also change the section Wireless LAN country to where your router is currently being operated. This will allow your Pi to connect to your Wi-Fi so that you can run viam-server wirelessly.
  10. Check Set locale settings and set your time zone and keyboard layout.
  11. Select the SERVICES tab, check Enable SSH, and select Use password authentication.
  12. Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on the microSD card. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the microSD card.
  13. Remove the microSD card from your computer when the installation is complete.

Connect with SSH

  1. Place the microSD card into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.

  2. Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the username and hostname you configured when you set up your Pi.

ssh <USERNAME>@<HOSTNAME>.local

# for example, my command would look like this:
ssh atacke@echo.local
  1. If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt.
  2. Update your Raspberry Pi to ensure all the latest packages are installed
sudo apt update
sudo apt upgrade

3. Full wiring preview

It's now time to wire our hardware components together! Here's what you'll be wiring together:

The following sections will focus on a single component at a time and show the localized wiring diagram. However, feel free to reference this full diagram when needed.

Alright, first up, the ultrasonic sensor!

4. Wire up the ultrasonic sensor

First, we'll set up the ultrasonic sensor. You'll need your

Wiring reference

  1. Review the wiring diagram: Refer to the following wiring diagram to see how to connect the ultrasonic sensor to the Raspberry Pi, using the breadboard and resistors to control the flow of electricity: The ultrasonic sensor will use 4 GPIO pins on the Raspberry Pi
Ultrasonic sensor <-> Raspberry Pi
VCC to GPIO 5V (Physical Pin 2)
GND to GPIO GND (Physical Pin 6)
TRIG to GPIO 23 (Physical Pin 16)
ECHO to GPIO 24 (Physical Pin 18)

Step-by-step wiring instructions

  1. Plug four of your jumper wires into the pins of the HC-SR04.
  2. Plug your VCC wire into the positive rail of your breadboard and your GND wire into the negative rail. From this point on, we'll use the breadboard to simplify the wiring process and provide a secure platform to connect components without soldering.
  3. Plug a jumper wire into GPIO 5V (Physical Pin 2) on your Pi and connect that wire to the positive rail of your breadboard, which connects it to VCC.
  4. Plug a jumper wire into GPIO GND (Physical Pin 6) on your Pi and connect that wire to the negative rail of your breadboard, which connects it to GND.
  5. Plug the TRIG wire from your ultrasonic sensor into a blank rail on your breadboard, then use another jumper wire to connect that rail to your Pi's GPIO 23 (Physical Pin 16) pin. (Technically, you can skip the connection on the breadboard and connect the TRIG wire directly to the Pi; it's a matter of preference!)
  6. Plug the ECHO wire from your ultrasonic sensor into another blank rail, then link it to another blank rail using a 1000 Ohm resistor (R1).
  7. Link your R1 rail to your GND rail using a 2000 Ohm (R2) resistor. Be sure to leave a space between the two resistors.
  8. Plug a jumper wire right where you left a space in between the resistors and connect that wire into your Pi's GPIO 24 (Physical Pin 18) pin.

Sweet! You've set up the ultrasonic sensor.

This will enable you to capture distance readings. Let's add the RGB LED next!

5. Wire up the RGB LED

Next, we'll set up the RGB LED. You'll need your

Wiring the hardware

  1. Review the wiring diagram: Refer to the following wiring diagram (ultrasonic wiring omitted for clarity) to see how to connect the RGB LED to the Raspberry Pi, using the breadboard and resistors to control the flow of electricity:

The RGB LED will use 4 GPIO pins on the Raspberry Pi
RGB LED <-> Raspberry Pi
Common Cathode (GND) to GND (Physical Pin 34)
Red to GPIO 13 (Physical Pin 33)
Green to GPIO 12 (Physical Pin 32)
Blue to GPIO 18 (Physical Pin 12)

Step-by-step wiring instructions

  1. Review the LED's orientation: A common cathode RGB LED has four legs:
  1. Plug your RGB LED into a blank rail on your breadboard. From here, you'll use jumper wires and resistors to connect it to your Pi.
  2. Plug a jumper wire next to the longest leg of the LED, then connect that wire to the Pi's GND pin (Physical Pin 34). This will be your ground.
  3. Link a 100 Ohm resistor to the red leg of the LED.
  4. Link a 10 Ohm resistor to the green leg and another 10 Ohm resistor to the blue leg of the LED.
  5. Connect the resistors to the Pi.
    • Connect a jumper wire from the red leg (100 Ohm resistor) to the Pi's GPIO 13 pin (Physical Pin 33)
    • Connect a jumper wire from the green leg (10 Ohm resistor) to the Pi's GPIO 12 pin (Physical Pin 32)
    • Connect a jumper wire from the blue leg (10 Ohm resistor) to the Pi's GPIO 18 pin (Physical Pin 12)
  6. Double-check connections to ensure correct polarity and avoid miswiring.

With the hardware all wired up, it's time to configure them within the Viam app, which we'll do in the next section.

6. Configure your machine

  1. In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.
  2. Click View setup instructions.
  3. To install viam-server on your Raspberry Pi (so you can communicate with and control your sensor and the RGB LED), select the Linux / Aarch64 platform for the Raspberry Pi, and leave your installation method as viam-agent.
  4. Use the viam-agent to download and install viam-server on your Raspberry Pi. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your Raspberry Pi.
  5. The setup page will indicate when the machine is successfully connected.

With a machine configured and connected, it's time to add the peripherals. First, the board (AKA your Raspberry Pi).

7. Configure your Raspberry Pi board

To access the GPIO pins of your Raspberry Pi, add the board to your machine in the Viam app.

  1. In the Viam app, find the CONFIGURE tab.
  2. Click the + icon in the left-hand menu and select Component.
  3. Select board, and find the raspberry-pi:rpi4 module. Click Add Module. Leave the default name board-1 for now, then click Create. This adds the module for working with the Raspberry Pi 4's GPIO pins.
  4. Notice adding this module adds the board hardware component called board-1. You'll see a collapsible card on the right, where you can configure the board component, and the corresponding board-1 part listed in the left sidebar.
  5. Click Save in the top right to save and apply your configuration changes.
  6. Expand the TEST section of the panel to experiment with writing to physical pins. For example, since our RGB LED's red leg is connected to physical pin 33, type 33 into the Pin field and set its signal to High. This should turn the RGB LED on and emit a red light.
  7. Set the signal to Low (for each pin previously set to High) to turn off the LED.

Now that your board is configured, you can configure your ultrasonic sensor next.

8. Configure your ultrasonic sensor

To access the ultrasonic sensor's measurements, add the sensor to your machine.

  1. In the Viam app, find the CONFIGURE tab.
  2. Click the + icon in the left-hand menu and select Component.
  3. Select sensor, and find the ultrasonic:sensor module. Click Add Module. Leave the default name sensor-1 for now, then click Create. This adds the module that gives you access to the ultrasonic sensor's readings.
  4. Notice adding this module adds the sensor hardware component called sensor-1. You'll see a collapsible card on the right, where you can configure the sensor component, and the corresponding sensor-1 part listed in the left sidebar.
  5. In the JSON configuration field (within the CONFIGURE panel), add the following attributes. This tells your sensor which pins to use for its Echo Pulse Output (ECHO) and Trigger Pulse Input (TRIG) and which board it is wired to. In your case, that's board-1, which is the Raspberry Pi you added earlier. You can read more about each attribute in the Documentation panel that's next to your JSON configuration
{
     "echo_interrupt_pin": "18",
     "trigger_pin": "16",
     "board": "board-1",
     "timeout_ms": 1000 // Optional;
}
  1. Click Save in the top right to save and apply your configuration changes.
  2. Expand the TEST section of the panel to experiment with the sensor. You should see a Get Readings label and a continuously updating measurement. Try placing your hand in front of the sensor and moving it farther away. The readings should reflect these changes, returning a smaller value as you place an object closer to the sensor and a larger value as you move the object farther away from the sensor.

Great! You now have a working sensor and access to your board. Let's add some logic to turn the RGB LED red or green depending on the measured readings.

9. Add the proximity alert module

We can indicate when something is too close or within a safe distance (relative to the sensor) by changing the color of the RGB LED. To do this, you can write some code that processes the ultrasonic sensor's readings and sets the RGB LED to turn red or green (unsafe and safe distances, respectively). Or you can use a prebuilt module from the Viam registry that already does this for you! This step will go over how to use the proximity-alert module.

  1. In the Viam app, find the CONFIGURE tab.
  2. Click the + icon in the left-hand menu and select Service.
  3. Select generic, and find the proximity-alert:hc-sr04_rgb-led module. Click Add Module. Be sure to change the default name to something more descriptive, like proximity-alert-service, then click Create. This adds a service that automatically turns the RGB LED red or green depending on the ultrasonic sensor's readings and a distance threshold you'll specify soon.
  4. Notice adding this module adds the generic service of your chosen name. You'll see a collapsible card on the right, where you can configure the proximity alert module, and the corresponding part listed in the left sidebar.
  5. In the CONFIGURE panel, add the following attributes (minus the comments). This tells the service which board and sensor to use (which should be the ones you've just configured), which GPIO pins to use to control the RGB LED, and a safe distance threshold to determine when to turn red or green.
// "board" and "sensor" values need to match your board and sensor component names in the Viam app
// "red_pin", "green_pin", and "blue_pin" values match GPIO pins you configured for your RGB LED
{
     "board": "board-1",
     "sensor": "sensor-1",
     "red_pin": "33",
     "green_pin": "32",
     "blue_pin": "12",
     "safe_distance": "0.3"
}
  1. Click Save to apply your configuration changes. This may take a moment.
  2. After a few moments, your RGB LED should flicker on and emit a light. Test it out! Place your hand immediately in front of the ultrasonic sensor. It should quickly emit a red light and stay red as long as you keep your hand there. When you remove your hand (and assuming there are no other objects in front of the sensor's path that is within the unsafe distance), the LED should emit a green light. To continue testing the service and ensure a bit more accuracy, position the ultrasonic sensor so that it faces some open space and that you are able to move an object within its path at variable ranges.

10. Conclusion And Resources

Congratulations! You've just built an automated proximity alert with a visual indicator! 🥳 Using some pretty common hardware components and a handy module from Viam, you created a useful device.

What You Learned

Real-world applications for proximity alerts with visual indicators

This project is a great way to learn about combining different components to produce something useful; it has practical applications as well:

Extend your proximity alert with Viam

Right now, you can give visual indicators based on proximity with the RGB LED. But there are other things you can do to extend your proximity alert! As an example, you could: