Posts
«  
  »

Android ADK terminal emulator for Arduino

By Oleg Mazurov

ADK Teminal

ADK Teminal


This is a little Android application providing basic terminal emulator functionality over ADK interface. Its primary purpose is to be able to use Android phone as laptop replacement while debugging Arduino projects in the field. It can also be used to provide simple alphanumeric display. Victor Serbo, my long time friend, helped develop this application. It can be downloaded from here and currently in beta – as soon as code stabilizes I will make source code available. [EDIT] The source code is now available. It is released under GPL2, if you modify it, please make your modifications available.[/EDIT]

When Arduino is connected to the phone via USB Host Shield, it can send characters to the application’s screen and receive characters typed on application’s keyboard. Standard CR and LF control codes are also recognized so it is possible to output, for example, single line with changing content. Additionally, the appearance and behaviour of the screen can be customized – font size and type, foreground and background colors, local echo, screen rotation and more. The app has been thoroughly tested on Nexus One and Nexus S phones and works well.

Two demo sketches has been posted to gitHub. The functionality of term_test can be seen on title picture – strings sent from Android are output back on the screen. The term_time sketch demonstrates single line output. Below is brief explanation of ways to provide input/output on Arduino. I’ll start with term_test; all necessary functionality is implemented in loop().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

void loop()
{
  uint8_t rcode;
  uint8_t msg[64] = { 0x00 };
  const char* recv = "Received: ";
 
   Usb.Task();
 
   if( adk.isReady() == false ) {
     return;
   }
   uint16_t len = 64;
 
   rcode = adk.RcvData(&len, msg);
   if( rcode & ( rcode != hrNAK )) {
     USBTRACE2("Data rcv. :", rcode );
   }
   if(len > 0) {
     USBTRACE("\r\nData Packet.");
 
    for( uint8_t i = 0; i < len; i++ ) {
      Serial.print(msg[i]);
    }
    /* sending back what was received */
    rcode = adk.SndData( strlen( recv ), (uint8_t *)recv );
    rcode = adk.SndData( strlen(( char * )msg ), msg );
 
   }//if( len > 0 )...
 
   delay( 1000 );
}
  • (4) This is the input buffer.
  • (5) This word is printed on the screen in front of a received data block sent back from Arduino.
  • (9-11) Connection check – until accessory mode has been established, loop() will return here.
  • (14) Attempt to receive data from Android. There are 3 possible results. If transaction NAK-ed, we need to wait. If we get an error, it will be printed on a serial console (Lines 15-17 ).
  • (18) If there was no error of any kind, msg will contain received data and len will contain actual length of received data.
  • (19-23) It will be printed on a serial console.
  • (25) A word “Received” is sent to Android.
  • (26) Received data block is sent back to Android. To keep code simple, I don’t check rcode ; in real life, rcode needs to be analyzed and data retransmitted, if necessary.

The term_time sketch demonstrates single line output. In prints current uptime in seconds and is very similar to the previous one. Here, I’d like to point out just on a couple of lines:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

void loop()
{
  uint8_t buf[ 12 ] = { 0 }; //buffer to convert unsigned long to ASCII
  const char* sec_ela = " seconds elapsed\r";
  uint8_t rcode;
 
   Usb.Task();
   if( adk.isReady() == false ) {
     return;
   }
 
    ultoa( millis()/1000, (char *)buf, 10 );
 
    rcode = adk.SndData( strlen((char *)buf), buf );
    rcode = adk.SndData( strlen( sec_ela), (uint8_t *)sec_ela );
 
      delay( 1000 );
}
  • (4) This is the string which is sent out at the end of each output. Note single ‘\r’ at the end – this is what makes single line output.
  • (5) buf is filled with ASCII representation of seconds.
  • (14-15) Data and “seconds elapsed” string are sent to the phone.

To run these sketches, you will need USB Host Shield r.2.0 library and USB Host Shield 2.0 hardware. Android phone pulls a lot of power while charging so it is recommended to fully charge it before connecting to the Arduino. Please give this application a try and let me know if you have any issues!

Oleg.

September 11th, 2011 | Tags: , , , , , | Category: Android, Android ADK, Arduino, MCU, programming, USB, USB Shield | 36 comments - (Comments are closed)

36 comments to Android ADK terminal emulator for Arduino

  • Janos Tolgyesi
    September 13, 2011 at 1:46 am

    Hi dear Oleg,
    In this monent I havenot any usb shield, but I plan to build one. I found your terminal app, I definitly need such thing on my android tablet. When I started to install it, sent me a Parse error.
    Has it some dependencies to your phone/android vesion, or somewhere else??
    best:
    t.janos

  • Janos Tolgyesi
    September 13, 2011 at 10:51 am

    Hmmm… this is a good question. The sytem, running on it, from here:
    Universal Uberoid WM8650 1.5.2 HoneyCombMOD v8
    http://techknow.freeforums.org/universal-uberoid-wm8650-1-5-2-honeycombmod-v8-t1012.html
    Maybe, its compatible with the Android 2.2
    The kernel version 2.6.32.9-default
    t.janos

  • Janos Tolgyesi
    September 14, 2011 at 5:45 am

    Hi Oleg,
    I asked my friend to try to install your terminal porg on a Samsung android phone woith android vers 2.2.
    He received the same error messages before the install, as I see on my tablet. He read it in hungarian, but I see it in the original form:
    —————
    Parse error
    There is a problem parsing the package
    —————
    Maybe the problem is the screen resolution at our devices?
    t.janos

  • keith
    September 15, 2011 at 1:19 pm

    hi,

    am i right to say that since it is connected in usb accessory mode, this mean that the usb host which is the arduino side in this scenario will be powering the bus and the usb device(android phone).

    a bit out of topic, i am wondering if let say u connect a flashdrive to a android phone that is 2.3.4 in accessory mode. who will be powering the bus? by right it should be the flashdrive as it act as usb host wheras android phone is usb device. however, flashdrive itself do not have power. so i puzzle why do it sitll work?

  • SAI
    September 21, 2011 at 5:54 pm

    Hi Oleg,
    Really nice post, definitely piqued my interest in purchasing an Arduino to start playing around with. The only problem I have is: What should I build?
    haha. Great site though!

    @Janos
    Android ADK is built for the Android 3.1 platform (also backported to Android 2.3.4)

    source: http://developer.android.com/guide/topics/usb/adk.html

  • AndyS
    September 23, 2011 at 8:49 am

    Thnaks for those snippets.
    I have a Nexus One (on 2.3.4) and your USB Host shield 2.0 and was struggling to get themt to talk to each other. For reference, although the Android site say 2.3.3 and 2.3.4 are both API level 10, it requires at least level 11 API to build the Open Accessory apps for the phone. Having got the ADK install (http://developer.android.com/guide/topics/usb/adk.html and https://dl-ssl.google.com/android/adk/adk_release_0512.zip). Is it just me or was that really unintuitive! Anyway, that has the AndroidAccessory arduino library as mentioned elsewhere on this site. Was trying the source from http://marioboehmer.blogspot.com/2011/05/android-adk-with-standard-arduino-uno.html
    initially but no luck. Finally got the connection going with the ArduinoTerminalBeta.apk above and the term_test arduino sketch above.
    Thanks for that.

    Are you able to provide the source for the ArduinoTerminalBeta.apk yet? It would be useful as a basis to understand managing the comms with the arduino even if it isn’t particularly robust yet. worked enough and I’m quite happy to hack around with it.

    Next it’s connecting an I2C device to the arduino and capturing the telemetry on the Nexus.
    Cheers
    Andy

  • keith
    September 27, 2011 at 2:27 pm

    do the phone have to be usb host enabled such as samsung galaxy s2 in order to run this?

    or will it be possible for me to use a htc desire hd on 2.3.4 for it?

    looking forward for the release of the source code for the arduino terminal as well. thk!

  • JGo
    October 11, 2011 at 9:43 am

    I’m tring to follow the tutorial at http://developer.android.com/guide/topics/usb/adk.html

    But I can get the code at Eclipe to work with any errors.
    We should import the project downloaded from ‘app’ folder from ADK package.
    Any modifications should be made at this code to work correctly?
    I can’t figure this out..

  • AndyS
    October 30, 2011 at 9:55 am

    Hi Oleg,

    Any more updates on the release of the source code for the ArduinoTerminal APK?

    Cheers
    Andy

  • PZuro
    November 27, 2011 at 1:16 am

    Hi Oleg,

    I’m an architecture student (read: not computer science or electrical engineering!) working on a prototype that–among others things–needs a string sent from an Arduino Uno to and HTC Sensation 4G (2.3.4), via your USB Host Shield + r2.0 library + Terminal Emulator App. So far, I’ve successfully compiled and uploaded the term_test code onto the Arduino, and installed the Terminal Emulator app onto my HTC Sensation. How I can’t get the two to talk? What do you mean by “basic terminal emulator functionality over ADK interface?” What are the criteria for phones being “ADK-capable,” other than running 2.3.4? Your direction is greatly needed and greatly appreciated!

  • Phillip
    December 4, 2011 at 2:40 am

    Works with LG Optimus One if you upgrade your rom/kernal as shown on this site:

    http://blogdodantas.dxs.com.br/2011/10/28/adding-adk-support-in-your-optimus-one-android-device/

  • Jeff
    December 10, 2011 at 6:30 am

    Hi,

    Thought I’d share my experiences with a Motorola XOOM tablet since it might help others in the future. It works with one small change to the Android Terminal Emulator app … in the AndroidManifest.xml file … simply make the change using the Application Tab and set the Theme to @android:style/Theme, or update the .xml directly if you wish, and you should be good-to-go. The problem was that the default theme (Theme.Holo if I’m not mistaken for Honeycomb 3.2.1 which is latest non-rooted version for the XOOM) didn’t like it when the ‘Custom Title’ changes were being made in the TerminalViewable class’ SetActivity function and would cause a force close. So forcing the app to just use ‘Theme’ rather than ‘Theme.Holo’ with the manifest change took care of the problem. Following that minor change, it works great with my Arduino Uno/USB Host Shield combo connected to my XOOM tablet.

  • Jeff
    December 10, 2011 at 7:52 am

    Oh, one more thing about my my experiences with the XOOM Tablet … the options menu doesn’t show up … might be because of the ‘Theme’ … but maybe not too … so you can’t access preferences … which unfortunately also means you are stuck with portrait mode … I just commented out code to force the orientation to be ‘sensor’ … that pretty much takes care of the problem … although you don’t get the ‘exit’ option either … but that’s minor I think. One of these days when time permits I might work on fixing that. But the keyboard works fine, the terminal communication works fine, etc.

  • Marto
    December 27, 2011 at 6:02 pm

    I thought it’s worth noting that USB Host library 2.0 won’t compile on Arduino 1.0 IDE.

    In order to do that, all includes of must be replaced with . It may be done in a conditional macro, as well.

    Also, line #26 in message.cpp (Serial.print(c,BYTE); …) must be corrected.

    Thanks for the shield design and the library 🙂

  • Marto
    December 27, 2011 at 6:13 pm

    Oops, I saw that < and > got removed. In short, includes of WProgram.h must be replaced with Arduino.h.

  • Mário Saleiro
    January 8, 2012 at 12:53 pm

    Hi! I just want to report that I tried to install ArduinoTerminalBeta.apk in a Huawei U8510 Ideos X3 with Android 2.3.5 and kernel 2.6.35.7-perf kernel (updated from official Vodafone Portugal 2.3.3 ROM to stock Huawei UK Tesco 2.3.5 ROM) and when I try to install I just get the message “Application not installed”

    • oleg
      January 9, 2012 at 7:36 am

      Does this model support ADK?

      • Mário Saleiro
        January 10, 2012 at 9:27 am

        I don’t know. I couldn’t find a list of the models that support ADK. I just found some websites saying that ADK has been backported to 2.3.4. Some others say that you must have at least version 2.3.4. I decided to try to install it to see if it works. Meanwhile I found another stock ROM from Kuweit which has Android version 2.3.4 but haven’t tried in that version yet. Is there any way to know which phones are supported and which are not? Btw, this probably doesn’t matter but the Huawei Ideos X3 sold by Vodafone here in Portugal comes with Google branding in the back cover.

  • Giuseppe Lazzara
    January 10, 2012 at 8:48 am

    Hello all, i’m Giuseppe Lazzara and writing from Reggio Calabria (Italy) :).

    Oleg congratulations for your skills. I admire you a lot.

    I want help you for install ArduinoTerminal on IDEOS and other androidMOD ( 2.3+ ) .

    Download these two packages:
    http://forum.xda-developers.com/showthread.php?t=1363593&page=160

    http://forum.xda-developers.com/showthread.php?t=1363593&page=160

    Send them in Android from “adb push” command
    adb push android.hardware.usb.accessory.xml /system/etc/permissions/
    adb push com.android.future.usb.accessory.jar /system/framework

    and reboot your phone.
    Sorry for my english,
    by by

  • Jack
    April 19, 2012 at 8:15 pm

    Oleg,

    you have an impressive production of topics, thanks from all beginners.

    I am trying to replicate your Terminal Emulator on Nexus One with Seeeduino. I have started with Eclipse (on Win7) and was able to run the solo version of the Terminal Emulator (without Seeeduino)in Android emulator. All great – java shows the keys but “no USB devices are currently attached”.

    Next, I downloaded the sketch to Seeeduino and connected it to PC. Restarted TermEmulator and “no USB devices are currently attached”.

    OK, went back to Nexus, installed TermEmulator.apk and at once it complained that “OSCOKIRQ failed to assert”. Any suggestion how to go around this?

    Thanks

    jack

    • oleg
      April 19, 2012 at 10:25 pm

      “OSCOKIRQ failed to assert” usually indicates that Arduino board can’t communicate with USB Host Shield. I’m not familiar with Seeeduino, you need to check how closely it follows standard layout.

  • Andronio
    May 3, 2012 at 2:09 am

    Congratulations on the impressive work done with the ADK.

    Only I have a question regarding how to debug the code from the android app. If I am right, when you connect the phone (USB DEVICE) to Shield (USB HOST), can not connect directly to PC (USB HOST) to debug the application from eclipse via adb and logcat.

    Would really appreciate your directions on how to connect everything to achieve android debug the application.

    Note ArduinoTerminal-0.9.2: the application breaks when you press the submit button with the command Text_ empty. A “return;” instruction that is missing:
    TerminalViewable.java
    (
    public void onSendAction (View view) {
    CommandText_.getText CharSequence text = ();
    if (text == null | | text.length () == 0) {
    return;
    }
    … )

    Tested in Nexus One android v2.3.6, works great.

    Best regards,
    Andronio.

  • Lenny
    September 23, 2012 at 12:26 pm

    Hi, I tried to install APK on Mediacomm 736i tablet but when correctly installation finish when start application I receive an error ‘ArduinoTerminal application stopped in abnormal mode’ (translated from my language).
    Have you any suggest?

    Thanks

  • Robert Seliger
    November 7, 2012 at 12:24 pm

    Same result as Lenny above with this app on a Nexus 7 running Android 4.1.2

  • shammir
    January 9, 2013 at 8:51 am

    Hello,

    I want some help from your side. I am working on the ublox receiver and smartphone application. but before in whole application we have used the Bluetooth receiver to get data from the ublox but now i want to take data directly by plunging the USB cable into the ublox and the mobile phone so can you suggest best way to do that.

    THANKS
    Shammir

  • Guy
    May 13, 2013 at 5:59 am

    I could use a little guidance. I’m trying to connect a Mega ADK to a USB ELM327 OBD II cable/adapter and I’m not quite sure how to go about this. I have verified the ELM device works fine when connected to a PC with a terminal program, and it basically responds to simple ASCII commands like “ATZ\r” which resets the device and responds with an ASCII string like “elm327 1.3b”. What would be a good example sketch to use as a starting point using the Mega ADK? I tried a modified test_term program after installing the shield host 2.0 library (modified for ADK), but it gets stuck in adk.isReady() = false. Am I going about this wrong? Thanks.

  • Eric
    June 17, 2013 at 10:18 am

    Thanks a lot.

    It work with ADKTerminalTest example of Arduino 1.5.2 with little bit of modification, .

    Tested on Nexus One with Android 2.3.6, but not work on HTC One X with Android 4.1.1, dur to issues of Theme!

  • Andi
    August 29, 2013 at 4:25 pm

    Hey! I’m trying to connect my Android phone with Arduino UNO via the USB Host. I’m trying to install Android Terminal apk on my phones and none seem to work. I have an 4.2.2 Android Galaxy S4 and 2.3.6 Galaxy mini2 S6500. On mini2 the app doesn’t install at all and on S4 it installs but force stops when I try to open the app.
    Please, I really need help for this project! I’d like to know if I can get something done for those to work. Thank you!