Archive for the ‘Android’ Category

Passing array with intents

Posted: September 12, 2011 in Android



I have an array of integers in the activity A:

int array[] = {1,2,3};

And i want to send that variable to the activity B, so i create a new intent and use the putExtra method:

Intent i = new Intent(A.this, B.class);
i.putExtra("numbers", array);

In the activity B i get the info:

Bundle extras = getIntent().getExtras();
int arrayB = extras.getInt("numbers");

But this is not really sending the array, i just get the value ‘0’ on the arrayB. I’ve been looking for some examples but i didnt found anything so… Can anybody help me here? 😀




8down voteaccepted

You are setting the extra with an array. You are then trying to get a single int.

Your code should be:

int[] arrayB = extras.getIntArray("numbers");




Posted: September 11, 2011 in Android

Android folds multiple ideas, (to name some: invoking other applications, invoking other components, events, actions, publish and subscribe), in to what is called an “Intent”.

At the simplest level you can use an intent to start an application that you write. Imagine you write an application whose startign screen or activity is called MY_SCREEN. Then you can have other programs invoke that screen by calling this function:

 public static invokeMyApplication(Activity parentActivity) { String actionName= "com.your-company.your-app.intent.action.MY_SCREEN"; Intent intent = new Intent(actionName); parentActivity.startActivity(intent); } 

The name of an action follows Java-style naming convention. For built in android actions such as Intent.ACTION_VIEW you would put android.intent.action.VIEW here. Or you can use the defined constant in your code: Intent.ACTION_VIEW. Custom actions should generally use a prefix matching the package name.

However the comes after your java package name is arbitrary but if you were to follow the android convention then it should “.intent.action.YOUR_ACTION_NAME”.

To make this work your application have to announce in androidmanifest.xml that it can be invoked for this action. Here is an example

 <activity android:name="MyApplication" android:label="@string/my_application_label"> <intent-filter> <action android:name="com.your-company.your-app.intent.action.MY_SCREEN" /> </intent-filter> </activity> 

Available Intents in Android

As Android comes with a predefined set of applications, it is reasonable to assume that there are some prefabricated applications out there that we can quickly invoke and test our understanding of intents. That is indeed the case. The following url 

documents the available intents. These include

  • A browser application to open a browser window
  • An application to call a telephone number
  • An application to present the dialer to type in the numbers and then call through the UI
  • A mapping application to show the map of the world at a given lat long
  • A detailed mapping application that can show google street views

Here is some sample code that exercises each of these applications

 public class IntentsUtils { public static void invokeWebBrowser(Activity activity) { Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(Uri.parse("")); activity.startActivity(intent); } public static void invokeWebSearch(Activity activity) { Intent intent = new Intent(Intent.ACTION_WEB_SEARCH); intent.setData(Uri.parse("")); activity.startActivity(intent); } public static void dial(Activity activity) { Intent intent = new Intent(Intent.ACTION_DIAL); activity.startActivity(intent); } public static void call(Activity activity) { Intent intent = new Intent(Intent.ACTION_CALL); intent.setData(Uri.parse("tel:904-905-5646")); activity.startActivity(intent); } public static void showMapAtLatLong(Activity activity) { Intent intent = new Intent(Intent.ACTION_VIEW); //geo:lat,long?z=zoomlevel&q=question-string intent.setData(Uri.parse("geo:0,0?z=4&q=business+near+city")); activity.startActivity(intent); } public static void tryOneOfThese(Activity activity) {; } } 

Intents and Data Uris

we have covered simplest of the intents where all we need is the name of an action. The ACTION_DIAL activity above falls under this criteria just like the “MY_SCREEN” example we started with. So to invoke the dialler all we need is the action of the dialler and nothing else. So let us reconsider that example:

 public static void dial(Activity activity) { Intent intent = new Intent(Intent.ACTION_DIAL); activity.startActivity(intent); } 

However if you notice other intents above you will see that they take an additional parameter called “Data” which normally points to a Uri. Let us take a look at the CALL activity

 public static void call(Activity activity) { Intent intent = new Intent(Intent.ACTION_CALL); intent.setData(Uri.parse("tel:904-905-5646")); activity.startActivity(intent); } 

For example one can not call a phone number unless they know what the phone number is. So invoking a “ACTION_CALL” would be useless unless we tell what number to call. This is what gets passed through the Data uri. so we now know that an “intent” has atleast two parts

  1. Action
  2. Data

Action is pointed by a string constant as we discussed earlier usually prefixed by the java package name. The Data portion is always a string representing a uri. The format of this uri could be specific to each Activity that is invoked by that action. In this case the “CALL” action decides what kind of data uri it would expect. From the Uri it extracts the telephone number.

The activity can also use the Uri as a pointer to a data source and extract the data from the data source and use that data instead. This would be the case for media such as audio and video or images.

Generic Actions

The actions Intent.ACTION_CALL and Intent.ACTION_DIAL could easily lead us to a wrong assumption that there is a one to one relationship between an action and what it invokes. To disprove this let us extract a counter example from the sample code above:

 public static void invokeWebBrowser(Activity activity) { Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(Uri.parse("")); activity.startActivity(intent); } 

If you notice, the action is simply stated as ACTION_VIEW. How does Android know which activity to invoke in response to such a generic action. Well android under these cases rely more heavily on the nature of the Uri. In this case it looks at the scehme of the uri which happens to be “http” and inquires all the registered activities to see which ones understand this scheme. Out of these it inquires which ones can handle the “VIEW” and then invokes that activity. For this to work the browser activity should have registered a VIEW intent against the data scheme of “http”. That intent declaration may look like

 <intent-filter> <action android:name="android.intent.action.VIEW" /> <data android:scheme="http"/> <data android:scheme="https"/> </intent-filter> 

You can learn more about the data options by looking at the XML definition for the Data element at 

The child elements or attributes of data include

 host mimeType path pathPattern pathPrefix port scheme 

The one that is often used is the mime type. For example the following IntentFilter for the activity that displays (views) a list of notes indicate the mime type as a directory of notes.

 <intent-filter> <action android:name="android.intent.action.VIEW" /> <data android:mimeType="" /> </intent-filter> 

Where as the screen that displays a single note declares its intent filter as handling of type “a single note item”

 <intent-filter> <action android:name="android.intent.action.INSERT" /> <data android:mimeType="" /> </intent-filter> 

Using Extra Info

Intent provides another facility to pass data between senders and receivers of an intent. This data is sometimes refered as “Extra” data. This “extra” data that an “Intent” carries with it is a set of key value pairs. The keys are recommended to start with the package name. The value can be any fundamental data type or an arbitrary object as long as it implements the Parcelable interface. So in that sense a bundle is a maping from string keys to various Parcelable type values.

A Parcelable interface allows classes to write their instances to and restored from a Parcel. A Parcel is a container for a message (data and object references) that can be sent through an IBinder. A Parcel can contain both flattened data that will be unflattened on the other side of the IPC (using the various methods here for writing specific types, or the general Parcelable interface), and references to live IBinder objects that will result in the other side receiving a proxy IBinder connected with the original IBinder in the Parcel.

Parcel is not a general-purpose serialization mechanism. This class (and the corresponding Parcelable API for placing arbitrary objects into a Parcel) is designed as a high-performance IPC transport. As such, it is not appropriate to place any Parcel data in to persistent storage: changes in the underlying implementation of any of the data in the Parcel can render older data unreadable.

There are a number of methods available on the “Intent” class to set and get this extra open ended data. Underneath an “Intent” stores this extra data as a single “Bundle”. With that information most of the methods related to “extra” information would make sense.

start with

 public static void exerciseExtraInfo(Intent intent) { //Get the Bundle from this intent Bundle extraBundle = intent.getExtras(); // Bundle anotherBundle = new Bundle(); ... intent.putExtras(anotherBundle); } 

Here is what “putExtras” does. It checks to see if there is currently a bundle in the intent. If it is there it adds the additional keys and values from the new bundle to this existing bundle. If the bundle doesn’t exist it will create a new one and adds the stuff from the new bundle to that bundle. So it is important to note that it doesn’t reference the incoming bundle rather replicates it. Which means if you were to change the passed in bundle it won’t change the bundle inside the Intent.

A number of methods exist to add fundamental types to the bundle. Here is a sample that adds simple data types to the “extra” data

 putExtra(String name, boolean value); putExtra(String name, int value); putExtra(String name, double value); putExtra(String name, String value); .... .... and more 

And here are some not so simple extras

 //simple array support putExtra(String name, int[] values); putExtra(String name, float[] values); //Serializable objects putExtra(String name, Serializable value); //Parcelable support putExtra(String name, Parcelable value); //Add another bundle at a given key //Bundles in bundles putExtra(String name, Bundle value); //Add bundles from another intent //copy of bundles putExtra(String name, Intent anotherIntent); //Explicit Array List support putIntegerArrayListExtra(String name, ArrayList arrayList); putParcelableArrayListExtra(String name, ArrayList arrayList); putStringArrayListExtra(String name, ArrayList arrayList); 

On the receiving side there are equivalent methods that start with “get” to get retrieve information from the extra bundle based on key names.

The “Intent” class defines a number of Extra key strings that go with certain actions. Here are some examples

EXTRA_ALARM_COUNT: Used as an int extra field in AlarmManager intents to tell the application being invoked how many pending alarms are being delievered with the intent. For one-shot alarms this will always be 1. For recurring alarms, this might be greater than 1 if the device was asleep or powered off at the time an earlier alarm would have been delivered. Constant Value: “android.intent.extra.ALARM_COUNT”

EXTRA_EMAIL: A String[] holding e-mail addresses that should be delivered to. Constant Value: “android.intent.extra.EMAIL”

EXTRA_SUBJECT: A constant string holding the desired subject line of a message. Constant Value: “android.intent.extra.SUBJECT”

EXTRA_BCC: A String[] holding e-mail addresses that should be blind carbon copied. Constant Value: “android.intent.extra.BCC”

EXTRA_CC: A String[] holding e-mail addresses that should be carbon copied. Constant Value: “android.intent.extra.CC”

EXTRA_DONT_KILL_APP: Used as an boolean extra field in ACTION_PACKAGE_REMOVED or ACTION_PACKAGE_CHANGED intents to override the default action of restarting the application. Constant Value: “android.intent.extra.DONT_KILL_APP”

EXTRA_INTENT: An Intent describing the choices you would like shown with ACTION_PICK_ACTIVITY. Constant Value: “android.intent.extra.INTENT”

EXTRA_KEY_EVENT: A KeyEvent object containing the event that triggered the creation of the Intent it is in. Constant Value: “android.intent.extra.KEY_EVENT”

EXTRA_PHONE_NUMBER: A String holding the phone number originally entered in ACTION_NEW_OUTGOING_CALL, or the actual number to call in a ACTION_CALL. Constant Value: “android.intent.extra.PHONE_NUMBER”

EXTRA_SHORTCUT_ICON: The name of the extra used to define the icon, as a Bitmap, of a shortcut. Used in conjunction with ACTION_CREATE_SHORTCUT action. Constant Value: “android.intent.extra.shortcut.ICON

EXTRA_SHORTCUT_ICON_RESOURCE: The name of the extra used to define the icon, as a ShortcutIconResource, of a shortcut. Constant Value: “android.intent.extra.shortcut.ICON_RESOURCE”

EXTRA_SHORTCUT_INTENT: The name of the extra used to define the Intent of a shortcut. Constant Value: “android.intent.extra.shortcut.INTENT”

EXTRA_SHORTCUT_NAME: The name of the extra used to define the name of a shortcut. Constant Value: “android.intent.extra.shortcut.NAME”

EXTRA_STREAM: A content: URI holding a stream of data associated with the Intent, used with ACTION_SEND to supply the data being sent. Constant Value: “android.intent.extra.STREAM”

EXTRA_TEXT: A constant CharSequence that is associated with the Intent, used with ACTION_SEND to supply the literal data to be sent. Note that this may be a styled CharSequence, so you must use Bundle.getCharSequence() to retrieve it. Constant Value: “android.intent.extra.TEXT”

EXTRA_TEMPLATE: The initial data to place in a newly created record. Use with ACTION_INSERT. The data here is a Map containing the same fields as would be given to the underlying ContentProvider.insert() call. Constant Value: “android.intent.extra.TEMPLATE”

EXTRA_TITLE: A CharSequence dialog title to provide to the user when used with a ACTION_CHOOSER. Constant Value: “android.intent.extra.TITLE”

EXTRA_UID: Used as an int extra field in ACTION_UID_REMOVED intents to supply the uid the package had been assigned. Also an optional extra in ACTION_PACKAGE_REMOVED or ACTION_PACKAGE_CHANGED for the same purpose. Constant Value: “android.intent.extra.UID”

Using components to directly invoke an Activity

In Android Activity, Service, ContentProvider and Application are considered application components. They all implement ComponentCallbacks. As an implementer of ComponentCallbacks they are expected to support two call back apis: onConfigurationChanged and onLowMemory.

The signatures of these methods are

 public void onConfigurationChanged(Configuration newConfig); public void onLowMemory(); 

onConfigurationChanged is called by the system when the device configuration changes while that component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources.

onLowMemory() is called when the overall system is running low on memory, and would like actively running process to try to tighten their belt. While the exact point at which this will be called is not defined, generally it will happen around the time all background processes have been killed, that is before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing. Applications that want to be nice can implement this method to release any caches or other unnecessary resources they may be holding on to. The system will perform a gc after returning from this method.

An Activity being a component we can specify the name of this component or class name as an argument to the Intent and use start activity on the intent to start the target activity identified by the component name.

In a similar manner a target service component can be started using the “startService” method on the context class.

There are a number of methods available on the Intent class to specify a component.

 setComponent(ComponentName name); setClassName(String packageName, String classNameInThatPackage); setClassName(Context context, String classNameInThatContext); setClass(Context context, Class classObjectInThatContext); 

Ultimately they are all shortcuts for calling one method

 setComponent(ComponentName name); 

Curiously ComponentName is a class which basically wraps a package name and a classname together. Although a component name is expected to point to a component implementing a “component” contract, the constructor of ComponentName does not do any particular checks to ensure that.

For example the following code invokes the “contacts” activity that gets shipped with the emulator

 Intent intent = new Intent(); intent.setComponent(new ComponentName( "" ,""); intent.setFlags(....) startActivity(intent) 

Notice that the package name and the classname are fully qualified and used in turn to construct the ComponentName before passing to the intent class.

However it must be noted that this is not the recommended way to invoke other appications. The approach is fine for activities that are are inside an application. But for applications or activities that need to be invoked from outside they should go through the action and data uri route.

Best practice for component designers

If you look at the design for the contacts application in Android you will notice some patterns for designing with intents. In the example above we have used an explicit way to invoke the contacts application.

To make this easier the “android.provider.contacts” package defines three Intent related classes. These are

 contacts.Intents contacts.Intents.Insert //nested class contacts.Intents.UI //nested class 

The top level class “Intents” defines the primary Intents that the contacts application will respond to and also the events it generates as it does its work.

The nested class Intents.Insert defines the supporing intents and other constants to insert new records. The Intents.UI nested class defines a number of ways invoking the UI. The intents here also clarifies the extra information needed to invoke the intents including key names and their expected value types.

As you design your own content providers and activites that act upon those content providers you may want to follow this pattern for making intents explicit.

What are categories and how are they used

Categories is a way to classify activities. As activities are designed, they may have certain capabilities that will restrict them or enable them under some circumstances. These common characteristics of these activities are declared through categories. Let us look at some known categories


let us examine a few of these categories whose meaning is obvious. Take for insnace GADGET category. Activities enabled for this category, can be embedded inside of another activity that is hosting gadgets. The implication is that such an activity needs to be bound by certain contracts. In a similar manner The EMBED category declares that an activity is capable of being embedded in a parent activity.

Here is an explanation for each of these categories.

CATEGORY_DEFAULT:Set if the activity should be an option for the default action (center press) to perform on a piece of data. Setting this will hide from the user any activities without it set when performing an action on some data. Note that this is normal -not- set in the Intent when initiating an action — it is for use in intent filters specified in packages. Constant Value: “android.intent.category.DEFAULT”

CATEGORY_BROWSABLE: Activities that can be safely invoked from a browser must support this category. For example, if the user is viewing a web page or an e-mail and clicks on a link in the text, the Intent generated execute that link will require the BROWSABLE category, so that only activities supporting this category will be considered as possible actions. By supporting this category, you are promising that there is nothing damaging (without user intervention) that can happen by invoking any matching Intent. Constant Value: “android.intent.category.BROWSABLE”

CATEGORY_TAB: Intended to be used as a tab inside of an containing TabActivity.

CATEGORY_ALTERNATIVE: Set if the activity should be considered as an alternative action to the data the user is currently viewing. See also CATEGORY_SELECTED_ALTERNATIVE for an alternative action that applies to the selection in a list of items. Supporting this category means that you would like your activity to be displayed in the set of alternative things the user can do, usually as part of the current activity’s options menu. You will usually want to include a specific label in the of this action describing to the user what it does.

The action of IntentFilter with this category is important in that it describes the specific action the target will perform. This generally should not be a generic action (such as ACTION_VIEW, but rather a specific name such as “ Only one alternative of any particular action will be shown to the user, so using a specific action like this makes sure that your alternative will be displayed while also allowing other applications to provide their own overrides of that particular action.

CATEGORY_EMBED: Capable of running inside a parent activity container. However this is being removed in favor of more explicit categories such as CATEGORY_GADGET

CATEGORY_SELECTED_ALTERNATIVE: Set if the activity should be considered as an alternative selection action to the data the user has currently selected. This is like CATEGORY_ALTERNATIVE, but is used in activities showing a list of items from which the user can select, giving them alternatives to the default action that will be performed on it.

CATEGORY_LAUNCHER: Should be displayed in the top-level launcher.

CATEGORY_HOME: This is the home activity, that is the first activity that is displayed when the device boots.

CATEGORY_PREFERENCE: This activity is a development preference panel.

CATEGORY_GADGET: This activity can be embedded inside of another activity that is hosting gadgets.

CATEGORY_TEST: To be used as a test (not part of the normal user experience).

CATEGORY_MONKEY: This activity may be exercised by the monkey or other automated test tools.

CATEGORY_OPENABLE: Used to indicate that a GET_CONTENT intent only wants URIs that can be opened with ContentResolver.openInputStream. Openable URIs must support the columns in OpenableColumns when queried, though it is allowable for those columns to be blank.

Categories and Intents

When you use an intent to start an activity, you can specify the kind of activity to choose by specifying a category. Or you can also search for activites that match a certain category.

Here is an example to retrieve a set of main activities that match the category of CATEGORY_SAMPLE_CODE. PackageManager is a key class that allows discovery of activities that match a certain intent with out invoking them. A programmer can cycle through the received activities and invoke them as see fit based on the ResolveInfo api.

 Intent mainIntent = new Intent(Intent.ACTION_MAIN, null); mainIntent.addCategory(Intent.CATEGORY_SAMPLE_CODE); PackageManager pm = getPackageManager(); List<ResolveInfo> list = pm.queryIntentActivities(mainIntent, 0); 

Following the same logic we can also get a list of all launchable applications by populating an intent with a category of CATEGORY_LAUNCHER. The sample code for this is below

 //Get me all launchable applications Intent mainIntent = new Intent(Intent.ACTION_MAIN, null); mainIntent.addCategory(Intent.CATEGORY_LAUNCHER); List mApps = getPackageManager().queryIntentActivities(mainIntent, 0); 

In fact we can do better. Let us go ahead and start an activity based on the Intent above. There are going to be more than one activity matching the intent. Which activity is Android going to start? Android instead presents a chooser dialog listing all possible activities. The title of this dialog says “Complete action using”.

 public static void invokeAMainApp(Activity activity) { Intent mainIntent = new Intent(Intent.ACTION_MAIN, null); mainIntent.addCategory(Intent.CATEGORY_LAUNCHER); activity.startActivity(mainIntent); } 

Here is another example of using an intent to go to a home page.

 //Go to home screen Intent mainIntent = new Intent(Intent.ACTION_MAIN, null); mainIntent.addCategory(Intent.CATEGORY_HOME); startActivity(mainIntent); 

You can also write your own home page instead of one that comes with Android and declare that activity to be of category HOME and then the code above will give you an option to open your home activity as there are now more than one home activities registered.

 //Replace the home screen with yours <intent-filter> <action android:value="android.intent.action.MAIN" /> <category android:value="android.intent.category.HOME"/> <category android:value="android.intent.category.DEFAULT" /> </intent-filter> 

Also note that when we launch these intents, they are still being launched as a new instance that is part of the same task/stack. If we want to launch it as a separate task (or bring the currently running instance of the app to the foreground) like the home app does, then we need to set the NEW_TASK_LAUNCH flag in the Intent.

The rules for resolving Intents to their components

So far we have discussed a number of aspects about intents. To recap we talked about actions, data uris, extra infos, and finally categories. Given these aspects Android uses the following algorithm to resolve the intents to activities or more specifically components:

At the top of the hierarchy, with an air of exclusivity, is the Component name attached to an intent. If this is set, then every other aspect or attribute of the intent is ignored and that component is chosen for execution.

If an intent indicates an action then the target activity must have that action listed as one it supports in the manifest file.

If an intent specifies a data uri, the type is retrieved from this uri, if not already supplied in the Intent. Like the action, if a type is included in the intent (either explicitly or implicitly in its data), then this must be listed by the component as one it handles.

For data that is not a content: URI and where no explicit type is included in the Intent, instead the scheme of the intent data (such as http: or mailto:) is considered. Again like the action, if we are matching a scheme it must be listed by the component as one it can handle.

The categories, if supplied, must all be listed by the activity as categories it handles. That is, if you include the categories CATEGORY_LAUNCHER and CATEGORY_ALTERNATIVE, then you will only resolve to components with an intent that lists both of those categories. Activities will very often need to support the CATEGORY_DEFAULT so that they can be found by Context.startActivity().

How should your applications declare intents

As you write new applications for Android you will want to declare intents for each of the activities you have in that application. Let us examine the notepad application to draw a pattern of these intent declarations.

 <manifest xmlns:android="" package=""> <application android:icon="@drawable/app_notes" android:label="@string/app_name"> <provider android:authorities="" /> <activity android:label="@string/title_notes_list"> <intent-filter> <action android:value="android.intent.action.MAIN" /> <category android:value="android.intent.category.LAUNCHER" /> </intent-filter> <intent-filter> <action android:value="android.intent.action.VIEW" /> <action android:value="android.intent.action.EDIT" /> <action android:value="android.intent.action.PICK" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> <intent-filter> <action android:value="android.intent.action.GET_CONTENT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> </activity> <activity android:label="@string/title_note"> <intent-filter android:label="@string/resolve_edit"> <action android:value="android.intent.action.VIEW" /> <action android:value="android.intent.action.EDIT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> <intent-filter> <action android:value="android.intent.action.INSERT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> </activity> <activity android:label="@string/title_edit_title" android:theme="@android:style/Theme.Dialog"> <intent-filter android:label="@string/resolve_title"> <action android:value="" /> <category android:value="android.intent.category.DEFAULT" /> <category android:value="android.intent.category.ALTERNATIVE" /> <category android:value="android.intent.category.SELECTED_ALTERNATIVE" /> <type android:value="" /> </intent-filter> </activity> </application> </manifest> 

As you can see there are three activities in this application that are exposed for public consumption. They are

 NotesList NoteEditor TitleEditor 

NotesList is the main entry point of the application listing all the notes in the database of notes. NoteEditor is the screen that allows you the content of a given note. A TitleEditor is the screen that allows you to edit the title of a note. You will want to put an icon in the launcher of android so that the notes application can be invoked. To facilitate this the main activity NotesList declares an intent as follows:

 <intent-filter> <action android:value="android.intent.action.MAIN" /> <category android:value="android.intent.category.LAUNCHER" /> </intent-filter> 

This allows Android to add this activity as a launchable activity. List activity is can also be invoked explicitly by some other program to view or edit a collection of notes in the notepad.

 <intent-filter> <action android:value="android.intent.action.VIEW" /> <action android:value="android.intent.action.EDIT" /> <action android:value="android.intent.action.PICK" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> 

By declaring a “PICK” action the NotesList activity is allowing the user to pick an item from the collection and return to the caller. This activity is also capable of returning the data for a given note item by allowing the user to pick one of the items of a note using the following intent. As you can see for these generic supported actions the main key is the mime type of the data. So an activity defines a set of allowed actions for each mime type in a separate filter.

 <intent-filter> <action android:value="android.intent.action.GET_CONTENT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> 

Let’s look at the NotesEditor activity to see how it defines its intent filters

 <activity android:label="@string/title_note"> <intent-filter android:label="@string/resolve_edit"> <action android:value="android.intent.action.VIEW" /> <action android:value="android.intent.action.EDIT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> <intent-filter> <action android:value="android.intent.action.INSERT" /> <category android:value="android.intent.category.DEFAULT" /> <type android:value="" /> </intent-filter> </activity> 

In the first intent filter it allows you to see and edit a single note. In the second filter it allows you to insert a note in to a directory of notes.

Finally lets look at the title editor

 <activity android:label="@string/title_edit_title" android:theme="@android:style/Theme.Dialog"> <intent-filter android:label="@string/resolve_title"> <action android:value="" /> <category android:value="android.intent.category.DEFAULT" /> <category android:value="android.intent.category.ALTERNATIVE" /> <category android:value="android.intent.category.SELECTED_ALTERNATIVE" /> <type android:value="" /> </intent-filter> </activity> 

This activity allows you to show a set of menu items to edit a title of a note. Notice that the action is a specific type and not a generic action.

Given these definitions here is what you can do with intents outside of this application

{ }: matches all of the activities that can be used as top-level entry points into an application.

{, }: is the actual intent used by the Launcher to populate its top-level list.

{ data=content:// }: displays a list of all the notes under “content://”, which the user can browse through and see the details on.

{ data=content:// }: provides a list of the notes under “content://”, from which the user can pick a note whose data URL is returned back to the caller.

{ }: is similar to the pick action, but allows the caller to specify the kind of data they want back so that the system can find the appropriate activity to pick something of that data type.

{ data=content://{ID} }: shows the user the content of note {ID}.

{ data=content://{ID} }: allows the user to edit the content of note {ID}.

{ data=content:// }: creates a new, empty note in the notes list at “content://” and allows the user to edit it. If they keep their changes, the URI of the newly created note is returned to the caller.

{ data=content://{ID} }: displays and allows the user to edit the title associated with note {ID}.

Exercising ACTION_PICK intent

So far we have exercised intents or actions that mainly invoke another activity and not expect any result back. Let us look at an activity that is a bit more involved and which returns a value as a result of that activity. ACTION_PICK is one such action. Here is what the documentation says about ACTION_PICK:

ACTION_PICK picks an item from the data, returning what was selected. The intent invoking ACTION_PICK should carry with it a URI containing a directory of data (*) from which to pick an item. This should be set using the setData() on the intent. The output from the action will be a URI of the item that was picked.

For all actions and intents that return data like this we cannot use startActivity() because startActivity() does not return any result. The reason why startActivity can not return result is because it opens the new activity as a modal dialog in a separate thread and leaves the main thread for attending events in the main ui thread. In other words “startActivity” is an asynchronous call with any call back to indicate what happened in the invoked activity. There is a variation on this method called startActivityForResult() that comes with a call back.

Let us look at the signature of this method from the Activity class:

 public void startActivityForResult(Intent intent, int requestCode) 

This method launches an activity for which you would like a result when it finished. When this activity exits, your onActivityResult() method will be called with the given requestCode. Using a negative requestCode is the same as calling startActivity(Intent) (the activity is not launched as a sub-activity).

Note that this method should only be used with Intent protocols that are defined to return a result. In other protocols (such as ACTION_MAIN or ACTION_VIEW), you may not get the result when you expect. For example, if the activity you are launching uses the singleTask launch mode, it will not run in your task and thus you will immediately receive a cancel result.

The result will come back to the activity through an overriden method called onActivityResult. The signature of this method is

 protected void onActivityResult(int requestCode, int resultCode, Intent data) 

Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it. The resultCode will be RESULT_CANCELED if the activity explicitly returned that, didn’t return any result, or crashed during its operation. You will receive this call immediately before onResume() when your activity is re-starting.

When an activity exits, it can call setResult(int) to return data back to its parent. It must always supply a result code, which can be the standard results RESULT_CANCELED, RESULT_OK, or any custom values starting at RESULT_FIRST_USER. In addition, it can optionally return back an Intent containing any additional data it wants. All of this information appears back on the parent’s Activity.onActivityResult(), along with the integer identifier it originally supplied. If a child activity fails for any reason (such as crashing), the parent activity will receive a result with the code RESULT_CANCELED.

Let us look at some samplecode demonstrating this

 Intent pickIntent = new Intent(Intent.ACTION_PICK); pickIntent.setData(Uri.parse("content://contacts")); int requestCode = 1; activity.startActivityForResult(pickIntent,requestCode); protected void onActivityResult(int requestCode, int resultCode, Intent outputIntent) { if (requestCode == 1) { if (resultCode == RESULT_OK) { Uri outputUri = outputIntent.getData(); //Log it out Log.d("test",outputUri.toString()); //Do something with the uri including viewing it outputIntent.setAction(Intent.VIEW); startActivity(outputIntent); } } } 

The constants RESULT_OK, RESULT_CANCEL, RESULT_FIRST_USER are all defined in the activity class. The numerical values of these constants are


The constant RESULT_FIRST_USER is used as a starting number for user defined activity results.

To make this work the implementer should have code that explicitly addresses the needs of a PICK. Notice how this is done in the sample note pad application. When the item is selected in the list of items, the intent that invoked the activity is checked to see if it is a PICK intent. If it is the data uri is set in a new intent and returned through setResult().

 @Override protected void onListItemClick(ListView l, View v, int position, long id) { Uri uri = ContentUris.withAppendedId(getIntent().getData(), id); String action = getIntent().getAction(); if (Intent.ACTION_PICK.equals(action) || Intent.ACTION_GET_CONTENT.equals(action)) { // The caller is waiting for us to return a note selected by // the user. The have clicked on one, so return it now. setResult(RESULT_OK, new Intent().setData(uri)); } else { // Launch activity to view/edit the currently selected item startActivity(new Intent(Intent.ACTION_EDIT, uri)); } } 

Exercising GET_CONTENT action

ACTION_GET_CONTENT allows the user to select a particular kind of data and return it. This is different than ACTION_PICK in that here we just say what kind of data is desired, not a URI of existing data from which the user can pick. A ACTION_GET_CONTENT could allow the user to create the data as it runs (for example taking a picture or recording a sound), let them browser over the web and download the desired data, etc.

Notice how the activity that displays a list of notes in the notepad application declares itself in response to PICK and GET_CONTENT:

 <intent-filter> <action android:name="android.intent.action.VIEW" /> <action android:name="android.intent.action.EDIT" /> <action android:name="android.intent.action.PICK" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="" /> </intent-filter> <intent-filter> <action android:name="android.intent.action.GET_CONTENT" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="" /> </intent-filter> 

For a PICK action you need to specify the uri which will yield a mime type of “directory of note” indicated by dir/note which will then resolve to this list activity.

The get_content action is defined in a separate filter identified by not a directory of notes but just an “item” of a note indicated by “item/note”. For a GET_CONTENT you will not specify the URI.

The sample code then will look like

 Intent intent = new Intent(Intent.ACTION_PICK); intent.setType(""); int requestCode = 1; activity.startActivityForResult(pickIntent,requestCode); 

Knowing the mime type android will then launch the best application to select that kind of data for you.

GET_CONTENT action also allows another way of picking a data uri. For instance, you may be interested in any of a set of types of content that you can pick. For example, an e-mail application that wants to allow the user to add an attachment to an e-mail message can use this action to bring up a list of all of the types of content the user can attach.

In this case, you should wrap the GET_CONTENT intent with a chooser (through createChooser(Intent, CharSequence)), which will give the proper interface for the user to pick how to send your data and allow you to specify a prompt indicating what they are doing. You will usually specify a broad MIME type (such as image/* or */*), resulting in a broad range of content types the user can select from.

When using such a broad GET_CONTENT action, it is often desireable to only pick from data that can be represented as a stream. This is accomplished by requiring the CATEGORY_OPENABLE in the Intent.

To reiterate the input to an ACTION_GET_CONTENT is the desired MIME type to retrieve. No URI is supplied in the intent, as there are no constraints on where the returned data originally comes from. You may also include the CATEGORY_OPENABLE if you can only accept data that can be opened as a stream. The result of invoking this action is a URI of the item that was picked. This must be a content: URI so that any receiver can access it.

List of of useful actions defined in Intent

Here is a quick sample of actions that the Intent class defines


The details of each of these actions are

ACTION_ALL_APPS: List all available applications

ACTION_MAIN: Invoke the main screen of an application.

ACTION_VIEW : Show an activity that is capable of seeing a uri. Input is the uri of the data to be shown.

ACTION_ATTACH_DATA: Used to indicate that some piece of data should be attached to some other place. For example, image data could be attached to a contact. It is up to the recipient to decide where the data should be attached; the intent does not specify the ultimate destination. Input is the Uri of the data to be attached. It has no output.

ACTION_EDIT : A generic action for editing data at a given input uri. no output.

ACTION_PICK : Picks the uri of a data item from a directory of data items. Input is the data uri for the directory of items. the output is the data uri of a specific item.

ACTION_CHOOSER :Activity Action: Display an activity chooser, allowing the user to pick what they want to before proceeding. This can be used as an alternative to the standard activity picker that is displayed by the system when you try to start an activity with multiple possible matches, with these differences in behavior:

You can specify the title that will appear in the activity chooser. The user does not have the option to make one of the matching activities a preferred activity, and all possible activities will always be shown even if one of them is currently marked as the preferred activity.

This action should be used when the user will naturally expect to select an activity in order to proceed. An example if when not to use it is when the user clicks on a “mailto:” link. They would naturally expect to go directly to their mail app, so startActivity() should be called directly: it will either launch the current preferred app, or put up a dialog allowing the user to pick an app to use and optionally marking that as preferred.

In contrast, if the user is selecting a menu item to send a picture they are viewing to someone else, there are many different things they may want to do at this point: send it through e-mail, upload it to a web service, etc. In this case the CHOOSER action should be used, to always present to the user a list of the things they can do, with a nice title given by the caller such as “Send this photo with:”.

As a convenience, an Intent of this form can be created with the createChooser(Intent, CharSequence) function.

Input: No data should be specified. get*Extra must have a EXTRA_INTENT field containing the Intent being executed, and can optionally have a EXTRA_TITLE field containing the title text to display in the chooser.

ACTION_GET_CONTENT: Similar to PICK but uses the data type instead of the data uri.

ACTION_DIAL : Show the dialler allowing a user to dial a number. Can pass a phone uri to prepopulate the dialler. No output.

ACTION_CALL : Make a call based on a phone uri. You may need permissions to call a number like this. You should use DIAL where needed. Emergency numbers can be dialled only through DIAL.

ACTION_SEND:Deliver some data to someone else. Who the data is being delivered to is not specified; it is up to the receiver of this action to ask the user where the data should be sent. When launching a SEND intent, you should usually wrap it in a chooser (through createChooser(Intent, CharSequence)), which will give the proper interface for the user to pick how to send your data and allow you to specify a prompt indicating what they are doing.

The intent should specify the MIME type of the data being sent. get*Extra can have either a EXTRA_TEXT or EXTRA_STREAM field, containing the data to be sent. If using EXTRA_TEXT, the MIME type should be “text/plain”; otherwise it should be the MIME type of the data in EXTRA_STREAM. Use */* if the MIME type is unknown (this will only allow senders that can handle generic data streams).

Optional standard extras, which may be interpreted by some recipients as appropriate, are: EXTRA_EMAIL, EXTRA_CC, EXTRA_BCC, EXTRA_SUBJECT.

ACTION_SENDTO: Send a message to someone specified by the data.

ACTION_ANSWER: Handle an incoming phone call. No inputs and outputs.

ACTION_INSERT : Insert an empty item into a given container. Needs a data uri pointing to the directory of items. Output is the uri of the data that was inserted.

ACTION_INSERT_OR_EDIT: Pick an existing item, or insert a new item, and then edit it. Input is the desired MIME type of the item to create or edit. The extras can contain type specific data to pass through to the editing/creating activity. Output is the URI of the item that was picked.

ACTION_DELETE : Delete what is pointed to by a Uri. Input is the data uri that is to be deleted. No outputs.

ACTION_SEARCH: invoke search activity using extra string information

ACTION_WEB_SEARCH: Opens a web page to search

ACTION_BUG_REPORT: show activity to report a bug. no inputs or outputs.

ACTION_SET_WALLPAPER: Show settings for chosing a wall paper

ACTION_VOICE_COMMAND: Start voice command

Here are some broadcast actions

ACTION_BATTERY_CHANGED: Charge level of the battery changed

ACTION_BATTERY_LOW: Battery is low

ACTION_BOOT_COMPLETED: This is broadcast once, after the system has finished booting. It can be used to perform application-specific initialization, such as installing alarms. You must hold the RECEIVE_BOOT_COMPLETED permission in order to receive this broadcast.

ACTION_CALL_BUTTON: The user pressed the “call” button to go to the dialer or other appropriate UI for placing a call. no inputs and outputs.

ACTION_CAMERA_BUTTON: The “Camera Button” was pressed. Includes a single extra field, EXTRA_KEY_EVENT, containing the key event that caused the broadcast.

ACTION_DATE_CHANGED: The date has changed.

ACTION_MEDIA_BUTTON: Media button was pressed. Includes a single extra field, EXTRA_KEY_EVENT, containing the key event that caused the broadcast.

ACTION_MEDIA_EJECT: User has expressed the desire to remove the external storage media. Applications should close all files they have open within the mount point when they receive this intent. The path to the mount point for the media to be ejected is contained in the Intent.mData field.

ACTION_MEDIA_MOUNTED: External media is present and mounted at its mount point. The path to the mount point for the removed media is contained in the Intent.mData field. The Intent contains an extra with name “read-only” and Boolean value to indicate if the media was mounted read only.

ACTION_PACKAGE_ADDED: A new package has been installed on the device. Name of the package will be in the intent.

ACTION_PACKAGE_CHANGED: A named package has been changed either by enabling a component or disabling.

ACTION_PACKAGE_INSTALL: A trigger to download and eventual installation of a package. The data part of the intent contains the uri of the package to download.

ACTION_PACKAGE_REMOVED: A named package has been removed.

ACTION_PROVIDER_CHANGED: Some content providers have parts of their namespace where they publish new events or items that the user may be especially interested in. For these things, they may broadcast this action when the set of interesting items change. For example, GmailProvider sends this notification when the set of unread mail in the inbox changes.

The data of the intent identifies which part of which provider changed. When queried through the content resolver, the data URI will return the data set in question.

The intent will have the following extra values:

count – The number of items in the data set. This is the same as the number of items in the cursor returned by querying the data URI. This intent will be sent at boot (if the count is non-zero) and when the data set changes. It is possible for the data set to change without the count changing (for example, if a new unread message arrives in the same sync operation in which a message is archived). The phone should still ring/vibrate/etc as normal in this case.

ACTION_SCREEN_OFF: Screen turned off

ACTION_SCREEN_ON: Screen turned on

ACTION_TIMEZONE_CHANGED: Time zone has changed. The id of the new time zone will be the extra info.

ACTION_TIME_CHANGED: The time was set.

ACTION_TIME_TICK: Sent every minute.

ACTION_UID_REMOVED: User id removed from the system. The user ID number is stored in the extra data under EXTRA_UID.

ACTION_WALLPAPER_CHANGED: Wall paper has changed.

Intent Flags

Intents use a set of flags to control the behavior of how new activities are invoked. Here is a brief look at these flags

FLAG_ACTIVITY_BROUGHT_TO_FRONT: This flag is not normally set by application code, but set for you by the system as described in the launchMode documentation for the singleTask mode.

FLAG_ACTIVITY_CLEAR_TOP : If set, and the activity being launched is already running in the current task, then instead of launching a new instance of that activity, all of the other activities on top of it will be closed and this Intent will be delivered to the (now on top) old activity as a new Intent.

For example, consider a task consisting of the activities: A, B, C, D. If D calls startActivity() with an Intent that resolves to the component of activity B, then C and D will be finished and B receive the given Intent, resulting in the stack now being: A, B.

The currently running instance of task B in the above example will either receiving the new intent you are starting here in its onNewIntent() method, or be itself finished and restarting with the new intent. If it has declared its launch mode to be “multiple” (the default) it will be finished and re-created; for all other launch modes it will receive the Intent in the current instance.

This launch mode can also be used to good effect in conjunction with FLAG_ACTIVITY_NEW_TASK: if used to start the root activity of a task, it will bring any currently running instance of that task to the foreground, and then clear it to its root state. This is especially useful, for example, when launching an activity from the notification manager.

FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS: If set, the new activity is not kept in the list of recently launched activities.

FLAG_ACTIVITY_FORWARD_RESULT :If set and this intent is being used to launch a new activity from an existing one, then the reply target of the existing activity will be transfered to the new activity. This way the new activity can call setResult(int) and have that result sent back to the reply target of the original activity.

FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY: If set, this activity is being launched from history (longpress home key).

FLAG_ACTIVITY_MULTIPLE_TASK :Do not use this flag unless you are implementing your own top-level application launcher. Used in conjunction with FLAG_ACTIVITY_NEW_TASK to disable the behavior of bringing an existing task to the foreground. When set, a new task is always started to host the Activity for the Intent, regardless of whether there is already an existing task running the same thing. Because the default system does not include graphical task management, you should not use this flag unless you provide some way for a user to return back to the tasks you have launched.

This flag is ignored if FLAG_ACTIVITY_NEW_TASK is not set.

FLAG_ACTIVITY_NEW_TASK :If set, this activity will become the start of a new task on this history stack. A task (from the activity that started it to the next task activity) defines an atomic group of activities that the user can move to. Tasks can be moved to the foreground and background; all of the activities inside of a particular task always remain in the same order. See the Application Model documentation for more details on tasks.

This flag is generally used by activities that want to present a “launcher” style behavior: they give the user a list of separate things that can be done, which otherwise run completely independently of the activity launching them.

When using this flag, if a task is already running for the activity you are now starting, then a new activity will not be started; instead, the current task will simply be brought to the front of the screen with the state it was last in. See FLAG_ACTIVITY_MULTIPLE_TASK for a flag to disable this behavior.

This flag can not be used when the caller is requesting a result from the activity being launched.

FLAG_ACTIVITY_NO_HISTORY : If set, the new activity is not kept in the history stack.

FLAG_ACTIVITY_PREVIOUS_IS_TOP : If set and this intent is being used to launch a new activity from an existing one, the current activity will not be counted as the top activity for deciding whether the new intent should be delivered to the top instead of starting a new one. The previous activity will be used as the top, with the assumption being that the current activity will finish itself immediately.

FLAG_ACTIVITY_RESET_TASK_IF_NEEDED :If set, and this activity is either being started in a new task or bringing to the top an existing task, then it will be launched as the front door of the task. This will result in the application of any affinities needed to have that task in the proper state (either moving activities to or from it), or simply resetting that task to its initial state if needed.

FLAG_ACTIVITY_SINGLE_TOP : If set, the activity will not be launched if it is already running at the top of the history stack.

FLAG_DEBUG_LOG_RESOLUTION : A flag you can enable for debugging: when set, log messages will be printed during the resolution of this intent to show you what has been found to create the final resolved list.

FLAG_FROM_BACKGROUND : Can be set by the caller to indicate that this Intent is coming from a background operation, not from direct user interaction.

FLAG_GRANT_READ_URI_PERMISSION: If set, the recipient of this Intent will be granted permission to perform read operations on the Uri in the Intent’s data.

FLAG_GRANT_WRITE_URI_PERMISSION : If set, the recipient of this Intent will be granted permission to perform write operations on the Uri in the Intent’s data.

FLAG_RECEIVER_REGISTERED_ONLY : If set, when sending a broadcast only registered receivers will be called — no BroadcastReceiver components will be launched.

Definitions for EXTRA Info

EXTRA_TEMPLATE :The initial data to place in a newly created record. Use with ACTION_INSERT. The data here is a Map containing the same fields as would be given to the underlying ContentProvider.insert() call.

EXTRA_TEXT :A constant CharSequence that is associated with the Intent, used with ACTION_SEND to supply the literal data to be sent. Note that this may be a styled CharSequence, so you must use Bundle.getCharSequence() to retrieve it.

EXTRA_TITLE :A CharSequence dialog title to provide to the user when used with a ACTION_CHOOSER.

EXTRA_UID :Used as an int extra field in ACTION_UID_REMOVED intents to supply the uid the package had been assigned. Also an optional extra in ACTION_PACKAGE_REMOVED or ACTION_PACKAGE_CHANGED for the same purpose.

The string keys for these extras start with “android.intent.extra.*”

satya – Saturday, February 05, 2011 11:03:40 AM

Directly invoking an intent

 private void invokeTabNav() { Intent i = new Intent(this,ActionBarActivity.class); startActivity(i); }


using a Latitude and Longitude value (Point A), I am trying to calculate another Point B, X meters away bearing 0 radians from point A. Then display the point B Latitude and Longitude values.

Example (Pseudo code):

PointA_Lat = x.xxxx; PointA_Lng = x.xxxx; Distance = 3; //Meters bearing = 0; //radians new_PointB = PointA-Distance; 

I was able to calculate the distance between two Points but what I want to find is the second point knowing the distance and bearing.

Preferably in PHP or Javascript.

Thank you


4 down vote accepted

It seems you are measuring distance (R) in meters, and bearing (theta) counterclockwise from due east. And for your purposes (hundereds of meters), plane geometry should be accurate enough. In that case,

dx = R*cos(theta) ; theta measured counterclockwise from due east dy = R*sin(theta) ; dx, dy same units as R 

If theta is measured clockwise from due north (for example, compass bearings), the calculation for dx and dy is slightly different:

dx = R*sin(theta) ; theta measured clockwise from due north dy = R*cos(theta) ; dx, dy same units as R 

In either case, the change in degrees longitude and latitude is:

delta-longitude = dx/(111320*cos(latitude)) ; dx, dy in meters delta-latitude = dy/110540 ; result in degrees long/lat 

The difference between the constants 110540 and 111320 is due to the earth’s oblateness (polar and equatorial circumferences are different).

Here’s a worked example, using the parameters from a later question of yours:

Given a start location at longitude -87.62788 degrees, latitude 41.88592 degrees, find the coordinates of the point 500 meters northwest from the start location.

If we’re measuring angles counterclockwise from due east, “northwest” corresponds to theta=135 degrees. R is 500 meters.

dx = R*cos(theta) = 500 * cos(135 deg) = -353.55 meters dy = R*sin(theta) = 500 * sin(135 deg) = +353.55 meters delta_longitude = dx/(111320*cos(latitude)) = -353.55/(111320*cos(41.88592 deg)) = -.004266 deg (approx -15.36 arcsec) delta-latitude = dy/110540 = 353.55/110540 = .003198 deg (approx 11.51 arcsec) Final longitude = start_longitude + delta_longitude = -87.62788 - .004266 = -87.632146 Final latitude = start_latitude + delta_latitude = 41.88592 + .003198 = 41.889118 


Positional Astronomy:
Spherical trigonometry

A great-circle arc, on the sphere, is the analogue of a straight line, on the plane.

Where two such arcs intersect, we can define the spherical angle
either as angle between the tangents to the two arcs, at the point of intersection,
or as the angle between the planes of the two great circles where they intersect at the centre of the sphere.
(Spherical angle is only defined where arcs of great circles meet.)

A spherical triangle is made up of three arcs of great circles, all less than 180°.
The sum of the angles is not fixed, but will always be greater than 180°.
If any side of the triangle is exactly 90°, the triangle is called quadrantal.

There are many formulae relating the sides and angles of a spherical triangle.
In this course we use only two: the sine rule and the cosine rule.

diagramConsider a triangle ABC on the surface of a sphere with radius = 1.

(See note)

We use the capital letters A, B, C to denote the angles at these corners;
we use the lower-case letters a, b, c to denote the opposite sides.
(Remember that, in spherical geometry, the side of a triangle is the arc of a great circle,
so it is also an angle.)

Turn the sphere so that A is at the “north pole”,
and let arc AB define the “prime meridian”.

Set up a system of rectangular axes OXYZ:
O is at the centre of the sphere;
OZ passes through A;
OX passes through arc AB (or the extension of it);
OY is perpendicular to both.
Find the coordinates of C in this system:
x = sin(b) cos(A)
y = sin(b) sin(A)
z = cos(b)


Now create a new set of axes,
keeping the y-axis fixed and moving the “pole” from A to B
(i.e. rotating the x,y-plane through angle c).
The new coordinates of C are
x’ = sin(a) cos(180-B) = – sin(a) cos(B)
y’ = sin(a) sin(180-B) =    sin(a) sin(B)
z’ = cos(a)

The relation between the old and new systems
is simply a rotation of the x,z-axes through angle c:
x’ = x cos(c) – z sin(c)
y’ = y
z’ = x sin(c) + z cos(c)

That is:
– sin(a) cos(B) = sin(b) cos(A) cos(c) – cos(b) sin(c)
sin(a) sin(B)  = sin(b) sin(A)
cos(a) = sin(b) cos(A) sin(c) + cos(b) cos(c)

These three equations give us the formulae for solving spherical triangles.

The first equation is the transposed cosine rule,
which is sometimes useful but need not be memorised.

The second equation gives the sine rule. Rearrange as:
   sin(a)/sin(A) = sin(b)/sin(B)
sin(b)/sin(B) = sin(c)/sin(C), etc.

So the sine rule is usually expressed as:
   sin(a)/sin(A) = sin(b)/sin(B) = sin(c)/sin(C)

The third equation gives the cosine rule:
cos(a) = cos(b) cos(c) + sin(b) sin(c) cos(A)
and similarly:
cos(b) = cos(c) cos(a) + sin(c) sin(a) cos(B)
cos(c) = cos(a) cos(b) + sin(a) sin(b) cos(C)

Here they are together:

sine rule:
   sin(a)/sin(A) = sin(b)/sin(B) = sin(c)/sin(C)

cosine rule:
cos(a) = cos(b) cos(c) + sin(b) sin(c) cos(A)
cos(b) = cos(c) cos(a) + sin(c) sin(a) cos(B)
cos(c) = cos(a) cos(b) + sin(a) sin(b) cos(C)

The cosine rule will solve almost any triangle if it is applied often enough.
The sine rule is simpler to remember but not always applicable.

Note that both formulae can suffer from ambiguity:
E.g. if the sine rule yields
sin(x) = 0.5,
then x may be 30° or 150°.
Or, if the cosine rule yields
cos(x) = 0.5,
then x may be 60° or 300° (-60°).
In this case, there is no ambiguity if x is a side of the triangle, as it must be less than 180°,
but there could still be uncertainty if an angle of the triangle was positive or negative.

So, when applying either formula, check to see if the answer is sensible.
If in doubt, recalculate using the other formula, as a check.


Alderney, in the Channel Islands, has longitude 2°W, latitude 50°N.
Winnipeg, in Canada, has longitude 97°W, latitude 50°N.
How far apart are they, in nautical miles, along a great-circle arc?

If you set off from Alderney on a great-circle route to Winnipeg,
in what direction (towards what azimuth) would you head?

Click here for the answer.



Aviation Formulary V1.46

Posted: August 18, 2011 in Android, Java, Mapping

By Ed Williams


This introduction is written for pilots (and others) who are interested in great circle navigation and would like to know how to compute courses, headings and other quantities of interest. These formulae can be programmed into your calculator or spreadsheet. I’ll attempt to include enough information that those familiar with plane trigonometry can derive additional results if required.

It is a well known that the shortest distance between two points is a straight line. However anyone attempting to fly from Los Angeles to New York on the straight line connecting them would have to dig a very substantial tunnel first. The shortest distance, following the earth’s surface lies vertically above the aforementioned straight line route. This route can be constructed by slicing the earth in half with an imaginary plane through LAX and JFK. This plane cuts the (assumed spherical) earth in a circular arc connecting the two points, called a great circle. Only planes through the center of the earth give rise to great circles. Any plane will cut a sphere in a circle, but the resulting little circles are not the shortest distance between the points they connect. A little thought will show that lines of longitude (meridians) are great circles, but lines of latitude, with the exception of the equator, are not.

I will assume the reader is familiar with latitude and longitude as a means of designating locations on the earth’s surface. For the convenience of North Americans I will take North latitudes and West longitudes as positive and South and East negative. The longitude is the opposite of the usual mathematical convention. True course is defined as usual, as the angle between the course line and the local meridian measured clockwise.

The first important fact to realise is that in general a great circle route has a true course that varies from point to point. For instance the great circle route between two points of equal (non-zero) latitude does not follow the line of latitude in an E-W direction, but arcs towards the pole. It is possible to fly between two points using an unvarying true course, but in general the resulting route differs from the great circle route and is called a rhumb line. Unlike a great circle which encircles the earth in a closed curve, a pilot flying a rhumb line would spiral poleward.

Natural questions are to seek the great circle distance between two specified points and true course at points along the route. The required spherical trigonometric formulae are greatly simplified if angles and distances are measured in the appropriate natural units, which are both radians! A radian, by definition, is the angle subtended by a circular arc of unit length and unit radius. Since the length of a complete circular arc of unit radius is 2*pi, the conversion is 360 degrees equals 2*pi radians, or:


Great circle distance can be likewise be expressed in radians by defining the distance to be the angle subtended by the arc at the center of the earth. Since by definition, one nautical mile subtends one minute (=1/60 degree) of arc, we have:


In all subsequent formulae all distances and angles, such as latitudes, longitudes and true courses will be assumed to be given in radians, greatly simplifying them, and in applications the above formulae and their inverses are necessary to convert back and forth between natural and practical units. Examples of this process are given later.

Note: the nautical mile is currently defined to be 1852 meters – which to be consistent with its historical definition implies the earth’s radius to be 1.852 * (180*60/pi) = 6366.71 km, which indeed lies between the currently accepted ( WGS84) equatorial and polar radii of 6378.137 and 6356.752 km, respectively. Other choices of the earth’s radius in this range are consistent with the spherical approximation and may for some specialized purposes be preferred.

For instance, the former FAI standard for aviation records used the “FAI sphere” with radius 6371.0 km.

To use a different spherical radius, use

      distance_km = radius_km * distance_radians
      distance_radians = distance_km/radius_km

to convert between angular and distance units.

A sample implementation of many of these formulae in the form of an Excel spreadsheet can be found here. The formulae are in VBA macros, for readability, so you will need to enable macros to have them work. If you are unable to open the spreadsheet with macros disabled (to check for viruses) etc, then you may need to patch your Excel. Try for Excel 97 SR-2.

If you decide to program up these formulae, you’d be well-advised to look at the implementation notes and check your results against the worked examples and spreadsheets.

Some great circle formulae:

Distance between points

The great circle distance d between two points with coordinates {lat1,lon1} and {lat2,lon2} is given by:


A mathematically equivalent formula, which is less subject to rounding error for short distances is:

d=2*asin(sqrt((sin((lat1-lat2)/2))^2 +
Lat/lon given radial and distance

A point {lat,lon} is a distance d out on the tc radial from point 1 if:

     IF (cos(lat)=0)
        lon=lon1      // endpoint a pole

This algorithm is limited to distances such that dlon <pi/2, i.e those that extend around less than one quarter of the circumference of the earth in longitude. A completely general, but more complicated algorithm is necessary if greater distances are allowed:

     lat =asin(sin(lat1)*cos(d)+cos(lat1)*sin(d)*cos(tc))
     lon=mod( lon1-dlon +pi,2*pi )-pi

Implementation notes:

Notes on mathematical functions

Note: ^ denotes the exponentiation operator, sqrt is the square root function, acos the arc-cosine (or inverse cosine) function and asin is the arc-sine function. If asin or acos are unavailable they can be implemented using the atan2 function:

  acos returns a value in the range 0 <= acos <= pi
  asin returns a value in the range -pi/2 <= asin <= pi/2

Note: Here atan2 has the conventional (C) ordering of arguments, namely atan2(y,x). This is not universal, Excel for instance uses atan2(x,y), but it has asin and acos anyway. Be warned. It returns a value in the range -pi < atan2 <= pi.

Further note: if your calculator/programming language is so impoverished that only atan is available then use:

   acos(x)=2*atan(sqrt((1-x)/(1+x)))       x>=0
          =pi - 2*atan(sqrt((1+x)/(1-x)))  x<0

   atan2(y,x)=atan(y/x)       x>0
   atan2(y,x)=atan(y/x)+pi    x<0, y>=0
   atan2(y,x)=pi/2            x=0, y>0
   atan2(y,x)=atan(y/x)-pi    x<0, y<0
   atan2(y,x)=-pi/2           x=0, y<0
   atan2(0,0) is undefined and should give an error.

Another potential implementation problem is that the arguments of asin and/or acos may, because of rounding error, exceed one in magnitude. With perfect arithmetic this can’t happen. You may need to use “safe” versions of asin and acos on the lines of:


Note on the mod function. This appears to be implemented differently in different languages, with differing conventions on whether the sign of the result follows the sign of the divisor or the dividend. (We want the sign to follow the divisor or be Euclidean. C’s fmod and Java’s % do not work.) In this document, Mod(y,x) is the remainder on dividing y by x and always lies in the range 0 <=mod <x. For instance: mod(2.3,2.)=0.3 and mod(-2.3,2.)=1.7

If you have a floor function (int in Excel), that returns floor(x)= “largest integer less than or equal to x” e.g. floor(-2.3)=-3 and floor(2.3) =2

        mod(y,x) = y - x*floor(y/x)

The following should work in the absence of a floor function- regardless of whether "int" truncates or rounds downward:

    mod=y - x * int(y/x)
    if ( mod < 0) mod = mod + x
Sign Convention

As stated in the introduction, North latitudes and West longitudes are treated as positive, and South latitudes and East longitudes negative. It’s easier to go with the flow, but if you prefer another convention you can change the signs in the formulae.


Building the Android kernel

Velibor Cakarevic

Downloading Android kernel code

If you download Android 2.1 platform you will not get the source code of the kernel. This is due to that there is quite a huge amount of code needed to be downloaded, it takes time to build the kernel and not many application developers are interested in the kernel code. Below is a description of how to download the Android source code and compile it for ARM, using Linux as your OS. Note that porting to hardware is not in the scope of this description.

First go to your home directory and create a directory where you wish to work in, e.g. myAndroid and step into that directory. Note that ‘$’ is not part of a command but illustrates in this document the commands.
$ cd ~
$ mkdir myAndroid
$ cd myAndroid

To clone the common Android kernel and get the kernel code use the command:

$ git clone git:// android-kernel

The command creates a new folder called ‘android-kernel’ (you can choose another name if you wish) in your ‘myAndroid’ folder and downloads the kernel code.

Go to that folder:

$ cd android-kernel

Building the Android kernel code

Android relies on Linux version 2.6. When building the kernel you will do these commands:
$ make menuconfig
$ make

The command ‘make menuconfig’ configures the kernel. This process involves specifying what functionality to put into the kernel. Additionally, decisions have to be made (when possible) whether kernel code should be statically or dynamically linked. Statically linking means that all modules are built and linked into the kernel. Optimized static kernels execute much faster, since there are no shared object lookups and their binary size is smaller.

With dynamic loading you can choose to manually load the modulus to the kernel by using insmod or modprobe tool/command. Loadable kernel modules allow changing code during runtime. Loadable modules are pieces of kernel code which are not linked (included) directly in the kernel. One compiles them separately, and can insert and remove them into the running kernel at almost any time. If you want a module to be dynamically loaded give it the option <M> during ‘make config’ procedure.

If you want to make an own module you should enable the module support after doing ‘make menuconfig’

Loadable module support —> [*] Enable loadable module support

When building for another processor architecture than the one that your host processor uses you must use a crosscompiler and set the architecture parameter. This will show you how to compile the code for an ARM processor architecture. Before doing ‘make menuconfig’ set the architecture parameter:

$ export ARCH=arm

Now start the configuration of the kernel:

$ make menuconfig

Picture 1 shows the menu when configuring the kernel.

After having modified the configuration you will at the exit be prompted by a question, whether you wish to save the changes. Choose Yes if you want to do so. You can check the generated .config file by:

$ nano .config

To set the crosscompiler use do the command:

$ export CROSS_COMPILE=arm-unknown-linux-gnueabi-

Note! I am using a compiler that you may not have. If you have downloaded the whole Android 2.1 platform (perhaps you have it in another folder) you could use

In that case the command to set the cross-compiler as the one delivered and precompiled in the Android platform is:

$ export CROSS_COMPILE=~/your_android_platform_folder/prebuilt/linux-x86/toolchain/arm-eabi-4.4.0/bin/arm-eabi-

Make starts the build process and builds the kernel according to the configuration file. To start the build process do:

$ make

The image is generated in the folder: arch/arm/boot/zImage

If you wish to search for the zImage use the find command:
$ find -name ‘zImage’

Some tips

When configuring the kernel in the menu (see figure 1) there may be some flags that you cannot remove. However you can still modify the ‘.config’-file directly if you wish to. You should on the other hand be sure of what you are doing. When building again, i.e. make you will be prompted by a question if you wish to keep that flag. Press ‘n‘ to exclude the module. If this question does not appear it is most likely that the module has not been removed.

When working with building of the kernel, the best approach is to remove modules that are not necessary in your kernel, and when adding new modules add them step by step. This will give you a fair chance to fix errors such as build failures, but also track down crashes when running on target.

When you have build errors and keep removing flags (i.e. modules) it is good to remove the object files and make a new build. Removing the objectfiles and rebuilding the kernel is done accordingly:
$ make clean
$ make

Edited 5 times. Last edit by KennyLeopold Amanda on Apr 22, 2011 at 8:46:27 PM (about 15 weeks ago).
March 15, 2011 3:35:08 PM PDT (22 weeks ago)
PhotoJayson Burak

BAE Systems
Member since Mar 15, 2011
Posts: 1
Hi there,

I apologize for asking a stupid question, but I’m curious as to what the next steps are from here, once the new zImage has been created…or in other words, how do I get the zImage loaded on the device? I have found a few different options, but none of them seem to work for me. What I mean by that is that whenever I try to flash new kernel or new boot image (kernel + ramdisk) to my device, it does not load. I don’t get any errors during the build or make process. So, I am either flashing the device wrong or something else that I have no knowledge of. Any help would be appreciated. Thanks.

~ Jay

March 16, 2011 1:25:26 AM PDT (22 weeks ago)
PhotoVelibor Cakarevic

Member since Apr 22, 2010
Location: Malmo
Posts: 2
Hello Jayson,

It is hard to tell what might be causing the device not to display the home screen. If you flash procedure would fail then you should get an error message during that procedure.

The zImage is an compressed code that is unzipped at the boot procedure. You can see the procedure in the command prompt when the device boots up (some boot-loaders print a dotted line to animate the procedure). If it is uncompressed then that should be a good sign, that you have flashed it ‘corrrectly’ (but I am comparing to my own projects). You tell the bootloader (set the environment variables) which memory address the image is stored at. I do not know which bootloader you are using but Uboot is the one I have been using [1].

Further you might not have the correct driver code for the display. Such driver code (Linux driver code) should be delivered to you by the vendor. You could ask them about this issue as well.

Have you enabled/added the display driver module (in the “make menuconfig”)? If it is statically linked (‘*’) it is built in the kernel. If it is dynamically linked (‘M’) then the kernel will load/insert the module in the runtime. You can also insert the modules manually by the ‘insmod’ [2] or ‘modprobe’ [3] command.

One tip is to mount the device’s filesystem on to a laptop (done in the bootloader by setting parameters) i.e. you boot up the device but the device gets the filesystem from a folder on your laptop. From there you can insert modules. This approach (mounting the filesystem) makes is ‘easier’ to work since you (most probably) have more space on your laptop then on your device and do not have to flash the filesystem on your device (saves you time).

Further if you are using Beagleboard, then there are ported versions of Android for their device.[4]

Google has also added some information since I posted this article. Please have a look at the “Android Platform Developer´s Guide” [5]

In order to help you I would have to be sitting next to you.



Download Android source

1. Make sure you have a ~/bin directory in your home directory, and check to be sure that this bin directory is in your path:

     $ cd ~

     $ mkdir bin

     $ echo $PATH

2. Download the repo script and make sure it is executable:

     $ curl >~/bin/repo

     $ chmod a+x ~/bin/repo

3. Download from CoreDruids Android repository –

    $ repo init -u git://

    $ repo sync

    $ make TARGET_PRODUCT=beagleboard

Prepare Root file system

     $ cd out/target/product/beagleboard

     $ mkdir android_rfs

     $ cp -r root/* android_rfs

     $ cp -r system android_rfs

     $ cd android_rfs

     $ chmod -R 777 *

     $ chown root.root *

prepare tar file for android_rfs directory

Prepare uImage

     $ cd <android_root_dir>/kernel

     $ make ARCH=arm omap3_beagle_android_defconfig

     $ export toolchain path

     $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage

For enabling USB EHCI port

1. Follow the steps in the following link to compile u-boot –
2. copy u-boot.bin in FAT partition of SD card

Prepare SD Card

To boot Android from SD card you need to create a dual partition card.

1. Follow the link for creating SD card partitions

2. Untar root file system in ext3 partition of SD card.

3. Copy the uImage to SD card’s FAT partition.

On Beagleboard

Execute the following commands in bootloader console to boot android on BeagleBoard

     $ setenv bootargs console=ttyS2,115200n8 noinitrd root=/dev/mmcblk0p2

 video=omapfb.mode=dvi:1280x720MR-24@50 init=/init rootfstype=ext3 rw rootdelay=1 nohz=off androidboot.console=ttyS2

     $ mmc init

     $ fatload mmc 0 80300000 uImage

     $ bootm 80300000

Known Issues

The kernel gives panic after couple of reboots (We observed that after re-flashing problem gets resolved)

As we know, Java 1.5 has not been maintained anymore and Java 6, has been hanging around for a while and Java 7 is coming soon. But it doesn’t mean everybody has to move on to Java 1.6. The problem in Ubuntu is they force you to use OpenJDK. Worse yet, they don’t let you downgrade to 1.5.There are lots of legacy systems running on Java 5 and we can’t forget that. It is also about freedom of choice. If you want to install Sun JDK 5 or 6 Ubuntu should not make your life difficult.

Ubuntu 10 and 11 don’t allow us to natively (or easily) install Sun JDK’s via apt-get.

It is so frustrate when we try to install it on Ubuntu 10.10 and have no luck:

sudo apt-get install sun-java5-jdk (or sudo apt-get install sun-java6-jdk)

After installed, the JDK will go to this directory: /usr/lib/jvm/java-6-sun

You can see all JDK’s installed running the following command:

sudo update-java-alternatives -l

After a while, finally got the solution for this:

sudo add-apt-repository “deb jaunty multiverse”

sudo add-apt-repository “deb jaunty-updates multiverse”

sudo apt-get update

sudo apt-get install sun-java5-jdk

Check it out just to confirm:

sudo update-java-alternatives -l

The commands above worked for me in Ubuntu 10 and 11, installing Sun JDK 1.5 and 1.6.
If it doesn’t work, try to add the following repositories and repeat the process: (anonymous suggestion – thanks a lot):

sudo add-apt-repository “deb hardy multiverse”
sudo add-apt-repository “deb hardy-updates multiverse”


SQLite in Android

Posted: July 9, 2011 in Android

1.1. SQLite in Android

SQLite is an Open Source Database which is embedded into Android. SQLight supports standard relational database features like SQL syntax, transactions and prepared statements. In addition it requires only little memory at runtime (approx. 250 KByte).

Using SQLite in Android does not require any database setup or administration. You specify the SQL for working with the database and the database is automatically managed for you.

Working with databases in Android can be slow due to the necessary I/O. Therefore is it recommended to perform this task in an AsyncTask . Please see Android Background Processing Tutorial for details.

SQLite supports the data types TEXT (similar to String in Java), INTEGER (similar to long in Java) and REAL (similar to double in Java). All other types must be converted into on of these fields before saving them in the database. SQLight itself does not validate if the types written to the columns are actually of the defined type, you can write an integer into a string column.

If your application creates an database this database is saved in the directory “DATA/data/APP_NAME/databases/FILENAME”. “DATA” is the path which Environment.getDataDirectory() returns, “APP_NAME” is your application name and “FILENAME” is the name you give the database during creation. Environment.getDataDirectory() usually return the SD card as location.

1.2. SQLightOpenHelper

To create and upgrade a database in your Android application you usually subclass “SQLightOpenHelper”. In this class you need to override the methods onCreate() to create the database and onUpgrade to upgrade the database in case of changes in the database schema. Both methods receive an “SQLightDatabase” object.

“SQLightDatabase” provides the execSQL() method which allows to execute SQL.

It also provides the methods getReadableDatabase() and getWriteableDatabase() to get access to the database either in read or write mode. The database is represented by an “SQLightDatabase” object.

For the primary key of the database you should always use the identifier “_id” as some of Android functions rely on this standard.

1.3. SQLightDatabase and Cursor

“SQLightDatabase” provides the methods insert(), update() and delete().

Queries can be created via the method rawQuery() which accepts SQL, query() which provides an interface for specifying dynamic data or SQLightQueryBuilder. SQLightBuilder is similar to the interface of an content provider therefore it is typically used for them. A query returns always a “Cursor”.

A Cursor represents the result of a query. To get the number of elements use the method getCount(). To move between individual data rows, you can use the methods moveToFirst() and moveToNext(). Via the method isAfterLast() you can check if there is still some data.

A Cursor can be directly used via the “SimpleCursorAdapter” in ListViews. Please see the ListView Tutorial for details.




ntroducing the BeagleBoard-xM

The BeagleBoard is a pocket-sized reference board containing a Texas Instruments Open Multimedia Application Platform (OMAP) 3 system-on-a-chip (SoC) processor, which includes an ARM Cortex-A8 core, Texas Instruments C64x+ digital signal processor (DSP), and onboard graphics engine, as well as integrated dual data rate (DDR) random-access memory (RAM). The BeagleBoard is an inexpensive platform for hobbyists, academics, and professionals who are learning Linux and small systems. Figure 1 shows the BeagleBoard-xM.
Figure 1. BeagleBoard-xM
Picture of the BeagleBoard-xM

In a previous developerWorks article, I explored booting Linux on BeagleBoard revision C, which hosts a 600MHz OMAP3530 processor, 256MB RAM, and 256MB NAND flash memory. Revision xM is more robust with a 1GHz OMAP3730 processor and 512MB RAM. It boots from the microSD card with no flash memory and hosts new interfaces, including a DB-9 serial connector, integrated 4-port Universal Serial Bus (USB) hub, and integrated Ethernet port. The BeagleBoard-xM retains many revision C features, including Digital Visual Interface (DVI)-D output, S-video, audio, Joint Test Action Group (JTAG), and a large expansion header.

Back to top

Building your working environment

The following sections show you how to source required components, set up, and test the console.

Sourcing components

The BeagleBoard-xM is packaged with a preformatted 4GB microSD card along with an adapter so you can plug the card into a standard Secure Digital (SD)/MultiMediaCard (MMC) slot, but no cables. You need the following:

Powering the BeagleBoard-xM

Traditionally, the BeagleBoard is powered from either an external 5V power source or a USB On-The-Go (OTG) cable. These cables, however, provide only up to 500mA, barely enough to power the xM. It is highly recommended that you use an external power supply—either a 5V power brick with a 2.1mm barrel (positive center) or a Y cable that plugs into two USB ports on your host.

  • Power supply
    Use a 5V external power supply.
  • Serial cable
    The BeagleBoard-xM provides a female DB9 port and requires a serial cable to connect the console to your host system. Use a straight-through (not null-modem) cable. If your host system has no serial port, use a DB9-to-USB cable.
  • USB keyboard and USB mouse
  • DVI-D capable monitor and a DVI-D to High-Definition Multimedia Interface (HDMI) cable
    Note that the board does not emit Video Graphics Array (VGA) signals through this connector, so a standard DVI-to-VGA converter cable won’t work.
  • 4GB+ microSD cards and a card reader
    You can overwrite the data on the provided card, but it is better to purchase a few cards to use with different distributions. Use a USB card reader if your host has no integrated reader.

Setting up the console

Linux users can use minicom, shown in the examples that follow. Microsoft® Windows® users can use Hyperterminal or PuTTy, and Mac users can use screen, ZTerm, or MacWise.

Connect the serial cable to the BeagleBoard-xM’s DB9 port and your host, and launch minicom in setup mode as root:

sudo minicom -s


Listing 1 shows the minicom configuration menu.
Listing 1. minicom configuration menu

            | Filenames and paths      |
            | File transfer protocols  |
            | Serial port setup        |
            | Modem and dialing        |
            | Screen and keyboard      |
            | Save setup as dfl        |
            | Save setup as..          |
            | Exit                     |
            | Exit from Minicom        |


Select Serial port setup. The resulting sub-menu is shown in Listing 2.
Listing 2. minicom serial port setup menu

    | A -    Serial Device      : /dev/ttyS0                                |
    | B - Lockfile Location     : /var/lock                                 |
    | C -   Callin Program      :                                           |
    | D -  Callout Program      :                                           |
    | E -    Bps/Par/Bits       : 115200 8N1                                |
    | F - Hardware Flow Control : No                                        |
    | G - Software Flow Control : No                                        |
    |                                                                       |
    |    Change which setting?                                              |
            | Screen and keyboard      |
            | Save setup as dfl        |
            | Save setup as..          |
            | Exit                     |
            | Exit from Minicom        |


If your cable is a straight-through serial cable, the serial device is /dev/ttyS0. If you use a USB converter, use /dev/ttyUSB0. If no text appears in the next step, it is possible your host assigned a different device, so increment 0 to 1 and try again. For all devices, the settings are 115200, 8 bits, no parity, 1 stop bit, and no hardware or software flow control.

When your settings are correct, save this setup as the default by choosing Save setup as dfl and then Exit. The minicom welcome message appears, as shown in Listing 3.
Listing 3. minicom welcome message

Welcome to minicom 2.3

Compiled on Oct 24 2008, 06:37:44.
Port /dev/ttyS0

       Press CTRL-A Z for help on special keys


To verify, apply power to your BeagleBoard-xM, and type a key to stop the boot countdown. Boot-loader messages appear showing the X-loader and U-boot version, date of build, and output, with U-boot showing specifics about system memory, input and output channels, expansion board information, and the board’s revision and die ID, as shown in Listing 4.
Listing 4. X-Loader and U-Boot

Texas Instruments X-Loader 1.4.4ss (Aug 19 2010 - 02:49:27)
Beagle xM Rev A
Reading boot sector
Loading u-boot.bin from mmc

U-Boot 2010.03-dirty (Aug 20 2010 - 20:50:46)

OMAP3630/3730-GP ES1.0, CPU-OPP2, L3-165MHz,
OMAP3 Beagle board + LPDDR/NAND
I2C:   ready
DRAM:  512 MB
NAND:  256 MiB
In:    serial
Out:   serial
Err:   serial

Probing for expansion boards, if none are connected you'll see a harmless I2C error.

No EEPROM on expansion board
Beagle xM Rev A
Die ID #77f600001bf00000015739ea0701c021
Hit any key to stop autoboot:  0


Unplug power from your BeagleBoard-xM.

Preparing to boot Linux

Monitor cable

Make sure to never plug the monitor cable in while the board is powered, because that could damage the board. Always unplug the power first.

Plug your keyboard and mouse into the USB sockets on the BeagleBoard-xM. Plug a network cable, if available, into the Ethernet jack. Connect the HDMI-to-DVI cable between the board and a DVI-D monitor.

The following instructions are intended only to get your board up and running with these three Linux distributions. The links in Resources contain development kits, toolchains, and instructions for setting up full development environments.

Back to top

Booting Angstrom Linux

Angstrom Linux is an operating system developed specifically for small computers such as the BeagleBoard-xM. The fastest way to boot Angstrom on the BeagleBoard-xM is with the microSD card that comes with the board, which contains an Angstrom image. However, the image on that card is a verification image, which means that it is provided only to verify the board’s operation. It does not contain a graphical user interface (GUI) and boots by default as a RAM disk; thus any changes you make are lost when you unplug.

The included microSD card contains a single File Allocation Table (FAT) partition of approximately 117MB, containing the following:

  • Boot loaders X-loader (MLO) and U-boot (u-boot.bin)
  • Linux kernel (uImage)
  • Boot script (user.scr)
  • RAM disk root file system (ramdisk.gz)
  • md5sum file to check file sizes

The rest of the card is unformatted.

To boot, insert the microSD card and apply power. After the boot countdown, the system automatically invokes the boot script. The boot-loader text is shown again on the console, followed by boot messages showing the boot processes, including execution of the script itself, loading the kernel and RAM disk, and finally starting the kernel, as shown in Listing 5.
Listing 5. Booting Angstrom

mmc1 is available
The user button is currently NOT pressed.
reading boot.scr

** Unable to read "boot.scr" from mmc 1:1 **
reading user.scr

755 bytes read
Running bootscript from mmc ...
## Executing script at 80200000
mmc1 is available
reading ramdisk.gz

19960110 bytes read
reading uImage

3190568 bytes read
Booting from ramdisk ...
## Booting kernel from Legacy Image at 80200000 ...
   Image Name:   Angstrom/2.6.32/beagleboard
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    3190504 Bytes =  3 MB
   Load Address: 80008000
   Entry Point:  80008000
   Verifying Checksum ... OK
   Loading Kernel Image ... OK

Starting kernel ...

Uncompressing Linux.....................................................................
[    0.000000] Linux version 2.6.32 (ubuntu@ip-10-204-115-71) (gcc version 4.3.3 .......


Linux boot messages follow, and then finally the Angstrom logo and a login prompt, as shown in Listing 6.
Listing 6. Angstrom login console

|       |                  .-.                     
|   |   |-----.-----.-----.| |   .----..-----.-----.
|       |     | __  |  ---'| '--.|  .-'|     |     |
|   |   |  |  |     |---  ||  --'|  |  |  '  | | | |
'---'---'--'--'--.  |-----''----''--'  '-----'-'-'-'
                -'  |

The Angstrom Distribution beagleboard ttyS2

Angstrom 2010.7-test-20100820 beagleboard ttyS2

beagleboard login:


Log in as root, no password necessary. You can run basic Linux commands to test the system. Try running testled, and watch the light-emitting diodes (LEDs) on the BeagleBoard-xM.

To see Angstrom in action, you need a full root file system and a matching kernel. The following instructions show how to download and boot the demo image:

  1. Navigate to the Angstrom BeagleBoard demo page and read the instructions.
  2. Download the binary images for the boot loader and root file system from the Angstrom BeagleBoard demo page. There files you need are:
    • mkcard.txt
    • MLO
    • u-boot.bin
    • Angstrom-Beagleboard-demo-image-glibc-ipk-2010.3-beagleboard.rootfs.tar.bz2
  3. Insert a microSD card with at least 4GB capacity, and determine its device name. For example, if you are using a USB card reader, use fdisk and look for a disk matching the card’s characteristics. The following example shows /dev/sdg:
    # fdisk -l
    Disk /dev/sdg: 3.9 GB, xxx bytes
    255 heads, 63 sectors/track, xxx cylinders
  4. Unmount any partitions on the card. Use your card’s device name in place of /dev/sdgin the following example:
    sudo umount /dev/sdg?
  5. Format your SD card using the mkcard.txtscript.Note: Be certain that you are targeting your SD card and not a system disk.

    Use your card’s device name in place of /dev/sdg in the following example:

    chmod +x mkcard.txt ; sudo ./mkcard.txt /dev/sdg

    When the operation is done, your microSD card contains two primary partitions:

    • One 70MB FAT partition labeled boot.
    • One ext3 partition labeled Angstrom that takes up the rest of the card’s capacity.

    If your system does not automatically mount these partitions after the script creates them, mount them by hand, replacing your card’s device name for /dev/sdg in the following example:

    sudo mkdir -p /media/boot ; sudo mount /dev/sdg1 /media/boot
    sudo mkdir /media/Angstrom ; sudo mount /dev/sdg2 /media/Angstrom

    The rest of this example assumes these partitions are mounted as /media/boot and /media/Angstrom.

  6. Unpack files to the root file system partition (this command may take some time):
    sudo tar -C /media/Angstrom -xjvf \
  7. Copy files to the boot partition, noting that the kernel image comes directly from the root file system:
    cp MLO /media/boot
    cp u-boot.bin /media/boot
    cp /media/Angstrom/boot/uImage /media/boot
  8. When all operations are done, synchronize file systems and unmount partitions:
    sync ; sudo umount /dev/sdg?
  9. Insert the card into the BeagleBoard-xM and apply power.Note: If the first boot fails with an error like this:
     Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block...

    Restart the system, stop the boot countdown, and type the following command:

    setenv mmcroot /dev/mmcblk0p2 rw

    Then boot the system by typing boot.

The first boot takes a while as the system configures itself. The Angstrom logo appears on the monitor, while on the console each component is configured. After about 10 minutes, an Angstrom login screen appears on the monitor and a boot prompt on the console. Use the login screen to set up a new user and log in. You can also log in on the console as root, no password required.

Back to top

Booting Android

Android has proven to be a popular operating system for the BeagleBoard, as the board is an inexpensive platform for Android application development and testing. There are several ports of Android to the BeagleBoard. This article uses the rowboat project. Be sure to connect a USB keyboard and mouse as well as a DVI monitor before starting.

  1. Download the precompiled binary tarball from the Texas Instruments Android DevKit page, making sure to identify the pre-built image for the BeagleBoard-xM (beagleboard-xm.tar.gz).
  2. Unpack the tarball:
    tar zxvf beagleboard-xm.tar.gz
  3. Read the instructions in README.txt.
  4. Insert a microSD card with at least 4GB capacity, and determine its device name. For example, if you are using a USB card reader, use fdisk and look for a disk matching the card’s characteristics. The following example shows /dev/sdg:
    # fdisk -l
    Disk /dev/sdg: 3.9 GB, xxx bytes
    255 heads, 63 sectors/track, xxx cylinders
  5. Format your SD card using the provided script.Note: Be certain that you are targeting your SD card and not a system disk.

    Use your card’s device in place of /dev/sdg in the following example: /dev/sdg

    When all operation is done, synchronize file systems and unmount partitions:

    sync ; sudo umount /dev/sdg?
  6. Insert the microSD card into the BeagleBoard-xM and apply power.The first boot takes a while as the system configures itself. After about four minutes, you should see the Android logo and then a home screen. If the network does not activate automatically, wait another five minutes and reboot. Note that the console remains active and automatically logs in as root.

Back to top

Booting Ubuntu

Ubuntu is fast becoming a popular distribution for netbooks, mobile Internet devices (MIDs), and other small systems. Canonical, Ubuntu’s parent company, has dedicated resources to porting Ubuntu to ARM processors such as the BeagleBoard. As with Android, make sure to plug in a monitor and USB keyboard and mouse before starting.

  1. Read the instructions on the Ubuntu OMAP Maverick Install page.
  2. Download the precompiled binary image. Make sure to identify the image for the BeagleBoard-xM: Preinstalled netbook image for TI OMAP3 computers (ubuntu-netbook-10.10-preinstalled-netbook-armel+omap.img.gz). Do not uncompress the image at this time.
  3. Insert a microSD card with at least 4GB capacity, and determine its device name. For example, if you are using a USB card reader, use fdisk and look for a disk matching the card’s characteristics. The following example shows /dev/sdg:
    # fdisk -l
    Disk /dev/sdg: 3.9 GB, xxx bytes
    255 heads, 63 sectors/track, xxx cylinders
  4. Write the image directly to the card.Note: Be certain that you are targeting your SD card and not a system disk.

    Use your card’s device in place of /dev/sdg in the following example:

    sudo sh -c 'zcat \
     ./ubuntu-netbook-10.10-preinstalled-netbook-armel+omap.img.gz > /dev/sdg'

    Note: If your BeagleBoard-xM is revision A3, you may need to download a different kernel. See the Ubuntu Maverick install page for details.

    When all operations are done, synchronize file systems and unmount partitions:

    sync ; sudo umount /dev/sdg?
  5. Insert the card into the BeagleBoard-xM and apply power.The first boot takes a while as the system configures itself, during which the monitor and console may stay dark. After about 5 minutes, the Ubuntu logo appears on the monitor, followed by a series of system configuration screens. Answer the configuration questions using the keyboard and mouse plugged into the BeagleBoard. If the network does not activate automatically, wait until the system is completely operational, shut it down (go to System and choose Shut Down), and then reboot.

The console does not remain active for Ubuntu. You must interact with the system through the monitor and keyboard or mouse. However, you can install a Virtual Network Computing (VNC) server from the Ubuntu Software Center and interact with the system through VNC.

Back to top

Where to go from here

Each of these operating systems has its own community ecosystem, including web sites, wikis, mailing lists, and Internet Relay Chat (IRC) channels, as does the BeagleBoard itself. Take advantage of these excellent resources while you learn about the BeagleBoard-xM and your chosen operating system.




Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.