x0xb0x User Manual: Bootloading

The x0xb0x firmware is responsible for all of the digital functionality: driving LEDs, reading switches, gating notes to the analog synthesizer, running the sequencer, etc. The firmware is essentially a compiled program that is burned into the microcontroller chip (in this case, the ATmega162). The x0xb0x firmware is written in C and can be (re)compiled using the ubiquitous and free avr-gcc compiler. You are encouraged to add functionality to the x0xb0x, fix any bugs, etc. and exchange firmware updates with others! (Within the constraints of the Open Source license.)

Normally, upgrading the firmware is performed by placing the microcontroller into an AVR-compatible programmer (such as the popular STK-500) and using the free AVR programming software to upload the new firmware. However, to make it easier to upload new firmware (and not have to purchase a specialized programmer) we have written and installed a bootloader onto the microcontroller. The bootloader is a small piece of code (.5K) that sits at the end of the program memory (at 15.5K) and is executed first. The bootloader checks to see if the FUNCTION knob is turned to bootload mode. If it is, and an escape character (0x1B ascii) is received over the USB connection, it enters bootload mode. If neither of these requirements are met, the bootloader jumps to address 0x0, which starts the x0xb0x firmware.

There is virtually no way to permanently confuse the bootloader to the point where firmware cannot be uploaded. (However, you shouldn't try...) Regardless, you should only use bootloader mode when bootloading, as sending certain character commands to the bootloader will erase/overwrite the chip, or (worse) erase/overwrite only part of the chip.

Bootloading does not erase or change the data stored in the external EEPROM. Therefore all patterns and tracks are safe from modification.

Trying to uploade firmware that is longer than 15.5K will be rejected by the bootloading software program.

Setting the FUNCTION knob to Bootload while the x0xb0x is already on does not enter bootload mode.

Of course, the USB driver must be installed as described in the fabrication manual.

Installing Bootloader Software

The bootloader software is written in Java. Therefore you must install a copy of the Java Runtime Enviroment (JRE) or Java Software Development Kit (JSDK). The former is just for running software, the latter comes with a compiler and necessary stuff for building Java apps. Check if you have it installed by running/searching for a program called java. (I think MacOS X has a JRE already)

Since the x0xb0x communicates over serial, you'll need to also download a copy of the JavaComm API library which allows Java to enumerate ports and communicate over them.

CommAPI/RXTX is a little annoying to install.

To install CommAPI for Windows (stolen from Jolt)

  1. Unzip the Java Communications API somewhere on your disk. A commapi folder will be created. There will be three files of interest in the commapi folder: javax.comm.properties, win32comm.dll and comm.jar. You need to install these files in the JRE directory. If you have installed the J2SDK, you need to install these files in the JRE directory under the J2SDK distribution. I'm going to assume you just installed the JRE since most people wont be modifying JAvrProg, just running it.
  2. Copy file javax.comm.properties from the commapi folder to JRE's lib folder. For example, if the JRE is installed in C:\Program Files\Java\jre1.5.0_02, you need to move the javax.comm.properties file in C:\Program Files\Java\jre1.5.0_02\lib.
  3. Copy file win32com.dll from commapi folder to JRE's bin folder (you need to display system files to see this DLL).
  4. Copy file comm.jar from the commapi folder to JRE's lib\ext directory.(!!!The instructions just say put it in lib but thats wrong!!!)
  5. Add the Communications API class and the current directory to the CLASSPATH environment variable. On Windows 9x, add the following line to autoexec.bat:
    (change the path to match your directory structure). On other Windows versions (NT, 2000, XP, etc.), the CLASSPATH environment variable can be set using the System utility in the Control Panel. (Control Panel -> System -> Advanced -> Env. Variables)

To install CommAPI for Linux (stolen from Jolt, untested but should work, tell me if not):

  1. Make sure you've downloaded the Solaris SPARC version of the Java Communications API.
  2. Copy file comm.jar from the Java Communications API directory into JRE's lib/ext directory.
  3. Download the latest RXTX 2.0 source distribution.
  4. Run ./configure from the RXTX directory. If not present, the javax.comm.properties file is created in $JAVA_HOME/jre/lib.
  5. Run make to build the package.
  6. Run make install to install the RXTX package. A .jar file will be installed in $JAVA_HOME/jre/lib/ext and two .so librairies will be installed in $JAVA_HOME/jre/lib/i386.

Now, d ownload the latest version of the JAvrProg bootloader from SourceForge. Uncompress it somewhere convenient. Open up a command window and go to that directory and type in java -jar JAvrProg.jar and the JAvrProg window should pop up.

If you click on Program, the program should print Trying to open port COM1 ... Failed to find AVR or something similar, not a bunch of errors. If JAvrProg doesnt show that it tried to open at least one COM port, check to make sure the CommAPI is installed correctly. When the x0xb0x is plugged in, there should be an extra COM port it searches (like, COM3 or COM4 on most computers)

How to bootload
  Unplug the x0xb0x, and quit any software that may be using the USB serial port.
  Turn the FUNCTION knob to Bootload
  After a few seconds, plug in the x0xb0x. Since it has not initialized, there may be odd LEDs lit up.
  Start up the bootloading software ("JAvrProg") on your computer. If it is not installed, follow the installation procedure.
  Click on "Browse..." and select the .hex file to be uploaded.
  Click on "Program" to begin uploading. You should see in the command window that x0xb0x1 was found. If not, start over from step 1.
  Assuming the firmware write was verified, quit the JAvrProg software and disconnect the x0xb0x. Turn the FUNCTION knob to some other location.
  After a few seconds, plug in the x0xb0x. Your x0xb0x has been upgraded!
May 17, 2011 20:07