rangesensor

README

rangesensor

A package to take a distance measurement from an HC-SR04 ultrasonic range sensor.

Basic Usage

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/asjoyner/rangesensor"
)

func main() {

	s, err := rangesensor.New("22", "23")
	if err != nil {
		fmt.Println("could not configure pin: ", err)
		os.Exit(1)
	}

	for {
		distance, err := s.MeasureDistance()
		if err != nil {
			fmt.Println(err)
		} else {
			fmt.Printf("Distance: %5.2f cm", distance.InCentimeters())
			fmt.Printf(" (%d us)\n", distance.InMicroseconds())
		}
		time.Sleep(time.Duration(250) * time.Millisecond)
	}

}

Credit

This takes inspiration from both of these repositories.

• https://github.com/jdevelop/golang-rpi-extras
• https://godoc.org/github.com/ricallinson/engine

Both of those are based on github.com/stianeikeland/go-rpio. I chose to reimplement a similar basic mechanic on top of the periph.io/x/periph/conn/gpio library so it would be easier to add testing, use the more sysfs kernel API, and leverage the associated interrupt-based edge detection.

Documentation

Overview

Package rangesensor facilitates measuring distance with an HC-SR04 ultrasonic ranging module.

Index

• func TimeToCentimeters(timeOfFlight int64) float32
• type Measurement
  • func (r *Measurement) InCentimeters() float32
  • func (r *Measurement) InInches() float32
  • func (r *Measurement) InMicroseconds() int64
  • func (r *Measurement) InMilliseconds() int64
  • func (r *Measurement) Trustworthy() bool
• type Sensor
  • func New(echo, trigger string) (*Sensor, error)
  • func (s *Sensor) MeasureDistance() (*Measurement, error)

Functions

func TimeToCentimeters

func TimeToCentimeters(timeOfFlight int64) float32

TimeToCentimeters takes a distance measurement in microseconds and converts that into a distance measurement in centimeters using a series of transparent assumptions. I do this tediously in long-hand, so if I've made some mistake others can notice and correct it. :)

At the end of the day, this function divides by two and multiplies by 0.0344, which aligns with the datasheet's suggestion to just divide by 58 to get centimeters.

Types

type Measurement

type Measurement struct {
	// contains filtered or unexported fields
}

Measurement expresses a sensor measurement and facilitates conversion to various units.

func (*Measurement) InCentimeters

func (r *Measurement) InCentimeters() float32

InCentimeters converts the time of flight measurement into centimeters.

func (*Measurement) InInches

func (r *Measurement) InInches() float32

InInches converts the time of flight measurement into inches.

func (*Measurement) InMicroseconds

func (r *Measurement) InMicroseconds() int64

InMicroseconds returns the raw time of flight measurement.

func (*Measurement) InMilliseconds

func (r *Measurement) InMilliseconds() int64

InMilliseconds returns the raw time of flight measurement.

func (*Measurement) Trustworthy

func (r *Measurement) Trustworthy() bool

Trustworthy indicates the reliability of the measurement. The datasheet indicates claims the module can render distances out to 400cm, but the modules I have experience with are not accurate beyond 200cm. More importantly, a failed read will often return a spurious result, in the 1k+ cm range.

type Sensor

type Sensor struct {
	EchoPin    gpio.PinIO
	TriggerPin gpio.PinIO
}

Sensor represents an HC-SR04 ultrasonic ranging module.

Datasheet: https://cdn.sparkfun.com/datasheets/Sensors/Proximity/HCSR04.pdf

func New

func New(echo, trigger string) (*Sensor, error)

New initializes and returns a Sensor object.

Echo is the name of the GPIO pin connected to the module's "Echo" pin. Trigger is the name of the GPIO pin connected to the module's "Trig" pin.

Both names should be in the format expected by this module's ByName function periph.io/x/periph/conn/gpio/gpioreg

For a RaspberryPi, this corresponds to the BCM pin number as a string.

func (*Sensor) MeasureDistance

func (s *Sensor) MeasureDistance() (*Measurement, error)

MeasureDistance returns a distance measurement from the sensor.