hcsr04sensor - Python Module

Contributing

Use Python to calculate distance and depth measurements with an HCSR04 Ultrasonic Sound Sensor and a Raspberry Pi.

The module does the following;

• Returns an error corrected distance by using the median reading of a sorted sample. NOTE - The default sample size is 11 readings.

  This module uses BCM pin values. See the Raspberry Pi pin layout documentation for your model.

• Rounds the value to a specified decimal place.

• Adjusts the reading based on temperature by adjusting the speed of sound.

• Allows measuring distance or depth in metric and imperial units.

• Raises an exception if a faulty cable or sensor prevents an echo pulse from being received.

Connecting the Sensor

• 5V VCC which connects to a 5V pin on the Raspberry Pi
• Trig Pin which connects to a valid GPIO pin. Diagram uses GPIO pin 17.
• Echo Pin which connects to a valid GPIO pin. Diagram uses GPIO pin 27.
• Ground which connects to any valid ground pin on the Raspberry Pi



GPIO pins are rated for 3.3V so you must insert a voltage divider as the power pin on the PI is 5V. In the above diagram a 470 Ohm resistor is soldered on the echo wire. A 1000 Ohm resistor is soldered between the echo and ground wires. This reduces voltage to GPIO pin 27 to 3.4V which is within a tolerable level. Failure to do this can damage your board.

Voltage divider calculator courtesy ohmslawcalculator.com.
Soldering tutorial (youtube) courtesy Xrobots James Bruton.

Installing hcsr04sensor

hcsr04sensor available on PyPi

Python 3

sudo pip3 install hcsr04sensor

Python 2

sudo pip install hcsr04sensor

Testing Your HCSR04 Sensor

Installation of the module also installs the hcsr04.py utility to /usr/local/bin. This utility allows you to take a quick measurement for testing your sensor.

Usage

pi@raspberry:~ $ hcsr04.py -h
usage: hcsr04.py [-h] -t TRIG -e ECHO [-sp SPEED] [-ss SAMPLES]

Script tests the HCSR04 sensor under different configurations

optional arguments:
  -h, --help            show this help message and exit
  -t TRIG, --trig TRIG  Trig Pin (Required - must be an integer)
  -e ECHO, --echo ECHO  Echo Pin (Required - must be an integer)
  -sp SPEED, --speed SPEED
                        Time between individual reading samples (Optional -
                        must be a float, default is 0.1 seconds)
  -ss SAMPLES, --samples SAMPLES
                        Reading Sample Size (Optional - must be an integer,
                        default is 11)

Sample Output

pi@raspberry:~ $ hcsr04.py -t 17 -e 27
trig pin = gpio 17
echo pin = gpio 27
speed = 0.1
samples = 11

The imperial distance is 12.3 inches.
The metric distance is 31.2 centimetres.

Interfacing with the sensor from a Python Console

Example of a measurement from the Python console in three simple lines.

Python 3.4.2 (default, Oct 19 2014, 13:31:11) 
[GCC 4.9.1] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from hcsr04sensor import sensor
>>> value = sensor.Measurement(17, 27)
>>> value.raw_distance()
31.761826466140448

Measure a rounded distance in centimeters.

>>> raw_distance = value.raw_distance()
>>> distance_cm = value.distance_metric(raw_distance)
>>> distance_cm
31.8

Measure a rounded distance in inches.

>>> distance_inches = value.distance_imperial(raw_distance)
>>> distance_inches
12.5

Measure the depth of a liquid in a hole 50 centimeters deep.

>>> depth_metric = value.depth_metric(raw_distance, 50)
>>> depth_metric
18.2

Measure the depth of a liquid in a hole 20 inches deep.

>>> depth_imperial = value.depth_imperial(raw_distance, 20)
>>> depth_imperial
7.5

More Info

Get it on Github

Various recipes for measuring distance or liquid depth.

HCSR04 Specification Manual

Donate

---

---

Copyright © 2017 Al Audet
MIT License