Difference between pages "Recursion" and "Creating an RBC file"

From ROBOTC API Guide
(Difference between pages)
Jump to: navigation, search
 
(Virtual World Index)
 
Line 1: Line 1:
<yambe:breadcrumb self="Recursion">General|General Programming</yambe:breadcrumb>
+
<yambe:breadcrumb self="Creating an RBC file">Main|Main page</yambe:breadcrumb>
<br />
+
  
{{tl|1|1}}
+
{{tl|1|}}
<br />
+
  
== Recursion ==
+
== What is an RBC file? ==
{| class="wikiText"
+
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
| Recursion is the ability for a function to call itself. Normally for a function to be called it must be created and then called from task main. However, with recursion a function can call itself multiple times; the downside of this is that until a function reaches its end brace '}' or reaches a 'return' command, it will stay in memory. This can lead to situations where the available memory fills up with too many concurrently running functions and causes a crash. Recursion in ROBOTC works on a "Last In First Out" (LIFO) process; the most recent function called will be the first one closed when a return command or an end brace '}' is reached.
+
|An RBC file is a special type of XML file that can be used with ROBOTC v3.52 or later. Once an RBC file is created properly, you will be able to configure ROBOTC's Platform Type, Compiler Target, Menu Level, and other important settings all with the click of a button. You can even configure the RBC program to load a user program and automatically download it to a robot or Virtual World of your choosing.
<br />
+
 
|-
 
|-
|For example, see the program below. First, a function called 'looping' is created and initialized. Inside of it there is a single 'return' command, which exits the function and 'returns' the program flow back to where the function was originally called from.  Next, there is task main with a single call to the function 'looping'.
+
|}
 +
 
 +
== How to create an RBC file ==
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
|[[File:Recursion_Return.png]]
+
|There are several steps required in order to create a working RBC file. You will need an activated installation of ROBOTC and a text file editor installed on the computer. For this demonstration, we used ROBOTC for VEX Robotics 4.0 and Notepad++ as our text file editor.
<br />
+
 
|-
 
|-
|When the program runs, the function 'looping' is created and the program starts at task main. The first command in task main is to call the function 'looping'. The Call Stack debugger window shows both task main and the function 'looping' being in memory at this point.
+
|'''1)''' Create a new file in your text file editor (generally found under the 'File -> New' menu option).
 
|-
 
|-
|[[File:Recursion_Return_Two.png]]
+
|'''2)''' Save the file with a custom name and a '.rbc' file extension. You may also need to change the 'File Type' dropdown menu to 'All Files', depending on the text editor settings.
<br />
+
 
|-
 
|-
|After 'looping' is called, its first command is to return to task main. This ends the function and clears it from memory (since the function has been exited, this can be seen in the Call Stack debugger window).
+
|'''3)''' Add the following parameters to the file:
 +
*<?xml version="1.0" encoding="UTF-8"?>
 +
*<RBCVersion>1.0.0</RBCVersion>
 +
*<Platform></Platform>
 +
*<CortexDLMethod></CortexDLMethod>
 +
*<CircuitBoard></CircuitBoard>
 +
*<MenuLevel></MenuLevel>
 +
*<CompilerMode></CompilerMode>
 +
*<CompileAndDownload></CompileAndDownload>
 +
*<VirtualWorldIndex></VirtualWorldIndex>
 +
*<SourceFileName>.c</SourceFileName>
 +
*<RVWParameters></RVWParameters>
 +
*<SourceCode></SourceCode>
 +
|-
 +
|'''4)''' Modify the parameters to fit the settings for the program. For a full listing of all of the available parameters, see the 'XML Parameters' section below.
 +
|-
 +
|'''5)''' Save the RBC file.
 +
|-
 +
|'''6)''' Manually open the RBC file icon by double clicking on it. If the file is configured correctly, ROBOTC should open with the specified parameters using the specified source code. If the program does not open correctly (or opens with the wrong settings), double check the parameters for accuracy.
 
|}
 
|}
<br />
+
 
== Memory Overload ==
+
== XML parameters ==
{|
+
===XML Version===
|One of the major issues that can arise when utilizing recursion is memory overload. This occurs when the onboard memory of a computer system or microprocessor is filled beyond maximum, or 'overloaded'.
+
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
|In the next example, we have simply placed a recursive call in 'looping' back to itself before the 'return' command. Now, each time 'looping' is called it reaches the recursive command first and opens up another copy of the function in memory. Since the program flow is directed to the new calling of the function before the return command or a closing brace is reached, each function remains open in memory.
+
| The XML Version parameter will identify the document as valid XML. This must always be at the top of the RBC document.
 +
*'''<?xml version="1.0" encoding="UTF-8"?>'''
 
|-
 
|-
|[[File:Recursion_Overload.png]]
+
|}
<br />
+
===RBC Version===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
|This eventually overloads the memory and causes a crash.
+
| Identifies the current RBC specification being used. As of today, this value should be specified as 1.0.0.
 +
*'''<RBCVersion>1.0.0</RBCVersion>'''
 
|-
 
|-
|[[File:Recursion_Error.png]]
+
|}
<br />
+
===Platform Type===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
 +
| Sets the platform type in ROBOTC. Requires the ROBOTC installation to have an appropriate license activated and valid in order to work properly.
 +
*'''<Platform>PlatformType</Platform>'''
 +
|-
 +
|}
 +
{| class="wikitable"
 +
|-
 +
|'''To set this platform type'''
 +
|'''Use this parameter'''
 +
|-
 +
|VEX PIC
 +
|VEX
 +
|-
 +
|VEX Cortex
 +
|VEX2
 +
|-
 +
|LEGO NXT
 +
|NXT
 +
|-
 +
|LEGO NXT + TETRIX
 +
|TETRIX
 +
|-
 +
|Arduino
 +
|ARDUINO
 
|}
 
|}
  
== Controlled Recursion ==
+
===Cortex Download Method (VEX Cortex only)===
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
+
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
|To use function recursion without running into a memory overload issue, the function must be set up to exit at some point. This can be done a variety of ways.  
+
| Sets the Cortex Download Method – used to modify the cortex download method to allow the Cortex to either require a VEXnet/USB cable in order to run, or to allow “standalone” mode to run a user’s program without searching for a COMM link. If the Cortex is using the VEXNet system or will be physically tethered to a Joystick Controller using the USB A-to-A cable, the VEXNet option should be used. Otherwise, use the USB-Only mode
 +
*'''<CortexDLMethod>DownloadMode</CortexDLMethod>'''
 
|-
 
|-
|One such possibility is to set up a simple if-else statement that checks a condition and 'returns' if one of the conditions are met. In the example below,  the if-else statement checks to see if the integer variable x (which starts with a value of 0) is less than 5. If it is, x is incremented by one and the function calls itself again. This process repeats until x is no longer less than 5 (the else statement), at which point the function ends and program flow returns to where the function was originally called from.
+
|}
 +
{| class="wikitable"
 
|-
 
|-
|[[File:Recursion_If_Else.png]]
+
|'''To set this download method'''
<br />
+
|'''Use this parameter'''
 
|-
 
|-
|A variant of this program that also works is to utilize parameters. By creating 'looping' with the integer x as its parameter, we can pass a value of 0 from task main and increment the value of x when it is passed to a new copy of looping every time recursion occurs.
+
|USB Only
 +
|USBOnly
 
|-
 
|-
|[[File:Recursion_If_Params.png]]
+
|USB or VEXNet
<br />
+
|USBorWifi
 +
|-
 +
|Competition (VEXNet)
 +
|Competition
 
|-
 
|-
 
|}
 
|}
  
== Ending Functions ==
+
===Circuit Board===
{|
+
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| This specifies the circuit board to be used. Has only real application with Arduino to differentiate between different board models (Uno,1280,2560,etc). Default value of blank (no value) for all other platforms.
 +
*'''<CircuitBoard></CircuitBoard>'''
 +
|-
 +
|}
 +
===Menu Level===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Sets the ROBOTC GUI Menu Level. Used to show/hide functionality by adjusting the menu level types (Basic, Advanced, and Super User)
 +
*'''<MenuLevel>Level</MenuLevel>'''
 +
|-
 +
|}
 +
{| class="wikitable"
 +
|-
 +
|'''To set this menu level'''
 +
|'''Use this parameter'''
 +
|-
 +
|Basic
 +
|Basic
 +
|-
 +
|Expert
 +
|Expert
 +
|-
 +
|Super User
 +
|SuperUser
 +
|-
 +
|}
 +
 
 +
===Compiler Mode===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Sets ROBOTC’s compiler mode (Compiler Target) – used to switch between real robots, the PC-based emulator, and Virtual Worlds compiling targets.
 +
*'''<CompilerMode>CompilerTarget</CompilerMode>'''
 +
|-
 +
|}
 +
{| class="wikitable"
 +
|-
 +
|'''To set this compiler target'''
 +
|'''Use this parameter'''
 +
|-
 +
|Physical Robot
 +
|Real
 +
|-
 +
|PC-based Emulator
 +
|Emulator
 +
|-
 +
|Virtual Worlds
 +
|VirtualWorlds
 +
|-
 +
|}
 +
 
 +
===Compile and Download===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Flag to specify if the source code should be “compiled” or “compiled and downloaded”. If set to “Yes”, the code will automatically be downloaded to the robot or Virtual World. Otherwise ("No", it will only be compiled.
 +
*'''<CompileAndDownload>Yes</CompileAndDownload>'''
 +
|-
 +
|}
 +
===Virtual World Index===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Sets the numerical type of the RVW Level Pack Index that should be launched. – This is only a numerical number that references the RVW Level Pack “ID” number.
 +
*'''<VirtualWorldIndex>IndexNumber</VirtualWorldIndex>'''
 +
|-
 +
|}
 +
{| class="wikitable"
 +
|-
 +
|'''To set this Virtual World'''
 +
|'''Use this index parameter'''
 +
|-
 +
|Learning ROBOTC Tables Preview
 +
|2
 +
|-
 +
|Curriculum Companion
 +
|3
 +
|-
 +
|FTC Block Party!
 +
|8
 +
|-
 +
|VEX Toss Up
 +
|9
 +
|-
 +
|FTC Ring It Up!
 +
|10
 +
|-
 +
|VEX Sack Attack
 +
|11
 +
|-
 +
|Robots to the Rescue: Operation Reset
 +
|12
 +
|-
 +
|Palm Island: Luau Edition
 +
|14
 +
|-
 +
|Ruins of Atlantis
 +
|15
 +
|-
 +
|RVW Level Builder
 +
|18
 +
|-
 +
|}
 +
 
 +
===Source File Name===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Name of the file that will be saved/displayed on the ROBOTC tab-bar at compile time – Note this file only is used if SourceCode is provided.
 +
*'''<SourceFileName>Name_Of_Program.c</SourceFileName>'''
 +
|-
 +
|}
 +
===RVW Parameters===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 +
|-
 +
| Command Line Parameters that will be passed the next time Robot Virtual Worlds is launched. If the “CompileAndDownload” flag is set to “NO”, these parameters will be stored for the next execution. After the Virtual Worlds has been executed once, these parameters are discarded.
 +
*'''<RVWParameters>parameter1 parameter2 parameter3</RVWParameters>'''
 +
|-
 +
|}
 +
===Source Code===
 +
{| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;" width="100%" cellpadding="5%" cellspacing="0" border="0"
 
|-
 
|-
|If the above programs are manually stepped through, there will be 5 steps to go through before task main is returned to. Remember, each time a function is called it opens another 'copy' of the function. Those extra steps are for the first, second, third, and fourth copies of the 'looping' function. The functions only clear out of memory when their end brace '}' or a return command is reached.
+
| Source Code of program to be open/compiled/downloaded. This is not a reference to an existing file but rather the actual contents of the file. Because the RBC file uses XML formatting, the file cannot contain any XML escape markups in the Source Code section. Instead, the escape markups must be replaced with the characters below:
 
|-
 
|-
 
|}
 
|}
<br />
 

Revision as of 16:31, 8 April 2014

Creating an RBC file


What is an RBC file?

An RBC file is a special type of XML file that can be used with ROBOTC v3.52 or later. Once an RBC file is created properly, you will be able to configure ROBOTC's Platform Type, Compiler Target, Menu Level, and other important settings all with the click of a button. You can even configure the RBC program to load a user program and automatically download it to a robot or Virtual World of your choosing.

How to create an RBC file

There are several steps required in order to create a working RBC file. You will need an activated installation of ROBOTC and a text file editor installed on the computer. For this demonstration, we used ROBOTC for VEX Robotics 4.0 and Notepad++ as our text file editor.
1) Create a new file in your text file editor (generally found under the 'File -> New' menu option).
2) Save the file with a custom name and a '.rbc' file extension. You may also need to change the 'File Type' dropdown menu to 'All Files', depending on the text editor settings.
3) Add the following parameters to the file:
  • <?xml version="1.0" encoding="UTF-8"?>
  • <RBCVersion>1.0.0</RBCVersion>
  • <Platform></Platform>
  • <CortexDLMethod></CortexDLMethod>
  • <CircuitBoard></CircuitBoard>
  • <MenuLevel></MenuLevel>
  • <CompilerMode></CompilerMode>
  • <CompileAndDownload></CompileAndDownload>
  • <VirtualWorldIndex></VirtualWorldIndex>
  • <SourceFileName>.c</SourceFileName>
  • <RVWParameters></RVWParameters>
  • <SourceCode></SourceCode>
4) Modify the parameters to fit the settings for the program. For a full listing of all of the available parameters, see the 'XML Parameters' section below.
5) Save the RBC file.
6) Manually open the RBC file icon by double clicking on it. If the file is configured correctly, ROBOTC should open with the specified parameters using the specified source code. If the program does not open correctly (or opens with the wrong settings), double check the parameters for accuracy.

XML parameters

XML Version

The XML Version parameter will identify the document as valid XML. This must always be at the top of the RBC document.
  • <?xml version="1.0" encoding="UTF-8"?>

RBC Version

Identifies the current RBC specification being used. As of today, this value should be specified as 1.0.0.
  • <RBCVersion>1.0.0</RBCVersion>

Platform Type

Sets the platform type in ROBOTC. Requires the ROBOTC installation to have an appropriate license activated and valid in order to work properly.
  • <Platform>PlatformType</Platform>
To set this platform type Use this parameter
VEX PIC VEX
VEX Cortex VEX2
LEGO NXT NXT
LEGO NXT + TETRIX TETRIX
Arduino ARDUINO

Cortex Download Method (VEX Cortex only)

Sets the Cortex Download Method – used to modify the cortex download method to allow the Cortex to either require a VEXnet/USB cable in order to run, or to allow “standalone” mode to run a user’s program without searching for a COMM link. If the Cortex is using the VEXNet system or will be physically tethered to a Joystick Controller using the USB A-to-A cable, the VEXNet option should be used. Otherwise, use the USB-Only mode
  • <CortexDLMethod>DownloadMode</CortexDLMethod>
To set this download method Use this parameter
USB Only USBOnly
USB or VEXNet USBorWifi
Competition (VEXNet) Competition

Circuit Board

This specifies the circuit board to be used. Has only real application with Arduino to differentiate between different board models (Uno,1280,2560,etc). Default value of blank (no value) for all other platforms.
  • <CircuitBoard></CircuitBoard>

Menu Level

Sets the ROBOTC GUI Menu Level. Used to show/hide functionality by adjusting the menu level types (Basic, Advanced, and Super User)
  • <MenuLevel>Level</MenuLevel>
To set this menu level Use this parameter
Basic Basic
Expert Expert
Super User SuperUser

Compiler Mode

Sets ROBOTC’s compiler mode (Compiler Target) – used to switch between real robots, the PC-based emulator, and Virtual Worlds compiling targets.
  • <CompilerMode>CompilerTarget</CompilerMode>
To set this compiler target Use this parameter
Physical Robot Real
PC-based Emulator Emulator
Virtual Worlds VirtualWorlds

Compile and Download

Flag to specify if the source code should be “compiled” or “compiled and downloaded”. If set to “Yes”, the code will automatically be downloaded to the robot or Virtual World. Otherwise ("No", it will only be compiled.
  • <CompileAndDownload>Yes</CompileAndDownload>

Virtual World Index

Sets the numerical type of the RVW Level Pack Index that should be launched. – This is only a numerical number that references the RVW Level Pack “ID” number.
  • <VirtualWorldIndex>IndexNumber</VirtualWorldIndex>
To set this Virtual World Use this index parameter
Learning ROBOTC Tables Preview 2
Curriculum Companion 3
FTC Block Party! 8
VEX Toss Up 9
FTC Ring It Up! 10
VEX Sack Attack 11
Robots to the Rescue: Operation Reset 12
Palm Island: Luau Edition 14
Ruins of Atlantis 15
RVW Level Builder 18

Source File Name

Name of the file that will be saved/displayed on the ROBOTC tab-bar at compile time – Note this file only is used if SourceCode is provided.
  • <SourceFileName>Name_Of_Program.c</SourceFileName>

RVW Parameters

Command Line Parameters that will be passed the next time Robot Virtual Worlds is launched. If the “CompileAndDownload” flag is set to “NO”, these parameters will be stored for the next execution. After the Virtual Worlds has been executed once, these parameters are discarded.
  • <RVWParameters>parameter1 parameter2 parameter3</RVWParameters>

Source Code

Source Code of program to be open/compiled/downloaded. This is not a reference to an existing file but rather the actual contents of the file. Because the RBC file uses XML formatting, the file cannot contain any XML escape markups in the Source Code section. Instead, the escape markups must be replaced with the characters below: