Difference between pages "ARDUINO MEGA Update Bootloader" and "Creating an RBC file"

From ROBOTC API Guide
(Difference between pages)
Jump to: navigation, search
(Software Needed)
 
(Virtual World Index)
 
Line 1: Line 1:
'''Note: This document only applies to the MEGA 2560 and MEGA ADK Arduino Boards. All other Arduino boards bootloaders are good!'''
+
<yambe:breadcrumb self="Creating an RBC file">Main|Main page</yambe:breadcrumb>
  
== Arduino 2560 Bootloader Issue ==
+
{{tl|1|}}
The current bootloader burned onto the Arduino MEGA 2560/ADK is not compatible with ROBOTC. In its current form, you will be able to download the ROBOTC Firmware to the Arduino MEGA 2560/ADK, but you will not able to download any user programs.
+
  
The reason for this is because there is a bug in the Arduino MEGA 2560/ADK firmware that does not allow flash write commands to start at anywhere but the beginning of flash memory (0x000000). See the bottom of this page for more technical details.
+
== What is 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"
 +
|-
 +
|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.
 +
|-
 +
|}
  
Because ROBOTC is not able to burn a new bootloader as of today, you will need to use the Arduino's Open Source language with our a modified bootloader file to re-burn your bootloader on your Arduino MEGA 2560/ADK boards. '''The enhanced bootloader is backwards compatible with the original one. That means you'll still be able to program it through the Arduino programming environment as before, in addition to ROBOTC for Arduino.'''
+
== 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"
 +
|-
 +
|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.
 +
|}
  
== Hardware Needed  ==
+
== XML parameters ==
To burn a new version of the Arduino bootloader to your MEGA 2560/ADK, you'll need an AVR ISP Compatible downloader.
+
===XML 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"
 +
|-
 +
| 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===
 +
{| 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"
 +
|-
 +
| 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===
 +
{| 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
 +
|}
  
'''Using an AVR ISP (In System Programmer)'''
+
===Cortex Download Method (VEX Cortex only)===
*Your Arduino MEGA 2560/ADK (to program)
+
{| 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"
*An AVR Programmer such as the [http://www.sparkfun.com/products/9825 AVR Pocket Programmer]
+
|-
*An AVR Programming Cable (the pocket programmer comes with one)
+
| 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>'''
 +
|-
 +
|}
 +
{| class="wikitable"
 +
|-
 +
|'''To set this download method'''
 +
|'''Use this parameter'''
 +
|-
 +
|USB Only
 +
|USBOnly
 +
|-
 +
|USB or VEXNet
 +
|USBorWifi
 +
|-
 +
|Competition (VEXNet)
 +
|Competition
 +
|-
 +
|}
  
----
+
===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
 +
|-
 +
|}
  
If you have extra Arduino boards, but no ISP programmer, SparkFun.com has a cool tutorial on how to flash a bootloader using an Arduino as an ISP.
+
===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
 +
|-
 +
|}
  
'''Using another Arduino as an ISP'''
+
===Compile and Download===
*Your Arduino MEGA 2560/ADK (to program)
+
{| 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"
*A Working Arduino (doesn't matter what kind)
+
|-
*Some Male-to-Male Jumper Cables
+
| 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 parameter index'''
 +
|-
 +
|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
 +
|-
 +
|}
  
For instructions on this method, take a look at the SparkFun.com website: http://www.sparkfun.com/tutorials/247
+
===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"
== Software Needed ==
+
|-
ROBOTC is not currently able to burn a bootloader onto an Arduino board, so you'll need to download a copy of the latest version of the Arduino Open-Source programming language.
+
| 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.
*Arduino Official Programming Language - [http://arduino.cc/en/Main/Software|Arduino Download Page]
+
*'''<SourceFileName>Name_Of_Program.c</SourceFileName>'''
 
+
|-
In addition, you'll need the ROBOTC modified bootloader. You can download that here:
+
|}
*ROBOTC Modified MEGA 2560/ADK Bootloader - [cdn.robotc.net/downloads/arduino/stk500boot_v2_mega2560.hex| Modified Bootloader]
+
===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"
== Bootload Download Instructions ==
+
|-
* Download the [http://arduino.cc/en/Main/Software Arduino Open Source Software] and a copy of the [http://cdn.robotc.net/downloads/arduino/stk500boot_v2_mega2560.hex Modified Bootloader] File
+
| 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.
* Copy the Modified Bootloader File into the /Arduino-1.0/hardware/arduino/bootloaders/stk500v2/ and overwrite the existing bootloader.
+
*'''<RVWParameters>parameter1 parameter2 parameter3</RVWParameters>'''
[[File:CopyBootloader.png|800px]]
+
|-
* Power up your Arduino MEGA 2560/ADK (either via USB or external power)
+
|}
* Plug in your AVR ISP Programmer to your computer (make sure you have any required drivers installed)
+
===Source Code===
* Connect your AVR ISP Programmer into your Arduino MEGA 2560/ADK Board via the ISP Header (the 2x3 header pins right above the Arduino Logo)
+
{| 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"
* Launch the Arduino Open Source Software
+
|-
[[File:ArduinoLaunch.png]]
+
| 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:
* Change your settings in the Arduino Software to look for an Arduino MEGA 2560/ADK
+
|-
[[File:ArduinoSelectPlatform.png]]
+
|}
* Change your settings in the Arduino Software to select your ISP Programmer Type (Check your programmer's documentation for the exact model)
+
[[File:ArduinoSelectProgrammer.png]]
+
* Select the "Burn Bootloader" option under the "Tools" menu. The modified bootloader will now be sent to your Arduino. This typically take a minute or so.
+
[[File:BurnBootloader.png]]
+
* You should be all set to download ROBOTC firmware and start using your Arduino MEGA 2560/ADK with ROBOTC!
+
 
+
== Technical Details ==
+
The Arduino Bootloader sets the "eraseAddress" to zero every time the bootloader is called. ROBOTC called the "Load Address" command to set the address in which we want to write/verify when downloading program.
+
 
+
When writing a page of memory to the arduino, the Arduino bootloader will erase the existing page and write a whole new page.
+
 
+
In the scenario of downloading firmware, everything is great because the Erase Address and the Loaded Address both start at zero.
+
 
+
In the scenario of writing a user program, we start writing at memory location 0x7000, but the Bootloader erases information starting at location zero because the "Load Address" command doesn't update where to erase.
+
 
+
Our modification is to set both the Load Address and the Erase Address so the activity of writing a user program doesn't cause the firmware to be accidentally erased!
+
 
+
=== Original Bootloader ===
+
<syntaxhighlight lang="ROBOTC">
+
case CMD_LOAD_ADDRESS:
+
#if defined(RAMPZ)
+
  address = (((address_t)(msgBuffer[1])<<24)|((address_t)(msgBuffer[2])<<16)|
+
            ((address_t)(msgBuffer[3])<<8)|msgBuffer[4]))<<1;
+
#else
+
  address = (((msgBuffer[3])<<8)|(msgBuffer[4]))<<1; //convert word to byte address
+
#endif
+
msgLength = 2;
+
msgBuffer[1] = STATUS_CMD_OK;
+
break;
+
 
+
case CMD_PROGRAM_FLASH_ISP:
+
case CMD_PROGRAM_EEPROM_ISP:
+
{
+
  unsigned int size = ((msgBuffer[1])<<8) | msgBuffer[2];
+
  unsigned char *p = msgBuffer+10;
+
  unsigned int data;
+
  unsigned char highByte, lowByte;
+
  address_t tempaddress = address;
+
 
+
  if ( msgBuffer[0] == CMD_PROGRAM_FLASH_ISP )
+
  {
+
    // erase only main section (bootloader protection)
+
    if (eraseAddress < APP_END )
+
    {
+
      boot_page_erase(eraseAddress); // Perform page erase
+
      boot_spm_busy_wait(); // Wait until the memory is erased.
+
      eraseAddress += SPM_PAGESIZE; // point to next page to be erase
+
    }
+
</syntaxhighlight>
+
=== ROBOTC Compatible Modification ===
+
<syntaxhighlight lang="ROBOTC">
+
case CMD_PROGRAM_FLASH_ISP:
+
case CMD_PROGRAM_EEPROM_ISP:
+
{
+
  unsigned int size = ((msgBuffer[1])<<8) | msgBuffer[2];
+
  unsigned char *p = msgBuffer+10;
+
  unsigned int data;
+
  unsigned char highByte, lowByte;
+
  address_t tempaddress = address;
+
 
+
 
+
  if ( msgBuffer[0] == CMD_PROGRAM_FLASH_ISP )
+
  {
+
    eraseAddress = address & 0xFFFFFF00;  // ROBOTC Custom Bootloader Addition
+
 
+
    // erase only main section (bootloader protection)
+
    if (eraseAddress < APP_END )
+
    {
+
      boot_page_erase(eraseAddress); // Perform page erase
+
      boot_spm_busy_wait(); // Wait until the memory is erased.
+
      eraseAddress += SPM_PAGESIZE; // point to next page to be erase
+
    }
+
</syntaxhighlight>
+

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 parameter index
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: