# Add an ultrasonic distance sensor to your Raspberry Pi with Viam

Wire an ultrasonic sensor to a Raspberry Pi, add the module from the Viam Registry, and stream live distance readings to your browser — in four steps.

Jalen Geason

Technical Product Marketing

Adrienne Tacke

Senior Developer Advocate

Have you ever wanted to detect how close an object is to your robot or device? With Viam and an HC-SR04 ultrasonic sensor, you can have live distance readings streaming to your browser in just four steps: wiring the sensor, adding the module from the Viam Registry, configuring it, and gathering live data.

## What you'll build

A working ultrasonic distance sensor connected to a Raspberry Pi, streaming live distance readings through the Viam app. Once you have this foundation, you can extend it into a full visual proximity alert that changes an RGB LED from green to red as objects approach — see ‘What’s Next?’ section at the end.

## What you'll need

**Hardware**  
- Raspberry Pi 4 (recommend at least 4 GB RAM)  
- microSD card  
- Power supply (5V 3A USB-C for the Pi)  
- HC-SR04 ultrasonic sensor  
- Solderless breadboard  
- Resistors: 1× 1kΩ and 1× 2kΩ (for the voltage divider on the Echo pin)  
- Jumper wires (female-to-male)

**Software**  
- A free [Viam account](https://app.viam.com/) — sign up at app.viam.com  
- Raspberry Pi Imager (to flash your Pi)

## Before you begin: Set up your Raspberry Pi

If your Pi is already running and connected to Viam, skip ahead to Step 1. If you're starting from scratch, follow the [Viam setup guide](https://docs.viam.com/operate/install/setup/) to flash your Pi, install viam-server, and get your machine showing as **Live** in the app.

## **Step 1: Wire it up**

The HC-SR04 operates at 5V logic, but the Raspberry Pi's GPIO pins are 3.3V tolerant. The Trig pin (output from the Pi) is fine at 3.3V. The Echo pin (output from the sensor back to the Pi) carries 5V, so a simple resistor voltage divider is needed to bring it down to a safe level.

- **VCC** → Pi 5V (Physical Pin 2)  
- **Trig** → Pi GPIO 23 (Physical Pin 16)  
- **Echo** → 1kΩ resistor → Pi GPIO 24 (Physical Pin 18); 2kΩ resistor from that junction to GND  
- **GND** → Pi GND (Physical Pin 6)

_Physical pin numbers refer to the location of the pin on the Raspberry Pi and are different from their GPIO pin numbers. Both are given to be more explicit. To find the physical pin numbers, first orient the pi to have ports facing downward (like in the diagram). Starting at the top-most, left pin is physical pin 1, top-most, right pin is physical 2, and so on…_

Use the breadboard to build the voltage divider and route the jumper wires from the sensor pins to the corresponding GPIO pins on the Pi.

## Step 2: Add your components

With your hardware wired and your Pi connected to the Viam app, navigate to your machine's **CONFIGURE** tab.

### Add the board component

The board component gives Viam access to the Raspberry Pi's GPIO pins — the ultrasonic sensor needs this to function.

1. Click the **+** icon and select **Configuration block**.
2. In the Registry search bar, type raspberry-pi. You’ll see several results. Select the **raspberry-pi:rpi4** or **raspberry-pi:rpi5** module depending on your board. Click **Add component**.
3. Give your component a name (e.g., pi) and click **Add component**.. 
4. Click **Save**.

### Add the ultrasonic sensor component

1. Click the **+** button to add a new component, then select **Configuration block**.
2. Type in ultrasonic. Select **ultrasonic/sensor** (the one listed as type **SENSOR**, authored by viam). Click **Add component**.
3. Give your component a name (e.g., ultrasonic) and click **Add component**. The supporting module will be installed automatically.
4. Click **Save**.

## Step 3: Configure the module

After adding the component, you'll land on its configuration panel. In the **JSON configuration** section, fill in the attributes for your sensor:

```javascript
{
  "trigger_pin": "16",
  "echo_interrupt_pin": "18",
  "board": "<your-board-name>",
  "timeout_ms": 1000
}
```

- **trigger_pin** — the GPIO pin number connected to the sensor's Trig pin (16 in this example).  
- **echo_interrupt_pin** — the GPIO pin number connected to the Echo pin output of your voltage divider (18 in this example).  
- **board** — the name of your board component in Viam (e.g., board-1).  
- **timeout_ms** — how long to wait for an echo response before timing out. 1000ms is a safe default.

Once you've filled in the fields, be sure to click **Save** (or press ⌘S / Ctrl+S). The app will show "Unsaved changes" in the header until you do. Once saved, the component status should switch from **MODIFIED** to **Ready**.

## Step 4: Get live data

Navigate to the **CONTROL** tab and find your ultrasonic sensor component. Click **TEST** to expand the testing panel.

Set the dropdown to **Refresh every second** to start streaming data. You'll see a distance field updating in real time (in meters) as you move your hand or an object toward and away from the sensor. That's it, now you have live ultrasonic distance data!

## What's next?

Now that you have a live distance sensor, you can take it further:

- **Add an RGB LED** and write a simple Viam module to change its color based on distance thresholds — turning green when an object is far away and red when it gets too close. That's exactly what the full [Visual Proximity Alert codelab](https://codelabs.viam.com/guide/visual-proximity-alert/index.html) walks you through.
- **Capture data** using Viam's built-in [data management](https://docs.viam.com/data-ai/capture-data/capture-sync/) to log distance readings over time.
- **Use** [**Viam Triggers**](https://docs.viam.com/data-ai/data/alert-data/) to send a notification or fire an action when an object enters a defined range.

Start building at [app.viam.com](https://app.viam.com/).