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.
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
Warning
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).
Note
If you want to use an HC-SR04 with MicroPython, I recommend checking out this library.
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 "D
"
are digital).
There are two ways of instantiating a :class:`~hcsr04.HCSR04` object: with or without using a context manager.
Note
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.
.. seealso:: `Adafruit's guide on Lifetime and ContextManagers <https://circuitpython.readthedocs.io/en/latest/docs/design_guide.html#lifetime-and-contextmanagers>`_ Gives more info on using context managers with CircuitPython drivers. :any:`board` A list of pins available on your device. To view this list, first `get a REPL <http://circuitpython.readthedocs.io/en/latest/docs/pyboard/tutorial/repl.html>`_ (the guide linked was written for the pyboard, but it still works), then input the following: :: import board dir(board)
In the example below, we create the :class:`~hcsr04.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()
In the example below, we use a context manager (the :any:`with <with>` statement) to create the :class:`~hcsr04.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.