VEX Library Guide

Vex Library

The VEX library is used in the EG1003 course to control the VEX robot and sensors using Arduino. The library is designed to more easily access the robot’s functionality. For more information on coding with Arduino, please reference the Arduino Coding Guide

The library is intended for use with the Adafruit Motor Shield V2, and VEX EDR 2-wire motors.

The library allows you to interface with the following sensors:

• MPU6050 Accelerometer and Gyroscope Sensor
• HC SR04 and VEX Ultrasonic Sensor
• VEX Touch/Button and VEX Limit Switch Sensor
• IR Obstacle Avoidance Sensor

The library also allows for the following functions of the motor board:

• Control single motor speed and direction
• Control two motors speed and direction simultaneously

Download the library files here

Library Structure

This library relies on multiple 3rd party libraries, including MPU6050, I2Cdev, and Adafruit Motor Shield V2, as well as inbuilt Arduino libraries including Wire.

There is one main class that controls the robot:

• Vex: commands the motor shield, and controls the motors for all robot movement

There are 2 classes that control different sensors:

• Gyro: reads data from the MPU6050 and provides the Euler angles around 3 axises
• Ultrasonic: reads the distance from itself to the nearest object it senses

Examples

Example files can be found by clicking on File>Examples>Vex. These Arduino C codes provided show the possibilities of the robot and provide tests for different functions.

• Movement Test: tests the standard robot movements, such as forward, turns, and claw movement
• Gyro Library Test: tests the gyro sensor to display the x,y, and z Euler angles
• Gyro Turning Test: tells the robot to do a 90o left and right turn based on the gyro sensor
• IR Obstacle Test: tests the IR obstacle avoidance sensor
• Touch Test: tests the touch sensor/limit switch to display whether or not the button/switch is pressed
• Ultrasonic Test: test the ultrasonic sensor by telling the robot to move forward until it is 5cm away from an obstacle

Importing the Library

• Open your main Arduino File.

• At the top of your screen, click on ‘Sketch,’ then ‘Include Library,’ then ‘Add .ZIP Library’’

Insert picture

• Next, find the library you would like to include. Make sure the file is unzipped. (If using Windows, to unzip a file, right-click the file and select ‘Extract All’). You must upload all four files in ‘EG VEX Libraries.’ Note: Arduino does not let you upload all of the libraries at once so repeat steps 2 and 3.

Insert picture

• Make sure to have ‘#include <Vex.h> ‘ at the top of your file.

insert picture

Alternative Way to Import the Library

• Download the zipped EG VEX Libraries file

insert picture

• Extract the four libraries to separate folders

insert picture

• Move the four libraries to the Arduino libraries folder
  • This is usually Documents/Arduino/Libraries

insert picture

• Restart the Arduino IDE to load the libraries

Vex Class

This class is used to interface with the motors connected to the Adafruit Motor Shield. The shield can support up to 4 DC motors and uses its own power source separate from the Arduino RedBoard.

Wiring

The Adafruit Motor Shield comes with pins that connect the shield directly on top of the microcontroller. The shield can then be used just like the microcontroller, as it also has the standard pins used for the Arduino. In order to use the motor terminals labeled M1, M2, M3, and M4, the shield must be powered. For the VEX library, this should be done by connecting an external power source to the terminal shown in Figure 1. Figure 1 shows how to wire the motor shield with four DC motors and an external battery. insert picture

Methods

Constructor

• In order to create a Vex object, the constructor must be called. Creating a Vex object allows you to call on the methods, which can also be referred to as functions, within the Vex Class. The constructor for a Vex object is empty meaning it has no parameters.

Syntax

• Vex vex;

Parameters

• None

Returns

• None

Example

• Create a Vex object named robot:

insert picture

Note: All constructors should be called outside of functions setup() and loop(). Additionally, your Vex object can have any name (i.e Robot, vex, etc).

begin()

• The begin() method initializes the VEX robot. It must be called in the setup() function to use any other Vex methods.

Note: begin() does not initialize sensors. Refer to the documentation for the wanted sensor for reference on initializing these other modules.

Syntax

• vex.begin();

Parameters

• None

Returns

• None

Example

• picture

setMotor()

• The setMotor() method sets up the motors for use with the motor shield. This function must be called in order to create the motor objects needed for the moveMotor() and moveTank() methods. It also cannot be used alone and must be called when setting an Adafruit_DCMotor object. See the example below for correct usage of the setMotor() method

Syntax

• Adafruit_DCMotor* motor = vex.setMotor(port);

Parameters

• port: An integer between 1 and 4, representing the motor port being used on the motor shield

Returns

• An Adafruit_DCMotor* object

Example

• picture

end()

• The end() method stops all robot movement. It is meant for use at the end of the code, to stop the robot from looping the original code over and over again.

Note: this method places the code within an infinite loop, therefore any code written after this method is called will not be run.

Syntax

• vex.end();

Parameters

• None

Return

• None

Example

• picture

moveMotor()

• The moveMotor() method allows for the movement of a single motor, for a set power and time

Syntax

• vex.moveMotor(motor, power, time);

Parameters

• motor: an Adafruit_DCMotor* object, previously created using the setMotor() method.
• power: a double between -100 and 100. Positive numbers will move the motor clockwise, while negative numbers will move the motor counterclockwise. 0 will cause the motor to not move.
• time: a positive double, representing the number of seconds to run the motor.

Returns

• None

Example

• picture

moveTank()

• The moveTank() method allows for the movement of two motors simultaneously, for two different power values, over a set period of time

Syntax

• vex.moveTank(motor1, motor2, power1, power2, time);

Parameters

• motor1: an Adafruit_DCMotor* object, previously created using the setMotor() method
• motor2: an Adafruit_DCMotor* object, previously created using the setMotor() method
• power1: a double between -100 and 100. This value controls the power of motor1. Positive numbers will move the motor clockwise, while negative numbers will move the motor counterclockwise. 0 will cause the motor to not move.
• power2: a double between -100 and 100. This value controls the power of motor2. Positive numbers will move the motor clockwise, while negative numbers will move the motor counterclockwise. 0 will cause the motor to not move.
• time: a positive double, representing the number of seconds to run the motor

Example

• picture

Gyro Class

This class is used to interface with the MPU6050 Accelerometer and Gyroscope. It is created specifically to provide the values of the Euler Angles as calculated from the gyroscope. Note: As the Gyro class is made specifically for this function, it cannot be used to access the additional functionalities of the MPU6050 device. Any other use of the MPU6050 outside of this class is at the discretion of the student.

Wiring

Figure 2 shows how to wire the MPU6050 sensor. Note that the Int pin on the MPU6050 must be connected to digital pin 2 on the Arduino board for the sensor to work within this library picture

Figure 2: Circuit Diagram for the MPU6050

Pins: VCC: 3V or 5V GND: ground SCL: analog pin 4 SDA: analog pin 5 INT: Digital Pin 2

Methods

Constructor

• In order to create a Gyro object, the constructor must be called. Creating a Gyro object allows you to call on the methods, which can also be referred to as functions, within the Gyro Class. The constructor for a Gyro object is empty (has no parameters).

Parameters

• None

Returns

• None

Example

• picture

begin()

• The begin() method initializes the gyro. It must be called in the setup() function to use any other Gyro methods

Note: begin() only initializes the gyro sensor. Refer to the documentation for the wanted sensor for reference on initializing other modules

Syntax

• gyro.begin();

Parameters

• None

Returns

• None

Example

• picture

getZAngle()

• The getZAngle() method returns the calculated Euler angle about the Z-axis

Syntax

• gyro.getZAngle();

Parameters

• None

Returns

• A float (decimal) value representing the angle.

Example

• picture

getYAngle()

• The getYAngle() method returns the calculated Euler angle about the Y-axis

Syntax

• gyro.getYAngle();

Parameters

• None

Returns

• A float value representing the angle

Example

• picture

getXAngle()

• The getXAngle() method returns the calculated Euler angle about the X-axis

Syntax

• gyro.getXAngle();

Parameters

• None

Returns

• A float value representing the angle

Example

• picture

Ultrasonic Class

The Ultrasonic Sensor is used to determine how far away an object is. This is useful for obstacle avoidance. The HC-SR04 ultrasonic sensor uses a process similar to echolocation to operate. The sensor transmits a high frequency signal, then it receives the signal after it gets reflected by the object. The sensor determines the time elapsed between transmission and reception. This can be used to calculate the distance from the sensor to the object using the speed of sound (343m/s). picture Figure 3: Source: Random Nerd Tutorials

Wiring

The ultrasonic sensor has four pins: Voltage (VCC), Ground (GND), Trigger (TRIG), and Echo. VCC and GND need to be connected to voltage and ground, respectively. Trigger (or transmitter) is used for the sensor to create the high-frequency signal that gets transmitted, while Echo (or receiver) is used to receive the reflected signal. Trig and Echo can be connected to any digital I/O pins. The working voltage for ultrasonic sensor is 5V, its maximum range is 4m, and its minimum range is 2cm. Male/female jumper wires can be used to connect the ultrasonic sensor to the breadboard. Figure 4A & 4B show how to correctly wire the ultrasonic sensor. picture picture

Pins VCC: 5V Trigger: digital I/O pin Echo: digital I/O pin GND: ground

Methods

Constructor

• In order to create an Ultrasonic object, the constructor must be called. The Ultrasonic constructor takes two parameters, one for the trigger pin and one for the echo pin.

Note: The Trigger and Echo Pins refer to the pin number on the Arduino/Motor Shield the trigger/echo pins are wired to.

Syntax

• Ultrasonic ultrasonic(triggerPin, echoPin);

Parameters

• triggerPin: an integer representing the digital pin used for the trigger
• echoPin: an integer representing the digital pin used for the echo

Returns

• None

Example

• picture

begin()

• The begin() method initializes the ultrasonic sensor. It must be called in the setup() function to use any other ultrasonic methods.

Syntax

• ultrasonic.begin();

Parameters

• None

Returns

• None

Example

• picture

checkUltrasonic()

• The checkUltrasonic() method returns the distance (in centimeters) between the sensor and the first object it detects.

Note: The minimum distance the sensor can detect is 2cm, while the maximum distance is 4m

Syntax

• ultrasonic.checkUltrasonic();

Parameters

• None

Returns

• A long representing the distance (in centimeters) between the sensor and the first object it detects.

Example

• picture

Touch Class

The Touch Class is used to interface with the VEX touch sensor or VEX limit switch. The class provides boolean values representing when the switch on the sensor has been pressed.

Wiring

The Touch Sensor is connected to two pins on the Arduino/Adafruit MotorShield, Ground (GND) and a Digital Pin. In Figure 5, the Digital Pin is connected to Digital Pin 3. The Touch Sensor works so that whenever it is pressed, a certain line of code or function can occur. picture picture

Pins GND: ground touchPin: Digital Pin

Methods

Constructor

• The constructor takes one parameter, for the digital pin. The constructor must be called in order to create a Touch object

Syntax

• Touch touch(pin);

Parameters

• Pin: an integer representing the digital pin used by the sensor

Returns

• None

Example

• picture

begin()

• The begin() method is used to initialize the touch sensor. It must be called in the setup() function in order to use any other Touch methods

Syntax

• touch.begin();

Parameters

• None

Returns

• None

Example

• picture

isPushed()

• The isPushed() method returns a boolean value depending on whether or not the button on the sensor has been pressed.

Syntax

• touch.isPushed();

Parameters

• None

Returns

• A boolean value. True indicates the button has been pushed, while false indicates the button has not been pushed

Example

• picture

IRObstacle Class

This class is used to interface with the IR Obstacle Avoidance Sensor. This sensor will only return whether or not there is an obstacle directly in front of the sensor.

The sensor uses an infrared emitter LED. This signal is then received by an infrared receiver to determine whether or not there is an obstacle. The distance adjust terminal can be used to adjust the detection distance. Turning the screw counterclockwise will decrease the distance while turning the screw clockwise will increase the distance.

picture

Note: As the IRObstacle class is made specifically for this function, it cannot be used to access the additional functionalities of the MPU6050 device. Any other use of the MPU6050 outside of this class is at the discretion of the student.

Wiring

Figure 7 shows how to wire the IR obstacle avoidance sensor.

Pins: VCC: 3V or 5V GND: ground OUT: digital pin

Methods

Constructor

• In order to create an IRObstacle object the constructor must be called. It has one parameter for the digital pin.

Syntax

• IRObstacle ir(pin);

Parameters

• Pin: an integer representing the digital pin used for the sensor

Returns

• None

Example

• picture

begin()

• The begin() method initializes the IR obstacle avoidance sensor. It must be called in the setup() function to use any other IRObstacle methods

Note: begin() only initializes the IR obstacle avoidance sensor. Refer to the documentation for the wanted sensor for reference on initializing other modules.

Syntax

• irobstacle.begin();

Parameters

• None

Returns

• None

Example picture

isObstacle()

• The isObstacle() method returns a boolean value depending on whether or not the sensor detects an obstacle.

Syntax

• irobstacle.isObstacle();

Parameters

• None

Returns

• A boolean value. HIGH indicates an obstacle is detected, while LOW indicates no obstacle was detected

Example picture