SonarI2C-RPi

Raspberry Pi Python library for the Octosonar breakout board by Alastair Young.

Links to Alastair's pages:
The original Arduino library: github.com
Hackaday: hackaday.io
Blog: redhunter.com
Buy it on Tindie: tindie.com

Summary

This is a Raspberry Pi Python library for the Octosonar by Alastair Young.

The Octosonar is a breakout board for connecting eight ultrasonic sensors (HC-SR04) to a microcontroller (Arduino). This library adds support for the Raspberry Pi as well. It's connected via I2C and only needs three pins (SCL/SDA and INT) on the Pi.

Will also work with a PCF8574 expander and a NOR gate. See Alastair's links above for more information on how to set that up.

Note: This is not a direct port of the Arduino library. It works perfectly with the Octosonar but the functions and classes are not the same.

Supported Platforms

Raspberry Pi (any model) with Python. Tested with Python 2.7 and Python 3.4

Getting Started

Hardware Set Up

Warning:
The Octosonar is a 5V device. You will need an I2C capable logic level converter or you WILL damage your Raspberry Pi! Do NOT connect the Octosonar directly to the Raspberry Pi!

It has been tested with this level converter from Adafruit. https://www.adafruit.com/product/757
SparkFun also has one. https://www.sparkfun.com/products/12009

It should work with any I2C capable logic level converter.

Software Requirements

This library requires the pigpio library. You can download it here: http://abyz.co.uk/rpi/pigpio/

To install it with PIP:

Python 2.x

pip install pigpio

Python 3.x

pip3 install pigpio

The pigpio deamon needs to be started for the pigpio library to work.

sudo pigpiod

Example Code

Example code is available in the src directory in the repository.

The code triggers all sonars in order (0-7) and prints a list containing the results. Press CTRL-C to cancel.

You will need to adjust the line octosonar = SonarI2C(pi, int_gpio=25) to suit your setup. See documentation below for the class. Example: octosonar = SonarI2C(pi, int_gpio=25, bus=1, addr=0x3d, max_range_cm=400)

Adjust the time.sleep(0.01) delay to suit your needs. Might be needed if you get a lot of echoes and false readings as the echos might spread to other sonars.

from SonarI2C import SonarI2C
import pigpio
import time

print("Press CTRL-C to cancel.")
pi = pigpio.pi()
if not pi.connected:
    exit(0)
try:
    octosonar = SonarI2C(pi, int_gpio=25)
    result_list = []
    while True:
        for i in range(8):
            sonar_result = octosonar.read_cm(i)
            time.sleep(0.01)
            if sonar_result is False:
                result_list.append("Timed out")
            else:
                result_list.append(round(sonar_result, 1))
        print(result_list)
        result_list = []

except KeyboardInterrupt:
    print("\nCTRL-C pressed. Cleaning up and exiting.")
finally:
    octosonar.cancel()
    pi.stop()

Class Definitions

Class SonarI2C

   Arguments:
    pi          -- pigpio instance
    int_gpio    -- the GPIO connected to the octosonars INT pin.
                   BCM numbering.
    bus         -- The i2c bus number, set 0 for the first Raspberry Pi
                   model with 256MB ram, else 1.
                   default: 1
    addr        -- i2c address of the octosonar.
                   default: 0x3d
    max_range_cm-- Maximum range for the sonars in centimeters.
                   default: 400

Example: octosonar = SonarI2C(pi, int_gpio=25, bus=1, addr=0x3d, max_range_cm=400)

SonarI2C.read()

    Takes a measurement on a port on the Octosonar.
    Not adjusted for round trip. This is the number of
    microseconds that the INT pin is high.

    Arguments:
    port    -- port on the Octosonar, Valid values: 0-7
    Returns: Distance in microseconds. False if timed out.

Example: octosonar.read(0)

SonarI2C.read_cm()

    Takes a measurement on a port on the Octosonar.
    Adjusted for round trip. Returns real distance to
    the object.

    Arguments:
    
    port    -- port on the Octosonar, Valid values: 0-7
    Returns: Distance in centimeters. False if timed out.

Example: octosonar.read_cm(0)

SonarI2C.read_inch()

    Takes a measurement on a port on the Octosonar.
    Adjusted for round trip. Returns real distance to
    the object.

    Arguments:
    
    port    -- port on the Octosonar, Valid values: 0-7
    Returns: Distance in inches. False if timed out.

Example: octosonar.read_inch(0)

SonarI2C.cancel()

    Cancels the Octosonar and cleans up resources.

Example: octosonar.cancel()