It's easy to use these ultrasonic distance sensors with Python and CircuitPython. These modules allow you to easily use Python code to read the distance from the sensor.

You can use the US-100 sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

CircuitPython Microcontroller Wiring

First wire up your sensor as shown below.

Here is an example of the HC-SR04 wired up to a Feather M4:

Feather USB or VBat to sensor VCC
Feather D5 to sensor trig
Feather D6 to 10k resistor - other side to GND
Sensor echo to 10k resistor - other side to D6
Feather and Sensor GND to breadboard ground rail

The HC-SR04 requires a voltage divider to allow the 5V logic to work with a 3V microcontroller.

Here is an example of the US-100 wired up to a Feather M4 in HC-SR04 compatibility mode:

Feather 3V to sensor VCC
Feather GND to sensor GND
Feather D5 to sensor trig/TX
Feather D6 to sensor echo/RX
Jumper removed from back of sensor

Here is an example of the US-100 wired up to a Feather M4 in UART mode:

Note: Typically with UART, you connect TX to RX and RX to TX, this is not the case with this sensor!

Feather 3V to sensor VCC
Feather GND to sensor GND
Feather TX to sensor trig/TX
Feather RX to sensor echo/RX
Jumper present on back of sensor

Python Computer Wiring

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.

Here is an example of the HC-SR04 wired up to a Raspberry Pi:

Pi 5v to sensor VCC
Pi D5 to sensor trig
Pi D6 to 10k resistor - other side to GND
Sensor echo to 10k resistor - other side to D6
Pi GND to breadboard ground rail
Sensor GND to breadboard ground rail

The HC-SR04 requires a voltage divider to allow the sensor 5V logic to work with 3V logic.

Here's an example of the US-100 in HC-SR04 compatibility mode wired up to a Raspberry Pi:

Pi 3.3V to sensor VCC
Pi GND to sensor GND
Pi D5 to sensor trig/TX
Pi D6 to sensor echo/RX
Jumper removed from back of sensor

You have two options for the US100 in UART mode: An external USB-to-serial converter, or the built-in UART on the Pi's TX/RX pins. Here's an example of wiring up the US100 to a USB-to-serial converter:

USB serial 5V to sensor VCC
USB serial GND to sensor GND
USB serial TX to sensor trig/TX
USB serial RX to sensor echo/RX

Note: Typically with UART, you connect TX to RX and RX to TX, this is not the case with this sensor!

For single board computers other than the Raspberry Pi, the serial port may be tied to the console or not be available to the user. Please see the board documentation to see how the serial port may be used

Here's an example with the US100 using the Pi's built-in UART:

Pi 3V to sensor VCC
Pi GND to sensor GND
Pi TX to sensor trig/TX
Pi RX to sensor echo/RX

Note: Typically with UART, you connect TX to RX and RX to TX, this is not the case with this sensor!

If you want to use the built-in UART, you'll need to disable the serial console and enable the serial port hardware in raspi-config. See the UART/Serial section of the CircuitPython on Raspberry Pi guide for detailed instructions on how to do this.

CircuitPython Installation of HC-SR04 / US-100 Library

To use the HC-SR04, you'll need to install the Adafruit CircuitPython HCSR04 library on your CircuitPython board.

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.

For the HCSR04 - You'll want to copy the necessary libraries from the bundle to your lib folder on your CIRCUITPY drive:

adafruit_hcsr04.mpy
adafruit_bus_device

Before continuing make sure your board's lib folder has the adafruit_hcsr04.mpy, and adafruit_bus_device files and folders copied over.

For the US100 you'll want to copy the necessary libraries from the bundle to your lib folder on your CIRCUITPY drive:

adafruit_us100.mpy
adafruit_bus_device

Before continuing make sure your board's lib folder has the adafruit_us100.mpy, and adafruit_bus_device files and folders copied over.

Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.

Python Installation of HC-SR04 / US100 Library

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

Once that's done, from your command line run the following command

sudo pip3 install adafruit-circuitpython-hcsr04 adafruit-circuitpython-us100

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

CircuitPython & Python Usage of HC-SR04

The following works for both the HC-SR04, and the US-100 in HC-SR04 compatibility mode.

To demonstrate usage of these sensors, we will initialise it and read the distance using the board's Python REPL.

Run the following code to import the necessary modules and initialize the connection with the sensor:

Download File

Copy Code

import time
import board
import adafruit_hcsr04
sonar = adafruit_hcsr04.HCSR04(trigger_pin=board.D5, echo_pin=board.D6)

import time
import board
import adafruit_hcsr04
sonar = adafruit_hcsr04.HCSR04(trigger_pin=board.D5, echo_pin=board.D6)

Now you're ready to read the values from the sensor using the following property:

distance - The distance measured by the sensor in cm.

Download File

Copy Code

while True:
    try:
        print((sonar.distance,))
    except RuntimeError:
        print("Retrying!")
    time.sleep(0.1)

while True:
    try:
        print((sonar.distance,))
    except RuntimeError:
        print("Retrying!")
    time.sleep(0.1)

That's all there is to using the HC-SR04 and the US-100 in HC-SR04 compatibility mode with CircuitPython or Python!

CircuitPython & Python Usage of US-100

To demonstrate the usage of this sensor, we will initialise it and read the distance using the board's Python REPL.

For use on a microcontroller, run the following code to import the necessary modules and initialise the connection with the sensor:

Download File

Copy Code

import board
import busio
import adafruit_us100
uart = busio.UART(board.TX, board.RX, baudrate=9600)
us100 = adafruit_us100.US100(uart)

import board
import busio
import adafruit_us100
uart = busio.UART(board.TX, board.RX, baudrate=9600)
us100 = adafruit_us100.US100(uart)

For use on a computer with a USB-to-serial cable, run the following code:

Download File

Copy Code

import serial
import adafruit_us100
uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=1)
us100 = adafruit_us100.US100(uart)

import serial
import adafruit_us100
uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=1)
us100 = adafruit_us100.US100(uart)

For use on Raspberry Pi/Linux using hardware UART, run the following code:

Download File

Copy Code

import serial
import adafruit_us100
uart = serial.Serial("/dev/ttyS0", baudrate=9600, timeout=1)
us100 = adafruit_us100.US100(uart)

import serial
import adafruit_us100
uart = serial.Serial("/dev/ttyS0", baudrate=9600, timeout=1)
us100 = adafruit_us100.US100(uart)

Now you're ready to read the values from the sensor using the following properties:

distance - the distance measured by the sensor in cm.
temperature - the on-chip temperature in Celsius.

Download File

Copy Code

print("Distance: ", us100.distance)
print("Temperature: ", us100.temperature)

print("Distance: ", us100.distance)
print("Temperature: ", us100.temperature)

Full Example Code

For HC-SR04:

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
import adafruit_hcsr04

sonar = adafruit_hcsr04.HCSR04(trigger_pin=board.D5, echo_pin=board.D6)

while True:
    try:
        print((sonar.distance,))
    except RuntimeError:
        print("Retrying!")
    time.sleep(0.1)

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
import adafruit_hcsr04

sonar = adafruit_hcsr04.HCSR04(trigger_pin=board.D5, echo_pin=board.D6)

while True:
    try:
        print((sonar.distance,))
    except RuntimeError:
        print("Retrying!")
    time.sleep(0.1)

For US-100:

Note: The delay between the temperature reading and the distance reading is required for use on Raspberry Pi/Linux. Due to the increased speed over a microcontroller, the distance reading occurs too quickly after the temperature reading and the sensor doesn't process the response properly. If you find the code is hanging on the distance reading, ensure you have the delay!

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time

# For use with a microcontroller:
import board
import busio
import adafruit_us100

uart = busio.UART(board.TX, board.RX, baudrate=9600)

# For use with USB-to-serial cable:
# import serial
# import adafruit_us100
# uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=1)

# For use with Raspberry Pi/Linux:
# import serial
# import adafruit_us100
# uart = serial.Serial("/dev/ttyS0", baudrate=9600, timeout=1)

us100 = adafruit_us100.US100(uart)

while True:
    print("-----")
    print("Temperature: ", us100.temperature)
    time.sleep(0.5)
    print("Distance: ", us100.distance)
    time.sleep(0.5)

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

import time

# For use with a microcontroller:
import board
import busio
import adafruit_us100

uart = busio.UART(board.TX, board.RX, baudrate=9600)

# For use with USB-to-serial cable:
# import serial
# import adafruit_us100
# uart = serial.Serial("/dev/ttyUSB0", baudrate=9600, timeout=1)

# For use with Raspberry Pi/Linux:
# import serial
# import adafruit_us100
# uart = serial.Serial("/dev/ttyS0", baudrate=9600, timeout=1)

us100 = adafruit_us100.US100(uart)

while True:
    print("-----")
    print("Temperature: ", us100.temperature)
    time.sleep(0.5)
    print("Distance: ", us100.distance)
    time.sleep(0.5)

This guide was first published on Dec 04, 2019. It was last updated on Dec 04, 2019.

This page (Python & CircuitPython) was last updated on Aug 12, 2022.