EV3 MATLAB Library Documentation

Startup and Shutdown

Before we can use the EV3 brick in MATLAB, we must make a bluetooth connection between the brick and Windows.

Go through the following steps at the beginning of each class:

1. Turn the EV3 brick on, and verify that the small Bluetooth icon is visible in the upper-left corner of the LCD. The icon looks like a capital-B composed of two triangles.
2. If the Bluetooth symbol is not visible, press the right arrow on the EV3 brick three times. Then, select Bluetooth, you'll be taken to this menu:

1. Make sure both "Visibility and "Bluetooth are checked.

1. On the EV3 brick, in the Bluetooth menu, select Connections.

1. Select each of the contacts and delete them until there are none left.
1. In Windows, open Control Panel > Devices and Printers to check whether the NXT brick has already been added to Devices.
2. If the EV3 brick is not among the devices, click Add a device.
3. In the Add a device wizard that opens, select your EV3 Bluetooth device, and click Next.

1. The LCD on the EV3 brick will ask if you want to connect. Select the Check mark, and then the EV3 will display the default passkey, 1234, promptly press the center button on the EV3 brick.
1. Enter the same passkey, 1234 at the prompt in windows.
2. When you see confirmation that the device has been added, click Close.
3. IMPORTANT: Restart the EV3 brick after adding the device.

ConnectBrick

Connect an EV3 brick to MATLAB over a bluetooth connection. This should be executed once at the beginning of using the brick, or after a connection is lost. Never use it in program scripts.

Syntax:

brick = ConnectBrick(brickname);

Notes:

• brickname is the name of your EV3 brick (see the top of the brick LCD screen) in single quotes.
• Returns a handle to the brick control class. Use this to send commands to the brick.

Usage Example:

brick = ConnectBrick('TacoBrick'); % Connects to the Brick

brick.beep();                      % Brick Beeps when connection is complete.

DisconnectBrick

Disconnect an EV3 brick from MATLAB over a bluetooth connection. This should be executed once at the end of using the brick, or after communication is lost. Never use it in program scripts.

Syntax:

DisconnectBrick(brick);

Notes:

• brick is the handle returned by ConnectBrick.

Usage Example:

DisconnectBrick(brick); % Disconnects the brick.

Sensors

Sensors are awesome.

Touch

These functions are for use with the EV3 touch sensor. To use these functions, at least 1 touch sensor must be connected to one of the numbered ports on the bottom of the EV3 brick.

TouchPressed

Returns whether or not a touch sensor is currently being pressed.

Syntax:

reading = brick.TouchPressed(SensorPort);

Notes:

• SensorPort is the number of the port that a touch sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns 1 if the touch sensor connected to SensorPort is being pressed, and 0 otherwise.

Usage Example:

while 1

touch = brick.TouchPressed(1); % Read a touch sensor connected to port 1.

if touch

brick.beep(); % Beep if the sensor was touched.

break; % End program

end

end

TouchBumps

Returns how many times a touch sensor has been bumped (pressed, then released) since the last brick reset.

Syntax:

bumps = brick.TouchBumps(SensorPort);

Notes:

• SensorPort is the number of the port that a touch sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns how many times a touch sensor has been bumped (pressed, then released) since the last brick reset as a positive integer.

Usage Example:

bumps = brick.TouchBumps(1); % Get bumps on port 1

display(bumps); % Print # of bumps to command window.

Color

These functions are for use with the EV3 color sensor. To use these functions, at least 1 color sensor must be connected to one of the numbered ports on the bottom of the EV3 brick.

SetColorMode

Sets the mode of the color sensor. This function must be called near the beginning of a program before any other color sensor function. The color sensor has 4 operating modes, see notes below.

Syntax:

brick.SetColorMode(SensorPort, Mode);

Notes:

• SensorPort is the number of the port that a color sensor is connected. Must be a number between 1 and 4.
• Mode is a number between 0 and 4 that corresponds to one of the following modes:

• brick is the handle returned by ConnectBrick
• Returns Nothing.

Usage Example:

brick.SetColorMode(1, 4); % Set Color Sensor connected to Port 1 to Color RGB Mode.

LightReflect

Returns the brightness of reflected light in front of the sensor. Also turns on the red LED.

Syntax:

brightness = brick.LightReflect(SensorPort);

Notes:

• SensorPort is the number of the port that a color sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns the brightness of reflected light in front of the sensor, as a positive integer between 0 and 255. 0 is dark, 255 is bright.

Usage Example:

brick.SetColorMode(1, 0); % Set Color Sensor connected to Port 1 to Reflected Light Mode

brightness = brick.LightReflect(1); % Get Reflected light on port 1.

display(brightness); % Print amount of reflected light.

LightAmbient

Returns the brightness of ambient light in front of the sensor. Also turns on a dim blue LED.

Syntax:

brightness = brick.LightAmbient(SensorPort);

Notes:

• SensorPort is the number of the port that a color sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
  • Returns the brightness of ambient light in front of the sensor, as a positive integer between 0 and 255. 0 is dark, 255 is bright.

Usage Example:

brick.SetColorMode(1, 1); % Set Color Sensor connected to Port 1 to AmbientLight Mode

brightness = brick.LightAmbient(1); % Get Ambient light on port 1.

display(brightness); % Print amount of Ambient light.

ColorCode

Returns the detected color in front of the sensor.

Syntax:

color = brick.ColorCode(SensorPort);

Notes:

• SensorPort is the number of the port that a color sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns the color of an object in front of the sensor, as an integer between 0 and 7:

Usage Example:

brick.SetColorMode(1, 2); % Set Color Sensor connected to Port 1 to Color Code Mode

color = brick.ColorCode(1); % Get Color on port 1.

display(color); % Print color code of object.

ColorRGB

Returns the detected color in front of the sensor as a row vector of 3 numbers corresponding to red, green, and blue values of reflected light.

Syntax:

color_rgb = brick.ColorRGB(SensorPort);

Notes:

• SensorPort is the number of the port that a color sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns the color of an object in front of the sensor, as a row vector of red, green, and blue values of reflected light.

Usage Example:

brick.SetColorMode(1, 4); % Set Color Sensor connected to Port 1 to Color Code Mode

color_rgb = brick.ColorRGB(1); % Get Color on port 1.

%print color of object

fprintf("\tRed: %d\n", color_rgb(1));

fprintf("\tGreen: %d\n", color_rgb(2));

fprintf("\tBlue: %d\n", color_rgb(3));

Ultrasonic

These functions are for use with the EV3 ultrasonic sensor. To use these functions, at least 1 ultrasonic sensor must be connected to one of the numbered ports on the bottom of the EV3 brick.

UltrasonicDist

Returns the distance from the front of the sensor to the nearest object.

Syntax:

distance = brick.UltrasonicDist(SensorPort);

Notes:

• SensorPort is the number of the port that an ultrasonic sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
  • Returns the positive distance from the front of the sensor to the nearest object in centimeters. If an object is too close or too far away, the function will return 255.

Usage Example:

distance = brick.UltrasonicDist(1); % Get distance to the nearest object.

display(distance); % Print distance.

Gyro

These functions are for use with the EV3 gryo sensor. To use these functions, at least 1 gryo sensor must be connected to one of the numbered ports on the bottom of the EV3 brick.

Warning: The Gyro sensor is often inaccurate or very unstable and often experiences drift (the value changes without the sensor moving) even after calibration.

GyroCalibrate

Resets and Calibrates the Gyro Sensor. For best results, the gyro sensor must be perfectly still when this function is called. The current position of the sensor becomes the new 0 reference.

Syntax:

brick.GyroCalibrate(SensorPort);

Notes:

• SensorPort is the number of the port that a gyro sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns Nothing.

Usage Example:

brick.GyroCalibrate(1); % Calibrates the Gyro Sensor.

GyroAngle

Returns the rotation angle in degrees of the gyro sensor since the last reset.

Syntax:

angle = brick.GyroAngle(SensorPort);

Notes:

• SensorPort is the number of the port that a gyro sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns the rotation angle in degrees of the gyro sensor since the last reset.

Usage Example:

angle = brick.GyroAngle(1); % Get the current Gyro angle

display(angle); % Print angle.

GyroRate

Returns the speed of rotation of the gyro sensor in degrees per second.

Syntax:

angleRate = brick.GyroRate(SensorPort);

Notes:

• SensorPort is the number of the port that a gyro sensor is connected. Must be a number between 1 and 4.
• brick is the handle returned by ConnectBrick
• Returns the speed of rotation of the gyro sensor in degrees per second.

Usage Example:

angleRate = brick.GyroRate(1); % Get the current Gyro angle rate

display(angleRate); % Print angle.

Motors

These functions are for use with the EV3 motors connected to one or more of the Lettered ports on the top of the EV3 brick.

Large Motor (Left) and Medium Motor (Right).

Continuous Rotation

MoveMotor

Starts a motor or multiple motors moving at a given speed.

Syntax:

brick.MoveMotor(MotorPort, Speed);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• Speed is the desired speed of the motor, as a signed number between -100 and 100. Negative numbers cause the motor to reverse, 0 causes the motor to stop.
• brick is the handle returned by ConnectBrick

Usage Example:

brick.MoveMotor('A', 50); % Motor A forward at half speed.

pause(1); % Let the motor turn for 1 second.

brick.MoveMotor('A', -50); % Motor A reverse at half speed.

pause(1); % Let the motor turn for 1 second.

brick.MoveMotor('AB', 10); % Move both motors A and B at 10%

pause(1); % Let the motors turn for 1 second.

brick.MoveMotor('AB', 0); % Stop both motors A and B

StopMotor

Stops a given motor, with 2 optional types of braking.

Syntax:

brick.StopMotor(MotorPort, BrakeType);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• BrakeType (optional) can be either the word 'Coast' or 'Brake' in single quotes.
  • 'Coast' allows the motor to drift to a stop.
  • 'Brake' performs a hard stop, and the brick tries to maintain that position. Over-use of this mode can drain the Brick batteries quickly.
• If no BrickType is given, defaults to 'Coast'.
• brick is the handle returned by ConnectBrick.

Usage Example:

brick.MoveMotor('A', 50); % Motor A forward at half speed.

pause(1); % Let the motor turn for 1 second.

brick.StopMotor('A', 'Coast'); % Motor A drift to Stop

StopAllMotors

Stops all motors connected to a brick.

Syntax:

brick.StopAllMotors(BrakeType);

Notes:

• BrakeType (optional) can be either the word 'Coast' or 'Brake' in single quotes.
  • 'Coast' allows the motor to drift to a stop.
  • 'Brake' performs a hard stop, and the brick tries to maintain that position. Over-use of this mode can drain the Brick batteries quickly.
• If no BrickType is given, defaults to 'Coast'.
• brick is the handle returned by ConnectBrick.

Usage Example:

brick.MoveMotor('AB', 50); % Motor A, B forward at half speed.

pause(1); % Let the motors turn for 1 second.

brick.StopAllMotors('Brake'); % Hard Stop, all motors.

Rotate by Angle

These functions allow a motor to be moved by precise angles.

MoveMotorAngleRel

Move a motor a certain angle relative to it's current position.

Syntax:

brick.MoveMotorAngleRel(MotorPort, Speed, Angle, BrakeType);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• Speed is the desired speed of the motor, as a positive number between 1 and 100. Negative numbers cause the motor to rotate in the opposite direction. A speed of 0 should not be used with this function.
• Angle is a positive integer in degrees of how much the motor should move. Negative numbers have no effect on this function.
• BrakeType (optional) can be either the word 'Coast' or 'Brake' in single quotes.
  • 'Coast' allows the motor to drift to a stop.
  • 'Brake' performs a hard stop, and the brick tries to maintain that position. Over-use of this mode can drain the Brick batteries quickly.
• If no BrickType is given, defaults to 'Coast'.
• brick is the handle returned by ConnectBrick.
• For proper operation, this function must always be followed by a call to the "WaitForMotor" function. Commands to other motors may be given first (for simultaneous operation) but a "WaitForMotor" call must be completed before a new command is given to the motor.

Usage Example:

% Reverse motor A, 90 degrees, with 20% speed. Hard stop.

brick.MoveMotorAngleRel('A', 20, -90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

MoveMotorAngleAbs

Move a motor a certain absolute angle. Zero degrees is wherever the motor starts at reset. (See ResetMotorAngle).

Syntax:

brick.MoveMotorAngleAbs(MotorPort, Speed, Angle, BrakeType);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• Speed is the desired speed of the motor, as a positive number between 1 and 100. Negative numbers cause the motor to rotate in the opposite direction. A speed of 0 should not be used with this function.
• Angle is a positive integer in degrees of how much the motor should move.
• BrakeType (optional) can be either the word 'Coast' or 'Brake' in single quotes.
  • 'Coast' allows the motor to drift to a stop.
  • 'Brake' performs a hard stop, and the brick tries to maintain that position. Over-use of this mode can drain the Brick batteries quickly.
• If no BrickType is given, defaults to 'Coast'.
• brick is the handle returned by ConnectBrick.
• For proper operation, this function must always be followed by a call to the "WaitForMotor" function. Commands to other motors may be given first (for simultaneous operation) but a "WaitForMotor" call must be completed before a new command is given to the motor.

Usage Example:

% Move to 0 position

brick.MoveMotorAngleAbs('A', 20, 0, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Move to 90 Position

brick.MoveMotorAngleAbs('A', 20, 90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Move to -90 Position

brick.MoveMotorAngleAbs('A', 20, -90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

WaitForMotor

Wait for a motor to complete it's angle rotation. Should only be used with MoveMotorAngleRel and MoveMotorAngleAbs commands.

Syntax:

brick.WaitForMotor(MotorPort);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• brick is the handle returned by ConnectBrick.

Usage Example:

% Move to 0 position

brick.MoveMotorAngleAbs('A', 20, 0, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Move to 90 Position

brick.MoveMotorAngleAbs('A', 20, 90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Move to -90 Position

brick.MoveMotorAngleAbs('A', 20, -90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

ResetMotorAngle

Resets the Absolute Position of a motor to 0. The current position of the motor becomes the new '0' angle.

Syntax:

brick.ResetMotorAngle(MotorPort);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• brick is the handle returned by ConnectBrick.
• For best results, include this function at the beginning of your program, called once for each connected motor.

Usage Example:

% Move to 0 position

brick.MoveMotorAngleAbs('A', 20, 0, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Move to 90 Position

brick.MoveMotorAngleAbs('A', 20, 90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

% Make Current Position 0

brick.ResetMotorAngle('A');

% Move another 90 degrees.

brick.MoveMotorAngleAbs('A', 20, 90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

GetMotorAngle

Returns the current position of a motor as an angle.

Syntax:

position = brick.ResetMotorAngle(MotorPort);

Notes:

• MotorPort is the Letter(s) of the port that a motor is connected, in single quotes. Must be 'A', 'B', 'C', 'D' or a combination of those.
• brick is the handle returned by ConnectBrick.
• Returns the current position of the motor, as a signed integer representing an angle in degrees.

Usage Example:

% Make Current Position 0

brick.ResetMotorAngle('A');

% Move another 90 degrees.

brick.MoveMotorAngleAbs('A', 20, 90, 'Brake');

brick.WaitForMotor('A'); % Wait for motor to complete motion

position = brick.GetMotorAngle('A'); % Get Current Position

display(position);

Miscellaneous

This is where all the weird stuff goes.

beep

Causes the brick to emit a short 'beep'.

Syntax:

brick.beep();

Notes:

• brick is the handle returned by ConnectBrick.

Usage Example:

brick.beep(); % Brick beeps.

playTone

Causes the brick to emit a tone, at a certain volume, pitch, and duration.

Syntax:

brick.playTone(volume, pitch, duration);

Notes:

• volume is the tone volume from 0 to 100.
• pitch is the tone pitch (frequency) in Hz. Positive integer between 200 and 44000
• duration is the duration of the tone in milliseconds(ms). 1 second = 1000 milliseconds.
• brick is the handle returned by ConnectBrick.

Usage Example:

% 100% Volume, at 300Hz, for half a second.

brick.playTone(100, 300, 500);

GetBattVoltage

Returns the current voltage of the battery, in volts.

Syntax:

v = brick.GetBattVoltage();

Notes:

• brick is the handle returned by ConnectBrick.
• Returns a decimal number representing the current battery voltage.

Usage Example:

v = brick.GetBattVoltage();

display(v);

GetBattLevel

Returns the current charge of the battery, as a level between 0% and 100%

Syntax:

v = brick.GetBattLevel();

Notes:

• brick is the handle returned by ConnectBrick.
• Returns a positive integer between 0 and 100 representing the current charge of the battery as a percentage.

Usage Example:

L = brick.GetBattLevel();

display(L);