jex-y / hc-sr04_driver

Linux driver to read a distance sensor

HC-SR04 Raspberry Pi Driver

This driver is designed to make reading the distance from the senor as simple as possible.

Build Instructions

git clone https://github.com/Jex-y/HC-SR04_driver
cd HC-SR04_driver
sudo apt install raspberrypi-kernel-headers
make
sudo insmod hcsr04_sensor.ko

To immediately load the module run:

sudo insmod hcsr04_sensor.ko

Note that this means that the driver will be removed on reboot. To load it on boot:

sudo mkdir -p /lib/modules/$(uname -r)/kernel/drivers/sensors
sudo cp hcsr04_sensor.ko /lib/modules/$(uname -r)/kernel/drivers/sensors
sudo depmod

and add the line hcsr04_sensor to /etc/modules

Usage

The device created is /dev/hcsr04

The GPIO pins can be set by writing to the device file and the round trip time in microseconds (as the bytes of an unsigned long) can be read from this file.

Example

ECHO_PIN = 3
TRIG_PIN = 2

with open('/dev/hcsr04', 'w') as file:
    file.write(f'ECHO {ECHO_PIN:02d}')
    file.write(f'TRIG {TRIG_PIN:02d}')

with open('/dev/hcsr04', 'rb') as file:
    data = file.read()

trip = int.from_bytes(data, 'little')
secs = trip * 1e-6 / 2
dist = 340 * secs
print(f'Total roundtrip took {trip} us, this gives us a distance of {dist * 100:.2f} cm')

Limitations

• Note that the driver requires that the pin numbers are zero padded to two digits so that the input is a constant length.
• The return value of a read is the single round trip time in microseconds. Conversion to distance should be done in higher level code as the user may want to account for pressure, temperature, humiditity etc. that affect the speed of sound.

hc-sr04_driver's Issues

Sensor giving inaccurate and inconsistent readings for distances > 1m

When trying to read distances of over about 1m the sensor returns values of 186000us-187000us with varying frequencies e.g. about 40% and 1.4 meters.

These values are about 30-32 meters and are just under half the timeout value for the sensor.

This is not expected behaviour for a timeout as the value returned should be MAX_ULONG.

Driver deals with writes incorrectly

When writing to the driver in python, the buffer is not flushed between writes therefore the driver receives all of the input at once. This causes a buffer overflow.

install instructions are wrong

The instructions to install the driver are repeated which appears to be a typo, remove one of them.

Driver deals with reading incorrectly

The driver does not take into account the offset when being read. This means that if

cat /dev/hcsr04_device

is called it repeatedly reads the sensor rather than once.

Sensor timeout does not work

When trying to use the driver without the sensor plugged in, the driver does not timeout but instead hangs.

Sensor Timeout

The sensor is not able to read distances due to what appears to be a timeout error.

Driver requires root permissions to read

When calling cat /dev/hcsr04_device as normal user getting permission denied.

Sensor Time Variability

The sensors seems to be outputting changing values as it repeats the short distance test. Possibly due to echoes or background vibrations.