blorggggIntroduction
Connecting your Mod to your Android phone opens up all sorts of possibilities for in-bedroom controls and connectivity, but it's not nearly as straightforward as it should be. Read on to find out if you're able to pull this off.
USB OTG
The USB protocol operates in a host/accessory configuration. Your computer is a USB host. It's the main device to which you attach other devices (such as a USB keyboard, printer, camera, or phone), and it's capable of providing power to operate and charge those devices.
Your phone typically behaves as an accessory, expecting to connect to a host and be manipulated by that host.
The USB OTG (On-The-Go) standard allows some devices that are typically accessories to behave as hosts, so you could, for instance, plug your printer in to your phone to print a document.
Android support
Android has had support for USB OTG since Android 3.1, but phone hardware is very hit-or-miss in its support. Many Android phones running Android 4.0+ do not support USB OTG, and the easiest way to check if your phone or tablet supports OTG is to check around on internet and see what other people report. So far we know that it works on the Nexus 5 and Nexus 7, but not the Nexus S 4G.
Getting it running
Once you've confirmed that your phone supports OTG, you'll need a USB OTG cable. These are about $2 from Amazon, and you could probably find them locally if you're in a rush. The small/male/micro-B end of the cable goes in your phone, and whatever you're trying to connect goes in the big/female/USB-A end of the cable.
You'll also need a USB terminal app for your phone or tablet. We've had the best luck with USB Serial Monitor Lite, and it gets bonus points for requiring no special permissions to run.
Connect your Mod to its USB cable, plug that into the OTG cable, and plug the small/micro-B end of OTG cable in to your phone. Turn the Mod on, and connect to it in the Serial Monitor app.
If you're lucky, you'll then be presented with a terminal screen, and when you try to type commands your phone or tablet doesn't present a keyboard for you to type on. Aha. Here's our next problem.
Mod Support
The ATmega32u4 microcontroller inside of the Mod has built-in USB functionality. That means it can present itself as a USB mouse, a USB keyboard, and a USB virtual terminal (what you want). The Arduino development environment includes the keyboard/mouse features (known as HID, or human interface device) as well the terminal features (known as CDC, or communications device class) and there's no way to tell the Arduino compiler "don't include software to act as USB keyboard or mouse unless my sketch specifically requires it." So your Mod is acting as a virtual serial port, but it's also acting as a virtual keyboard. Android connects to the serial port, but thinks there is also an external keyboard present and no longer shows the soft keyboard.
We have to force Arduino not to include any HID features. The way you do this is to edit the USBDesc.h file included with Arduino. On a Mac, this is found inside of the Arduino.app itself. From the Finder, right click on the Arduino application, and choose "Show Package Contents". From there, go through Contents > Resources > Java > hardware > arduino > cores > arduino and you'll find USBDesc.h (in the 1.5.x Arduino development environment, this file is found in Contents > Java > hardware > arduino > avr > cores > arduino). Open USBDesc.h and edit it:
Old:
#define CDC_ENABLED #define HID_ENABLED
New:
#define CDC_ENABLED /* #define HID_ENABLED */
That's it! You have commented out the line defining the HID_ENABLED variable. You may have to quit and reload the Arduino app and then recompile your sketch for it to take effect. Now only CDC features will be defined, and your Mod should still present itself as a virtual terminal, but not a virtual keyboard. You can talk to your Mod over its standard serial console and turn motors on/off, cycle patterns, alter pattern frequency and intensity, and read inputs.