The Beginners Guide to ROBOTC Volume 2, 3 rd Edition Written by George Gillard Published: 18-July-2016
Introduction ROBOTC is an application used for programming robots. There are many different versions of ROBOTC, but I highly recommend using the latest version, and use the same version across your whole team. That way, different people in your team can program the same robot without having to download the firmwares every time. In this guide to ROBOTC, I'm using ROBOTC for VEX Robotics version 4.52, a VEX Cortex Microcontroller and a VEXnet Joystick. ROBOTC for VEX Robotics is able to program the VEX Cortex and VEX IQ Brain. If you wish to program the discontinued VEX PIC Microcontroller, you will need to install ROBOTC 3.X for Cortex & PIC. There are also many different styles of programming - this guide has been written for the way that I personally program. My last guide was aimed at getting a beginner programmer to be able to program a robot to a level at which it could be operated by a driver, and with some simple autonomous programming a good start for a competition. In this guide, I will expand on the previous guide, building upon the previous knowledge to write more and elegant code, which can be implemented better in practice. Sections 1. Driver Control Code (Part 2) 2. The ROBOTC Debugger 3. Variables 4. Functions and Tasks 5. Simple Improvements to Control 6. LCD Display Programming This guide is provided to assist those learning how to program VEX Robots. This is a free document, but I ask that you ask for my consent before redistributing online, but please feel free to share a link. This document, along with my others, are available for free download from http://georgegillard.com. Page 2 Published: 18-July-2016 George Gillard
1 Driver Control Code (Part 2) In the previous guide, we learned how to control motors with commands from the joystick. In this guide, we ll optimize this code a bit further, with some additional concepts. 1.1 Deadbands You ll find that when releasing a thumb-stick on a joystick, it most likely will not fall at exactly zero it ll be slightly off. In practice this isn t too much of an issue, because the motors won t actually be able to turn anything under load until they have a significant amount of power applied to them this could be as little as 15 or as much as 30. However, it is often still desirable to cut out the noise from a not-perfectly centred thumb-stick. What we need to do, is determine if the thumb-stick is within a certain threshold, which will be our deadband or dead zone if you like. Something like this: If the thumb-stick is more than 10 OR less than -10 Use the actual thumb-stick output value Else Consider as zero Note, the value of 10 is completely arbitrary, and would need testing. It might be that 15 works better for you, for example. I m using tank control for this example, for the left hand side of a drive train. We d then copy this again for the right hand side, changing the channel number and motor name as required: Figure 1.1.1 However, we could make this a little more elegant. For this, we ll meet a new friend the absolute operator. The absolute operator (abs(input)) basically returns the magnitude of a number, that is, it returns the same number, but ignores if it is positive or negative. For example: abs(5) is equal to 5 abs(-5) is equal to 5 abs(0) is equal to 0 abs(127) is equal to 127 abs(-127) is equal to 127 Page 3 Published: 18-July-2016 George Gillard
This is useful for our purpose, because if we took the absolute of the thumb-stick value, we could use this to very easily determine if it is within the deadband region, as shown below: Figure 1.1.2 If we wanted to be really fancy, we can actually reduce all of this down to a single line. For this, we could use a ternary operator. The ternary operator is used as a replacement for an if/else statement, when we want to directly control the value of something. It works something like this: Motor value = either vexrt[ch3], or 0, depending on the deadband Ternary operators are written in the format: Value = (condition)? (output 1) : (output 2); The? and : are the operating bits here. You could think of it this way: The question mark says, Is the condition true?. If so, it will give Value = output 1. Otherwise (says the colon), it will give Value = output 2. In our example, we get this: Figure 1.1.3 Note: A lot of people don t like ternary operators because they can look a little bit confusing/scary. It is perfectly acceptable to just use an if/else structure if that s what you prefer. 1.2 Trim Sometimes, motors need to be given a bit of extra power to help hold something in place. For example, an arm might fall back down due to gravity if it hasn t any power resisting this. Ideally, you d use elastic to help the arm stay up such as from rubber bands, however in some cases this isn t so simple. Another example would be a claw/manipulator, which just needs an extra bit of power to hold something, when you don t want to apply full power to hold an object (which would likely cause the motor s thermal protector to trip, and the motor would stop working). Page 4 Published: 18-July-2016 George Gillard
In such cases, we want to apply a small amount of power (such as 15 out of 127) when the arm is at rest. Two ways that we could do this would be by simply add 15 to the existing control speed, however this means that the maximum negative speed would now become -112 instead of -127, or, we could just set the power to 15 when the power from the joystick would be 0. In this example, we ll use an arm motor, being operated by the 5U and 5D buttons on the joystick. Method 1: This is pretty simple we just use addition: Method 2: motor[arm] = (vexrt[btn5u] vexrt[btn5d])*127 + 15; This is a little more complicated we need to detect when the power from the joystick is zero. The following example does this by just checking if either button is being pressed. if ( vexrt[btn5u] vexrt[btn5d] ) motor[arm] = (vexrt[btn5u] vexrt[btn5d])*127; else motor[arm] = 15; 1.3 Preset Heights This is a topic in itself, so in this guide, I will just explain the concept. I have a separate document on my website which explains how I personally write code for preset heights. The idea of a preset height is that you could press a button on the joystick, and an arm (or other elevating mechanism) would lift automatically to a particular height. You might use this for lifting to a goal, without having to worry about controlling the arm as well as other mechanisms such as a drive train. First, you d need to determine the height of each goal or preset height you wish to use. Using the ROBOTC debugger, this is pretty easy make sure you have the sensors window open, and start the debugger, and you should see the value of the potentiometer or whichever sensor you use on your lift change as you move it around. Record the relevant values for the right heights you ll need to put them in your code. Then, in your code, you need to detect when the relevant button on your joystick is pressed this will be the activation of the preset control. Finally, you need some autonomous code within your driver control code which executes the actions to lift the arm to the required heights. Page 5 Published: 18-July-2016 George Gillard
2 The ROBOTC Debugger The ROBOTC Debugger is a powerful tool when testing your robot. It s most useful for getting real-time feedback and data from your robot, particularly if you want to know what the sensors are reading, or if you want to run through your code line-by-line or up to breakpoints, allowing you to analyse the execution of your code as it happens. When you download code to your robot, a little box will display on your screen: Figure 2.1 This is the main control of the debugger. By clicking the Start button, your robot will begin the program. Once started, you can click Stop which will stop the program. The ROBOTC Wiki/API has a great explanation of the various functions in the debugger. For this guide, we ll just worry about the Start/Stop control. Below the main text editor, you ll see a big box, something like this: Figure 2.2 This is where you ll find information from your sensors, motors, variables, etc. By going to Robot Debugger Windows, you ll be able to choose whichever windows you wish to use. Try not to have too many open at once, or the debugger will slow down. Page 6 Published: 18-July-2016 George Gillard
Figure 2.3 Say we have an arm on our robot with a potentiometer. If we wanted to see what the potentiometer was reading, we d have to check the Sensors window was checked in the list on Robot Debugger Windows, and then so long as our sensor has been set up correctly in the Motors and Sensors Setup window, we should see our potentiometer in the debugger window along the bottom of the screen. Figure 2.4 You can even control motors from the debugger if you really wanted to open the Motors window, and type in a value for the Power column. When using the larger red Quadrature Encoders, try testing them with the debugger. Quite often you ll find that the wires are plugged in in the wrong order, and the debugger can be really useful for finding these sorts of issues. Page 7 Published: 18-July-2016 George Gillard
3 Variables Variables are used to label and store a value in memory. A bit like how in algebra, you might use the letter x to replace a value, variables can be helpful to keep things simple in code. There are multiple types of variable in ROBOTC, such as: Integer (int) a whole number (e.g. -3, -2, -1, 0, 1, 2, or 3) Floating decimal number (float) a number with a decimal point (e.g. 1.5, 0.321, -123.456) Boolean (bool) either true or false/1 or 0. Character (char) a single number, letter, or symbol String (string) a series of characters There are others too, such as bytes, and variations of integers such as short or long, however we ll focus only on the types above. 3.1 Creating a Variable To create a variable, we must declare it. To do this, we type the code for what type it is (in brackets above), followed by a name. If we know what value we want it to be, we can set that straight away, as shown: Unknown/Normal: int myvariable; With a known value: int myvariable = 20; If we want to define multiple variables of the same type, we can do so in a single line by separating the names by a comma: int apples, bananas, pears; If we never want our variable to change, and we know it s value, we can set it up as a constant when we define the variable: const int lifttrim = 15; Page 8 Published: 18-July-2016 George Gillard
Or, instead, we could use the #define command to do a similar thing: #define lifttrim 15 Note: We don t need an equal sign or a semicolon for a #define. The way the define command works, is that it essentially does a find a replace through the code in the program when it is downloaded. It will replace lifttrim with 15 in the above case, whenever lifttrim is seen in the code. 3.2 Using a Variable Once defined, we can give our variable a new value, like shown below: myvariable = 30; Or, perhaps a more practical use: currentangle = sensorvalue(armpotentiometer); If we want to read a value in a variable, we can do so like shown: speed = 127; motor[leftdrive] = speed; We can do pretty much anything with a variable, for example, maths: Or, apples = 6; bananas = 5; piecesoffruit = apples + bananas; boxheight = 5; boxwidth = 10; boxarea = boxheight * boxwidth; You can view the value of a variable in the ROBOTC Debugger when your program is running. Page 9 Published: 18-July-2016 George Gillard
4 Functions and Tasks Functions and tasks are used to add a bit more structure to your code mainly to avoid writing repetitive sections of code, and hence make it all shorter and more user-friendly. 4.1 Functions 4.1.1 Void-type functions Recall the simple autonomous from Volume 1 of The Beginners Guide to ROBOTC: Figure 4.1.1.1 This code was used to drive forwards for 5 seconds, turn left for 1 second, drive forwards for another 2.5 seconds, and then stop. Wouldn t this be simpler if we could write something like this: Figure 4.1.1.2 Apart from clearly being shorter, it also is much easier to understand. This is an example of a use of functions where we create a command, and then use it to make the code much more elegant and user-friendly. To use a function, we must first have declared it (created its name), much like a variable. void functionname (input parameters); We use a void when we want the function to do a job, without needing a value out of it. For the driveforward function used above, we d declare it as follows: void driveforward(int time); In this case, time is an input parameter (a variable) we use in the function, but we must declare it with the function, in the round brackets. Page 10 Published: 18-July-2016 George Gillard
Of course, to go with the declaration, we must write the code that actually does the job the definition. Once again though, we must write the type of function at the front, and the declaration of variables in the round brackets. The definition of the driveforward function would look something like the following: Figure 4.1.1.3 Note: No semicolon is needed at the end of the very first line (after void driveforward(int time) ), unlike in the definition. If we define the function before we actually use it, we don t actually have to declare it at all the definition will take care of that for us. We only need to declare it separately if we use the function before we have defined it. Generally, it s far more common to define all the functions at the very beginning of your program, and just keep it straightforward without extra declarations. What if we wanted to control the speed, as well as the time? Our definition would look something like this: Figure 4.1.1.4 We d then incorporate that into our code like so: driveforward(5000, 127); What if we wanted to be able to control the speed, but also wanted it to have a default value so that if we don t specify a speed, it automatically assumes 127? Our definition would look something like this: Figure 4.1.1.5 Page 11 Published: 18-July-2016 George Gillard
4.1.2 Variable-type Functions Not all functions have to be of the type void. Quite often, we might want a value out of the function. Variables too, can be used as functions, and are created in the exact same was as void-type functions. Say, we might want to calculate the area of a box as a simple example, or maybe a more practical solution would be to calculate the average value of two drive encoders (one left, one right). Inside the definition of the function, we use return to write the output. For the first example, let s assume that we want to plug in a height and a width, both integers, and get an area out of that. We know that the output must also be an integer, so, we can create an int-type function: Figure 4.1.2.1 Then, when we wish to use the function, we would just write something like: area = findarea(5, 6); For the second example, so long as we know the names of the encoders we wish to use, and want to create a function to just find the average of these (rather than a generic average function), we could create a function with no input variables. We know that both encoders will be integers, but the output might not for example if one encoder was 120 and the other was 125, the average would be 122.5. For this, we d need a float-type function: Figure 4.1.2.2 Note: We can create and use variables like normal within the function, but only need to use the return command for the final output value. We would then call this function by writing something like: currentdistance = aveencoders(); Note: we still need to use the two round brackets alongside the function name, even if there are no inputs. Page 12 Published: 18-July-2016 George Gillard
4.2 Tasks Tasks are similar in concept to functions in the sense that you can replace huge chunks of repetitive code with them, however they work quite differently. Tasks are started or stopped, and work in the background, rather than sequentially like functions. This makes tasks more ideal for multitasking purposes. For example, it is quite common to use functions to control a drive-train, but a task to control an arm. This means that the wheels can continue to drive on with the next instructions, while the arm begins to lift, without having to wait. You will probably recognise tasks from task main(), or task usercontrol() or task autonomous(). The latter two are created as tasks, so the competition template still retains control, and can cut off the usercontrol() or autonomous() tasks without having to wait. Tasks are defined much like a function, however they cannot have any input parameters. They are defined as shown below: task taskname() { } Tasks are then called in your code by using: starttask(taskname); Tasks can be stopped by using: stoptask(taskname); If you wish to have the equivalent of an input parameter, you ll need to set up a global variable. Page 13 Published: 18-July-2016 George Gillard
The following task is used to control an arm: Figure 4.2.1 Note: A threshold is used because it is highly unlikely that the arm s potentiometer would read the exact value of height when it has lifted, meaning that the arm would continuously bounce up and down as it overshoots the perfect value. Therefore, an acceptable range was created for the above code. The target height is then specified and task is then called once by using: height = 1500; starttask(arm); Throughout the autonomous code, if the target height were to be changed, the only thing that needs doing is changing the value of height. For example: Figure 4.2.2 Page 14 Published: 18-July-2016 George Gillard
5 Simple Improvements to Control The programming taught so far for controlling wheels and arms has been quite crude. There are a number of improvements that can greatly improve the accuracy or smoothness of code. The first improvement is to use sensors wherever appropriate, as the inbuilt timer to ROBOTC depends on the motors running at the same speed every time which of course won t be true when your batteries aren t at the same voltage. As you get more and more confident with programming, I highly encourage you to experiment with some of your own ideas for improvements, and also explore other ideas, but for now, here are some reasonably good ways to quickly improve the control you have: 5.1 Braking for Drive-trains A common issue with drive-trains is that you ll instruct the robot to drive forwards a certain distance at full speed, and then suddenly stop. Due to the inertia of the robot, the robot will never stop quite like you would like, so applying some slight power in the opposite direction for a short period of time will provide some resistance to the continued movement of your robot. Taking the driveforwards function from earlier, we can implement braking like shown below: Figure 5.1.1 Warning: This can be quite nasty to the motors. Don t do this on a heavy robot moving quite fast when it tries to brake, or you ll most likely damage quite a few motors! 5.2 Driving Straight Driving in a perfectly straight line can be really tricky. Whilst this solution won t get your robot driving perfectly straight, it will probably be an improvement. This is a very basic implementation of a proportional controller in the rotational dimension, applied to the basic driveforwards function. A variable called turncorrection is created, which will be positive when the robot has unintentionally turned left slightly. By adding this value to the left hand side and subtracting it from the right hand side, the new speeds of the motors should correct the curve somewhat. Page 15 Published: 18-July-2016 George Gillard
This code also uses the encoders to get a more accurate measured distance in the forward direction, rather than by using time. The aveencoders function created earlier is also used. Figure 5.2.1 If the robot now shakes as it drives, we might need to multiply the value of turncorrection by 0.5 or so, to get it to smoothen up. 5.3 Smoother Lifting The task created earlier to control an arm needed a threshold as an acceptable range for the arms position, otherwise the arm would bounce as it overshot the target height. This threshold then means that we have a reasonably large acceptable range, which means we could be significantly off the target height at the end. We can make the speed of the arm go up proportional to how far away the arm currently is from where we want it to be, and that way the arm will be going slow enough near the target not to bounce too much. This way, we don t need an acceptable range at all, and the arm will be both smoother and more accurate. Like the turn correction solution in Section 5.2, this is a basic implementation of a proportional controller. Figure 5.3.1 If the arm is a bit unstable/bouncy around the target height, we might need to multiply difference by 0.5 or so to get it to smoothen up. Page 16 Published: 18-July-2016 George Gillard
6 LCD Display Programming The VEX LCD is a simple display which has two rows, each of which can show 16 characters. There are three buttons below the display, which can be used as an input. These LCDs are commonly used to display data from the robot, such as battery voltage or sensor values, or to select an autonomous routine before a competition game, if the robot has multiple stored routines. You can open a mock LCD display in the ROBOTC Debugger. If you wish to program and test some code for an LCD without having a robot present to download onto, you can use the PC-Based Emulator option (Robot Compiler Target PC-Based Emulator), which allows you to test code without needing a Cortex. The best way to program an LCD display is to be creative. There are so many things you can do and ways of doing it, so I will just show you the tools you ll need to explore and have fun. 6.1 The Screen The screen has two rows and 16 columns, where 0 is the top line, 1 is the bottom line, 0 is the far left column and 15 is the far right column. clearlcdline(linenumber); This command will print all characters along a row (either 0 or 1). displaylcdcenteredstring(rownumber, "STRING"); This command will print a line of text along a row, such that it is centred horizontally. displaylcdstring(rownumber, columnnumber, "STRING"); This command will print a line of text, starting at the specified position, moving right. displaylcdchar(rownumber, columnnumber, CHARACTER ); This command will print a single character (letter, number, or symbol). Page 17 Published: 18-July-2016 George Gillard
displaylcdnumber(rownumber, columnnumber, value); This command will print a number at the specified position. setlcdposition(rownumber, columnnumber); This command will set the next position think of this as the location of a text cursor. displaynextlcdstring("string"); This command will print a string from the set position of the text cursor. displaynextlcdchar('character'); This command will print a single character from the set position of the text cursor. displaynextlcdnumber(value); This command will print a value from the set position of the text cursor. The following code would print out the value of a sensor in real-time, and an image of the LCD Display debugger window follows: Figure 6.1.1 Page 18 Published: 18-July-2016 George Gillard
Figure 6.1.2 sprintf(string to write to, STRING AND FORMATTING, values); This command writes to a pre-declared string, a string which follows the specified text and formatting, with any relevant values at the end. This can be quite confusing to learn, but can make printing complicated strings much easier. Type text as per normal for the string you wish to display. Wherever you want to insert a value, use a % symbol, then type a specifier d for an integer, f for a float, c for a character or s for a string. If you want to be specific about how much of the number is displayed, you can type the formatting as %(minimum width).(precision)(specifier). For example, %5.2f would have a minimum width of 5 digits, 2 decimal places, and would be a floating point number (e.g. if the value was 123.456, it would display 123.46). %.5d would have a precision of 5 places, and be a decimal value (e.g. if the value was 123, it would display 00123). Example: Creating the string Battery: 7.2V : Figure 6.1.3 Figure 6.1.4 Page 19 Published: 18-July-2016 George Gillard
6.2 Buttons We can get the value from the LCD Display buttons, by calling nlcdbuttons. This variable will have a value of 1 for the left button, 2 for the middle button, or 4 for the right button, when pressed. If multiple buttons are pressed, the value will be the sum of the values for each independent pressed button. When detecting if a button has been pressed, it is worth having a way of waiting for the button to be released again. If pressing the same button twice would have some action, without waiting for the release, you d skip straight through to the second action. Either use time, or detect when the button is released again. 6.3 Routines for Autonomous Selection Sometimes, having one autonomous routine for competition is not enough. Adaptability, flexibility, and unpredictability are valuable assets in competition. You could write multiple autonomous routines, but to do this, you d need a selection method. Quite common solutions include using a potentiometer as a selection dial, or buttons, or jumper switches (which act as a digital input, giving a 1 or 0 value). These are all pretty easy to work with. However, you may decide that actually you d like to use the LCD display to run a routine of its own to select an autonomous routine. If you choose to do this, write this code in the pre_auton() function in the competition template this will run when you switch the robot on, and allow you to select a routine in the period prior to the start of the game. Tip: Consider what would happen if your robot were to disconnect in a game. You want a fail-safe, such that the robot wouldn t be stuck in a game waiting for a user input for the autonomous selection. Either have a timeout, or use the bifirobotdisabled boolean variable, so that the selection routine only runs when the robot is disabled, and therefore not in the middle of an autonomous or driver control routine. Conclusion I hope that this guide has been of good use to you, and that you now feel more confident in programming using ROBOTC. When I began programming, I was incredibly nervous the first time I tried to write code. Thankfully, ROBOTC is very forgiving, and will point out most issues with your code when you compile it. In the current day and age, learning to program is an incredibly useful skill, and ROBOTC is a great language to learn in. I have other guides available on my website, and there are plenty of other fantastic resources online. For example, ROBOTC have a great wiki/api on their website, which has more-or-less everything you d need to know to be able to use the language. ROBOTC also provide plenty of sample programs, which are useful for learning. Good luck with all of your future programming endeavours! Page 20 Published: 18-July-2016 George Gillard