Sensor classes¶
Note: If you are using a BrickPi rather than an EV3, you will need to manually configure the ports before interacting with your sensors. See the example here.
Dedicated sensor classes¶
These classes derive from ev3dev2.sensor.Sensor
and provide helper functions
specific to the corresponding sensor type. Each provides sensible property
accessors for the main functionality of the sensor.
Touch Sensor¶
-
class
ev3dev2.sensor.lego.
TouchSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
Touch Sensor
-
MODE_TOUCH
= 'TOUCH'¶ Button state
-
is_pressed
¶ A boolean indicating whether the current touch sensor is being pressed.
-
wait_for_pressed
(timeout_ms=None, sleep_ms=10)¶ Wait for the touch sensor to be pressed down.
-
wait_for_released
(timeout_ms=None, sleep_ms=10)¶ Wait for the touch sensor to be released.
-
wait_for_bump
(timeout_ms=None, sleep_ms=10)¶ Wait for the touch sensor to be pressed down and then released. Both actions must happen within timeout_ms.
-
Color Sensor¶
-
class
ev3dev2.sensor.lego.
ColorSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
LEGO EV3 color sensor.
-
MODE_COL_REFLECT
= 'COL-REFLECT'¶ Reflected light. Red LED on.
-
MODE_COL_AMBIENT
= 'COL-AMBIENT'¶ Ambient light. Blue LEDs on.
-
MODE_COL_COLOR
= 'COL-COLOR'¶ Color. All LEDs rapidly cycling, appears white.
-
MODE_REF_RAW
= 'REF-RAW'¶ Raw reflected. Red LED on
-
MODE_RGB_RAW
= 'RGB-RAW'¶ Raw Color Components. All LEDs rapidly cycling, appears white.
-
COLOR_NOCOLOR
= 0¶ No color.
-
COLOR_BLACK
= 1¶ Black color.
-
COLOR_BLUE
= 2¶ Blue color.
-
COLOR_GREEN
= 3¶ Green color.
-
COLOR_YELLOW
= 4¶ Yellow color.
-
COLOR_RED
= 5¶ Red color.
-
COLOR_WHITE
= 6¶ White color.
-
COLOR_BROWN
= 7¶ Brown color.
-
reflected_light_intensity
¶ Reflected light intensity as a percentage (0 to 100). Light on sensor is red.
-
ambient_light_intensity
¶ Ambient light intensity, as a percentage (0 to 100). Light on sensor is dimly lit blue.
-
color
¶ - Color detected by the sensor, categorized by overall value.
- 0: No color
- 1: Black
- 2: Blue
- 3: Green
- 4: Yellow
- 5: Red
- 6: White
- 7: Brown
-
color_name
¶ Returns NoColor, Black, Blue, etc
-
raw
¶ Red, green, and blue components of the detected color, as a tuple.
Officially in the range 0-1020 but the values returned will never be that high. We do not yet know why the values returned are low, but pointing the color sensor at a well lit sheet of white paper will return values in the 250-400 range.
If this is an issue, check out the rgb() and calibrate_white() methods.
-
calibrate_white
()¶ The RGB raw values are on a scale of 0-1020 but you never see a value anywhere close to 1020. This function is designed to be called when the sensor is placed over a white object in order to figure out what are the maximum RGB values the robot can expect to see. We will use these maximum values to scale future raw values to a 0-255 range in rgb().
If you never call this function red_max, green_max, and blue_max will use a default value of 300. This default was selected by measuring the RGB values of a white sheet of paper in a well lit room.
Note that there are several variables that influence the maximum RGB values detected by the color sensor - the distance of the color sensor to the white object - the amount of light in the room - shadows that the robot casts on the sensor
-
rgb
¶ Same as raw() but RGB values are scaled to 0-255
-
lab
¶ Return colors in Lab color space
-
hsv
¶ HSV: Hue, Saturation, Value H: position in the spectrum S: color saturation (“purity”) V: color brightness
-
hls
¶ HLS: Hue, Luminance, Saturation H: position in the spectrum L: color lightness S: color saturation
-
red
¶ Red component of the detected color, in the range 0-1020.
-
green
¶ Green component of the detected color, in the range 0-1020.
-
blue
¶ Blue component of the detected color, in the range 0-1020.
-
Ultrasonic Sensor¶
-
class
ev3dev2.sensor.lego.
UltrasonicSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
LEGO EV3 ultrasonic sensor.
-
MODE_US_DIST_CM
= 'US-DIST-CM'¶ Continuous measurement in centimeters.
-
MODE_US_DIST_IN
= 'US-DIST-IN'¶ Continuous measurement in inches.
-
MODE_US_LISTEN
= 'US-LISTEN'¶ Listen.
-
MODE_US_SI_CM
= 'US-SI-CM'¶ Single measurement in centimeters.
-
MODE_US_SI_IN
= 'US-SI-IN'¶ Single measurement in inches.
-
distance_centimeters_continuous
¶ Measurement of the distance detected by the sensor, in centimeters.
The sensor will continue to take measurements so they are available for future reads.
Prefer using the equivalent
UltrasonicSensor.distance_centimeters()
property.
-
distance_centimeters_ping
¶ Measurement of the distance detected by the sensor, in centimeters.
The sensor will take a single measurement then stop broadcasting.
If you use this property too frequently (e.g. every 100msec), the sensor will sometimes lock up and writing to the mode attribute will return an error. A delay of 250msec between each usage seems sufficient to keep the sensor from locking up.
-
distance_centimeters
¶ Measurement of the distance detected by the sensor, in centimeters.
Equivalent to
UltrasonicSensor.distance_centimeters_continuous()
.
-
distance_inches_continuous
¶ Measurement of the distance detected by the sensor, in inches.
The sensor will continue to take measurements so they are available for future reads.
Prefer using the equivalent
UltrasonicSensor.distance_inches()
property.
-
distance_inches_ping
¶ Measurement of the distance detected by the sensor, in inches.
The sensor will take a single measurement then stop broadcasting.
If you use this property too frequently (e.g. every 100msec), the sensor will sometimes lock up and writing to the mode attribute will return an error. A delay of 250msec between each usage seems sufficient to keep the sensor from locking up.
-
distance_inches
¶ Measurement of the distance detected by the sensor, in inches.
Equivalent to
UltrasonicSensor.distance_inches_continuous()
.
-
other_sensor_present
¶ Boolean indicating whether another ultrasonic sensor could be heard nearby.
-
Gyro Sensor¶
-
class
ev3dev2.sensor.lego.
GyroSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
LEGO EV3 gyro sensor.
-
MODE_GYRO_ANG
= 'GYRO-ANG'¶ Angle
-
MODE_GYRO_RATE
= 'GYRO-RATE'¶ Rotational speed
-
MODE_GYRO_FAS
= 'GYRO-FAS'¶ Raw sensor value
-
MODE_GYRO_G_A
= 'GYRO-G&A'¶ Angle and rotational speed
-
MODE_GYRO_CAL
= 'GYRO-CAL'¶ Calibration ???
-
angle
¶ The number of degrees that the sensor has been rotated since it was put into this mode.
-
rate
¶ The rate at which the sensor is rotating, in degrees/second.
-
angle_and_rate
¶ Angle (degrees) and Rotational Speed (degrees/second).
-
calibrate
()¶ The robot should be perfectly still when you call this
-
reset
()¶ Resets the angle to 0.
- Caveats:
- This function only resets the angle to 0, it does not fix drift.
- This function only works on EV3, it does not work on BrickPi, PiStorms, or with any sensor multiplexors.
-
wait_until_angle_changed_by
(delta, direction_sensitive=False)¶ Wait until angle has changed by specified amount.
If
direction_sensitive
is True we will wait until angle has changed bydelta
and with the correct sign.If
direction_sensitive
is False (default) we will wait until angle has changed bydelta
in either direction.
-
circle_angle
()¶ As the gryo rotates clockwise the angle increases, it will increase by 360 for each full rotation. As the gyro rotates counter-clockwise the gyro angle will decrease.
The angles on a circle have the opposite behavior though, they start at 0 and increase as you move counter-clockwise around the circle.
Convert the gyro angle to the angle on a circle. We consider the initial position of the gyro to be at 90 degrees on the cirlce.
-
Infrared Sensor¶
-
class
ev3dev2.sensor.lego.
InfraredSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
,ev3dev2.button.ButtonBase
LEGO EV3 infrared sensor.
-
MODE_IR_PROX
= 'IR-PROX'¶ Proximity
-
MODE_IR_SEEK
= 'IR-SEEK'¶ IR Seeker
-
MODE_IR_REMOTE
= 'IR-REMOTE'¶ IR Remote Control
-
MODE_IR_REM_A
= 'IR-REM-A'¶ IR Remote Control. State of the buttons is coded in binary
-
MODE_IR_CAL
= 'IR-CAL'¶ Calibration ???
-
on_channel1_top_left
= None¶ Handler for top-left button events on channel 1. See
InfraredSensor.process()
.
-
on_channel1_bottom_left
= None¶ Handler for bottom-left button events on channel 1. See
InfraredSensor.process()
.
-
on_channel1_top_right
= None¶ Handler for top-right button events on channel 1. See
InfraredSensor.process()
.
-
on_channel1_bottom_right
= None¶ Handler for bottom-right button events on channel 1. See
InfraredSensor.process()
.
-
on_channel1_beacon
= None¶ Handler for beacon button events on channel 1. See
InfraredSensor.process()
.
-
on_channel2_top_left
= None¶ Handler for top-left button events on channel 2. See
InfraredSensor.process()
.
-
on_channel2_bottom_left
= None¶ Handler for bottom-left button events on channel 2. See
InfraredSensor.process()
.
-
on_channel2_top_right
= None¶ Handler for top-right button events on channel 2. See
InfraredSensor.process()
.
-
on_channel2_bottom_right
= None¶ Handler for bottom-right button events on channel 2. See
InfraredSensor.process()
.
-
on_channel2_beacon
= None¶ Handler for beacon button events on channel 2. See
InfraredSensor.process()
.
-
on_channel3_top_left
= None¶ Handler for top-left button events on channel 3. See
InfraredSensor.process()
.
-
on_channel3_bottom_left
= None¶ Handler for bottom-left button events on channel 3. See
InfraredSensor.process()
.
-
on_channel3_top_right
= None¶ Handler for top-right button events on channel 3. See
InfraredSensor.process()
.
-
on_channel3_bottom_right
= None¶ Handler for bottom-right button events on channel 3. See
InfraredSensor.process()
.
-
on_channel3_beacon
= None¶ Handler for beacon button events on channel 3. See
InfraredSensor.process()
.
-
on_channel4_top_left
= None¶ Handler for top-left button events on channel 4. See
InfraredSensor.process()
.
-
on_channel4_bottom_left
= None¶ Handler for bottom-left button events on channel 4. See
InfraredSensor.process()
.
-
on_channel4_top_right
= None¶ Handler for top-right button events on channel 4. See
InfraredSensor.process()
.
-
on_channel4_bottom_right
= None¶ Handler for bottom-right button events on channel 4. See
InfraredSensor.process()
.
-
on_channel4_beacon
= None¶ Handler for beacon button events on channel 4. See
InfraredSensor.process()
.
-
proximity
¶ An estimate of the distance between the sensor and objects in front of it, as a percentage. 100% is approximately 70cm/27in.
-
heading
(channel=1)¶ Returns heading (-25, 25) to the beacon on the given channel.
-
distance
(channel=1)¶ Returns distance (0, 100) to the beacon on the given channel. Returns None when beacon is not found.
-
heading_and_distance
(channel=1)¶ Returns heading and distance to the beacon on the given channel as a tuple.
-
top_left
(channel=1)¶ Checks if
top_left
button is pressed.
-
bottom_left
(channel=1)¶ Checks if
bottom_left
button is pressed.
-
top_right
(channel=1)¶ Checks if
top_right
button is pressed.
-
bottom_right
(channel=1)¶ Checks if
bottom_right
button is pressed.
-
beacon
(channel=1)¶ Checks if
beacon
button is pressed.
Returns list of currently pressed buttons.
Note that the sensor can only identify up to two buttons pressed at once.
-
process
()¶ Check for currenly pressed buttons. If the new state differs from the old state, call the appropriate button event handlers.
To use the on_channel1_top_left, etc handlers your program would do something like:
def top_left_channel_1_action(state): print("top left on channel 1: %s" % state) def bottom_right_channel_4_action(state): print("bottom right on channel 4: %s" % state) ir = InfraredSensor() ir.on_channel1_top_left = top_left_channel_1_action ir.on_channel4_bottom_right = bottom_right_channel_4_action while True: ir.process() time.sleep(0.01)
-
Sound Sensor¶
-
class
ev3dev2.sensor.lego.
SoundSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
LEGO NXT Sound Sensor
-
MODE_DB
= 'DB'¶ Sound pressure level. Flat weighting
-
MODE_DBA
= 'DBA'¶ Sound pressure level. A weighting
-
sound_pressure
¶ A measurement of the measured sound pressure level, as a percent. Uses a flat weighting.
-
sound_pressure_low
¶ A measurement of the measured sound pressure level, as a percent. Uses A-weighting, which focuses on levels up to 55 dB.
-
Light Sensor¶
-
class
ev3dev2.sensor.lego.
LightSensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ Bases:
ev3dev2.sensor.Sensor
LEGO NXT Light Sensor
-
MODE_REFLECT
= 'REFLECT'¶ Reflected light. LED on
-
MODE_AMBIENT
= 'AMBIENT'¶ Ambient light. LED off
-
reflected_light_intensity
¶ A measurement of the reflected light intensity, as a percentage.
-
ambient_light_intensity
¶ A measurement of the ambient light intensity, as a percentage.
-
Base “Sensor”¶
This is the base class all the other sensor classes are derived from. You generally want to use one of the other classes instead, but if your sensor doesn’t have a dedicated class, this is will let you interface with it as a generic device.
-
class
ev3dev2.sensor.
Sensor
(address=None, name_pattern='sensor*', name_exact=False, **kwargs)¶ The sensor class provides a uniform interface for using most of the sensors available for the EV3.
-
address
¶ Returns the name of the port that the sensor is connected to, e.g.
ev3:in1
. I2C sensors also include the I2C address (decimal), e.g.ev3:in1:i2c8
.
-
command
¶ Sends a command to the sensor.
-
commands
¶ Returns a list of the valid commands for the sensor. Returns -EOPNOTSUPP if no commands are supported.
-
decimals
¶ Returns the number of decimal places for the values in the
value<N>
attributes of the current mode.
-
driver_name
¶ Returns the name of the sensor device/driver. See the list of [supported sensors] for a complete list of drivers.
-
mode
¶ Returns the current mode. Writing one of the values returned by
modes
sets the sensor to that mode.
-
modes
¶ Returns a list of the valid modes for the sensor.
-
num_values
¶ Returns the number of
value<N>
attributes that will return a valid value for the current mode.
-
units
¶ Returns the units of the measured value for the current mode. May return empty string
-
value
(n=0)¶ Returns the value or values measured by the sensor. Check num_values to see how many values there are. Values with N >= num_values will return an error. The values are fixed point numbers, so check decimals to see if you need to divide to get the actual value.
-
bin_data_format
¶ Returns the format of the values in
bin_data
for the current mode. Possible values are:u8
: Unsigned 8-bit integer (byte)s8
: Signed 8-bit integer (sbyte)u16
: Unsigned 16-bit integer (ushort)s16
: Signed 16-bit integer (short)s16_be
: Signed 16-bit integer, big endians32
: Signed 32-bit integer (int)float
: IEEE 754 32-bit floating point (float)
-
bin_data
(fmt=None)¶ Returns the unscaled raw values in the
value<N>
attributes as raw byte array. Usebin_data_format
,num_values
and the individual sensor documentation to determine how to interpret the data.Use
fmt
to unpack the raw bytes into a struct.Example:
>>> from ev3dev2.sensor.lego import InfraredSensor >>> ir = InfraredSensor() >>> ir.value() 28 >>> ir.bin_data('<b') (28,)
-