PiicoDev Ultrasonic Rangefinder | Getting Started Guide

To work with PiicoDev hardware, we need to download some drivers. The drivers provide all the functions to easily connect and communicate with PiicoDev hardware. Select your dev board from the options above.

This invisible tripwire project is a flexible starter project with loads of applications. You could set it up to range across a doorway - when somebody passes through the door a message is displayed. This is a useful starter project for other range-alert style projects - for example, you could create an invisible limbo-bar that tells you when somebody didn't limbo low enough!

The project is self-calibrating, meaning you don't have to manually set any range thresholds. The tripwire will adapt to a steady-state range, and if it detects any sudden, large errors in the range measurement a trip event is reported. This is handled by continuously updating an average range (using exponential smoothing). A trip event occurs when any one range sample deviates too far from the average.

# A self-calibrating tripwire that looks for gross changes in distance
# Slowly calibrates for new distances - no manual tuning required.

from PiicoDev_Ultrasonic import PiicoDev_Ultrasonic
from PiicoDev_Unified import sleep_ms
 
ranger = PiicoDev_Ultrasonic() # Initialise the rangefinder

tuning = 0.1                   # a tuning parameter that affects how quickly new distances are calibrated
sensitivity = 50               # [mm] any change greater than this amount will count as a trip
average = ranger.distance_mm   # Initialise the moving average with a range sample

sleep_ms(1000)

while True:
    
    distance = ranger.distance_mm    
    print(distance, average)
    
    # check if the wire has been tripped
    if abs(average - distance) > sensitivity:
        print("Trip!")
        ranger.led = True # Indicate a trip
    else:
        ranger.led = False
        
    # update the moving average https://en.wikipedia.org/wiki/Exponential_smoothing
    average = tuning * distance + (1 - tuning) * average
    
    sleep_ms(100)

A theremin is a musical instrument controlled without physical contact. Real theremins use changing electric fields to control the sound output - here we can use the hands proximity to the Ultrasonic Rangefinder. Hold your hand closer to produce lower notes, and farther away to produce higher notes.

This project requires a PiicoDev Buzzer, and the PiicoDev_Buzzer.py module.

# A non-contact musical instrument. Hold your hand near the rangefinder and move
# closer or farther to play different notes.

from PiicoDev_Ultrasonic import PiicoDev_Ultrasonic
from PiicoDev_Buzzer import PiicoDev_Buzzer
from PiicoDev_Unified import sleep_ms
 
ranger = PiicoDev_Ultrasonic() # Initialise the rangefinder
buzzer = PiicoDev_Buzzer()

def get_note_from_distance(distance):
    """Converts a distance [mm] to a note [Hz] from a supplied scale"""
    scale_Hz = [523, 587, 659, 698, 784, 880, 988, 1047] # Cmajor scale
    note_number = round( (distance - 100) / 50 ) # spaces notes 50mm apart, starting 100mm away from the rangefinder
    
    # make sure the note stays within bounds
    if 0 <= note_number < len(scale_Hz):
        return scale_Hz[note_number]
    else:
        return 0 # silence if not being actively played

note_duration = 250 # [ms]
while True:
    distance = ranger.distance_mm        
    note = get_note_from_distance(distance)
    buzzer.tone(note, note_duration)
    
    print(distance, note)
    
    sleep_ms(note_duration)

This project uses the plotter in Thonny to draw a simple obstacle-avoiding, 2D-scrolling game - similar to Flappy Bird or the timeless classic Helicopter Game. The player flies through a winding cave and must avoid crashing into the walls. The player position is controlled by the Ultrasonic Rangefinder.  The cave is procedurally generated - the frame counter drives a generate_cave() function which uses simple trig functions (sin, cos) to create an infinite cave.

This project requires a PiicoDev Buzzer, and the PiicoDev_Buzzer.py module.

# Cave explorer game. Use the ultrasonic rangefinder to control the position of the player as you
# fly through a narrow, winding cave. Don't crash into the walls!

import math
from PiicoDev_Ultrasonic import PiicoDev_Ultrasonic
from PiicoDev_Buzzer import PiicoDev_Buzzer
from PiicoDev_Unified import sleep_ms
 
ranger = PiicoDev_Ultrasonic() # Initialise the rangefinder
buzzer = PiicoDev_Buzzer() # Initialise the buzzer


def generate_cave():
    """generate a new cave floor and ceiling based of the frame number. Changing these constants will affect game difficulty"""
    floor = range + \
                 range/2 * math.sin(2*math.pi * frame/200) + \
                 range/4 * math.cos(2*math.pi * frame/88)  + \
                 range/4 * math.sin(2*math.pi * frame/33)
    
    ceiling = floor + cave_size
    return floor, ceiling

def player_in_bounds():
    return player > cave_floor and player < cave_ceiling

def play_start_sound():
    buzzer.tone(1200,300)

def play_crash_sound():
    buzzer.tone(1200,300)
    sleep_ms(300)
    buzzer.tone(600,300)

#################
# Game Variables
#################

cave_size = 150   # height of the cave
cave_floor = 150  # starting floor height
range = 150       # how much room the player needs to move around
frame = 0         # frame counter is used to generate the cave, and keep score

bound_counter = 0 # how many frames the player was out of bounds. glitches happen, so we look for consecutive out-of-bounds to trigger a crash

state = 'prestart'
print("Game starts when player is in bounds")
sleep_ms(1000)

while True:
    
    # Update the game
    cave_floor, cave_ceiling = generate_cave()
    player = ranger.distance_mm
    
    # Check for out-of-bounds
    if player_in_bounds():
        bound_counter = 0
        if state == 'prestart':
            state = 'play'
            play_start_sound()
    else:
        bound_counter += 1
        
    
    # Plot the game state
    print(f"{player} {cave_ceiling} {cave_floor} 0 {2*range + cave_size}")
    
    # Crash when out of bounds for consecutive frames
    if bound_counter > 2 and state == 'play':
        print(f"You crashed! Score: {frame}")
        play_crash_sound()
        break;
       
    frame += 1
    sleep_ms(100)