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:
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:
|
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:
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:
|
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:
Note: Typically with UART, you connect TX to RX and RX to TX, this is not the case with this sensor! |
Here's an example with the US100 using the Pi's built-in UART:
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:
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:
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!
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)
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)
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)
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)
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)
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)
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("Temperature: ", us100.temperature) time.sleep(0.5) print("Distance: ", us100.distance) time.sleep(0.5)