MojoScale Studio Docs
API Reference

ultrasonic

Ultrasonic distance sensor module.

All modules Open Studio
Studio Docs Sensors & I/O

import ultrasonic

The ultrasonic module reads HC-SR04-style trigger/echo distance sensors. Create one sensor object with the trigger and echo pins, then ask for distance in the unit you need. The firmware enforces timeouts and a minimum measurement gap so a missing echo cannot lock up the device forever. Most HC-SR04 boards drive ECHO at 5V. Use a voltage divider or level shifter before connecting ECHO to an ESP32 GPIO.

Quick example

import ultrasonic
import system

sensor = ultrasonic.Ultrasonic(trigger=5, echo=18)
print(sensor.distance_cm())

def watch():
    reading = sensor.read()
    if reading["ok"] and reading["distance_cm"] < 30:
        print("object near", reading["distance_cm"])

system.schedule("distance", 1000, 1000, -1, watch)

stable = sensor.sample(count=5, interval_ms=60)
print(stable)

importultrasonic

Ultrasonic distance sensor module.

The ultrasonic module reads HC-SR04-style trigger/echo distance sensors. Create one sensor object with the trigger and echo pins, then ask for distance in the unit you need. The firmware enforces timeouts and a minimum measurement gap so a missing echo cannot lock up the device forever. Most HC-SR04 boards drive ECHO at 5V. Use a voltage divider or level shifter before connecting ECHO to an ESP32 GPIO.

API 15 available

ultrasonic.Ultrasonic(trigger: int, echo: int, max_distance_cm: float = None, temperature_c: float = None) -> ultrasonic_sensor

Create an ultrasonic distance sensor.

Parameters
Name Type Pass as Required Description
trigger int positional or keyword Yes GPIO output pin connected to the sensor TRIG input.
echo int positional or keyword Yes GPIO input pin connected to the sensor ECHO output.
max_distance_cm float positional or keyword No Optional maximum expected distance in centimeters. Defaults to 400. Used to derive the echo timeout.
temperature_c float positional or keyword No Optional ambient temperature in degrees Celsius. Defaults to 20. Used to adjust speed-of-sound conversion.
Returns

ultrasonic_sensor ultrasonic_sensor object.

ultrasonic.Ultrasonic().distance_cm() -> float

Trigger one measurement and return distance in centimeters, or nil if no valid echo is received.

ultrasonic.Ultrasonic().distance_mm() -> int

Trigger one measurement and return distance in millimeters, or nil if no valid echo is received.

ultrasonic.Ultrasonic().distance_m() -> float

Trigger one measurement and return distance in meters, or nil if no valid echo is received.

ultrasonic.Ultrasonic().duration_us() -> int

Trigger one measurement and return echo pulse width in microseconds, or nil if no valid echo is received.

ultrasonic.Ultrasonic().read() -> dict

Trigger one measurement and return ok, valid, error, distance_cm, distance_mm, distance_m, duration_us, timestamp_ms, pins, and configuration.

ultrasonic.Ultrasonic().sample(count=5, interval_ms=60) -> float

Take several readings, ignore invalid samples, and return the median distance in centimeters, or nil if none are valid.

Parameters
Name Type Pass as Required Description
count int positional or keyword No Optional value. Defaults to 5.
interval_ms int positional or keyword No Optional value. Defaults to 60.

ultrasonic.Ultrasonic().is_near(distance_cm, samples=1) -> bool

Return True when the measured distance is less than or equal to distance_cm. Measurement failure returns False.

Parameters
Name Type Pass as Required Description
distance_cm float positional or keyword Yes Required value.
samples int positional or keyword No Optional value. Defaults to 1.

ultrasonic.Ultrasonic().set_temperature(value_c) -> bool

Update ambient temperature compensation.

Parameters
Name Type Pass as Required Description
value_c any positional or keyword Yes Required value.

ultrasonic.Ultrasonic().set_max_distance(distance_cm) -> bool

Update maximum expected distance and derived timeout.

Parameters
Name Type Pass as Required Description
distance_cm float positional or keyword Yes Required value.

ultrasonic.Ultrasonic().configure(max_distance_cm=300, temperature_c=25, trigger_pulse_us=10, minimum_interval_ms=60) -> bool

Update measurement limits and timing.

Parameters
Name Type Pass as Required Description
max_distance_cm float positional or keyword No Optional value. Defaults to 300.
temperature_c float positional or keyword No Optional value. Defaults to 25.
trigger_pulse_us int positional or keyword No Optional value. Defaults to 10.
minimum_interval_ms int positional or keyword No Optional value. Defaults to 60.

ultrasonic.Ultrasonic().last() -> dict

Return the latest reading without triggering another measurement.

ultrasonic.Ultrasonic().reset() -> bool

Clear the latest reading and leave the sensor configured.

ultrasonic.Ultrasonic().info() -> dict

Return pins, timing, timeout, temperature compensation, and latest status.

ultrasonic.Ultrasonic().close() -> bool

Close the native sensor object.