EV3 and Brian Sensors¶

Brian allows you to work with four different types of sensors:

EV3 Touch Sensor
EV3 Color Sensor
EV3 Ultrasonic Sensor
EV3 Gyroscopic Sensor

If you are using Brian sensors, you can use them exactly the same way as EV3 sensors.

Initialisation and Connection¶

First, you have to initialize the sensor. You must specify the sensor type and port (S1, S2, S3, S4). Here is an example of initialization:

import brian.sensors as sensors

TS = sensors.EV3.ColorSensorEV3(sensors.SensorPort.S1)
CS = sensors.EV3.TouchSensorEV3(sensors.SensorPort.S2)
US = sensors.EV3.UltrasonicSensorEV3(sensors.SensorPort.S3)
GS = sensors.EV3.GyroSensorEV3(sensors.SensorPort.S4)

Now you can use your own names to control sensors, just separate method with dot. For example TS.is_connected().

After initialisation, you have to check, whether is sensor ready. These functions will help you:

is_connected¶

is_connected(self) → bool

Returns:: True iff sensor is connected and not in the process of rebooting, False otherwise

is_ready¶

is_ready(self) → bool

Ready-state indicates that the attempt to read values will give valid results. Example reasons for invalid results:

Sensor is not connected (is_connected returns False)
Sensor is rebooting or not initiated yet
Sensor is changing modes and the change is not finished yet
Connected sensor is incompatible with this handler (e.g. wrong type of sensor is connected)

In all of the above cases, this function will return False. :return: True iff values are ready for the next read, False otherwise

wait_until_ready¶

wait_until_ready(self, timeout_ms: int = -1) → bool

Waits until the sensor is ready. This function is blocking. When changing modes, the sensor enters a “not ready” state for a short period (until the mode change is propagated). Therefore, it is recommended to first set the correct mode using set_mode() before the calling this function. This only applies to sensors with modes.

Parameters:

timeout_ms – Maximum number of milliseconds to wait. If the timeout is negative, the function will wait indefinitely.

Return success:

True: The sensor is ready.
False: The sensor is not ready and time ran out.

reboot¶

reboot(self) → None

Turn off power to the port and turn it back on. This will forcibly reboot the sensor.

The powered-down state lasts about 100ms. In case of some (mostly digital) sensors, there can be some additional time (~1s or more) to boot up and process connection handshake with Brian.

EV3 Touch Sensor¶

class brian.sensors.EV3.TouchSensorEV3.TouchSensorEV3(
   port: SensorPort
)

is_pressed¶

is_pressed(self) → bool

Measures the sensor state. Returns boolean of the last button pressed state. If the sensor is not ready, returns False.

Returns:: True if the sensor button is pressed, False otherwise. Or False if the sensor is not ready.
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

wait_for_press¶

wait_for_press(self, timeout_ms: int = -1) → bool

Waits for next button press event. This function is blocking.

Parameters:

timeout_ms – Maximum number of milliseconds to wait. If the timeout is negative, the function will wait indefinitely.

Return success:

True: If the desired button event was caught.
False: If the timeout ran out.

wait_for_release¶

wait_for_release(self, timeout_ms: int = -1) → bool

Waits for next button release event. This function is blocking.

Parameters:

timeout_ms – Maximum number of milliseconds to wait. If the timeout is negative, the function will wait indefinitely.

Return success:

True: If the desired button event was caught.
False: If the timeout ran out.

wait_for_press_and_release¶

wait_for_press_and_release(self, timeout_ms: int = -1) → bool

Waits for next button press and release event. This function is blocking.

Parameters:

timeout_ms – Maximum number of milliseconds to wait. If the timeout is negative, the function will wait indefinitely.

Return success:

True: If the desired button event was caught.
False: If the timeout ran out.

EV3 Color Sensor¶

class brian.sensors.EV3.ColorSensorEV3.ColorSensorEV3(
   port: SensorPort
)

EV3 Color Sensor can operate in 5 different modes:

REFLECT = 0
AMBIENT = 1
COLOR_DETECT = 2
REFLECT_RAW = 3
RGB_RAW = 4

You can set mode with the function set_mode(). For example:

import brian.sensors as sensors
CS = sensors.EV3.ColorSensorEV3(sensors.SensorPort.S1)

CS.set_mode(CS.Mode.REFLECT) # set REFLECT mode
CS.set_mode(CS.Mode(1)) # set AMBIENT mode

Besides NO_COLOR, there are 7 colors detected by Color Sensor: BLACK, BLUE, GREEN, YELLOW, RED, WHITE, BROWN.

Example of how to access color name:

import brian.sensors as sensors
CS = sensors.EV3.ColorSensorEV3(sensors.SensorPort.S1)

print(CS.Color(1)) # print the name of color Black

Next usage of Color Sensor is by method RawRGB (red, green, blue). Colors given are represented by numbers in the range [0-1023]. Example usage:

import brian.sensors as sensors
CS = sensors.EV3.ColorSensorEV3(sensors.SensorPort.S1)

CS.set_mode(CS.Mode(4)) # set RGB_RAW mode
CS.wait_until_ready() # wait until sensor is ready

rgb = CS.rgb_values_raw() # store rgb values
print(rgb[0]) # print red values

set_mode¶

set_mode(self, 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 SensorIsNotReady exceptions.

Parameters:: mode – desired mode to be set

reflected_value¶

reflected_value(self) → int

Sets the sensor mode to REFLECT and returns the last value.

Returns:: reflectivity in % (0-100).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

REFLECT mode: Measure surface reflectivity for red light. The values are calibrated within the sensor itself. Returns the values in percent, in range 0-100. The measurement is corrected for the ambient light change.

reflected_value_raw¶

reflected_value_raw(self) → int

Sets the sensor mode to REFLECT_RAW and returns the last value.

Returns:: reflectivity raw values (0-1023).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

REFLECT_RAW mode: Measure surface reflectivity for red light. The values are uncalibrated. Code using this function must thus perform range scaling/shifting manually. Measuring in this mode should provide more resolution over REFLECT mode. Returns values in range 0-1023. The measurement is corrected for the ambient light change.

ambient_value¶

ambient_value(self) → int

Sets the sensor mode to AMBIENT and returns the last value.

Returns:: ambient in % (0-100).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

AMBIENT mode: Measure ambient light intensity. The values are calibrated within the sensor itself. Returns the values in percent, in range 0-100.

detected_color¶

detected_color(self) → Color

Sets the sensor mode to COLOR_DETECT and returns the last value.

Returns:: color constants corresponding to Color.[COLOR].
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

COLOR_DETECT mode: Measure and discriminate the color. The discrimination is provided by the sensor itself. If this works poorly for your use case, you can use RGB_RAW instead.

get_color_name¶

get_color_name(color: Color) → str

Parameters:: color – Color to get the name of.
Returns:: English name of the provided color. This is a convenience function for UI or logging.

rgb_values_raw¶

rgb_values_raw(self) → RawRGB

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

Returns:: RGB raw values (0-1023 each channel). You can access them with RGB.red, RGB.green and RGB.blue, or by using subscription (RGB[0], RGB[1], …)
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

RGB_RAW mode: Measure surface reflectivity for red, green and blue light. The values are uncalibrated. Code using this function must thus perform range scaling/shifting manually. The measurement is corrected for the ambient light change.

EV3 Ultrasonic Sensor¶

class brian.sensors.EV3.UltrasonicSensorEV3.UltrasonicSensorEV3(
   port: SensorPort
)

EV3 Ultrasonic Sensor can operate in 5 different modes:

DISTANCE_MM = 0
DISTANCE_TENTHS_OF_INCH = 1
DETECT_OTHER_US = 2
SINGLESHOT_MM = 3
SINGLESHOT_TENTHS_OF_INCH = 4

You can set mode with the function set_mode(). For example:

import brian.sensors as sensors
US = sensors.EV3.UltrasonicSensorEV3(sensors.SensorPort.S1)

US.set_mode(US.Mode.DISTANCE_MM) # set DISTANCE_MM mode
US.set_mode(US.Mode(1)) # set DISTANCE_TENTHS_OF_INCH mode

set_mode¶

set_mode(self, 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 SensorIsNotReady exceptions.

Parameters:: mode – desired mode to be set

distance_mm¶

distance_mm(self) → int

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

Returns:: distance in mm (0-2550). Or 2550 it reported a measurement error.
Raises:: brian.sensors.SensorIsNotReadyError – 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.

distance_tenths_of_inch¶

distance_tenths_of_inch(self) → int

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

Returns:: distance in tenths of an inch (0-1003).
Raises:: brian.sensors.SensorIsNotReadyError – 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.

last_single_shot_mm¶

last_single_shot_mm(self) → int

If the sensor is in SINGLESHOT_MM mode, returns the last value. If the sensor is in a different mode returns 2550. This method does not trigger the measurement. To trigger the measurement, use trigger_single_shot_measurement_mm().

Returns:: distance in mm (0-2550). Or 2550 if it reported a measurement error.
Raises:: brian.sensors.SensorIsNotReadyError – 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.

trigger_single_shot_measurement_mm¶

trigger_single_shot_measurement_mm(self) → 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.SensorIsNotReadyError – 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.

last_single_shot_tenths_of_inch¶

last_single_shot_tenths_of_inch(self) → int

If the sensor is in SINGLESHOT_TENTHS_OF_INCH mode, returns the last value. If the sensor is in a different mode, returns 1003. This method does not trigger the measurement. To trigger the measurement, use trigger_single_shot_measurement_tenths_of_inch()

Returns:: distance in tenths of an inch (0-1003). Or 1003 if it reported a measurement error.
Raises:: brian.sensors.SensorIsNotReadyError – 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. last_single_shot_tenths_of_inch

trigger_single_shot_measurement_tenths_of_inch¶

trigger_single_shot_measurement_tenths_of_inch(self) → 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.SensorIsNotReadyError – 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¶

is_other_us_detected(self) → bool

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

Returns:: True if other ultrasonic sensor is active and in range, False otherwise.
Raises:: brian.sensors.SensorIsNotReadyError – 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.

EV3 Gyroscopic Sensor¶

class brian.sensors.EV3.GyroSensorEV3.GyroSensorEV3(
   port: SensorPort
)

EV3 Gyroscopic Sensor can operate in 6 different modes:

ANGLE = 0
SPEED = 1
SPEED_COARSE = 2
ANGLE_AND_SPEED = 3
TILT_SPEED = 5
TILT_ANGLE = 6

You can set mode with the function set_mode(). For example:

import brian.sensors as sensors
GS = sensors.EV3.GyroSensorEV3(sensors.SensorPort.S1)

GS.set_mode(GS.Mode.ANGLE) # set ANGLE mode
GS.set_mode(GS.Mode(1)) # set SPEED mode

set_mode¶

set_mode(self, 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 SensorIsNotReady exceptions.

Parameters:: mode – desired mode to be set

angle¶

angle(self) → int

Sets the sensor mode to ANGLE and returns the last value.

Returns:: angle (int) in degrees (-32768 to 32768).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

ANGLE mode: Measures the tilt angle and returns the value in degrees in range -32768 to 32767.

Clockwise is positive when looking at the side of the sensor with the arrows.

If you spin around too many times in ANGLE, ANGLE_AND_SPEED or TILT_ANGLE mode, it will get stuck at 32767 or overflow through -32768 depending on when the sensor was manufactured.

speed¶

speed(self) → int

Sets the sensor mode to SPEED and returns the last value.

Returns:: angular speed in degrees/s (-500 to 500).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

SPEED mode: Measures angular speed and returns the value in degrees/second in range -500 to 500.

Clockwise is positive when looking at the side of the sensor with the arrows.

tilt_speed¶

tilt_speed(self) → int

Sets the sensor mode to Modes::TILT_SPEED and returns the last value.

Returns:: angular speed in degrees/s (-500 to 500).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

TILT_SPEED mode: Measures angular speed around a second axis and returns the value in degrees/second in range -500 to 500. Clockwise is positive when looking at the side of the sensor opposite the cable jack.

tilt_angle¶

tilt_angle(self) → int

Sets the sensor mode to TILT_ANGLE and returns the last value.

Returns:: angle (int) in degrees (-32768 to 32768).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

TILT_ANGLE mode: Measures the tilt angle around a second axis and returns the value in degrees in range -32768 to 32767.

This mode is not present in older sensors (date code ending with 2 or 3). Clockwise is positive when looking at the side of the sensor opposite the cable jack.

If you spin around too many times in “ANGLE”, “ANGLE_AND_SPEED” or “TILT_ANGLE” mode, it will get stuck at 32767 or overflow through -32768 depending on when the sensor was manufactured.

speed_coarse¶

speed_coarse(self) → int

Sets the sensor mode to SPEED_COARSE and returns the last value.

Returns:: angular speed in degrees/s (-1464 to 1535).
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

SPEED_COARSE mode: Measures angular speed and returns the value in degrees/second in range -1464 to 1535. Lower resolution, but wider range than the “SPEED” mode.

Clockwise is positive when looking at the side of the sensor with the arrows.

angle_and_speed¶

angle_and_speed(self) → Tuple[int, int]

Sets the sensor mode to ANGLE_AND_SPEED and returns the last value.

Returns:: Tuple consisting of two integers: - The first integer represents the angle (deg) measurement. - The second integer represents the speed (deg/s) measurement.
Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

ANGLE_AND_SPEED mode: Measures the tilt angle and angular speed and returns the value in degrees in range -32768 to 32767 for angle and -500 to 500 for speed.

Clockwise is positive when looking at the side of the sensor with the arrows. If you spin around too many times in “ANGLE”, “ANGLE_AND_SPEED” or “TILT_ANGLE” mode, it will get stuck at 32767 or overflow through -32768 depending on when the sensor was manufactured.

set_zero_point¶

set_zero_point(self) → None

Adjusts the angle readings to create new zero point angle. Adjusts angle only in “ANGLE”, “ANGLE_AND_SPEED” and “TILT_ANGLE” modes. Does not fix drift (for drift fixing, reboot the sensor using the reboot() function).

Raises:: brian.sensors.SensorIsNotReadyError – If the sensor is not ready.

reboot¶

reboot(self) → None

Reboots the sensor to force recalibration.

During the recalibration, keep the sensor steady to minimize drifting.

Reboot Turn off power to the port and turn it back on. This will forcibly reboot the sensor.

The powered-down state lasts about 100ms. In case of some (mostly digital) sensors, there can be some additional time (~1s or more) to boot up and process connection handshake with Brian.

Further Information¶

For further information about EV3 sensors, go check API Reference.