The HC-SR04 is an inexpensive solution for measuring distances using microcontrollers. This library provides a simple driver for controlling these sensors from CircuitPython.
This driver depends on:
Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.
Installing from PyPI
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:
pip3 install adafruit-circuitpython-hcsr04
To install system-wide (this may be required in some cases):
sudo pip3 install adafruit-circuitpython-hcsr04
To install in a virtual environment in your current project:
mkdir project-name && cd project-name python3 -m venv .env source .env/bin/activate pip3 install adafruit-circuitpython-hcsr04
The HC-SR04 uses 5V logic, so you will have to use a level shifter between it and your CircuitPython board (which uses 3.3V logic).
You'll need to dedicate two pins to communicating with the HC-SR04. The sensor communicates in a very rudimentary
manner, so it doesn't matter which pins you choose, as long as they're digital IO pins (pins that start with "
There are two ways of instantiating a HCSR04 object: with or without using a context manager.
It is technically possible to communicate with the HC-SR04 using only one wire since the trigger and echo signals aren't ever active at the same time. Once I have a chance to determine a safe way to do this, I plan to add this as a feature to the library.
- Adafruit's guide on Lifetime and ContextManagers
- Gives more info on using context managers with CircuitPython drivers.
A list of pins available on your device. To view this list, first get a REPL (the guide linked was written for the pyboard, but it still works), then input the following:import board dir(board)
Without a Context Manager
In the example below, we create the HCSR04 object directly, get the distance every 2 seconds, then de-initialize the device.
from adafruit_hcsr04 import HCSR04 sonar = HCSR04(trig, echo) try: while True: print(sonar.dist_cm()) sleep(2) except KeyboardInterrupt: pass sonar.deinit()
With a Context Manager
In the example below, we use a context manager (the with statement) to create the HCSR04 instance, again get the distance every 2 seconds, but then the context manager handles de-initializing the device for us.
from adafruit_hcsr04 import HCSR04 with HCSR04(trig, echo) as sonar: try: while True: print(sonar.dist_cm()) sleep(2) except KeyboardInterrupt: pass
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
For information on building library documentation, please check out this guide.