brian.sensors.EV3.UltrasonicSensorEV3

brian.sensors.EV3

• UltrasonicSensorEV3
  • __init__
  • Mode
    • DISTANCE_MM
    • DISTANCE_TENTHS_OF_INCH
    • DETECT_OTHER_US
    • SINGLESHOT_MM
    • SINGLESHOT_TENTHS_OF_INCH
  • set_mode
  • distance_mm
  • distance_tenths_of_inch
  • last_single_shot_mm
  • trigger_single_shot_measurement_mm
  • last_single_shot_tenths_of_inch
  • trigger_single_shot_measurement_tenths_of_inch
  • is_other_us_detected

UltrasonicSensorEV3 class objects

class UltrasonicSensorEV3(Sensor)

Class for interacting with EV3 ultrasonic sensor.

Sensor is automatically registered in the constructor of the base class and un-registered in its destructor. It can also be unregistered with the UltrasonicSensorEV3.close_sensor() function.

There can be at most one instance at any given time, of any sensor class per port in the entire program.

__init__

def __init__(port: SensorPort)

Initialize a EV3 ultrasonic sensor at the given port.

Arguments:

• port: Sensor port to which the sensor is attached.

Mode class objects

class Mode(Enum)

Sensor modes for set_mode().

DISTANCE_MM

Continuous distance in mm, used by distance_mm()

DISTANCE_TENTHS_OF_INCH

Continuous distance in tenths of an inch, used by distance_tenths_of_inch()

DETECT_OTHER_US

Detection of another active ultrasonic sensor, used by is_other_us_detected()

SINGLESHOT_MM

Single-shot distance in mm, used by last_single_shot_mm()

SINGLESHOT_TENTHS_OF_INCH

Single-shot distance in tenths of an inch, used by last_single_shot_tenths_of_inch()

set_mode

def set_mode(mode: Mode) -> None

This function sets the sensor to the desired mode. While it’s not mandatory, it is recommended to call this

function before accessing values from the sensor in a specific mode to prevent SensorNotReady exceptions.

Arguments:

• mode: desired mode to be set

distance_mm

def distance_mm() -> int

Sets the sensor mode to DISTANCE_MM and return the last value.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. DISTANCE_MM mode: Continuously measures the distance and returns the value in mm. Returns the last measured distance in mm, in range 0-2550. If the measurement fails, the sensor reports a magic number (distance) of 2550.

Returns:

distance in mm (0-2550). Or 2550 it reported a measurement error.

distance_tenths_of_inch

def distance_tenths_of_inch() -> int

Sets the sensor mode to DISTANCE_TENTHS_OF_INCH and return the last value.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. DISTANCE_TENTHS_OF_INCH mode: Continuously measures the distance and returns the value in tenths of an inch. Returns the last measured distance in tenths of an inch, in range 0-1003. If the measurement fails, the sensor reports a magic number (distance) of 1003. distance_tenths_of_inch

Returns:

distance in tenths of an inch (0-1003).

last_single_shot_mm

def last_single_shot_mm(retrigger_measurement: bool = False) -> int

Returns the last single-shot measurement in mm.

If the sensor is already in SINGLESHOT_MM mode, returns the last value without triggering a new measurement (unless retrigger_measurement is True). If the sensor is in a different mode, sets the mode to SINGLESHOT_MM (which triggers a measurement) and waits for the result.

Arguments:

• retrigger_measurement: If True, always triggers a new measurement even if already in SINGLESHOT_MM mode. Note: Using retrigger_measurement=True will block until the measurement completes. For non-blocking behavior, use trigger_single_shot_measurement_mm() or set_mode(Mode.SINGLESHOT_MM) to trigger the measurement, then call last_single_shot_mm() later to retrieve the result.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. SINGLESHOT_MM mode: Activates once and measures the distance. After the measurement, the sensor goes to sleep and does not produce ultrasonic waves. This mode can be used when handling multiple ultrasonic sensors at the same time, to avoid interference between them. The single shot mode should not be called more often than about once in 250ms. Returns the last measured distance in mm, in range 0-2550. If the measurement fails, the sensor reports a magic number (distance) of 2550.

Returns:

distance in mm (0-2550). Or 2550 if it reported a measurement error.

trigger_single_shot_measurement_mm

def trigger_single_shot_measurement_mm() -> None

Sets the sensor mode to SINGLESHOT_MM and triggers the measurement.

Does not wait for the result and does not return anything.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. SINGLESHOT_MM mode: Activates once and measures the distance. After the measurement, the sensor goes to sleep and does not produce ultrasonic waves. This mode can be used when handling multiple ultrasonic sensors at the same time, to avoid interference between them. The single shot mode should not be called more often than about once in 250ms. Returns the last measured distance in mm, in range 0-2550. If the measurement fails, the sensor reports a magic number (distance) of 2550.

last_single_shot_tenths_of_inch

def last_single_shot_tenths_of_inch(
        retrigger_measurement: bool = False) -> int

Returns the last single-shot measurement in tenths of an inch.

If the sensor is already in SINGLESHOT_TENTHS_OF_INCH mode, returns the last value without triggering a new measurement (unless retrigger_measurement is True). If the sensor is in a different mode, sets the mode to SINGLESHOT_TENTHS_OF_INCH (which triggers a measurement) and waits for the result.

Arguments:

• retrigger_measurement: If True, always triggers a new measurement even if already in SINGLESHOT_TENTHS_OF_INCH mode. Note: Using retrigger_measurement=True will block until the measurement completes. For non-blocking behavior, use trigger_single_shot_measurement_tenths_of_inch() or set_mode(Mode.SINGLESHOT_TENTHS_OF_INCH) to trigger the measurement, then call last_single_shot_tenths_of_inch() later to retrieve the result.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. SINGLESHOT_TENTHS_OF_INCH mode: Activates once and measures the distance. After the measurement, the sensor goes to sleep and does not produce ultrasonic waves. This mode can be used when handling multiple ultrasonic sensors at the same time, to avoid interference between them. The single shot mode should not be called more often than about once in 250ms. Returns the last measured distance in tenths of an inch, in range 0-1003. If the measurement fails, the sensor reports a magic number (distance) of 1003.

Returns:

distance in tenths of an inch (0-1003). Or 1003 if it reported a measurement error.

trigger_single_shot_measurement_tenths_of_inch

def trigger_single_shot_measurement_tenths_of_inch() -> None

Sets the sensor mode to SINGLESHOT_TENTHS_OF_INCH and triggers the measurement.

Does not wait for the result and does not return anything.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. SINGLESHOT_TENTHS_OF_INCH mode: Activates once and measures the distance. After the measurement, the sensor goes to sleep and does not produce ultrasonic waves. This mode can be used when handling multiple ultrasonic sensors at the same time, to avoid interference between them. The single shot mode should not be called more often than about once in 250ms.

is_other_us_detected

def is_other_us_detected() -> bool

Sets the sensor mode to DETECT_OTHER_US and return the last value.

Raises:

• brian.sensors.SensorNotReadyError: If the sensor is not ready. DETECT_OTHER_US mode: Check if another ultrasonic sensor is active within the hearing distance of this sensor. Returns boolean value - True indicates that another ultrasonic sensor has been detected. A true value can also be triggered by a loud noise such as clapping.

Returns:

True if other ultrasonic sensor is active and in range, False otherwise.