Skip to content

IOIO OTG Bootloader and IOIODude

Jump to bottom
ytai edited this page Sep 22, 2014 · 8 revisions

IOIO-OTG Bootloader and IOIODude

The IOIO-OTG boards include a microcontroller (of the PIC24F family) that runs firmware which makes the board do what it does. When the boards are manufactured, someone on the production line programs (or "flashes") the latest stable version of the firmware to the flash memory that is on the microcontroller, so that when you get the board, it already works out of the box.

However, the firmware code is under continuous development, and every so often new features are introduced, or bugs are fixed. This means that by upgrading the firmware, you can constantly improve the value of your board without needing to buy a new one! Upgrading the firmware is a simple and fast process, and this document will guide you through the required steps. Furthermore, if you are familiar with PIC programming and would like to add a custom feature to your IOIO, you can download the firmware code, make changes to it, package it, and then use the information in this document to program it to your IOIO board, or distribute your custom firmware for others to enjoy.

Note: This information is specific to IOIO-OTG boards. For IOIO V1 boards, please refer to The IOIO Manager Application page.

Understanding the Bootloader and Application Firmware

Although you can upgrade the IOIO firmware by following some steps without really understanding what you are doing - most IOIO users probably do want some inside information :) The IOIO firmware actually comprises two separate programs, both programmed to the internal flash memory in different addresses. The one that is simpler to understand is called the Application. This is the firmware that you are normally using when running the IOIO - the one that can establish a connection to a host (PC or Android) and let it control the pins. This is also the firmware that you mostly care about upgrading when a new version comes out. The second program is called the Bootloader. The bootloader has a single, very simple role: it is used for upgrading the Application firmware!

Every time the IOIO is reset (normally after power-up), the first thing it does is to run the bootloader. The bootloader immediately does one simple operation: it checks whether or not the boot pin on the board is shorted to ground (GND). If not, the bootloader runs the Application and disappears. This happens so quickly that it will feel as if the application immediately starts running, but the bootloader was always there first. The interesting case in this context is when the bootloader detects that the boot pin is grounded - this is when the bootloader application will actually start doing its thing and get the IOIO into a state where it is ready to receive and install new application firmware.

Note: The bootloader cannot upgrade itself. This is intentional and is normally a good thing! It means that even if you mistakenly flash some bad firmware image on the board, the bootloader is always intact (it is protected in hardware), and can be used to put good application firmware back on the board. This makes bricking the board via bad firmware close to impossible. The downside, of course, is for the cases where you specifically do want to upgrade the bootloader. This can be done only with a PIC programmer (e.g. PICkit), or something acting as one, such as a second IOIO. Read more here.

Getting Ready to Upgrade

The application firmware upgrade takes place by connecting your IOIO to a PC (NOT an Android, like in IOIO v1 boards bootloader), putting it in bootloader mode (instructions below) and using a program called IOIODude for transferring the new firmware image to the board and writing it to its internal flash memory.

The first thing to do is to grab the latest version of IOIODude (earlier versions can be found here). It is a command-line Java application that can run on Windows / Linux / OSX. Once you download the zip file, extract it somewhere, and open a command shell where it is extracted. Three files are included in the zip, one is the JAR file, with the actual program, the other are a bash script and batch file making it easier to run the JAR. On Linux / OSX, you may need to add execute permissions to the bash script after unzipping:

$ chmod a+x ioiodude

Now you can check that it is working. On Windows, run:

> ioiodude

On Linux / OSX, run:

$ ./ioiodude

And you should see something like:

IOIODude V1.0

Usage:
ioiodude <options> versions
ioiodude <options> fingerprint
ioiodude <options> write <ioioapp>

Valid options are:
--port=<name> The serial port where the IOIO is connected.
--reset Reset the IOIO out of bootloader mode when done.
--force Bypass fingerprint matching and force writing.

The next thing you'll need is the application firmware itself. Those come in packages called firmware bundles, which both IOIODude and IOIO Manager can understand. Essentially, each such bundle contains a few copies of the same application firmware, each built for a different platform. IOIODude, IOIO Manager and the bootloader are smart enough to pick the right one, so you don't need to worry about it. The standard firmware bundles are available for download from the Downloads page, under the "Application Firmware Bundle" column. Versions 3.30 or higher support the IOIO-OTG boards. Download the bundle (a .ioioapp file) and store it on your PC.

You're now ready to go! Read on...

The boot Pin and Boot Sequence

To put your IOIO into "bootloader" mode you have to follow a simple sequence:

  • Power off the IOIO (detach it from a power supply AND from the PC, until the red pwr LED is off).
  • Jumper the boot pin (near pin number 34) to GND.
  • With the jumper in place, plug the IOIO to your PC, using a micro-B cable. The IOIO should power on (red pwr LED is on) and the yellow stat LED should be on as well (in fact, the boot pin in connected in parallel to the IOIO pin which controls the LED, so by jumpering boot and GND you are forcing it to light!).
  • Now, remove the jumper. The stat LED should blink a few times, telling you that the bootloader is now running.
  • Once done blinking, the IOIO should enumerate itself on your PC (i.e. you should see it in the Devices screen in Windows or in lsusb on Linux).

If you are using Windows, and this is the first time you are using the IOIO with your PC, you may be asked for drivers. Download the IOIO Windows driver from the Downloads page, and point the driver installation wizard at it. On other OS, you should need no drivers.

Finding the Port

The IOIO exposes itself as a serial port to the PC. You need to figure out the name the PC assigned to this port before you can move on.

  • On Windows 7, open the "Devices and Printers" application from the start menu. You should see something like IOIO-OTG (COMxx). Note the COM number.
  • On earlier versions of Windows, right click "My Computer" > Manage > Device Manager > expand Ports (COM & LPT) and find the COM number of IOIO-OTG.
  • On OSX, run ls /dev/tty.usb* and note the output. If there is more than one, the simplest thing to do it to run this twice with and without the IOIO connected and note the difference.
  • On Linux, run ls /dev/IOIO* and note the output. If you don't see any device by that name, you probably forgot to install the udev rule available from the Downloads page.

Testing

To test whether IOIODude can successfully communicate with the IOIO, run:

(Windows)

ioiodude --port=COM<number> versions

(Linux / OSX)

./ioiodude --port=/dev/tty<whatever> versions

If all is well, the output should resemble:

IOIO Bootloader detected.

Hardware version: SPRK0020
Bootloader version: IOIO0400
Platform version: IOIO0030

If you try this command when the IOIO is connected, but NOT in bootloader mode, and you are running the standard firmware, the output of this command will tell you which version of the application you have installed. For example:

IOIO Application detected.

Hardware version: SPRK0020
Bootloader version: IOIO0400
Application version: IOIO0330

You are now ready to write new firmware!

Writing New Firmware

Simply run:

 ioiodude --port=<your_port> --reset write <new_firmware>.ioioapp

The output should look like:

Comparing fingerprints...
Fingerprint mismatch.
Writing image...
[########################################]
Writing fingerprint...
Done.

Typically, programming will take around 3-4 seconds. Or otherwise, if you are trying to install the exact same firmware your IOIO already has:

Comparing fingerprints...
Fingerprint match - skipping write.

You can force a write using the --force flag. The --reset flag above, would cause the IOIO to reset as soon as the operation is complete. Since, the boot pin is not jumpered to GND at this point, the newly installed application will start running. As mentioned above, if this is the standard firmware, you can then use IOIODude to verify the version.

Experimenting

If you want to get a sense of what it looks like to be running custom firmware, grab the Blink-IOIO0003 (or later) from the Downloads page. Use IOIODude to install it, and see that it is a dead-simple firmware that just blink the stat LED on the board. It will not even establish a USB connection with a PC or an Android when this application is running! Now, reboot the IOIO into bootloader mode, and use IOIODude re-install the standard firmware. Now your IOIO is back to being a IOIO :)

Configuration Wipe

The bootloader keeps an area in Flash memory for its own use. Currently, this includes a fingerprint of the currently-installed application image and an oscillator tuning value. The latter is discussed in detail below. In case you want to start fresh for some reason, it is possible to force the bootloader to wipe this memory area. This is accomplished by executing the Boot Sequence while pin 1 is shorted to GND. If connected to a host while doing so, the bootloader will immediately start after the wipe. Otherwise, an oscillator calibration must be performed first.

Oscillator Calibration

The PIC chip on the IOIO board uses an internal RC oscillator as its clock source. The advantage of using it is reduced cost, board space and 2 extra pins available for fun. The disadvantage is that the RC oscillator may be inaccurate if not properly tuned, which may cause USB connectivity to be unreliable. To mitigate that, the IOIO-OTG bootloader is capable of automatically calibrate the oscillator, by synchronizing itself on a clock provided by a USB host. When the IOIO-OTG is powered on, if the bootloader detects that there is no current tuning value, it will start blinking the stat (yellow) LED very quickly, signaling that it is expecting you to connect it to a USB host. Once you do that, it will calibrate itself, store the value in Flash memory and move on. Upon next power-up, the value will be read from Flash and the calibration process is skipped.

You may encounter this fast-blink situation on a freshly-installed bootloader, or if you executed the configuration wipe procedure described above (which is also how you would force a recalibration if you ever wanted to). If you just got a new IOIO-OTG, chances are that the initial calibration procedure has been done for you at the factory, so if the LED does not blink, it does not mean that something is wrong.

Clone this wiki locally