Important note: This guide is intended for people who develop IOIO, not people who develop with IOIO. A user guide will soon be published too. However, one important point to stress is that IOIO users are not required to do any sort of embedded programming, nor are they required to set up a development environment for PIC. The mainstream usage of IOIO involves only Android programming and the entire functionality of the board is exposed via a Java API. If you're only interested in that sort of usage, until there's proper documentation, you might want to download the code and have a look at software/IOIOLib as well as at some sample apps (e.g. software/IOIOSimpleApp).
Important note 2: This guide is slightly outdated. It will eventually be fixed, but this is a lower priority than some of the other stuff that's going on. My apologies in advance...
Update: We recently moved all firmware projects to MPLAB-X, which is currently in Beta, but still much better than MPLAB 8, and most importantly, available for Linux, Mac and Windows.
You'll need the following software installed on your development machine:
The bootloader is a piece of firmware, running on the PIC24 microcontroller that is on the IOIO board. This firmware is always the first thing that runs when the IOIO is powered on. Roughly speaking, at power-up the bootloader will do the following:
Once the application firmware is executing, the bootloader is still responsible for providing it with some services, mostly ADB connections and Flash read/write.
You can skip this step if you have a IOIO with a bootloader or already have the bootloader image. The bootloader project is in firmware/bootloader Depending on whether your using a V0.3/V0.4 board or a V1.0/V1.1/V1.2 board, you need to change the following project settings:
Note: The checked-in version matches the latest V1.2 boards. No need to change anything for those boards.
Build the project in MPLAB to produce the bootloader image (a .hex file under firmware/bootloader/dist). There's a pre-processor macro called ENABLE_LOGGING which causes the bootloader to output debug messages on a 38400 UART pin. However, the bootloader link stage will fail for memory constraints, so the linker scripts need to be tweaked to allow more RAM for the bootloader.
You can skip this step if your IOIO already has a bootloader and you don't care about modifying the bootloader. You can use PICKit3 using the standalone programming software (GUI or command line) or from within MPLAB IDE. Just select it from the "programmer" menu.
If you only have a PICKit2, you can hack it to support PIC24FJ128DA106 by backing up the PK2DeviceFile.dat file found on your PICKit2 installation directory and replacing it with this one. Note that the rest of the MCUs on this file might have gotten corrupt as result of the hack, so only use this device file for PIC24FJ128DA106 / PIC24FJ256DA206.
If you want to flash the bootloader and the application firmware as one hex file, you can build the application firmware as explained below. You can then merge both hex files into one by simply concatenating them (they are text files) after removing the last line ("EOF") from the first one. This is useful for distributing the entire firmware as one standalone image.
Connect the PICKit to the IOIO as follows:
Not all boards have a silk-screen, so hold the board with the top side (on with the components) facing you with the USB jack on the right.
For programming purposes only, you can skip connecting 5V/Vin, and power the PIC from the programmer (3.3V). This is done by enabling Project Properties > PICkit3 > Power > Power target circuit from PICkit3.
The application firmware is in firmware/app_layer_v1. It exposes a protocol to the Android app, which enables controlling many of the PIC's functions in a simple way, over a simple TCP connection. On the Android side, there is a Java library called IOIOLib, which implements the other side of this protocol and provides the client with a very simple and high level API for controlling IOIO. The application layer sits on top of an API provided by the bootloader, called BLAPI. This API is in firmware/blapi. In this directory there's also linker scripts that any IOIO app should be linked with. They enforce the bootloader ABI, i.e. RAM/ROM locations bootloader symbol addresses, etc. Open the firmware/app_layer_v1 project in MPLAB and build it. The resulting hex file (under dist directory) now contains the application executable. There are two ways of getting it to run on the IOIO. The short way (which requires a programmer) is to use a programmer and Flash it normally. It is possible to merge the bootloader hex with the application hex by removing the last line from one of them and concatenating (this is just a simple textual format). The long way, which does not involve a programmer and facilitates the bootloader is detailed below.
A simple utility is provided in tools/hex2ioio. It gets two arguments, one is an input hex file (of an application firmware), the other is the result filename (conventionally, with a .ioio suffix). The .ioio file contains the exact same information as the hex file, but it is more compact and much simpler to process by the bootloader.
./tools/make-ioio-bundle firmware/latency_tester/dist lat IOIO0023 will create a lat.zip file that if you rename it to lat.ioioapp file then the IOIOManager will know how to use it after pushing it to the sdcard. Note: you may need to build the bootloader with -DBYPASS_SECURITY when using a IOIOManager you built instead of downloading from the Marketplace because the keys will not match.
This is a very simple Android app for developers. What it does is listen on a Bluetooth serial socket. When data comes in, it stores it in a file called image.ioio in the exact location the bootloader looks at. Effectively, this allows the Android device to function as a wireless firmware programmer. The app is only available for Android 2.*, since this is when they introduced Bluetooth API. The application code and Eclipse project is under software/IOIOManagerBT. Build it and install it on your Android device. When you run the application, all it does is launch a service that will be indicated by a IOIO+BT notification icon. To stop, expand the notification drawer and click the icon. In order to work with the BT programmer, you first need to pair your Android device to your workstation and map the "IOIO Programmer " Bluetooth service to a serial port. This process is slightly painful on Linux and requires manually messing around with the rfcomm service. If anyone knows how to automate this process, let us know. Then, whenever you want to copy a new firmware to the Android device, just open a connection on this port, send the bytes and close the connection. A pop-up message should appear on the Android device, confirming reception of the new image. On Linux (or Cygwin), this is very conveniently done by issuing a command similar to this one: cp myimage.ioio /dev/ttyS21 Where the actual serial port mapped should replace /dev/ttyS21
If all is well, you can now reset the IOIO and connect it to the Android device. Make sure the Android has USB debugging switched on. The LED turns on shortly when the bootloader is connecting. Then, the application starts running.
If this works - congratulations - you've completed the entire cycle and are now ready to develop your own firmware or application!
Under the software directory you will find IOIOLib, which is the library you should work with in order to use IOIO. The public APIs are all documented. There are some sample applications under the software directory that can be used as usage examples.
Last edited by robodan,