Mech - User contributions [en]

Interfacing the PIC32 with an Android device

2013-04-22T16:28:50Z

ShengWu: /* Introduction */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]] or on [https://github.com/shengwu/android-pic32 Github]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. In Eclipse, this requires going to the Help menu at the very left and selecting "Install New Software". '''You must install the ADT Plugin to develop Android applications with Eclipse.''' After doing that, you'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." Source: [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credit ==

This project adapts code from two projects for the PIC32. The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2013-02-11T10:25:59Z

ShengWu: /* Credits */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. In Eclipse, this requires going to the Help menu at the very left and selecting "Install New Software". '''You must install the ADT Plugin to develop Android applications with Eclipse.''' After doing that, you'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." Source: [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credit ==

This project adapts code from two projects for the PIC32. The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-11-14T20:18:39Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. In Eclipse, this requires going to the Help menu at the very left and selecting "Install New Software". '''You must install the ADT Plugin to develop Android applications with Eclipse.''' After doing that, you'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." Source: [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-24T18:43:30Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. In Eclipse, this requires going to the Help menu at the very left and selecting "Install New Software". You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." Source: [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-08T01:30:18Z

ShengWu: /* Overview of an Android application */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." Source: [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-08T01:30:01Z

ShengWu: /* Overview of an Android application */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. Activities are exited when a user presses "back" but are only paused when a user presses "home." From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-08T01:28:57Z

ShengWu: /* Overview of an Android application */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when certain member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-08T01:28:35Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Overview of an Android application ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-08T01:27:38Z

ShengWu: /* Microphone demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends this maximum amplitude to the PIC as an integer. The PIC comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:40:49Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation (linked above), [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:40:28Z

ShengWu: /* Introduction */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

Get the starter code: [[Media:Android_PIC_starter_code.zip]]

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:40:06Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, [[Media:Android_PIC_starter_code.zip]]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:39:49Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, [Media:Android_PIC_starter_code.zip]. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:39:32Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T13:39:23Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

File:Android PIC starter code.zip

2012-10-05T13:38:48Z

ShengWu: Starter code v1 for interfacing an Android device with a PIC32 development board

Starter code v1 for interfacing an Android device with a PIC32 development board

Interfacing the PIC32 with an Android device

2012-10-05T06:44:30Z

ShengWu: /* GPS demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates that will end up somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T06:44:17Z

ShengWu: /* GPS demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a random set of coordinates from somewhere in Africa, Europe, or Asia.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T06:12:08Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming. Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T06:11:56Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T06:11:31Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

Tip: Ctrl-Shift-O in Eclipse updates your Java imports based on the code in the file.

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T05:39:43Z

ShengWu: /* Things you need */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages. For my Nexus S 4G, I downloaded the Android 2.3.3 and the Google USB Driver packages. Turn on USB debugging on your Android device in Settings > Applications > Development > USB debugging. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

You'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T05:34:05Z

ShengWu: /* Microphone demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T05:33:56Z

ShengWu: /* Android Sensor Demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC. When the PIC receives a set of coordinates, it will send back a somewhat random set of coordinates.

See the [http://developer.android.com/training/basics/location/index.html Location documentation] for more information.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

See Android's [http://developer.android.com/training/camera/index.html Camera documentation]. Usually, it's best to use the approach described in "Taking Photos Simply", where you use the device's built-in camera activity to capture an image.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

This activity uses <tt>AudioRecord</tt> to access raw data from the microphone, rather than <tt>MediaRecorder</tt>, which is designed to record audio and/or video for saving to files.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:44:32Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when the member functions are called in an Activity's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:43:36Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|This describes when <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:42:34Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|When <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (see right). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:42:00Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|513 px|When <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

<div style="clear:both;"></div>

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:41:37Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|513 px|When <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:41:25Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Activity_lifecycle.png|thumb|400 px|When <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:41:11Z

ShengWu: /* Basics of Android programming */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

[[Image:Android_lifecycle.png|thumb|400 px|When <tt>Activity</tt> functions are called in an application's lifecycle. From the [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Android documentation].|right]]

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

File:Activity lifecycle.png

2012-10-05T04:39:51Z

ShengWu: The Android activity lifecycle. Licensed under Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0

The Android activity lifecycle.

Licensed under Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0

Interfacing the PIC32 with an Android device

2012-10-05T04:38:04Z

ShengWu: /* Troubleshooting */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs, with the correct Android SDK platforms.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:37:14Z

ShengWu: /* Troubleshooting */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

'''Everything should work as downloaded.''' If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-05T04:27:12Z

ShengWu: /* String Passing Demo */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. (You must connect or reset the pic AFTER starting the application.) If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T07:16:36Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. (Avoid using large amounts of solder.)|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:58:31Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. Avoid using large amounts of solder.|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:58:20Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Wires soldered to the VBUS and VUSB pads on the NU32. Avoid large amounts of solder.|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:57:14Z

ShengWu:

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[Image:Vbus_vusb_soldered.jpg|thumb|300 px|Avoid using large amounts of solder.|right]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.
<div style="clear:both;"></div>

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:55:38Z

ShengWu: /* Accessing USB on the PIC */

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===
[[File:Vbus_vusb_soldered.jpg‎]]

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

File:Vbus vusb soldered.jpg

2012-10-03T06:55:21Z

ShengWu: Soldered wires to the VBUS and VUSB pads on the NU32 development board.

Soldered wires to the VBUS and VUSB pads on the NU32 development board.

Interfacing the PIC32 with an Android device

2012-10-03T06:54:16Z

ShengWu:

[[Image:PICAndroid.jpeg|thumb|500 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:54:06Z

ShengWu:

[[Image:PICAndroid.jpeg|thumb|400 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-03T06:53:56Z

ShengWu:

[[Image:PICAndroid.jpeg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect the USB cable to the Android device. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

File:PICAndroid.jpeg

2012-10-03T06:53:27Z

ShengWu: A photo of the touchscreen demo from the PIC Android project in action.

A photo of the touchscreen demo from the PIC Android project in action.

Interfacing the PIC32 with an Android device

2012-10-01T16:02:21Z

ShengWu: /* Accessing USB on the PIC */

[[Image:test.jpg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

You'll need to create a USB cable to connect your Android device to the PIC and some other parts. Here's a list:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. Ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on the development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect it. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-01T15:59:07Z

ShengWu: /* Things you need */

[[Image:test.jpg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclipse and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

First, you'll need a USB cable to connect your Android device to the PIC. You'll probably need the following:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. We can ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on your development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect it. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-01T15:58:56Z

ShengWu: /* Things you need */

[[Image:test.jpg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website])

Follow the instructions to get the ADT Plugin for Eclips and to link the SDK Manager to Eclipse. You'll need to open the SDK Manager (probably as administrator) and download the appropriate packages - for my Nexus S 4G, the Android 2.3.3 and the Google USB Driver packages. It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

First, you'll need a USB cable to connect your Android device to the PIC. You'll probably need the following:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. We can ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on your development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect it. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-01T15:56:42Z

ShengWu: /* Troubleshooting */

[[Image:test.jpg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website] and follow the instructions to link it to Eclipse)

It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

First, you'll need a USB cable to connect your Android device to the PIC. You'll probably need the following:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. We can ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on your development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect it. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for each firmware project. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked. Because of these specific settings, it's recommended to right click the String Passing Demo and select "Copy..." to start a new firmware project.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].

Interfacing the PIC32 with an Android device

2012-10-01T15:55:29Z

ShengWu: /* Troubleshooting */

[[Image:test.jpg|thumb|300 px|The touchscreen demo in action|right]]
__TOC__
<div style="clear:both;"></div>

== Introduction ==

Learn to connect an Android device and a PIC32 microprocessor. This guide was developed with the NU32 (2012 version).

== Getting Started ==

=== Things you need ===

You'll need the following hardware:

* A PIC32 microprocessor (i.e. the NU32 development board)
* An Android device running at least version 2.2
* USB cables:
** Type-A to Mini-B cable (computer to PIC32)
** Type-A to Micro-B cable (computer to Android device)
** A spare USB cable with a Micro-B end (Android device to PIC32)

and the following software:

* Microchip's MPLAB X with the C32 compiler (download from [http://www.microchip.com/pagehandler/en-us/family/mplabx/#downloads Microchip's website])
* Eclipse (download from the Eclipse project's [http://www.eclipse.org/downloads/ website] -- Eclipse Classic recommended)
* Android SDK (download from the [http://developer.android.com/sdk/index.html Android website] and follow the instructions to link it to Eclipse)

It's optional, but you'll want the HD44780, a 2 by 16 character LCD with libraries available for the PIC32.

In addition, you'll need the starter code associated with this documentation, FILE_LINK_HERE. The code includes the '''String Passing Demo''', a firmware/application pair that passes raw sequences of bytes back and forth, interpreted as strings. There's also the '''Android Sensor Demo''', a firmware/application pair that shows you how to access the GPS, camera, touchscreen, and microphone of the Android device to collect data that may be useful for the PIC.

The PIC32 firmware is written in C and compiled with MPLAB X and C32; the Android applications are written in Java and are built with Eclipse. Be sure to take advantage of the features in MPLAB X and Eclipse. These IDEs can quickly rename variables (Ctrl-R in MPLAB X, Alt-Shift-R in Eclipse), jump to where a function is defined (hold Ctrl and click), and perform other refactoring that will save you time when programming.

=== Accessing USB on the PIC ===

First, you'll need a USB cable to connect your Android device to the PIC. You'll probably need the following:

* Spare USB cable with a Micro-B end
* (2) capacitors in the 1 uF range
* Soldering iron
* Red, black, green, and white wire
* Electrical tape

Cut the non-Micro-B end off your USB cable. Inside the outer insulation, you should see four wires: a red wire (VBUS), a black wire (GND), a green wire (D+), and a white wire (D-). Solder each stranded wire to a solid wire of the same color, and wrap the joints in electrical tape so they don't accidentally bump into each other.

On the NU32 board, you'll need to solder wires to the VBUS and VUSB pads right below the microprocessor.

Now, you'll need to wire everything up. Here's the diagram from the PIC32MX reference manual: [[Media:Pic32_usb_wiring.pdf]]. We can ignore VBUSON and wire VBUS directly to 5V. D+ is G2 and D- is G3 on the NU32. When you power on your development board and connect your Android device, the device should begin charging.

== String Passing Demo ==

Unzip the folder you downloaded earlier. From the applications folder, import String Passing Demo into Eclipse. From the firmware folder, import String Passing Demo into MPLAB X. Connect your Android device to your computer and write the program onto the device by pressing the green play button. In MPLAB X, build the firmware and write the .hex file onto the PIC.

Start the String Passing Demo on your Android device. Then turn on the PIC and connect it. If you see "Hello from PIC32!" on your Android device, congratulations!

=== Firmware ===

The firmware consists of initialization code and a while loop with a state machine. When the phone is connected to the PIC, the state is STATE_CONNECTED. The code under the STATE_CONNECTED case transmits a string to the Android device if the user button has been pressed or released. When data is received, the function ADBCallback is called. The ADBCallback for the String Passing Demo displays any bytes received as a string on the LCD.

=== Application ===

The main parts of the application code are StringPassing.java inside <tt>src/lims.stringpassing.app</tt> and main.xml inside <tt>res/layout</tt>. There's also code that manages the connection inside <tt>src/lims.stringpassing.server</tt>.

StringPassing.java starts with the declaration of several variables: Buttons, TextViews, etc. Inside <tt>onCreate</tt>, these variables are linked to parts of the layout in main.xml. Most of the code describes listeners - basically, code that is executed in response to an event like a button press or when data is received.

== Android Sensor Demo ==

This code contains demonstrations of four Android sensors: the GPS/location service, the camera, the touchscreen, and the microphone.

=== GPS demo ===

The location demonstration will try to determine the device's current location. It will transmit the coordinates to the PIC and the PIC will return the location directly across the world (the antipode). For Chicago, this is southwest of Australia in the ocean.

=== Camera demo ===

The camera demo captures a 640 by 480 image. It saves the image as a .jpeg, then creates a 40 by 30 pixel version and sends that to the PIC in a 3600-byte array of RGB values. The PIC inverts the RGB data and sends the sample back.

=== Touchscreen demo ===

The touchscreen demonstration detects where you've touched the screen and indicates this with the purple cursor. It scales each of the touch coordinates to a float between 0 and 1 and sends this pair of floats to the PIC. (That's why the integer coordinates displayed on the PIC's LCD aren't exact.) Every time the PIC receives data, it responds with coordinates for the orange cursor, which is moved around randomly.

=== Microphone demo ===

The microphone demo captures data from the Android device's microphone but doesn't do much with it. The level bar in the application shows the maximum amplitude found in the previous sample. It sends up to 100 bytes of each sample to the PIC, which comments on the loudness.

== Basics of Android programming ==

The '''Activity''' is the basic building block of an Android application. There's an Activity for each screen in an app. The String Passing Demo is an application that consists of a single Activity because there's only one screen. The Android Sensor Demo has one Activity for the menu and four Activities for the four sensor demos. To create your own activity, you create ClassName.java file containing a subclass of Android's <tt>Activity</tt> class. In the String Passing Demo, the file is called <tt>StringPassing.java</tt> and the class declaration is <tt>public class StringPassing extends Activity</tt>.

Inside the <tt>Activity</tt> class, there are functions that are called at different parts of the Activity's life (for a diagram, see [http://developer.android.com/reference/android/app/Activity.html#ActivityLifecycle Activity Lifecycle] in the documentation). When the Activity is started by the user, a method called <tt>onCreate</tt> is called. When the user closes the Activity by pressing the back button, the <tt>onDestroy</tt> method is called. For example, here's some code from the String Passing Demo:
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
</pre>
The <tt>@Override</tt> designation means we're overriding the base <tt>Activity</tt> class's <tt>onCreate</tt> function. For things to work properly, the superclass's <tt>onCreate</tt> function still needs to be called; that's what <tt>super.onCreate(savedInstanceState)</tt> does. The <tt>savedInstanceState</tt> is a structure in which you can save variables. We're not going to worry about it. The final line, <tt>setContentView(R.layout.main)</tt>, tells Android that the application should display the <tt>main.xml</tt> layout. The rest of <tt>onCreate</tt> is code that we want to execute at the start of the Activity.

An application's layout files are found in <tt>res/layouts</tt> in the Eclipse Package Explorer. A layout file is an xml file describing how text fields, buttons, checkboxes, and other widgets will be laid out on the screen. Eclipse gives you a friendly drag-and-drop interface with which to create these.

Of course, we need to connect the layout widgets to our application code so we can control their functionality. In the String Passing Demo, you'll see
<pre>
public class StringPassing extends Activity {

Button sendButton;
Button clearButton;
...
</pre>
and later, in the <tt>onCreate</tt> function,
<pre>
sendButton = (Button) findViewById(R.id.button1);
clearButton = (Button) findViewById(R.id.button2);
...
</pre>
This associates the buttons in the layout with variables (here, <tt>sendButton</tt> and <tt>clearButton</tt>). Now, we can call <tt>sendButton.setOnClickListener</tt> to execute certain code when <tt>sendButton</tt> or <tt>clearButton</tt> is pressed by the user.

To learn more, see the official [http://developer.android.com/guide/components/index.html documentation].

== Communication overview ==
[[Image:Communication_overview.png|thumb|400 px|A basic look at Android-PIC32 communication using ADB. The dotted arrows represent the functions used in the firmware and application code to transfer data. The solid arrows represent the actual data path.|right]]

Here's a little bit about how we're transferring data.

We're using a protocol based on the [http://developer.android.com/tools/help/adb.html Android Debug Bridge] (ADB). ADB is a tool that's usually used for development of Android applications. Google has released the Open Accessory protocol for communication with Android USB accessories, but it's only guaranteed to be supported on devices running Android 3.1 or above, where ADB is compatible with devices running Android 1.6 or above.

In this code, the Android device acts as a TCP server. On the PIC, we're able to abuse ADB to send arbitrary sequences of bytes to an Android device. The Android side uses ADB libraries to accept incoming connections from the PIC and to send data to the PIC. All of this runs on top of Microchip USB libraries for the PIC and Linux USB drivers used by the Android operating system.

<div style="clear:both;"></div>

== Troubleshooting ==

Everything should work as downloaded. If you're getting errors, the first thing to do is to make sure you've installed all of the correct programs.

In MPLAB X, there's a very specific compiler configuration for the firmware projects. Right click the project name in the right toolbar and choose Properties. The compiler toolchain should be C32 (v2.02 when this was written). Under the tab at left called C32 (Global Options), you'll see <tt>pic32-as</tt>, <tt>pic32-gcc</tt>, and <tt>pic32-ld</tt>. Under <tt>pic32-as</tt>, only "Have symbols in production build" should be checked. Under <tt>pic32-gcc</tt>, "Have symbols in production build" should be checked too. The "Preprocessor macros" should appear as <tt>PLATFORM=400;NDEBUG</tt>. The include directories should reference all of the libraries and should be the following list:
<pre>
..\_Libraries\libadb
..\_Libraries\libconn
..\_Libraries\libusb
..\_Libraries\libbtstack\src
..\_Libraries\libbtstack\include\btstack
..\_Libraries\libbtstack
..\_Libraries\microchip\common
..\_Libraries\microchip\usb
..\_Libraries\microchip\include
..\_Libraries\microchip\include\USB
..\_Libraries\common
</pre>
Because of this list, you shouldn't need to import the library projects into MPLAB X. Doing so may introduce problems. Under the <tt>pic32-ld</tt> tab, the heap size should be 3000 bytes and "Remove unused sections" should be checked.

Each of the firmware projects includes <tt>procdefs.ld</tt>, <tt>NU32.h</tt>/<tt>NU32.c</tt>, and <tt>LCD.h</tt>/<tt>LCD.c</tt> libraries meant for the NU32. If you aren't using the NU32, remove these files and their references in the code.

If you want to use XC32 compiler (recently released when this was written), you'll need to right click the project name in the left toolbar, select Properties, and switch to the XC32 compiler toolchain. You'll have to do this for the firmware (Android Sensor Demo or String Passing Demo) as well as for each of the four libraries and patch up the compiler errors. It's best to just download and use the C32 compiler.

In Eclipse: if you're getting compiler errors with the projects, right click the project name at left > Android Tools > Fix Project Properties. If there are still errors, go to right click > Properties and check the following. In the Android tab, make sure you're building for Android 2.3.3 or for a version that's at least 2.2. In the Java compiler tab, make sure the compiler compliance level is 1.6.

== Credits ==

The firmware uses Ytai Ben-Tsvi's libadb, libbtstack, libconn, and libusb libraries from the [https://github.com/ytai/ioio/wiki ioio project]. The application code uses server libraries from [http://code.google.com/p/microbridge/ microbridge].