WPILib

1
WPILib

• A programming API for use with Vex and FIRST.
  This presentation focuses only on Vex.

2
Intro

• WPILib is a programming library written by Brad
  Miller at Worchester Polytechnical Institute.
  This tutorial assumes MPLAB is installed with the
  C18 compiler, version 2.40, and that the WPILib
  folder is installed under Program Files of your
  computer. The 1 reference for WPILib is the PDF
  file included with the WPILib folder, named
  WPILib.pdf This PDF gives more precise usage
  instruction than this presentation.

3
Basic C Source File Outline

• The general setup of a C source file is as
  follows
• Including header files to be used
• Defining words as values
• Program functions
• Defining variables (integers or characters)?
• Statements such as prewritten functions from the
  header files and libraries, all ending with a
  semicolon.

4
Basic C Functions/Syntax

• Variables are words that you can hold numbers or
  letters within so you can recall them later. You
  have to define the variables at the beginning of
  a function
• void main() int answer, a 2, b4 answer
  (a b)a/b
• In this example, the variable answer is equal
  to 3. means to multiply, / means to divide.
• char c'x' would make the variable c be equal
  to the letter x. The x has to be in single
  quotes.

5
Basic C Functions/Syntax cont.

• There are two main conditional statements in C
• if(condition) do this once
• Will run if condition is true (1), but not if
  it's false (0)?
• while(condition) do this while condition is
  true
• while(1) code will run code forever.
• The condition can be anything that could be
  true or false
• if (3gt2) printf(I can do math.\n)
• When seeing if two things are equal, you must use
  two equal signs (), or it will think you are
  TELLING it the condition is true.

6
Basic C Functions/Syntax cont.

• The two above conditionals can either execute
  code within curly brackets, or simply a line
  underneath, ended with a semicolon
• while(1) printf(I like cheese.\n)
• while(1) printf(I like cheese.\n)
• while(1) printf(I like cheese.\n)
• These are all the same to the computer.

7
Basic C Functions/Syntax cont.

• To type a value to the computer screen, use
  printf(). Inside the parentheses, use a string
  of text inside quotations. Ending the string
  (still within the quotations), you can use \n
  to go to the next line on the screen. For Vex,
  through the programming cable, you must use
  \n\r. To display the value of a variable, you
  use placeholders d for an integer, c for a
  character. To do this, you put the placeholder
  in the quotation marks somewhere, add a comma
  after the quotations, then list your variables
• printf(Forwardd Channel 4c, forward,
  channel)
• The variables have to have been defined
  previously.

8
Basic C Functions/Syntax cont.

• If there's something you need to remember, you
  can use a comment, a line hidden from the
  compiler
• //The rest of this line is a comment.
• / Everything between these is a comment /This
  second one can be used to take out a block of
  useless code.
• If you need to say something is not true, use an
  exclamation mark (!) in front of it.
• if(4!3) printf(I passed first grade.\n)
• if(!GetOIDInput(1, 2)) printf(Bottom left
  button isn't pressed.\n)

9
Files

• For every project, you need these files
• API.h The header file of main functions
• BuiltIns.h Some secondary functions
• 18f8250.lkr Linker needed to assemble code
• WPILibVex.lib WPILib library for Vex
• Vex_library.lib Standard library for Vex
• Main C code file (create your own, any name)?
• Vex_Library MUST be listed after WPILibVex in
  MPLAB in order to work.
• All files except the .c file are found in the
  WPILib/Vex folder on the computer.

10
Making a Project

• Open MPLAB. Go to the Project menu.
• Click Project Wizard
• The microcontroller type should be set to
  18f8250
• Add new files from the WPILib/Vex folder (located
  in Program Files). Add everything in that
  folder.
• When the wizard is completed, go to the View
  menu and click Project. This will open a
  navigation window for the project. Right click
  the Libaries folder to change the order of
  Vex_library.lib and WPILibVex.lib. WPILibVex.lib
  should be first (on top).
• Go to the File menu, and click New Source
  File. Save this file in the project directory
  under any name (like main.c). Make sure all of
  the WPILib files are in the project directory.
  Save the entire project under any name.

11
Source File Setup

• You must start off the program by including the
  header files like so
• include BuiltIns.h
• BuiltIns.h includes the API.h header, which in
  turn includes the stdio.h header, so you do not
  need to include those.
• You may want to define certain words as values,
  such as defining RADIO_PORT as the number 1
• define RADIO_PORT 1
• Now set up the program functions (next)?

12
WPILib Source Functions

• Write the following functions in this order
• void IO_Initialization()
• void Initialize()
• void Autonomous()
• void OperatorControl()
• void main()
• You may want to enter twice between each curly
  bracket to leave a line of space.

13
void IO_Initialization()?

• This function is run when the robot turns on and
  initializes the controller input/output and
  competition mode. Two functions are necessary
  for the controller, and competition mode
• DefineControllerIO()?
• SetCompetitionMode()?
• DefineControllerIO() needs 17 values in the
  parentheses, separated by commas First, the
  number of anolog channels. The rest will be
  digital. The next sixteen are either a 1 for
  input, or a 0 or output. Alternatively, you can
  type INPUT or OUTPUT.
• SetCompetitionMode() needs two values, the
  autonomous period length in seconds, and the
  operator control period length, in seconds. A
  value of 0 for autonomous means it is not a
  competition project, and will skip Autonomous()
  and OperatorControl() and go straight to main().
  1 is not supported. Any number greater than 1
  is acceptable. 2 is a good autonomous time
  for testing OperatorControl() in a competition
  structure.

14
void Initialize()?

• The Initialize() function starts any sensors that
  need to be started (like gyros or encoders), and
  will not be covered in this tutorial. The
  Initialize() function is not necessary for the
  program to run, and is generally better to be
  left out if not used.

15
void Autonomous()?

• The Autonomous() function is run before
  OperatorControl(), and disables the use of the
  radio, thereby forcing the robot to act only on
  its own programming. The Autonomous() function
  is run for the period of time defined in
  SetCompetitionMode(). To use only the
  Autonomous() function for an unlimited time, put
  a jumper in IO port 5 of the controller before
  turning it on.

16
void OperatorControl()?

• The OperatorControl() function starts after
  Autonomous() finishes, and enables radio control.
  The OperatorControl() function is only run for
  the period of time defined in SetCompetitionMode()
  . To use only OperatorControl() mode for an
  unlimited time, put a jumper in IO port 6 of the
  controller before turning it on.

17
void main()?

• The main() function is necessary for any program
  to run on the robot. If in a competition
  structure, the main() function can be left empty.
  It will only be run if SetCompetitionMode() has
  a 0 in the autonomous period. If not using a
  competition structure, this is the only necessary
  function and will be started automatically, but
  be careful. If you want to use any IO, you still
  have to use IO_Initialization() with a
  DefineControllerIO().

18
Individual Motor Control

• You can control any motor by 2 functions
• SetPWM()?
• SetMotor()?
• SetPWM() needs 2 values a motor port, and a
  speed between 0 (full reverse), 127 (stopped) and
  255 (full forward).
• SetMotor() is exactly the same, but uses a range
  between -127, 0, and 127. SetPWM() is generally
  more useful.

19
Driving Control

• There are several functions setup for driving
  ease
• Drive()?
• Tank2()?
• Tank4()?
• Arcade2()?
• Arcade4()?
• Each is described on a following slide.

20
Drive()?

• The Drive() function takes two values, the
  forward speed (between -127 and 127), and the
  turning speed (same range). In order to use it,
  you need to define the wheel configuration before
  using the Drive() fucntion
• TwoWheelDrive() - 2 values left motor and right
  motor ports.
• FourWheelDrive() - 4 values left rear, left
  front, right rear, right front.
• Any motors that are backwards can be reversed
  (inverted) with the SetInvertedMotor() function.
  It takes one value in the parentheses, the motor
  port to be inverted. These statements can be
  typed in the Initialize() function at the
  beginning of the program, or in the Autonomous(),
  OperatorControl() or main() functions, but must
  be before you use the Drive() function.

21
Tank2()?

• The Tank2() function allows a two-wheeled drive
  train to be controlled with the vertical axes of
  two joysticks on the controller. It takes 7
  values
• Radio input port (usually 1)?
• Left control channel on the radio (usually 3)?
• Right control channel on the radio (usually 2)?
• Left drive motor port
• Right drive motor port
• Invert left motor (1 for invert, 0 to leave it
  alone)?
• Invert right motor
• You don't need to define TwoWheelDrive() or
  FourWheelDrive() for this or any of the following.

22
Tank4()?

• Same as Tank2(), but adding 4 values
• Radio input
• Left control channel
• Right control channel
• Left front motor port
• Right front motor port
• Left rear motor port
• Right rear motor port
• Invert left front
• Invert right front
• Invert left rear
• Invert right rear

23
Arcade2()?

• Arcade2() allows you to control a 2-wheel drive
  robot with a single joystick. It takes the same
  values as Tank2(), except it replaces the left
  control channel with a forward channel, and the
  right control channel with a turning channel.

24
Arcade4()?

• Same inputs as Tank4(), but replace left control
  channel with a forward/back channel and the right
  control channel with a turning channel.

25
Radio

• To get the value of a channel on the radio
  directly, you can use one of 3 functions
• GetOIAInput() - Analog channel value (chan 1-4)?
• GetOIDInput() - Digital channel value (chan 56)?
• GetRxInput() - Raw value of any channel

26
GetOIAInput()?

• GetOIAInput() needs 2 values, the radio port
  (usually 1), and an analog channel (1, 2, 3, or
  4). It returns a value between 0 (full bottom or
  left), 127 (center) and 255 (full top or right).
  You can either put the whole function in another
  function as a value, or set a variable equal to
  it
• Drive(GetOIAInput(1, 2), GetOIAInput(1, 1))
• int forward GetOIAInput(1,2)

27
GetOIDInput()?

• GetOIDInput() needs two values, the radio input
  port and a specific button (1 for top left, 2 for
  bottom left, 3 for top right, 4 for bottom
  right). GetOIDInput() returns a 1 if the
  button is pushed, or a 0 if it's not.
  GetOIDInput() is generally not used, and
  GetRxInput() is favored.

28
GetRxInput()?

• GetRxInput() returns the raw value of any radio
  channel, and needs two values the radio input
  port, and the channel number. It returns the
  same values as GetOIAInput() for channels 1-4,
  but GetOIAInput() is usually used instead. For
  channels 5 and 6, it returns a near-zero value
  for bottom, near-255 for top, and near-127 for
  neither. Usually, a threshold value below 90 or
  above 150 is used to figure out which is pushed.

29
Inputs

• To get a number from an IO port defined as a
  digital input (in DefineControllerIO()), you use
  the GetDigtalInput() function
• The only value in the parentheses is the digital
  input port number.
• The function returns a 1 for pushed (as in a
  switch) and 0 for open/no sensor.
• GetAnalogInput() is the same, but for an analog
  input port, and returns a number between 0 and
  255.

30
Outputs

• SetDigitalOutput() is used to set a value of
  either 0 or 1 to a digital output port. It
  accepts two values
• The digital output port number
• The value to send to that port
• The SetAnalogOutput() function is the same, but
  uses a range from 0 to 255 instead of 0 or
  1.

31
wait()?

• The wait() statement will halt the program for a
  certain number of milliseconds
• Drive(127,0)wait(1000)Drive(0,0)
• That code will drive forward for 1 second, and
  then stop.

32
Sample Program

• On the next slide is a program to go forward for
  10 seconds autonomously. Then it goes into
  operator control. In operator control, if a
  bumper switch mounted on the front, plugged into
  port 5, is pressed (the robot runs into
  something), it will back up for 3 seconds. The
  robot is driven in Tank2() mode. Operator
  control lasts for 2 minutes.

33
Sample Program

• include BuiltIns.h
• void IO_Initialization()
• //The first 4 ports are analog, the rest are
  digital. The first half of each are inputs.
• DefineControllerIO(4, 1, 1, 0, 0, 1, 1, 1, 1, 1,
  1,0,0,0,0,0,0)
• SetCompetitionMode(10, 120)
• void Initialize()
• TwoWheelDrive(1, 2)
• SetInvertedMotor(2)
• void Autonomous()
• Drive(127, 0)
• void OperatorControl()
• int left, right

34
Sample Program cont.

• while(1)
• //In the next line, ! means not, and is
  equivalent to GetDigitalInput(5) 0
• while(!GetDigitalInput(5))
• left GetOIAInput(1, 3)
• right GetOIAInput(1, 2)
• Tank2(1, 3, 2, 1, 2, 0, 1)
• printf(Left d Right d\r\n\r\n, left,
  right)
• Drive(-127, 127)
• wait(3000)
• void main()