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:

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

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

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:

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

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:

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

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.

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

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:

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.

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:

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:

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:

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.

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

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

Full Example Code

For HC-SR04:

# 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!

# 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(f"Temperature: {us100.temperature}°C")
    time.sleep(0.5)
    print(f"Distance: {us100.distance} cm")
    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(f"Temperature: {us100.temperature}°C")
    time.sleep(0.5)
    print(f"Distance: {us100.distance} cm")
    time.sleep(0.5)