Steve Bertrand

NAME

RPi::HCSR04 - Interface to the HC-SR04 ultrasonic distance measurement sensor on the Raspberry Pi

SYNOPSIS

    use RPi::HCSR04;

    my $trig_pin = 23;
    my $echo_pin = 24;

    my $sensor = RPi::HCSR04->new($trig_pin, $echo_pin);

    my $inches = $sensor->inch;
    my $cm     = $sensor->cm;
    my $raw    = $sensor->raw;

    ...

DESCRIPTION

Easy to use interface to retrieve distance measurements from the HC-SR04 ultrasonic distance measurement sensor.

Requires wiringPi to be installed.

TIMING WITHIN A LOOP

This software does no timing whatsoever; it operates as fast as your device will allow it.

This often causes odd results. It's recommended that if you put your checks within a loop, to sleep for at least two milliseconds (0.02). You can use select(undef, undef, undef, 0.02);, or usleep() from Time::HiRes.

VOLTAGE DIVIDER

The HC-SR04 sensor requires 5V input, and that is returned back to a Pi GPIO pin from the ECHO output on the sensor. The GPIO on the Pi can only handle a maximum of 3.3V in, so either a voltage regulator or a voltage divider must be used to ensure you don't damage the Pi.

Here's a diagram showing how to create a voltage divider with a 1k and a 2k Ohm resistor to lower the ECHO voltage output down to a safe ~3.29V. In this case, TRIG is connected to GPIO 23, and ECHO is connected to GPIO 24.

METHODS

new

Instantiates and returns a new RPi::HCSR04 object.

Parameters:

    $trig

Mandatory: Integer, the GPIO pin number of the Raspberry Pi that the TRIG pin is connected to.

    $echo

Mandatory: Integer, the GPIO pin number of the Raspberry Pi that the ECHO pin is connected to.

inch

Returns a floating point number containing the distance in inches. Takes no parameters.

cm

Returns a floating point number containing the distance in centemetres. Takes no parameters.

raw

Returns an integer representing the return from the sensor in raw original form. Takes no parameters.

REQUIREMENTS

  • wiringPi must be installed.

  • You must regulate the voltage from the ECHO pin down to a safe 3.3V from the 5V input. See "VOLTAGE DIVIDER" for details.

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2017 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.