Enea Android Blog

Creating a custom view, part 1 - Graphics

2011-10-19T14:54:00.001+02:00

It's not often I write about user interface and applications, but since I have now received a few question on the subject, I thought I would describe one rather common task - how to create a custom view.

An activity containing a horizontal and vertical slider.

You will make your own customised slider, with the following features:

Scale and stretch it depending on screen size, UI design and orientation.
Change position from the activity.
React to touches.
Set min and max values from xml or application code.

There are many other features that could be added, but I will only add them if requested enough times in the comments.

The howto is divided into a few distinct steps, each describing a feature of the customised view.
Depending on the purpose of your own custom view, not all of the steps may be needed. Furthermore I have divided the howto into three parts, to make it a bit less overwhelming:

Part I - Graphics - Draw the slider on the screen.
Part II - Interaction - Change the position of the indicator, from source code or by touching it.
Part III - Xml Attributes - Configure the layout of the slider from Xml.

The source code can be downloaded from github, and all steps are tagged in the git database. Each step will be preceded with the git command you need in order to look at the code step by step. If you prefer, you can just look at the latest commit in git, since that includes the complete example.

Step 0. Download the source.

This is really optional, but it's probably a good idea to have the code nearby so you can compare my code with yours.
All these git commands are written for Linux command line. It should be very easy to from MS Windows or Mac OS as well, but unfortunately I have no experience in using git on any of those so you will have to find out yourself.

Create a working directory and cd to it. I have called mine "enea":

mkdir enea
cd enea

Use git clone to get the project, and cd to it:

git clone git://github.com/androidenea/CustomView.git
cd CustomView

You may now import the CustomView project to Eclipse.

All further steps in this howto have been clearly tagged for easy access. Each step starts with one line showing the git command needed to get to the correct place.

Please note that checking out a tag in git will get you to the correct version of the source code, but you are not allowed to commit any changes (unless you know what you are doing.)
If you want to modify your code and store that in git, you will need to create your own branch first. This is not the time and place for a tutorial about git, but I highly recommend the book "Pro Git" if you want to know more.

Step 1. Create a project

git checkout step_1

The first step will just give you a playground and a test harness in the shape of an activity.
Grab the code from the git repository for an easy starting point, or do it yourself in Eclipse:
Open Eclipse and create an Android project and fill in the following parametres:

Project name: CustomView
Build target: 1.6 or newer
Application name: CustomView
Package name: com.enea.training.customview
Create Activity: CustomViewActivity
Min SDK version: 4

Click finish to create your project. If you don't really understand what all those things actually mean, you will have a hard time understanding the other steps, as this tutorial is rather advanced. Read through a few other beginner's tutorials first and then you are most welcome back here.

To get a good base layout for the tests, and to get an idea of what this whole tutorial is about, you should replace the LinearLayout in main.xml with a RelativeLayout containing a SeekBar. The contents of main.xml should look like this:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
    <SeekBar android:id="@+id/slider"
      android:layout_height="wrap_content"
      android:layout_width="fill_parent"
      android:layout_alignParentLeft="true"
      android:layout_alignParentTop="true"
/>
</RelativeLayout>

That's it for step 1. That wasn't too bad was it?

Step 1. Standard SeekBar.

Step 2. Add a custom view.

This is by far the biggest step in this howto. We will add bitmaps and source code and we will also replace the SeekBar in step 1 with the custom view. We will do this in small steps to keep things apart.

Step 2.1 Bitmaps

git checkout step_2_1

There are three bitmaps that will be needed. I suggest you grab the ones from the git repository, even if you are implementing the rest without looking at my sample. The reason is that designing stretchable bitmaps is not within the scope of this tutorial. There are very good guidelines on how to design stretchable, or NinePatch, bitmaps on the Android SDK web page, here: Draw 9-patch

Copy the whole of directory res/drawable to your project. I have not spent much time on the graphics, other than making sure to use the nice Enea-red colour, but the bitmaps do scale well and will not look too shabby on anything from my small 2.6" QVGA phone to my nice 10.1" WXGA tablet.

Step 2.2 Slider class

git checkout step_2_2

Ok, so let's try to make use of those bitmaps, shall we?
Create a new class in the same package as earlier, and let it extend android.widget.View. In Eclipse, right-click on the package and select New->Class.
Fill in the blanks as follows:

Name: CustomSlider
Superclass: android.view.View
Generate constructors from superclass

Everything else should be left as default. Click Finish to create the class.

The two simpler constructors can just call to the most flexible one, with 0 or null as parameters, like so (the line numbers should roughly match the source code in git, assuming that you have checked out the corresponding step):

public CustomSlider(final Context context) {
  this(context, null, 0);
}

public CustomSlider(final Context context, final AttributeSet attrs) {
  this(context, attrs, 0);
}

The last constructor will need to do a few things though. It will be extended as we go along, but for now all that is needed is to point out the bitmaps to be used. For that you will also need to add references to the bitmaps.
Add the following members to your class:

private final Drawable mIndicator;
private final Drawable mBackground;

To initialise them, you will need a handle to the resources, and then set them, using the resource reference id.
Your third constructor should look like this:

public CustomSlider(Context context, AttributeSet attrs, int defStyle) {
  super(context, attrs, defStyle);

  final Resources res = context.getResources();
  mIndicator = res.getDrawable(R.drawable.indicator_horizontal);
  mBackground = res.getDrawable(R.drawable.background_horizontal);
}

Let Eclipse add any missing imports that might be needed.

Step 2.3 onDraw

git checkout step_2_3

All the drawing is happening in onDraw(). This method is potentially called quite often, so make a good habit out of making it as fast as possible. In particular, avoid allocating and freeing memory in it.
In this example, onDraw() will calculate the position for the indicator and draw the background, followed by the indicator, positioned relative to the background's end points.
For this to work there are a few member fields needed. First of all the normalised position of the indicator:

private float mMin;
  private float mMax;
  private float mPosition;

These need to be initialised in the constructor. For now just assume that the slider goes from -1.0 to 1.0 and that the indicator is positioned in the middle.
Add the following lines to the bottom of the constructor:

mMin = -1.0f;
    mMax = 1.0f;
    mPosition = (mMax - mMin) / 2 + mMin;

Then a few member fields are needed to help out with the drawing. We need somewhere to store the view's absolute drawing area:

private Rect mViewRect;

The offset, min and max absolute positions for the indicator are also stored, so we don't need to recalculate them every time.

private int mIndicatorOffset;
  private int mIndicatorMaxPos;
  private int mIndicatorMinPos;

And finally there's the actual onDraw method:

@Override
  protected void onDraw(final Canvas canvas) {

First, check if the absolute drawing area is null, and if it is, fill in all the absolute values:

if (mViewRect == null) {
      mViewRect = new Rect();
      getDrawingRect(mViewRect);
      mIndicatorOffset = mIndicator.getIntrinsicWidth();
      mIndicatorMaxPos = mViewRect.right - mIndicatorOffset;
      mIndicatorMinPos = mViewRect.left + mIndicatorOffset;
      mBackground.setBounds(mViewRect.left, mViewRect.top, mViewRect.right,
          mViewRect.bottom);
    }

Now it's time to calculate the position of the indicator bar, based on min and max values, offset, etc. Get some local variables to hold the position and edges of the indicator, and calculate the position:

final float pos;
    final int left;
    final int right;
    final int top;
    final int bottom;

    pos = mIndicatorMinPos
        + ((mIndicatorMaxPos - mIndicatorMinPos) / (mMax - mMin))
        * (mPosition - mMin);

When setting the drawing bounds for the indicator, there are some calculations to be made, since pos above is the centerpoint of the indicator, and not one of the edges:

left = (int) pos - (mIndicator.getIntrinsicWidth() / 2);
    top = mViewRect.centerY() - (mIndicator.getIntrinsicHeight() / 2);
    right = left + mIndicator.getIntrinsicWidth();
    bottom = top + mIndicator.getIntrinsicHeight();
    mIndicator.setBounds(left, top, right, bottom);

And finally, it's time to draw (don't forget the closing bracket):

mBackground.draw(canvas);
    mIndicator.draw(canvas);
  }

As you have perhaps already figured out, the system will know where to draw the bitmaps through the call to setBounds() for each bitmap. The rest where just there to calculate the bounds.

Step 2.4 onMeasure

git checkout step_2_4

One more thing needs to be added to the CustomView class, before we can start using it in step 2.5. The layout engine still don't know how large our view is. To find out, it will need to measure the view. Whenever that happens, there will be a call to onMeasure().
The implementation of onMeasure() is far simpler than onDraw(). All that is needed is to specify the width and the height of the view.

First of all there needs to be a call to the super.onMeasure(). This will set the width and height to maximum possible values, based on your layout parameters, such as fill_parent (or match_parent) and wrap_contents, margins, etc.:

@Override
  protected void onMeasure(final int widthMeasureSpec,
     final int heightMeasureSpec) {
    super.onMeasure(widthMeasureSpec, heightMeasureSpec);

For horizontal rendering of the slider view, the width should be the maximum possible, but the height should be limited to the height of the indicator (if you use the bitmaps from my sample project.):

setMeasuredDimension(getMeasuredWidth(), mIndicator.getIntrinsicHeight());
  }

As usual, don't forget the closing bracket. (If you are wondering where the code for vertical rendering is, you will have to be patient, as it won't be added until step 5.)

Phew, that's it with the implementation for now. It will still not show up on screen, though. That is because it hasn't been added to the main.xml layout file. So let's do that.

Step 2.5 Use the view.

git checkout step_2_5

The final thing to do in order to see the work we have just done is to replace the SeekBar with the CustomSlider. There is only one thing to change to do that - In the xml file, replace SeekBar with com.enea.training.customview.CustomSlider. Note that the package name must be included, or the view will not be found by the layout engine. Here is what that edited line should look like:

<com.enea.training.customview.CustomSlider android:id="@+id/slider"

If you run your project now, you should see the new shiny slider stretched horizontally across the top of the screen. Tilt your Android device between landscape and portrait and you will see that the bitmaps are nicely stretched. You may also want to change the constructor to initialise mPosition to different values and see that the indiator is placed correctly. Usually the end points are the trickiest ones to get right, so try setting mPosition to mMin and mMax respectively and try the view in both portrait and landscape to make sure it looks good.

SeekBar replaced with CustomSlider

Custom

There are a few situations when this would be all you want to do with a view, but most likely you want to be able to change the slider indicator from your activity and also interact with it by touching it. Or maybe you want a vertical slider instead?

Finally, if you want simple ways of reusing it, you probably want to be able to set things like min and max directly in the xml file.

So let's do all that. Get some fresh coffee and head over to the second part of this tutorial.

Please use the comments field if you have any questions.

/Robert

Creating a custom view, part 3 - Xml Attributes

2011-10-19T14:49:00.001+02:00

This is the final part in the series of articles describing how to create a custom view.
For the other parts, follow these links:

Part I - Graphics
Part II - Interaction
Part III - Xml Attributes

In this part, you will see how to make your slider vertical, and how to set attributes from within xml, just the way you do with all the built-in views.

Step 5 Vertical slider

Making the slider vertical is slightly more challenging than step 4. The view must be aware of its orientation, and all position calculations must detect orientation. The complexity of this step means that we are back to doing sub-steps.

Step 5.1 A Vertical member.

git checkout step_5_1

The orientation of the slider can only be vertical or horizontal (I leave it to you as an exercise to implement a diagonal slider), so storing orientation can be done in a boolean:

private boolean mIsVertical;

mIsVertical will need to be initialised in the constructor. It's just going to be hard-coded to true here, until things improve in step 6.
Near the top of the constructor, just after the call to super, this line should be added:

mIsVertical = true;

Obviously, the slider will not become vertical just because of this, that's why there are a few more steps.

Step 5.2 Pick your bitmaps.

git checkout step_5_2

Now that there is a boolean to check for orientation, it's time to act upon it. The first thing to do is to select the correct bitmaps. In the constructor, add an if statement that will initalise the mIndicator and mBackground drawables accordingly:

if (mIsVertical) {
      mIndicator = res.getDrawable(R.drawable.indicator_vertical);
      mBackground = res.getDrawable(R.drawable.background_vertical);
    } else {
      mIndicator = res.getDrawable(R.drawable.indicator_horizontal);
      mBackground = res.getDrawable(R.drawable.background_horizontal);
    }

Step 5.3 onTouchListener revisited.

git checkout step_5_3

The calculations in the touch listener should also be updated. This is where it becomes a bit tricky. For horizontal orientation the mMin corresponds to mIndicatorMinPos, that is pixels and values are growing in the same direction. Whereas for vertical orientation mMin corresponds to mIndicatorMaxPos, that is pixels and values grow in opposite directions.
In the touch listener that is located in the constructor, surround the calculations with the following if-statement:

if (mIsVertical) {
          pos = (mMax - ((mMax - mMin) / (mIndicatorMinPos - mIndicatorMaxPos))
              * event.getY());
        } else {
          pos = (mMin + ((mMax - mMin) / (mIndicatorMaxPos - mIndicatorMinPos))
              * event.getX());
        }

Note how the calculation of pos differs.

Step 5.4 Improve the drawings.

git checkout step_5_4

The onDraw() and onMeasure() will also need to be dependent on the orientation. Let's do onDraw() first.
The first part of onDraw() initialises indicator min, max and offset values, in relation to the view's drawing rectangle. Surround the initialisation with the following if statement:

if (mIsVertical) {
        mIndicatorOffset = mIndicator.getIntrinsicHeight();
        mIndicatorMaxPos = mViewRect.top + mIndicatorOffset;
        mIndicatorMinPos = mViewRect.bottom - mIndicatorOffset;
      } else {
        mIndicatorOffset = mIndicator.getIntrinsicWidth();
        mIndicatorMaxPos = mViewRect.right - mIndicatorOffset;
        mIndicatorMinPos = mViewRect.left + mIndicatorOffset;
      }

Note how max and min relates to the mViewRect coordinates.

The second part of onDraw() calculates the real position of the indicator, based on the values above. Only pos and top left corner will need to modified for the indicator, since the other corners are relative to this one. Surround the calculations with the following:

if (mIsVertical) {
      pos = mIndicatorMaxPos
          + ((mIndicatorMinPos - mIndicatorMaxPos) / (mMax - mMin))
          * (mMax - mPosition);
      left = mViewRect.centerX() - (mIndicator.getIntrinsicWidth() / 2);
      top = (int) pos - (mIndicator.getIntrinsicHeight() / 2);
    } else {
      pos = mIndicatorMinPos
          + ((mIndicatorMaxPos - mIndicatorMinPos) / (mMax - mMin))
          * (mPosition - mMin);
      left = (int) pos - (mIndicator.getIntrinsicWidth() / 2);
      top = mViewRect.centerY() - (mIndicator.getIntrinsicHeight() / 2);
    }

Finally, onMeasure() will need to be modified. This is much simpler, since no calculations are needed. Surround the setter with the following:

if (mIsVertical) {
      setMeasuredDimension(mIndicator.getIntrinsicWidth(), getMeasuredHeight());
    } else {
      setMeasuredDimension(getMeasuredWidth(), mIndicator.getIntrinsicHeight());
    }

Done. You are now finished with step 5. Run your project and make sure the slider works as expected. Change the initialisation of mIsVertical in the constructor to make sure that you haven't broken the horizontal layout.
Note that when rendering the slider vertically, it pushes the reset button off the screen. Correcting it would require a modification of your activity's layout, which will be done next.

Step 6 Add key-value attributes in xml.

Almost there, the only thing left in this tutorial is to add some attributes that can be set from within the xml layout. Let's start with specifying the attributes.
I'm not going to go too far, but at least it makes sense to be able to set orientation, min and max from the xml. Once you've seen how to do this, adding other attributes should be easy.

Step 6.1 xml modifications.

git checkout step_6_1

Right-click on your project and select New->Android xml file.
Specify the file name "attrs.xml" and select the Values radio button. Click Finish to generate the file.
Open up the xml view of attrs.xml. This is where the attributes should go.
The node to use is called declare-stylable, and is used to identify a group of attributes. The sub-nodes are all of type attr and contains name and type of the attribute. Min and max are floats, whereas orientation is vertical or horizontal.
Your attrs.xml file should look like this:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <declare-styleable name="CustomSlider">
    <attr name="orientation">
      <enum name="horizontal" value="0" />
      <enum name="vertical" value="1" />
    </attr>
    <attr name="max" format="float"/>
    <attr name="min" format="float"/>
  </declare-styleable>
</resources>

This provides three key-value pairs that can be set for the slider. It's worth noting that there are other ways of specifying attributes. For example, if you want to re-use the enum for orientation, you may declare it outside of the
tag and just refer to it. Just ask, and I will in the comments describe how to do that.

Step 6.2 Modified constructor.

git checkout step_6_2

There is one more thing to do to get this to work - modify the constructor to make use of the new attributes.
This is really quite easy. One of the input parameters to the constructor is an AttributeSet, containing all the attributes for your view.

From that, you need to extract the attributes you are interested in.

At the top of your constructor, right after the call to super(), you should add the following lines to get a TypedArray with the attributes:

final TypedArray a = context.obtainStyledAttributes(attrs,
        R.styleable.CustomSlider);

Now, instead of just hard-coding mIsVertical to true or false, you should grab the orientation from your attributes. But since the orientation attribute
translates horizontal/vertical to an integer, based on the enum, you will need your java code to turn it into true or false. This code should replace the "mIsVertical=true" statement:

final int vertical = a.getInt(R.styleable.CustomSlider_orientation, 0);
    mIsVertical = (vertical != 0);

Look at the help for getInt() and make sure that you understand what the parameters mean.

The min and max values are done in a similar way, but they are already floats, so no extra treatment is necessary. Replace the mMin and mMax initialisation statements with the following:

final int max = a.getInt(R.>final float max = a.getFloat(R.styleable.CustomSlider_max, 1.0f);
    final float min = a.getFloat(R.styleable.CustomSlider_min, -1.0f);
    setMinMax(min, max);

Ok, done with the slider. Let's put that latest piece of code to some use.

Step 6.3 Attributes in layout

git checkout step_6_3

Once the new attributes are declared, you can refer to them from your main.xml layout file.
You will need to add the namespace to the layout and then obviously set the attributes for the CustomSlider.

The namespace is an attribute for the RelativeLayout, so the first few lines in main.xml should now look like this:

Once that is added, it's just a matter of setting the attributes for the slider views. The updated slider tag should look like this:

<com.enea.training.customview.CustomSlider android:id="@+id/slider_horizontal"
      CustomView:orientation="horizontal"
      CustomView:min="0.0"
      CustomView:max="100.0"
      android:layout_height="wrap_content"
      android:layout_width="fill_parent"
      android:layout_alignParentLeft="true"
      android:layout_alignParentTop="true"
    />

To make things a bit more interesting, you could add another slider, and make it vertical:

<com.enea.training.customview.CustomSlider android:id="@+id/slider_vertical"
      CustomView:orientation="vertical"
      CustomView:min="-50.0"
      CustomView:max="50.0"
      android:layout_height="fill_parent"
      android:layout_width="wrap_content"
      android:layout_alignParentLeft="true"
      android:layout_below="@+id/slider_horizontal"
      android:layout_alignParentBottom="true"
    />

As you can see, the new attributes are being set exactly the same way as the standard attributes, the only difference is the namespace.

That new slider needs some code in the activity as well. You will need a new member field and a new position listener, and displayValues() will need to display the vertical value.
Furthermore, since the horizontal slider now gets the initial values from xml, there is no need to call the setters in onCreate().
The onReset() callback method for the button will also need to be updated to reset both sliders.
Here is the complete listing of the activity. As you can see, it's just a matter of duplicating the code of the horizontal slider for the vertical.

public class CustomViewActivity extends Activity {
  private TextView     mValues;
  private CustomSlider mSliderHorizontal;
  private CustomSlider mSliderVertical;

  @Override
  public void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    mValues = (TextView) findViewById(R.id.values);

    mSliderHorizontal = (CustomSlider) findViewById(R.id.slider_horizontal);
    mSliderHorizontal.setPositionListener(new CustomSliderPositionListener() {
      public void onPositionChange(final float newPosition) {
        displayValues();
      }
    });
    mSliderVertical = (CustomSlider) findViewById(R.id.slider_vertical);
    mSliderVertical.setPositionListener(new CustomSliderPositionListener() {
      public void onPositionChange(final float newPosition) {
        displayValues();
      }
    });

    displayValues();
  }

  void displayValues() {
    final String str = String.format("Horizontal: %3.2f\nVertical: %3.2f",
        mSliderHorizontal.getPosition(), mSliderVertical.getPosition());
    mValues.setText(str);
  }

  public void onReset(final View v) {
    float min = mSliderHorizontal.getMin();
    float max = mSliderHorizontal.getMax();
    float newPos = (max - min) / 2 + min;
    mSliderHorizontal.setPosition(newPos);

    min = mSliderVertical.getMin();
    max = mSliderVertical.getMax();
    newPos = (max - min) / 2 + min;
    mSliderVertical.setPosition(newPos);
  }
}

That's it! Try your application again, perhaps a few times while changing the attributes in main.xml.

Where to go from here

Even though this series of articles is a long read, the actual steps are not that difficult.

The view just implemented is far from complete, but I do believe it's a good starting point. Things you may want to add are:

Make the view retain values between orientation changes.
Different colour of the indicator when touched, like the standard views.
React to long clicks or double clicks.
Displaying the value within the view instead of a separate view.
Animations, 3D graphics.

Keep in mind though, that this example extends a standard View. If you only want to modify one of the already existing views, for example a new behaviour for a button, you can opt for the much simpler route of just extending that type of view and only modify the things you need.

Now go and create astonishing views for your applications, and feel free to use the comments field below for any questions.

If you don't want to use the back button to read the articles again, you can use these links:

Part I - Graphics
Part II - Interaction
Part III - Xml Attributes

Thanks for reading. Please use the comments field if you have any questions.

/Robert

Creating a custom view, part 2 - Interaction

2011-10-19T14:47:00.003+02:00

This is the second part in my article about how to create a custom view in Android.
Please follow these links for the other parts:

In this part of the article, the slider will get some useful functionality, like being able to position the indicator from the activity, and react on touches.

Step 3 Change indicator position from the activity.

This step is far from the complexity in step 2, but still complex enough to warrant a few substeps.

Step 3.1 Setters and getters.

git checkout step_3_1

The requirement for this step was to be able to change the indicator position, but it makes sense to also make it possible to also alter the min and max values.

The getters are easy, but the setters need a few extras.
Let Eclipse do the easy part for you, by right-clicking on your class and selecting Source->Generate Getters and Setters. Tick mMin, mMax and mPosition and make sure to generate both getter and setter for mPosition and mMin. You don't need one for mMax, for reasons that will become clear in a moment.
After the code has been generated, you probably want to tidy up the method names slightly. Your getters should look something like this:

public float getMin() {
    return mMin;
  }

  public float getMax() {
    return mMax;
  }

  public float getPosition() {
    return mPosition;
  }

As I said, the setters require a few extra lines. Since calling a setter will possibly alter a visible view, the view should be invalidated. But since invalidating views trigger a redrawing of it and possibly neighbouring views you should not invalidate unless needed. Furthermore you probably don't want the position to be outside of min and max, so you should check for that. Your setter for mPosition should thus look like this:

public void setPosition(float position) {
    position = within(mMin, mMax);

    if(position != mPosition) {
      mPosition = position;
      invalidate();
    }
  }

You will also need to implement that helper method, within(). It should look something like this:

private float within(float position, final float min, final float max) {
    if (position < min) {
      position = min;
    }
    if (position > max) {
      position = max;
    }
    return position;
  }

Here is the reason for not generating a setter for mMax. For the slider to work properly, mMin must always be smaller than mMax, and the indicator must always be positioned somewhere in between min and max. That's why mMin and mMax must be set in the same method. The setter should check min and max, and throw an exception if they are wrong, and it should also adjust the position of the indicator. The adjustment can be done by reusing the setter for the position, like this (renaming setMin to setMinMax):

public void setMinMax(final float min, final float max) {
    if ((min != mMin) || (max != mMax)) {
      if (min > max) {
        throw new IllegalArgumentException(
            "setMinMax: min must be smaller than max.");
      }
      mMin = min;
      mMax = max;
      setPosition(mPosition);
      invalidate();
    }
  }

Step 3.2 onPositionChanged

git checkout step_3_2

Being able to set and get the position is handy, but you will also need some way for the view to tell the activity that values have changed.
For this you will need a listener interface for your view and your activity needs to implement it in a usual manner. (The activity will be modified in the next step.)
Adding an listener interface is just a matter of specifying what should go in the interface and which object that should be tied to it.
First the interface. Put this into your class:

interface CustomSliderPositionListener {
    void onPositionChange(float newPosition);
  }

A new member field is also needed:

private CustomSliderPositionListener mPositionListener;

The field will need a setter:

public void setPositionListener(final CustomSliderPositionListener listener) {
    mPositionListener = listener;
  }

And it should be initialised in the constructor, so you should add this line to the end of the constructor:

mPositionListener = null;

Finally, the listener should be called if the position does indeed changes, so you will need to add a few lines to setPosition, inside the if statement just after the call to invalidate:

if (mPositionListener != null) {
        mPositionListener.onPositionChange(mPosition);
      }

Ok, done.
(You should really add similar code for getting notified about changes to min and max as well. Feel free to do that, but I will not add it here, for the sake of the size of the tutorial.)

Step 3.3 Update the activity.

git checkout step_3_3

Again, the activity is there to show you that things are working, so let's do just that.
In you main.xml, add a text view and a button. The purpose of the text view is to show the current position of the indicator, and the purpose of the button is to reset it to the centre.
Your new main.xml should look something like this:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
    <com.enea.training.customview.CustomSlider android:id="@+id/slider_horizontal"
      android:layout_height="wrap_content"
      android:layout_width="fill_parent"
      android:layout_alignParentLeft="true"
      android:layout_alignParentTop="true"
    />
    <Button android:id="@+id/button_reset"
      android:text="@string/reset"
      android:onClick="onReset"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_alignParentRight="true"
      android:layout_alignParentBottom="true"
      />
    <TextView android:id="@+id/values"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_alignParentRight="true"
      android:layout_above="@id/button_reset"
      />
</RelativeLayout>

Notice that I have changed the id of the slider, this is a hint of what is to come...
You will also need to add a string for your button. Add this to res/values/strings.xml:

<string name="reset">Reset</string>

You will also need to add a fair bit of code to your CustomSliderActivity. First of all you will need two member fields, for the text view and the slider:

private TextView     mValueHorizontal;
  private CustomSlider mSliderHorizontal;

You will also need to initialise th fields in onCreate. That includes implementing the onPositionChanged listener added in step 3.2, and setting min, max and position by calling the setters in step 3.1.
The listener calls to a helper method, displayValues() that will show the position of the indicator properly formatted in a text view.
Your new onCreate(), and the helper method, should look like this:

@Override
  public void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    mValues = (TextView) findViewById(R.id.values);

    mSliderHorizontal = (CustomSlider) findViewById(R.id.slider_horizontal);
    mSliderHorizontal.setPositionListener(new CustomSliderPositionListener() {
      public void onPositionChange(final float newPosition) {
        displayValues();
      }
    });

    mSliderHorizontal.setMinMax(-100.0f, 100.0f);
    mSliderHorizontal.setPosition(30.0f);
    displayValues();
  }

  void displayValues() {
    final String str = String.format("Horizontal: %3.2f",
        mSliderHorizontal.getPosition());
    mValues.setText(str);
  }

All that is left now is to implement the callback for the button. Upon clicking the button, the indicator should go to the center of the slider. The code should look like this:

public void onReset(final View v) {
    final float min = mSliderHorizontal.getMin();
    final float max = mSliderHorizontal.getMax();
    final float newPos = (max - min) / 2 + min;
    mSliderHorizontal.setPosition(newPos);
  }

Time for another test run of your project. Make sure the code works as expected, and don't forget to click the button.
Modify the hard-coded values in onCreate and verify that the slider reflects your changes.

Step 4 onTouchListener

git checkout step_4

About time to interact a bit more. This is probably the simplest step of them all. All you need to do is in your constructor tell your view that it should use a touch listener:

setOnTouchListener(new OnTouchListener() {
      public boolean onTouch(final View v, final MotionEvent event) {
        final float pos;
        pos = (mMin + ((mMax - mMin) / (mIndicatorMaxPos - mIndicatorMinPos))
              * event.getX());
        setPosition(pos);
        return true;
      }
    });

Done. Run your project and try to move the indicator with your finger. Hit the reset button to get it back to the center.

That's it for this part of the article. In the next part, you will see how to make a vertical slider, and how to set some attributes from xml.

Please use the comments field if you have any questions.

/Robert

Using NFC in Android

2011-10-14T10:30:00.001+02:00

Near Field Communication (NFC) is a technology for data exchange between devices in close proximity. It traces its root back to RFID, where a reader drives a passive electronic tag through a magnetic field. This is a typical use case for NFC, but it can also be used by two active devices to communicate with each other.

APIs for NFC have now been added to the Android SDK, and a few phones with the NFC capability are available. I have looked into how we could use NFC to improve an existing Android application we develop. The application is targeted for cities, and one of its features is to provide information about various places of public interest, and in some cases allow reports of malfunction to be sent through the application. This feature could make use of NFC by having tags posted at the places of interest, which would allow users to get directly to the information about the place by just tapping the phone on the tag. Another possibility would be to use Peer-to-Peer data exchange to let a user running the application tap another phone. If the other phone has the application installed, it would start the application on the same activity, otherwise the other phone may be redirected to the application on Android Market.

I looked more closely at the first use case of having tags at places of interest. One initial consideration is that the number of phones with NFC is still very small. It would therefore be desirable to have an alternative way to achieve the same functionality for other phones. For this reason I also had a look at using QR codes, which can be read through the camera in the phone.

When the Android system detects an NFC device, it searches for the most suitable application to process the data. NFC only works over a very short range, so having the user select the application to use from a list is only used as a last resort, since this would typically cause the user to move the phone away from the device, and thereby break the NFC connection. Instead, the NFC API has defined several types of intents with different priorities, and with different options to filter on tag content or technology. The highest priority is given to the foreground application, which can register itself to intercept any NFC intent. This is not a good option in our application, since it would require the user to start the application before tapping the phone on the tag.

The next highest priority is applications that filter on tag content, which would work well in this case. The content could be set to anything we want, since the tags would be made specifically for our application. A standard type of content which has support for filtering in Android is URIs. To ensure that our application gets the NFC intent we could use a non-standard scheme. The host part of the URI could be used to select the activity to use within the application, and an identifier could be included as a URI parameter:

abc://point?id=123

The intent filter for these NFC tags would look like this:

<intent-filter>
  <action android:name="android.nfc.action.NDEF_DISCOVERED" />
  <data android:host="point" android:scheme="abc" />
  <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

The same URI could also be encoded in a QR code. I used a bar code reader called ZXing which can easily be integrated with other applications. It can also do the reverse, i.e. generate a bar code image from text data which is useful for testing. There are two ways to use ZXing to get the scanned QR code into our application:

Our application can send a specific intent defined by ZXing for integration. This starts the ZXing application and a result is returned when the scan is complete (or the scan was cancelled).
The ZXing application is started and a QR code is scanned by the user. When the content is a URI, the user gets an option to open it. Our application can get the intent generated by this option by declaring an intent filter matching the URI.

For maximum usability, both ways could be implemented, allowing the user to proceed regardless of which application was started first. The way described in 1 above is described on the ZXing web page. The second way, which is what I tried, is quite simple. Our application declares an intent filter, which is very similar to the NFC intent filter above:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <data android:host="point" android:scheme="abc" />
  <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

The URI can then be retrieved through the getData method on the received intent, in order to extract the id parameter, and this is used to find and display the desired information.

Some of the NFC features were introduced in API level 9, and the other were introduced in API level 10. The Android SDK develper guide describes how to declare an application to require this API level as well as NFC permission and hardware. This is however not what we want for our application. We want to use NFC if it is available, but the application should install and work without NFC and on old devices at lower API levels. The NFC permission must be declared to get NFC to work when it is available. The platform will use the permission declaration to implicitly derive the NFC hardware requirement, but the application can override this by explicitly declaring that NFC hardware is not required. Finally, the required API level can be kept at a low level while still allowing the application to use the NFC features in API level 10, by using the targetSdkVersion attribute. The result is the following declarations:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />
<uses-sdk android:minsdkversion="4" android:targetsdkversion="10" />

The application can then be compiled with the API level 10 SDK, but can still be installed on anything with API level 4 or higher. In order to make use of NFC, the application will have to use classes in the android.nfc package, which is not available before API level 9. This may cause a VerificationError on the application if it is not handled correctly. The solution is to put all dependencies on NFC into separate application classes that are only loaded on devices that actually support NFC. This works because the Dalvik VM only loads and verifies the application classes the first time any method or member in them are accessed. So even though some application classes would not compile on the API level of the device, the application will still run without errors as long as the classes using a higher API level are not touched. The application can check the API level of the device at runtime through the constant ”Build.VERSION.SDK_INT”. The application can also check if the NFC feature is available through the ”PacketManager.hasSystemFeature” method. Note that this method is only available from API level 5, so the API level must be checked first, and the feature check needs to be in a separate application class that is not loaded on lower API level devices.

The QR code alternative does not have the same problem with API levels (as the ZXing barcode reader only requires API level 3), but it will obviously only work if the barcode reader is installed. If the integration is implemented by starting the scan from ZXing, which then sends a ”VIEW” intent, then the application is not required to check anything. However in the other integration option, where the application sends an intent to the barcoder reader to initiate the scan, the application must check at runtime if the barcode reader is available. This check can be done with the ”PacketManager.queryIntentActivities” method. When the result of this check is negative, the application could disable any ”scan” button or anything else in the user interface used to initiate a scan operation. The application could also provide a link to the barcode reader in Android market to make it easy for the user to enable the QR code scanning feature. The link could be made like this:

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("market://search?q=pname:com.google.zxing.client.android"));
startActivity(intent);

In summary, I found that the NFC capability could indeed be used to add a new feature to our application. It would make the application easier to use, and it could be implemented without limiting the availablility of the application to phones that have NFC hardware. If QR codes are used as a complement to NFC tags, then the same functionality could be implemented for phones without NFC.

/Mikael

Using Android in industrial applications

2011-09-05T12:02:00.000+02:00

Enea will be represented at the SICS (Swedish Institute for Computer Science) Android theme day about Android beyond phones and tablets.
Our Android expert Robert Niemi will do a speach titled "Android in industrial applications - today and tomorrow."

The day will be filled with interesting seminars, followed by a panel discussion.

The theme day is in Stockholm, Sweden on Sept. 21. Please follow this link for more information: http://www.sics.se/androiddagen2011

/Robert

An example of porting existing code to a custom Android device

2011-08-30T13:54:00.000+02:00

It is due time for another technical post here on the blog. This post will be about porting existing c-libraries to Android, something I did as part of the dev board demos we are doing here at Enea.

Platform addition or NDK

There are two ways of bringing native code to an Android device, either add it to the platform itself and integrate it with the framework, or include it with an application package. The latter method have evolved a lot and with the release of NDK version 5 even allows you to hook directly into the application lifecycle http://developer.android.com/reference/android/app/NativeActivity.html from the NDK. The NDK is useful for any application where you have need of native performance, have portable C libriaries you want to reuse or just some legacy native code that could be included in your application. The NDK integrates well with the Android SDK and is a great way to include native functionality in your application. It should be the preferred way for any application that needs to be reusable across a lot of Android devices.

The other option is to include your functionality, it may be native or Java, as an API extension for all applications to use. This will only work on devices that implement these extensions and it may be a suitable option for device builders. This is the variant that we aim for here.

Analyze the existing project
Porting native code to Android is not always straight forward, especially if we are talking about C++ code due to the fact that Android uses its own c-runtime with limited support for exceptions among other things. If you want to know more about the details of bionic there is an overview in the NDK docs.

The code I wanted to port for this project was the Enea LINX for Linux framework which is a fast IPC framework. My purpose was to be able to interact with control systems running our OSE real time operating system which also implements this kind of IPC. LINX consists of a couple of kernel driver modules, a user space library and some configuration and control utilities. It is written in C. I had created a small demo with LINX in Android before where I compiled it separately and used static linking but for this project I wanted a complete port to the Android build system. It did not have any issues with bionic compatability so the port should be straight forward.

I just want to add a short disclaimer about LINX. I use it here since it is a good example of integrating a solution into Android from kernel drivers up to the API levels. This particular piece of code does add additional IPC mechanisms to the systems which more or less messes up the security model so do not use it unless you are aware of the implications. The steps needed to port code to Android described in this post are however applicable for any type of driver/framework/library that you may want to include on your product.

Adding kernel driver modules
The first step was to add the kernel modules to the Android build. One way would have built a new kernel and include them directly but for this project I chose to keep them as separate modules. Building for the kernel is not handled by the Android build system meaning that we build them as we would do with any Linux system. The target is an Atmel based development board and in the LINX module build I provide the headers and cross compilation toolchain for that kernel and architecture.

Now for the Android specific parts. We need to add the compiled kernel modules to the platform build system in some way and create an Android.mk file that includes them in the system image when we build. Add a folder in the source tree where your project will go, device or external are suitable candidates. I created a folder called linx that will hold the entire linx port and in that I added a subfolder called modules where I place the prebuilt kernel modules. Now what we need is an Android makefile to copy them to the suitable place in the out folder for system image generation. This will look like:

LOCAL_PATH := $(my-dir)

include $(CLEAR_VARS)



LOCAL_MODULE := linx.ko



LOCAL_MODULE_CLASS := SHARED_LIBRARY



# This will copy the file in /system/lib/modules

#

LOCAL_MODULE_PATH := $(TARGET_OUT_SHARED_LIBRARIES)/modules



LOCAL_SRC_FILES := $(LOCAL_MODULE)



include $(BUILD_PREBUILT)

The standard location for modules on the Android system image is System/lib/modules so that is where we copy them. If we build the platform now the build system will copy our precompiled module linx.ko to the system image that we use for our device. The next step is to make sure that we have the module installed on the system when we run it. This can either be done manually via the shell or via a script that we run during init.

In this case I have created a shell script to be launched from init.rc with the following content:

#linx init

insmod /lib/modules/linx.ko

insmod /lib/modules/linx_tcp_cm.ko

netcfg eth0 up

ifconfig eth0 192.168.1.12

mktcpcon --ipaddr=192.168.1.21 ControlConn

mklink --connection=tcpcm/ControlConn control_link

This includes installing the modules and configuring the network and LINX-link. We launched this from init.rc by adding:

...

#linx init script

service linx-setup /system/etc/linx_setup.sh

oneshot

...

The setup script is added to the system image in the same way by including it as a prebuilt target.

LOCAL_PATH := $(my-dir)

include $(CLEAR_VARS)



LOCAL_MODULE := linx_setup.sh



LOCAL_MODULE_CLASS := ETC



LOCAL_MODULE_PATH := $(TARGET_OUT)/etc



LOCAL_SRC_FILES := $(LOCAL_MODULE)



include $(BUILD_PREBUILT)

Creating Android make files for the user space code
Now that we have the drivers in place the next step is to look at porting the user space libraries. The default LINX build system uses standard GNU make files but we need to create new ones adapted to the Android build system. Start out by adding the source files needed to the linx directory created in the Android source tree. This gives the following structure:

Android.mk  

include  

liblinx  

linx_basic  

linxcfg  

linx_setup.sh  

modules

I have the linx setup script and the main Android.mk file in the top directory and then we have the source files in separate folders and the include files in the include folder. To illustrate how the Android make files for each source component is created we can use liblinx as an example. The Android.mk file looks like:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)



LOCAL_SRC_FILES := linx.c

LOCAL_C_INCLUDES += $(LOCAL_PATH)/../include

LOCAL_MODULE := liblinx

LOCAL_PRELINK_MODULE := false

include $(BUILD_SHARED_LIBRARY)

We set our sources by specifying LOCAL_SRC_FILES and the name of the library by specifying LOCAL_MODULE. We also need to supply the header files in the include directory by specifying LOCAL_C_INCLUDES. Finally this is a shared library that we are porting so use the BUILD_SHARED_LIBRARY template. This will build the library with the Android build system and add it to the system image as a shared library with the name liblinx.so.

The rest of the code is moved to the Android build system in the same way, by creating Android.mk files and specifying type and any dependencies. As another example we may look at the syntax for building the mktcpcon configuration program. This depends on the library we just created and hence the makefile looks entry looks like:

LOCAL_SRC_FILES := mktcpcon.c

LOCAL_C_INCLUDES += $(LOCAL_PATH)/../include

LOCAL_STATIC_LIBRARIES += liblinxcfg

LOCAL_SHARED_LIBRARIES += liblinx

LOCAL_MODULE := mktcpcon

include $(BUILD_EXECUTABLE)

Here we use the BUILD_EXECUTABLE template and we also need to specify static and shared libraries that we link against.

Summary
I hope that provides some insight in how you setup the build for an existing linux project to run on an Android system. The steps to follow are:

Build any kernel related things using the correct kernel build system and config for your device
Add the kernel modules (and/or kernel) to the platform build system and create Android.mk files for them using the prebuilt template.
Create config and intialization services for your drivers if needed and add them to init.
Move the rest of your code (user space) to the Android source tree and create Android.mk files for them.
If you encounter build errors work them out in the source code and see what incompatabilities your code have with the specifics of the Android C-runtime.

That wraps up my post for today. Having done this we are now able to use our added drivers and API:s from native programs running in the shell. The next step is to create a JNI layer and java library to allow regular Android applications to make use of our platform additions.

I have been away for half a year on paternal leave (nice Swedish benefit) but now it is full time Android hacking again and pushing the team to publish things. Hopefully you will see more activity here including a follow up on this post discussing applications APIs.

/Mattias

Android Only

2011-05-05T20:53:00.000+02:00

Don’t miss the Android Only Conference in Malmö, Sweden in June, the dates are 13 – 14 June 2011.

The focus will primarily be on Programming and development of Android applications and services. Presentations will also cover design and user interaction, and utilities and services for the developer as well as the end-user of Android devices. Check out the details on http://swdc-central.com/androidonly2011malmo/

Enea is a Silver Sponsor for this event and our expert Mattias Björnheden will give a presentation with the title:

“Create your own Android device—working with Android on development boards”

We will run two of our popular Android trainings at the Android Competence Center in Lund (located 18 km from Malmö) in connection with the event:

15 – 17 June: “Android Platform for System Engineers”

20 June: “Android Advanced”

We will host a competition at the show, where you can win a seat at these trainings!

See you there!

Erik

Working with Android on development boards

2010-10-26T16:05:00.001+02:00

This will be the first of a set of post on a project we are doing where we will use an Android powered dev board to provide UI and user control features for an embedded system. I will get back to the setup in later posts but in brief it will consist of two boards, one running a traditional control system and one running a slightly adapted Android platform with extra API:s to interact with the control system. This part focuses on working with Android on dev boards in general and discusses a couple of boards in particular.

For platform level hacking the open source project provides a good start with the emulator and that is useful for things like working with the base applications and examining the framework. The emulator is however limited and for a lot of platform level work real hardware is the best way to go. For real hardware there are two routes, either use an existing phone or use some kind of development board. Existing phones are fun platforms for tinkering and enabling features in the way they to it at xda-developers and other forums. As a general lab environment they are limited since they often have very few hardware interfaces exposed and they are often locked down in ways that make interacting with them difficult.

Development boards on the other hand are often made especially for trying out new designs, connecting hardware and having easy debug access. These are often the best platform for working with low level stuff on Android. In fact most phone manufacturers start out with some kind of platform dev board to facilitate early development before they wrap everything in great looking metal and plastic.

So let us look at working with Android on embedded development boards. First you should decide on why you want to go this route. Dev boards are excellent for:

Low level work on the Android open source project, testing and debugging hardware interaction etc.
Hobby projects where you want to design a great Android based interface for your home-made toaster and need to hook up the android system to some outside electronics.
Professional projects where you are considering building an Android based product, be it a phone, a tablet, music player etc.
Anyone else who wants to explore the full capabilities of Android and understand the platform without the limitations of the emulator or set hardware design of a phone.

Dev boards are probably not the way to go for:

Getting a basic understanding of how to build and run the Android source code. The open source project and the emulator are more than sufficient for that.
Application development work. The SDK and existing phones are perfect for that and saves you a lot of hassle with jumpers, adb bridging and so on.

Factors to consider

Now let us say that you are still interested in working with Android on a development board. Then we get to the interesting part on deciding on which one to get. Here I would say there are a few important factors to consider:

Purpose - what to you plan to do with the board
Price
Performance
Existing Android ports for the board
Community
Debugging utilities
Expansion possibilities

All of these are important but do not underestimate the power of having an active community around your platform that can help you out if you run into problems. Start by looking at the above factors and note down your requirements in each aspect. And do not forget to take into account other things that I have left out in this bullet list. Once you have some idea of what you need we can start looking at what is available. And that is becoming quite a lot.

Let me start by grouping the different boards into a few categories. And here I will add in a limitation. I will mostly consider ARM-based dev boards since this is the architecture with the widest Android adoption so far and almost all commercial devices shipped so far are based on ARM. That said there is a very active community around Android on x86 and also MIPS ports. And probably a few more. The most prominent feature of any dev board is the applications processor and system on chip design that will run the actual Android system. Based on that I will use the following categories for ARM based designs:

State of the art - these are dev boards with high performance system on chips that are often prototypes of platforms that are not even available in commercial products yet.
High end, these are dev boards with an applications processor that matches the high end Android phones that are available today.
Mid and low end - these are either boards with performance that matches early or low end Android phones.

State of the art development boards

These platforms are based on dual-core Arm Cortex A9, 1 GHz plus, system on chips with graphics acceleration and other features. In this category I am only aware of a couple of platforms that can be obtained as development boards for general purposes. Two are based on the TI Omap 4 system on chip and can be ordered either as the cheap panda board or as the more full featured Blaze kit which include touch screens and keyboard. If you are based in North America it is also possible to get the Tegra 250 dev kit from Nvidia with similar specs. These boards are interesting since they have more processing power available than anything else on the market but they are also fairly new designs with limited community track record. They may be perfect for experienced embedded hobbyists that want to build a HTPC setup or similar. If you have very little experience working with embedded development it may be better to start out with something with a longer track record and more information available on forums, blogs and wikis. For professionals you need to consider if you really need this kind of processing power in your design. Maybe advanced 3D graphics and full HD video is not part of your use case and then maybe these types of platforms will eat more power and cause more issues with advanced features than they provide benefits.

High end development boards.

These are ARM Cortex A8 based designs similar to what is powering most of the high end Android smarthphones that are available today. In this category we have a number of SoC and a large amount of development boards based on these SoCs. To mention a few of the families we have the Freescale i.Mx 515, evolution dev kit and android tool and the Texas Instruments OMAP3, most notable the Beagle board and the Zoom II dev kit. Since these run on the same CPU family (ARM Cortex A8) as most of the commercially available Android phones do and have been around for a while they are often well tested and relatively stable. This is especially true of the Omap based Beagle board which features a large developer community. The Omap on the Beagle board is also very similar to the Omap that powers the popular Motorola Droid phone. There are a number of derivatives from the Beagle with more peripherals and expansion possibilities.

Mid and low end development boards.

This is a more unexplored area but with some interesting products. Android this far has been a lot about performance and most community boards have been higher end boards but as interest for using Android outside the smartphone space is increasing so is the number of low cost platforms with support for the system. These boards are generally based on ARM926 or ARM11 CPUs and have a limited set of accellerators and peripherals. Many dev boards in this category have too little memory to run Android (128 MB RAM is some kind of current minimum but more is even better). There are some Samsung boards, something from Renesas and once again probably a lot of others. The board that we have worked with in this category is from Atmel, the AT91SAM9M10-EKES borad. While their Android community is relatively young compared to the Beagle board Atmel has a tradition of having a thriving community around their at91 platforms in general.

Some practical details

Now that we are finally past the overview we can get to the practical details on working with development boards. If you are considering to get a develoment board for Android I would suggest that you try to download and build whatever Android distribution is availble for that board before you get the hardware. The state of the distribution will tell you a lot about how hard it will be to get the hardware working later on. If there is no Android distribution available for your hardware make sure that you are aware what the porting effort will be and also analyze that the hardware will even be capable of running Android in terms of performance and memory available.

Another thing to investigate is how you will boot and run Android on the dev board. Does it contain a NAND flash or SD card interface. Is it possible to set up a network file system and boot Android from that? Having working adb tools are also very nice when working on a dev board. It is much more convenient to update just your shared library through an adb sync instead of having to build, generate a system image and flash it to the board every time you need to test an update.
Regardless of what board you choose prepare to spend some time understanding how to boot it up with your Android build. Often they are delivered with some other software as default configuration. Prepare to spend a few hours up to a few days just to get familiar with boot and flash options. How to set the jumpers in the correct state to be able reflash the board etc.

Our experience

These are some impressions for three of the different boards that we have worked with so far.

Beagle board:

BeagleBoard in action

Pros:

Very powerful board for the price tag.
Good community around Android and the Rowboat distribution on TI Omap
Well tested CPU for Android, very similar to the SoC powering the Motorola Droid and other devices
A lot of other Linux work happening on the Omap platform such as MeeGo
Decent debug support
Relatively easy to get started with and several boot options

Cons:

No ethernet support in default configuration, has to be added via USB.
No touch screen or other peripherals included, not even power adapter

Summary:
The Beagle board is a very powerful board for the price ($149) and if you connect to a regular monitor and keyboard it is a very capable development platform for low level work. We have run a number of projects on this platform ranging from initial demos and driver projects to advanced research stuff. The limitations made to keep the price down are a bit annoying and nowadays I would recommend getting the updated BeagleBoard xM version instead. That will add an ethernet port and more USB ports. There are also versions and derivatives that include screens etc.

Zoom II:
This is another OMAP based device but includes and the SoC is very similar to the BeagleBoard but it is packaged more like a real device with touch screen and keyboard.
Pros:

Much more peripherals included compared to the Beagle
Portable device like package, good for demos

Cons:

More expensive than the Beagle

Summary:
This device is very similar to the Beagle board and shares the same attributes beyond the two things mentioned here.

Atmel AT91SAM9M10-EKES:

An Atmel boad with Android up and running

Pros:

Includes touch screen directly on the board
Connection cables and power supply included
Good community around the at91 boards in general, emerging Android community
Based on relatively small and low cost ARM926 CPU
Good value for money for a relatively complete kit

Cons:

Dev tools seem a bit Windows focused, it was a little bit tricky to get started from a Linux dev machine
Android support is relatively new for this platform, not as well tested as the Omap distributions

Summary:
I think this is a really interesting dev kit. Especially when looking at developing things that do not have the high-end smartphone level of performance requirements. Since it includes a screen and decent amount of connections it can be used as a compact demo board. We got this relatively recently and will probably base our next demo on it. After some initial hickups with the tools it is straight forward to develop on and the support from Atmel and the community seems to be growing rapidly. We still need to do some benchmarking though and see how it handles Android compared to higher end alternatives.

I hope this article provides some insight on working with Android on development boards. With the amount of Android related news currently I am sure I have missed some capable platforms. Feel free to add whatever platform you are familiar with in the comments and I will update this post with more info. Once again I would like to remind you that I have skipped entire architectures such as x86, MIPS and PowerPC in this article.

/Mattias

Slides from the presentation on Security Concepts at Android Only

2010-10-04T15:53:00.000+02:00

The slides from my presentation on Android Security Concepts held at the Android Only conference in Stockholm on September are now available. The video from the presentation will be available on the conference homepage in a couple of weeks.

/Mattias

Android Only conference and plans for the fall

2010-09-17T10:59:00.000+02:00

Once again it has been low activity here during the summer months but hopefully we will get back up to 1-2 posts a month from now on. We are currently working on a demo system that combine an Android CPU for user interaction with a control system running on a separate CPU and we hope to describe the steps in some detail.

Android only

I will give a presentation on Android security concepts at the Android Only conference in Stockholm, Sweden, on September 29-30. Looks like it could be a really cool conference. Interesting speakers and hopefully a lot of new Android devices to check out. Follow the link for more details.

New hardware on the horizon

If you are looking for a technical post and can't wait a few more days I wrote a piece on the ARM Cortex A15 launch on the Enea corporate blog. Not directly Android but definitely mobile computing related. You can find that post here: http://blog.enea.com/Blog/bid/51605/ARM-Cortex-A15-What-Multicore-Developers-Need-to-Know.

/Mattias

Sky Is The Limit - Now on Android Market

2010-06-24T13:18:00.000+02:00

Finally we're releasing our first app on Android Market. The app is actually a new type of game that is using the accelerometer in an exiting way. The game is really easy, all you have to do is to throw your phone up in the air as high as you dare. As mentioned we're using the accelerometer and also some secret algorithms to calculate how high a user can throw. We are also using an SQLLite database to store the highscores on the phone and a server with a SQL database to store global highscores.

During development we accidently crashed the sensors on one phone, but considering how many throws we've done, that's ok. Included in the game is four different highscores, Phone, National, Global and also a global hisghscore based on your phone model.
Right now the Android Team record is 8.5m high! Do you dare try to beat us?!
The name of the game is SkyIsTheLimit and can be downloaded on android market. Search for "skyisthelimit". Or use the QR code with a barscanner:

Some screenshots:

/Henrik and Tommy

Using the local_manifest.xml file in repo to customize your Android project setup

2010-06-21T17:10:00.000+02:00

This post will discuss how to use repo and the local_manifest.xml file to keep track of projects that are not part of the default manifest for the Android open source project. This can be used to keep track of some projects that are maintained by the Android team but are not included in the default distribution. It can also be used to include other git-based projects within your android platform source tree. Adding a local manifest file is a good way to set up a personalized environment to work with Android for hacking or in a small team. Any additions to Android can be kept in separate git repositories and tracked using the local manifest. For commercial level projects it may be better to run your own repo server and edit the manifest directly to make sure that it is version controlled and that all developers see the same projects. We may get back to that topic in a separate blog post.

Now let's take a look at the practical details. The format of the local manifest file follows the standard manifest format described in the manifest-format.txt file under .repo/repo/docs in the Android Open Source project. To create a local manifest add a file with the name local_manifest.xml and place it directly in the .repo folder of your Android Open Source Project. It will be parsed by repo as part of a normal repo sync.

I keep a project on machine to track the latest development in the Android platform. It is setup to track the current master branch in the default configuration. Since I often work with hardware as well I am also interested in developments in the kernel. Currently there are a number of different kernel trees being run as part of android. None of them are part of the default manifest. In my setup I want to track the common kernel but also see what is going on with hardware support for Qualcomm (msm) and TI (omap) platforms. These are all maintained by the android team and I can use the default remote site to get them. I need however to inform repo about what branch I want to track by adding the revision tag. For each project add a tag like this:

<project path="kernel"
      name="kernel/common"
      remote="korg"
      revision="android-goldfish-2.6.29"/>

Another thing I also find myself using is Busybox and since I set it up the build config and do some adaptations when using it with Android I like to track the source for that as well within my Android tree. This can easily be achieved in the local manifest by adding a new remote site for Busybox and then adding the project itself like this:

<remote  name="busybox"
           fetch="git://git.busybox.net/"/>
<project path="busybox"
      name="busybox"
             remote="busybox"/>

To sum things up this means that each time I do a repo sync I will get the latest version of the Android Open source project and also updated repositories for the three different kernel trees that I track and an updated busybox source. All in all my local_manifest file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
  <manifest>

    <remote  name="busybox"
           fetch="git://git.busybox.net/"/>

    <project path="kernel"
      name="kernel/common"
      remote="korg"
      revision="android-goldfish-2.6.29"/>
    <project path="kernel_msm"
      name="kernel/msm"
      remote="korg"
             revision="android-msm-2.6.32"/>
    <project path="kernel_omap"
      name="kernel/omap"
      remote="korg"
             revision="android-omap-2.6.32"/>
    <project path="busybox"
      name="busybox"
             remote="busybox"/>
  </manifest>

/Mattias

Android Open Source Project workflow

2010-05-10T09:16:00.000+02:00

Thought I should share a couple of flowcharts showing how to do basic work with the platform source code. In this case we assume that there is a platform library that need some adaptations. It is impossible to cover all the steps in an overview like this but look at is as a basic guide if you have limited experience of the platform source. I have divided the guide into two different images. The first one shows the practical work itself (i.e. the "happy hacking") while the second one illustrates the steps needed to handle the change in an environment using repo and gerrit.

Part 1 - code changes
This part assumes you are working with the Android open source project for a device or some other project and have some changes that need to be made to a platform module. The utility commands described here all come from the envsetup script. There is a lot more to say about things like testing depending on your general setup but I hope this provides an illustration on how to go about making a small change in the Android platform and trying it out.

Part 2 - commit and review
Making a change is all good if you are just trying things out. In a real project however you are probably working with a setup using repo and gerrit for your project and would like to submit your changes. This flowchart provides additional details on the repo and git commands needed to go along with a change as described in part 1.

Feel free to comment if you find these charts useful or if you think I should add or change things.

/Mattias B

Using Checkstyle with Android Open Source Project

2010-04-21T14:14:00.000+02:00

This post provides a small Checkstyle template that we have been using to conform with the code style guide proposed by the Android Open Source Project. For pure formatting issues also see this question on stackoverflow.

1. Make sure that the Checkstyle plugin is installed in Eclipse. If not, follow the steps below. Note that these instructions are for Eclipse Galileo. If you are using another version, some of the installation steps might differ.

1. Open "Help" -> "Install New Software"

2. Paste the link: http://eclipse-cs.sf.net/update into the "Work with:" field and click "Add..."

3. Name the site e.g. "Checkstyle"

4. Check the box next to the latest version of the Checkstyle plugin and press "Next->"

5. Follow the instructions to complete the installation

2. Save the contents below to a new xml file and place it on a location of your choice.

3. Open "Window" -> "Preferences" and choose Checkstyle

4. Press "New..."

5. Fill in the configuration properties

"Type: External Configuration File"

"Name: Android checkstyle by Enea"

"Location:" Browse to the saved android_cs.xml file

6. Press OK twice

7. Right click on your Android project and choose Properties

8. Choose Checkstyle and check the box "Checkstyle active for this project"

9. Select "Android checkstyle by Enea" from the drop down list

10. Rebuild the project to analyze your code

Done!

Karin, Fredrik and Karl

Note: If you want to edit the checkstyle configuration open "Window" -> "Preferences" and choose Checkstyle.

Mark the Check Configuration you want to edit and press "Properties..."

Save this to an .xml file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//Puppy Crawl//DTD Check Configuration 1.3//EN" "https://home.enea.com/dtds/,DanaInfo=www.puppycrawl.com,CT=dtd+configuration_1_3.dtd">

<!--
    This configuration file was written by the eclipse-cs plugin configuration editor
-->
<!--
    Checkstyle-Configuration: Android checkstyle by Enea
    Description: none
-->
<module name="Checker">
  <property name="severity" value="warning"></property>
  <module name="TreeWalker">
    <property name="tabWidth" value="4"></property>
    <module name="JavadocMethod">
      <property name="logLoadErrors" value="true"></property>
      <property name="suppressLoadErrors" value="true"></property>
    </module>
    <module name="JavadocType"></module>
    <module name="JavadocVariable"></module>
    <module name="JavadocStyle"></module>
    <module name="ConstantName"></module>
    <module name="LocalFinalVariableName"></module>
    <module name="LocalVariableName"></module>
    <module name="MemberName">
      <metadata name="net.sf.eclipsecs.core.comment" value="only public starts without m"></metadata>
      <property name="applyToProtected" value="false"></property>
      <property name="applyToPrivate" value="false"></property>
    </module>
    <module name="MethodName"></module>
    <module name="PackageName"></module>
    <module name="ParameterName"></module>
    <module name="StaticVariableName">
      <metadata name="net.sf.eclipsecs.core.comment" value="starts with 's'"></metadata>
      <property name="format" value="^[s][a-zA-Z0-9]*$"></property>
    </module>
    <module name="TypeName"></module>
    <module name="AvoidStarImport"></module>
    <module name="IllegalImport"></module>
    <module name="RedundantImport"></module>
    <module name="UnusedImports"></module>
    <module name="LineLength">
      <property name="severity" value="ignore"></property>
      <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
    </module>
    <module name="MethodLength"></module>
    <module name="ParameterNumber"></module>
    <module name="EmptyForIteratorPad"></module>
    <module name="MethodParamPad"></module>
    <module name="NoWhitespaceAfter">
      <property name="tokens" value="BNOT,DEC,DOT,INC,LNOT,UNARY_MINUS,UNARY_PLUS"></property>
    </module>
    <module name="NoWhitespaceBefore"></module>
    <module name="OperatorWrap"></module>
    <module name="ParenPad"></module>
    <module name="TypecastParenPad"></module>
    <module name="WhitespaceAfter"></module>
    <module name="WhitespaceAround"></module>
    <module name="ModifierOrder"></module>
    <module name="RedundantModifier"></module>
    <module name="AvoidNestedBlocks"></module>
    <module name="EmptyBlock"></module>
    <module name="LeftCurly"></module>
    <module name="NeedBraces"></module>
    <module name="RightCurly"></module>
    <module name="AvoidInlineConditionals"></module>
    <module name="DoubleCheckedLocking"></module>
    <module name="EmptyStatement"></module>
    <module name="EqualsHashCode"></module>
    <module name="HiddenField"></module>
    <module name="IllegalInstantiation"></module>
    <module name="InnerAssignment"></module>
    <module name="MagicNumber"></module>
    <module name="MissingSwitchDefault"></module>
    <module name="RedundantThrows">
      <property name="logLoadErrors" value="true"></property>
      <property name="suppressLoadErrors" value="true"></property>
    </module>
    <module name="SimplifyBooleanExpression"></module>
    <module name="SimplifyBooleanReturn"></module>
    <module name="DesignForExtension">
      <property name="severity" value="ignore"></property>
      <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
    </module>
    <module name="FinalClass"></module>
    <module name="HideUtilityClassConstructor"></module>
    <module name="InterfaceIsType"></module>
    <module name="VisibilityModifier"></module>
    <module name="ArrayTypeStyle"></module>
    <module name="FinalParameters">
      <property name="severity" value="ignore"></property>
      <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
    </module>
    <module name="TodoComment">
      <property name="severity" value="ignore"></property>
      <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
    </module>
    <module name="UpperEll"></module>
    <module name="MethodLength">
      <property name="max" value="40"></property>
    </module>
    <module name="MemberName">
      <metadata name="net.sf.eclipsecs.core.comment" value="non public members should start with m"></metadata>
      <property name="applyToPublic" value="false"></property>
      <property name="format" value="^[m][a-zA-Z0-9]*$"></property>
    </module>
    <module name="LineLength">
      <property name="max" value="100"></property>
    </module>
  </module>
  <module name="JavadocPackage"></module>
  <module name="NewlineAtEndOfFile">
    <property name="severity" value="ignore"></property>
    <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
  </module>
  <module name="Translation"></module>
  <module name="FileTabCharacter">
    <property name="severity" value="ignore"></property>
    <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
  </module>
  <module name="RegexpSingleline">
    <property name="severity" value="ignore"></property>
    <property name="format" value="\s+$"></property>
    <property name="message" value="Line has trailing spaces."></property>
    <metadata name="net.sf.eclipsecs.core.lastEnabledSeverity" value="inherit"></metadata>
  </module>
</module>

Share memory using ashmem and binder in the android framework

2010-03-22T10:34:00.002+01:00

To share memory between different processes in the android framework ashmem can be used. Ashmem is a android shared memory addon to the linux kernel.
Ashmem has reference counting so that if many processes use the same area the area will not be removed until all processes has released it, the memory is also virtual and not physically contiguous. If physically contiguous memory is needed like for hardware reasons pmem can be used, but it has no reference counting and is not part of standard Android kernel.
In this blog post we will concentrate only on ashmem.

Ashmem is allocated via ashmem_create_region() that gives you an file descriptor then you use mmap() on it to get a memory area:

int fd = ashmem_create_region("SharedRegionName", size); if(fd == 0) {
  data = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
  if(data != MAP_FAILED)
  {
    /* It works do your stuff*/
  }
}

But this will not solve your problem on how to share the memory area. The first problem is that the memory pointer "data" in our example above is per process and can't be shared. The next problem is that for security reasons the name "SharedRegionName" in the example above are not shared between processes. The "other" process that want to access the same shared memory area can't use a ashmem_create_region() with the same name to get access to the same physical memory area. Instead the file descriptor (fd in the example above) needs to be used in a new mmap() in the "other" process. Here comes the third problem, the file descriptor are per process and can't be shared with the other process just like that. Bummer!

The solution is to share the file descriptor with the binder since the binder has special functions that can be used to transfer file descriptors over it's interface.
To help you with ashmem handeling and file descriptor sharing the class MemoryHeapBase can be used.

To transfer the MemoryHeapBase object you can use the asBinder() on the IMemoryHeap interface class on the server side to transfer the needed information to setup an new area on the client side mapped to the same physical memory.

sp<imemoryheap> memHeap = ...
reply->writeStrongBinder(memHeap->asBinder())

On the client side the MemoryHeapBase class will take care of all the needed stuff for you and all you need to do in your binder wrapper class is something like this:

sp<imemoryheap> memHeap;
memHeap = interface_cast<imemoryheap> (reply.readStrongBinder());

Please remember that the mmap:ed memories virtual address is not equal to the physical address even more important that the virtual address is different to each process and might be different for every call to the
getBufferMemPointer() function even if the same ashmem region is used so be careful if you have stored your pointer somewhere and still operate on it.

Here is a complete example setting up everything needed to get this working.

Interface header: IEneaBuffer.h

/*
 * IEneabuffer.h
 *  Created on: 19 mars 2010  Author: Zingo Andersen
 *  License: Public Domain (steal and use what you like)
 *
 * Buffer classes to handle the binder communication  */

#ifndef IENEABUFFER_H_
#define IENEABUFFER_H_

#include <utils/RefBase.h>
#include <binder/IInterface.h>
#include <binder/Parcel.h>
#include <binder/IMemory.h>
#include <utils/Timers.h>

namespace android {

class IEneaBuffer: public IInterface
{
public:
  DECLARE_META_INTERFACE(EneaBuffer);
  virtual sp<IMemoryHeap>           getBuffer() = 0;
};

/* --- Server side --- */

class BnEneaBuffer: public BnInterface<IEneaBuffer>
{
public:
  virtual status_t    onTransact( uint32_t code,
                                  const Parcel& data,
                                  Parcel* reply,
                                  uint32_t flags = 0);
};

}; // namespace android

#endif /* IENEABUFFER_H_ */

Interface class: IEneaBuffer.cpp

/*
 * IEneaBuffer.cpp
 *  Created on: 19 mars 2010  Author: Zingo Andersen
 *  License: Public Domain (steal and use what you like)
 *
 * Buffer classes to handle the binder communication
 */

//#define LOG_TAG "IEneaBuffer"
#include <utils/Log.h>
#include <stdint.h>
#include <sys/types.h>
#include <binder/MemoryHeapBase.h>
#include <IEneaBuffer.h>

namespace android {

enum {
    GET_BUFFER = IBinder::FIRST_CALL_TRANSACTION
};

/* --- Client side --- */
class BpEneaBuffer: public BpInterface<IEneaBuffer>
{
public:
  BpEneaBuffer(const sp<IBinder>& impl) : BpInterface<IEneaBuffer>(impl)
    {
    }

  sp<IMemoryHeap> getBuffer()
  {
    Parcel data, reply;
    sp<IMemoryHeap> memHeap = NULL;
    data.writeInterfaceToken(IEneaBuffer::getInterfaceDescriptor());
    // This will result in a call to the onTransact()
    // method on the server in it's context (from it's binder threads)
    remote()->transact(GET_BUFFER, data, &reply);
    memHeap = interface_cast<IMemoryHeap> (reply.readStrongBinder());
    return memHeap;
  }
};

IMPLEMENT_META_INTERFACE(EneaBuffer, "android.vendor.IEneaBuffer");

/* --- Server side --- */

status_t BnEneaBuffer::onTransact(uint32_t code, const Parcel& data, Parcel* reply, uint32_t flags)
{
  switch (code)
  {
    case GET_BUFFER:
    {
      CHECK_INTERFACE(IEneaBuffer, data, reply);
      sp<IMemoryHeap> Data = getBuffer();
      if (Data != NULL)
      {
        reply->writeStrongBinder(Data->asBinder());
      }
      return NO_ERROR;
      break;
    }
    default:
      return BBinder::onTransact(code, data, reply, flags);
  }
}

}; // namespace android

Then use it in your server class by inherit the server class with something like this:

Server command: EneaBufferServer.cpp

/*
 * EneaBufferServer.cpp
 *  Created on: 19 mars 2010  Author: Zingo Andersen
 *  License: Public Domain (steal and use what you like)
 *
 *  The Server will create a shared area that the client will then use
 *  The server will initiate the first int in the area and print it's value every
 *  5s. If you start the client in parallell it will try to change this value
 *  (value=value+1).
 */


#include "IEneaBuffer.h"
#include <binder/MemoryHeapBase.h>
#include <binder/IServiceManager.h>
#include <binder/IPCThreadState.h>

namespace android {

#define MEMORY_SIZE 10*1024  /* 10Kb shared memory*/

class EneaBufferService : public BnEneaBuffer {
public:
  static void instantiate();
  EneaBufferService();
  virtual ~EneaBufferService();
  virtual sp<IMemoryHeap> getBuffer();
private:
  sp<MemoryHeapBase> mMemHeap;
};

sp<IMemoryHeap> EneaBufferService::getBuffer()
{
  return mMemHeap;
}

void EneaBufferService::instantiate()
{
  status_t status;
  status = defaultServiceManager()->addService(String16("vendor.enea.Buffer"), new EneaBufferService());
}

EneaBufferService::EneaBufferService()
{
  //The memory is allocated using a MemoryHeapBase, and thereby is using ashmem
  mMemHeap = new MemoryHeapBase(MEMORY_SIZE);
  unsigned int *base = (unsigned int *) mMemHeap->getBase();
  *base=0xdeadcafe; //Initiate first value in buffer
}

EneaBufferService::~EneaBufferService()
{
  mMemHeap = 0;
}


static sp<IMemoryHeap> receiverMemBase;

unsigned int * getBufferMemPointer(void)
{
  static sp<IEneaBuffer> eneaBuffer;

  /* Get the buffer service */
  if (eneaBuffer == NULL)
  {
    sp<IServiceManager> sm = defaultServiceManager();
    sp<IBinder> binder;
    binder = sm->getService(String16("vendor.enea.Buffer"));
    if (binder != 0)
    {
      eneaBuffer = IEneaBuffer::asInterface(binder);
    }
  }
  if (eneaBuffer == NULL)
  {
    LOGE("The buffer service is not published");
    return (unsigned int *)-1; /* return an errorcode... */
  }
  else
  {
    receiverMemBase = eneaBuffer->getBuffer();
    return (unsigned int *) receiverMemBase->getBase();
  }
}


}

using namespace android;

int main(int argc, char** argv)
{
 unsigned int *base;

    EneaBufferService::instantiate();

    //Create binder threads for this "server"
    ProcessState::self()->startThreadPool();
    LOGD("Server is up and running");

    base = getBufferMemPointer();


    for(;;)
    {
     LOGD("EneaBufferServer base=%p Data=0x%x", base,*base);
     sleep(5);
    }
    // wait for threads to stop
    //   IPCThreadState::self()->joinThreadPool();
    return 0;
}

You need add the following line to register the service in the file frameworks/base/cmds/servicemanager/service_manager.c

{ AID_MEDIA, "vendor.enea.Buffer" },

On the client process side you can use something like the code snippet below to get the memory pointer.
NOTE: MemoryHeapBase is based on strong pointer and will be "magical" ref counted and removed thats why the client put the object pointer in a static variable in the example below to keep it from being removed.

/*
 * EneaBufferClient.cpp
 *  Created on: 19 mars 2010  Author: Zingo Andersen
 *  License: Public Domain (steal and use what you like)
 *
 *  Get the shared memory buffer from the server and change the first int value
 *  by adding one to it. The Server should be running in parallell pleas view
 *  the logcat for the result
 */


#include "IEneaBuffer.h"
#include <binder/MemoryHeapBase.h>
#include <binder/IServiceManager.h>

namespace android {
static sp<IMemoryHeap> receiverMemBase;

unsigned int * getBufferMemPointer(void)
{
  static sp<IEneaBuffer> eneaBuffer = 0;

  /* Get the buffer service */
  if (eneaBuffer == NULL)
  {
    sp<IServiceManager> sm = defaultServiceManager();
    sp<IBinder> binder;
    binder = sm->getService(String16("vendor.enea.Buffer"));
    if (binder != 0)
    {
      eneaBuffer = IEneaBuffer::asInterface(binder);
    }
  }
  if (eneaBuffer == NULL)
  {
    LOGE("The EneaBufferServer is not published");
    return (unsigned int *)-1; /* return an errorcode... */
  }
  else
  {
    receiverMemBase = eneaBuffer->getBuffer();
    return (unsigned int *) receiverMemBase->getBase();
  }
}

}

using namespace android;

int main(int argc, char** argv)
{
 // base could be on same address as Servers base but this
 // is purely by luck do NEVER rely on this. Linux memory
 // management may put it wherever it likes.
    unsigned int *base = getBufferMemPointer();
    if(base != (unsigned int *)-1)
    {
     LOGD("EneaBufferClient base=%p Data=0x%x\n",base, *base);
       *base = (*base)+1;
       LOGD("EneaBufferClient base=%p Data=0x%x CHANGED\n",base, *base);
        receiverMemBase = 0;
    }
    else
    {
     LOGE("Error shared memory not available\n");
    }
    return 0;
}

And my Android.mk file for this:

# Ashmem shared buffer example
# Created on: 19 mars 2010  Author: Zingo Andersen # License: Public Domain (steal and use what you like)

LOCAL_PATH:= $(call my-dir)

#
# BufferServer
#

include $(CLEAR_VARS)

LOCAL_SRC_FILES:=        \
 IEneaBuffer.cpp      \
 EneaBufferServer.cpp \
   
LOCAL_SHARED_LIBRARIES:= libcutils libutils libbinder

LOCAL_MODULE:= EneaBufferServer

LOCAL_CFLAGS+=-DLOG_TAG=\"EneaBufferServer\"

LOCAL_PRELINK_MODULE:=false
include $(BUILD_EXECUTABLE)

#
# BufferClient
#

include $(CLEAR_VARS)

LOCAL_SRC_FILES:=        \
 IEneaBuffer.cpp      \
 EneaBufferClient.cpp \
   
LOCAL_SHARED_LIBRARIES:= libcutils libutils libbinder

LOCAL_MODULE:= EneaBufferClient

LOCAL_CFLAGS+=-DLOG_TAG=\"EneaBufferClient\"

LOCAL_PRELINK_MODULE:=false
include $(BUILD_EXECUTABLE)

/Rebecka & Zingo

Everyone wants to learn more about Android

2010-02-04T20:00:00.000+01:00

It's been a really busy start on the new year here at the Enea Android Team. We've been fully occupied providing Android trainings all over the place. The whole Q1 is fully scheduled (if you're interested you could take a look in our training brochure at www.enea.com/android). On top of that we have MWC 2010 in Barcelona coming up, where we are working on a really cool demo. We apologize for not sharing with you this last month, but please stay tuned. Interesting posts will come shortly.

Enea Android Team

Using Android to control Lego Mindstorms

2010-02-03T11:23:00.000+01:00

This is a short post on the more entertaining side of Android showing a project that the Enea team in Linköping, Sweden, prepared for an expo. It is a one minute video from the demonstration.

It is two LEGO Mindstorms robots controlled by one HTC Hero Android phone. The Hero is running an Android application written by Enea Linköping that send motor commands to the LEGO brick. LEGO has been kind enough to put a Bluetooth chip in the Mindstorms NXT controller. By using the built in demonstrational Bluetooth commands the NXT brick provides there is no need for an application to be downloaded into the NXT brick.
There was however one obstacle in the limited Bluetooth support in Android OS version 1.5 (not supporting the Bluetooth serial port profile, SPP). Instead we used the wifi capabilities on the phone to send information to an Ubuntu Linux Laptop with a TCP/IP to Bluetooth tunnel (just a raw tunnel, no logic or programming). HTC has been rumored to be releasing Android OS version 2.1 (with Bluetooth) later in february and we hope to be able to put forth a new version that skip the WiFi laptop step.

Video below:

Adding a system server to the Android framework

2009-12-29T09:31:00.001+01:00

Following our other posts about booting and the system server, here are some more details of how to add a service to the system server.

It should be noted that extending the system server and other framework features is not recommended, as the code requires to be ported to future releases of the framework.
The most common reason for adding a system server would be for supporting proprietary hardware.

Design considerations
There are a few questions to be answered before implementing a system server, such as threads needed, application interfaces, and hardware interfaces. It's no easy task specifying your server design, but considering the following will hopefully help you out:
1. How frequently will the server run? If the server is only needed occasionaly, it might very well run within the system server context, even though the most common way is give it its own thread. A typical infrequent server is the Headset observer, which will only run when a headset is connected or removed.
2. How is the hardware accessed? Standard hardware could be accessible through device file access and file observers, but the best solution is no doubt to implement a HAL library. The HAL makes it easier to port your server to other hardware, and also makes it possible to run some functionality in native threads if needed.
3. Application interfacing? It is sometimes possible to get away with using intents and implementing your server as a receiver, but for anything but the simplest requests, you will no doubt have to use aidl.
4. Extending the framework? If you want to make your new interface visible to the applications, you will have to update the api description and build your own sdk. (That is easily done with "make update-api", followed by "make sdk".) However, if you only want the your nifty features to be accessible from your own proprietary applications, you should make use of the javadoc @hide-option for your interface.
5. Is there another way? Adding your own server adds migration work for new releases of the framework. To minimise files added, it's easy to be tempted to alter existing services instead of adding your own. That is fine to do, but keep in mind that if some functionality changes, third-party applications may not work anymore. Again, if your server will only be accessed from a proprietary application and not publicly available, consider adding the code to the application instead.

Code sample
Following is an example of a proprietary service, that knows how to set a value. For simplicity, the code is just added to the framework. For a production implementation, the code should go into the vendor directory.

Specifying the interface.
This example uses aidl, so the first step is to add an interface definition file:
frameworks/base/core/java/android/os/IEneaService.aidl

package android.os;

interface IEneaService {
/**
* {@hide}
*/
void setValue(int val);
}

The interface file will need to be added to the build system:
frameworks/base/Android.mk
Add the following around line 165 (the end of the list of SRC_FILES):

core/java/android/os/IEneaService.aidl \

Implementing the server
The service spawns a worker thread that will do all the work, as part of the system server process. Since the service is created by the system server, it will need to be located somewhere where the system server can find it.
frameworks/base/services/java/com/android/server/EneaService.java

package com.android.server;

import android.content.Context;
import android.os.Handler;
import android.os.IEneaService;
import android.os.Looper;
import android.os.Message;
import android.os.Process;
import android.util.Log;

public class EneaService extends IEneaService.Stub {
private static final String TAG = "EneaService";
private EneaWorkerThread mWorker;
private EneaWorkerHandler mHandler;
private Context mContext;

public EneaService(Context context) {
    super();
    mContext = context;
    mWorker = new EneaWorkerThread("EneaServiceWorker");
    mWorker.start();
    Log.i(TAG, "Spawned worker thread");
}

public void setValue(int val)
{
    Log.i(TAG, "setValue " + val);
    Message msg = Message.obtain();
    msg.what = EneaWorkerHandler.MESSAGE_SET;
    msg.arg1 = val;
    mHandler.sendMessage(msg);
}

private class EneaWorkerThread extends Thread{
    public EneaWorkerThread(String name) {
      super(name);
    }

    public void run() {
      Looper.prepare();
      mHandler = new EneaWorkerHandler();
      Looper.loop();
    }
}

private class EneaWorkerHandler extends Handler {
    private static final int MESSAGE_SET = 0;

    @Override
    public void handleMessage(Message msg) {
      try {
        if (msg.what == MESSAGE_SET) {
          Log.i(TAG, "set message received: " + msg.arg1);
        }
      } catch (Exception e) {
        // Log, don't crash!
        Log.e(TAG, "Exception in EneaWorkerHandler.handleMessage:", e);
      }
    }
}
}

You may want to add to the log printouts the thread id or name just to visualise which thread the code is executing in.

All that's left to do now is to type make to build the repository, and then start up the emulator. Using logcat, you will find the message saying that the thread has been spawned.

Test program
You probably want to test your service as well. For this you can create a "Hello World" activity using the project wizard. Place the project in the vendor/enea directory.

In the main activity class of your test program, add the following lines to onCreate()

IEneaService em = IEneaService.Stub.asInterface(ServiceManager.getService("EneaService"));
try {
em.setValue(7); // Any value would do, really.
} catch (Exception e) {
e.printStackTrace();
}

You will also need to import android.os.IEneaService and of course add an apropriate Android.mk to build your test program.

Start your test program and look in the log. You should now find the "set value"-messages.

Cheers
Robert

Howto setup a android project in Eclipse that access both Java and C/C++ code

2009-12-21T17:20:00.004+01:00

If you follow the instructions on http://source.android.com/using-eclipse you will only have a Java project and will only see the C/C++ project files as 2:nd class citizens without any indexing. I will propose a another solution that will combine the ideas from http://lorinc.blogspot.com/2006/10/how-to-mix-java-and-c-code-in-singe.html.
1. Copy the already available Java setup

$ cd <your mydroid folder>
$ cp development/ide/eclipse/.classpath .
# You might need to make the copy writable (describe on android.com) 
$ chmod u+w .classpath

2. From Eclipse create a new C++ project File -> New -> Other, select C/C++ -> C++ Project give it a project name and uncheck "Use default location"
and give it the path to your directory (often called the mydroid dir)
Select Project Type: "Makefile project" -> "Empty Project", let the "-- Other Toolchain" be selected and press "Finish"

3. Add in Java to the same project
Close Eclipse as you will edit a file it holds open and will overwrite otherwise Now a /.project file has been created open it in a text editor and add the following:

<buildCommand>
    <name>org.eclipse.jdt.core.javabuilder</name>
    <arguments></arguments>
</buildCommand>

and

<nature>org.eclipse.jdt.core.javanature</nature>

as described here:

<?xml version="1.0" encoding="UTF-8"?>
<projectdescription>
    <name>android zoom2</name>
    <comment></comment>
    <projects>
    </projects>
    <buildspec>
------------------------------- below is added 
        <buildCommand>
            <name>org.eclipse.jdt.core.javabuilder</name>
     <arguments>
     </arguments>
        </buildCommand>
------------------------------- end of the added stuff 
        <buildcommand>
            <name>org.eclipse.cdt.managedbuilder.core.genmakebuilder</name>
            <triggers>clean,full,incremental,</triggers>
...
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.eclipse.cdt.core.cnature</nature>
 <nature>org.eclipse.cdt.core.ccnature</nature>
  <nature>org.eclipse.cdt.managedbuilder.core.managedBuildNature</nature>
 <nature>org.eclipse.cdt.managedbuilder.core.ScannerConfigNature</nature>
------------------------------- below is added 
 <nature>org.eclipse.jdt.core.javanature</nature>
------------------------------- end of the added stuff 
    </natures>
...

Now start eclipse again, now the Java classes are available in "Project Explorer" view and C/C++ files in "C/C++ Projects" view.

One problem remain when you build it will use "make all" and that will not work and need to be changed to "make" this can be done if you right-click on the project and select "Properties"
In the "Properties" window select "C/C++ Build" and click on the "Behaviour" tab and remove "all" from all the places where available.

I still used the java heap enlargement in eclipse.ini from the first link by changing the numbers in eclipse.ini to the numbers below:

-Xms128m
-Xmx512m
-XX:MaxPermSize=256m

The standard eclipse from Ubuntu 9.10 (installed from synaptic) uses this file /usr/lib/eclipse/eclipse.ini you need to be root to edit it e.g.

$ sudo gedit /usr/lib/eclipse/eclipse.ini

/Zingo

2010-12-08 Edit: removed wrongly formated spaces around < and >

Ubuntu 9.10, Java 5 and the Android Open Source Project

2009-12-03T17:51:00.001+01:00

Currently there is an issue with building the Android Open Source project on Ubuntu 9.10 Karmic Koala, or more specific with the Java 5 support. Java 5 was obsoleted by Sun on October 30 2009 and is not part of the Ubuntu 9.10 distribution. However there is still a need to use Java 5 for building Android since Java6 is not yet supported. There are two methods to get Java5 working on Ubuntu 9.10.

Method 1 - download and install from Sun
This method will let you install the Java5 JDK in a separate directory and add it to the path when

Download the Java5 JDK for Linux from http://java.sun.com/javase/downloads/5u21/jdk
This is a binary file that you should save to a suitable location like ~/tools
In order to make i executable chmod the file as

$ chmod 777 jdk-1_5_0_21-linux-i586.bin

and run it

$ ./jdk-1_5_0_21-linux-i586.bin

This will install the jdk to the current directory.
To use the JDK5 tools you need to add it first in the path before building the Android Open Source Project

$ export PATH=~/tools/jdk1.5.0_21/bin:$PATH

This allows you to remove the JDK5 from the path when not building Android and use the standard Java settings instead.

Method 2 - use the Ubuntu 9.04 repositories to get Java5
This method adds the Jaunty repositories and installs Java5 as the default java setting in the system. Open the sources file (/etc/apt/sources.list) for editing, as root

$ sudo gedit /etc/apt/sources.list

and add:

deb http://us.archive.ubuntu.com/ubuntu/ jaunty multiverse
deb http://us.archive.ubuntu.com/ubuntu/ jaunty-updates multiverse

save the file and close gedit. Next sync your sources by running

$ sudo apt-get update

and install

$ sudo apt-get install sun-java5-jdk

To set the system to use Java 5 you need to update your java alternatives by running

$ sudo update-alternatives --config java

Choose java-1.5.0-sun and you should be done.

Hopefully the Android Open Source Project will build with Java 6 shortly but the above solutions should get you going with platform work on Ubuntu 9.10.

Train Tracker - our first Android application

2009-11-20T13:25:00.005+01:00

Even though application development has not been the main focus of the Enea Android Competence Center we decided to give it a try in order to widen our knowledge. For a couple of weeks we have been working on an application called Train Tracker. The application is mainly aimed to be used as an internal reference. The application shows real time train traffic information from Swedish train stations, some of the main features are:

Show all departing/arriving trains at a specific train station
Detect and warn for delayed trains.
Station search with auto complete text
Follow a train route (all arrival and departure times at all stations) for a specific train
Filter list of arrivals/departures (e.g. all departures from Lund towards Malmö)
Save a filter as a favourite. Favourites can be selected directly from the start page.
Set an alarm on train routes to get notified when the train is delayed.
Global search for stations and favourites integrated in Google Quick Search Box (Requires Android platform 1.6 or later and that Train Tracker is made searchable in Settings/Search/Searchable Items)

The information presented in the application is downloaded from http://banverket.se. Unfortunately Banverket was not willing to give us API access which is why our application is parsing HTML in order to get the information. This means that the application is likely to stop working if Banverket decides to change the layout of the webpage. Right now the application works quite well and if you want to try it out you can download TrainTracker.apk here, or use your favorite barcode scanner to get it:

Keep in mind that the application language is Swedish and it can only show information from Swedish trains and train stations. Here are some screenshots from Train Tracker:

Train Tracker start activity. Search for a station or select one of your saved favourites.

Train Tracker station activity. In this view you will find all arrivals/departures of a specific station.

Train Tracker filter activity. Here you can filter the list of arrivals/departures. Select “Spara Filter” to save the filter as a favourite. Select “Använd Filter” to apply the selected criteria.

Back at the station activity. This time filtered with the selected filter criteria and one of the departures has been expanded. Tapping the “Aktivera alarm” line will schedule an alarm for train 1067. Tapping The “Tåg 1067” line will take you to the train route activity for this train.

Train Tracker train route activity. At this view we display all train stops for a specific train. At the top of the screen a train delayed notification is received.

Global search in Google Quick Search Bar. Search hits from Train Tracker shows up together with ordinary search hits. Search hits gain higher priority in the search result list as they are selected.

/Erik

Android report in Elektroniktidningen

2009-11-05T09:34:00.000+01:00

Recently I wrote an expert report on Android for Swedish magazine Elektroniktidningen. This has now been published as a downloadable pdf, as part of their Embedded Expert initiative.
The reports are in Swedish.
Look here for details. Other very interesting reports can be found over here

Regards
Robert

Examples on extending the framework

2009-10-16T13:47:00.000+02:00

This post covers a couple of examples that are available in the Android open source project that provide a good start to exploring the framework and the JNI implementations in Android. If you are working with Android Open Source Project on hardware and want to test adding new API:s to the platform without breaking the structure these examples are really good.

The reason you may want to do this is that you are creating a device with some new features that you want to be available for some specific applications shipped with the device. It is also a good exercise to run through in order to understand the frameworks used by Android. This is the preferred way to do this and to quote Dianne Hackborn on the official mailing lists (found here):

If you are going to allow the user to keep Market on their phone, and are adding any new features, please do this the official way: include your own shared library with the features that applications use, rather than having magic hacks in the framework for them.

The example for this reside in the vendor/samples folder in the Android open source project. There are several components in this example:

The PlatformLibraryExample code itself which is a sample native library implementing some example platform functionality.
A java library that interfaces the platform library through JNI and exposes the API:s to applications.
A sample client application that uses this functionality

It is even possible to create an SDK add-on in order to have the added features easily available when developing applications. We will talk more about SDK add-ons in a later post.

To understand what is in this sample start out by reading the readme file in vendor/sample/frameworks/PlatformLibrary. This file describes the above components in more detail and will also tell you what you need to know in order to test the framework additions on a system.

If you are like us and like to try things out on the platform and work directly with some features that are not currently available in Android it is a good thing to follow these examples. It removes the need for making changes directly in the framework when exploring the possibilities of the platform.

/Mattias

Officially a competence center

2009-09-07T11:24:00.000+02:00

There was an announcement today that the Android team here at Enea have now officially morphed into the Enea Android Competence Center. Based on this it seems fitting to add a more general post here. Currently we are engaged in some external projects which I can't say very much about except the info on the new and expanded Android section on Enea's web site. But there is also a lot of other activity in the team.

We have some application work going on where we aim to have something useful to share in a month or so. We also use that project to explore some areas around testing for Android and it is our intention to have some testing and application articles up here on the blog soon.

In the lower layers we have been working a lot with the platform framework, build system and start up as you may know if you have been following the blog. Currently we are moving into the areas of performance and security and plan some activities around that in the coming months. This will probably reflect on the blog as well.

During the summer we have been preparing flexible Android training with a focus on the platform level and that will be a part of what we offer in the competence center. There are some great people from the team that will lead these trainings. This does not mean that we will stop sharing things here on the blog. It is a way to offer some personal hands-on training for those of you who want to know more.

The blog will remain a place for mostly technical articles and discussion but now you know a little bit more about us and what we aim to discuss here in the coming months. The team is very happy with this change since it means that we are now an official part of Enea and will be able to keep working on fun projects for that very interesting mobile technology platform known as Android.

/Mattias

Starting an Android service after boot

2009-09-01T15:06:00.001+02:00

After some consideration we decided that we should have a post about adding a regular Android service at boot and not just consider the cases where you have to modify the platform itself.

Simple boot service example

The key to this is the broadcast action android.intent.action.BOOT_COMPLETED that is sent out once the platform boot is complete. To perform an action on boot you need to include a broadcast receiver in your application that registers for this intent. The rest of the implementation follows the standard design for Android services and applications.
I have a small example that adds an Android service to perform a similar task as the native service that we had in the blog post about the init process. The service will start up at boot and then write something to the log at regular intervals. The first part we need is the broadcast receiver to take care of the boot intent:

package com.enea.training.bootdemo;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

/**
 * Simple receiver that will handle the boot completed intent and send the intent to 
 * launch the BootDemoService.
 * @author BMB
 *
 */
public class BootDemoReceiver extends BroadcastReceiver {
 @Override
 public void onReceive(final Context context, final Intent bootintent) {
  Intent mServiceIntent = new Intent();
mServiceIntent.setAction("com.enea.training.bootdemo.BootDemoService");
  context.startService(mServiceIntent);
 }
}

This component is basic and it will just create an intent to start our background service when it receives the boot completed intent.

The service will create a Timer task to write to the log at a preset interval. Once it is started the timer task will be registered and the service will keep running in the background.

package com.enea.training.bootdemo;

import java.util.Timer;
import java.util.TimerTask;

import android.app.Service;
import android.content.Intent;
import android.os.IBinder;
import android.util.Log;

/**
 * Simple demo service that schedules a timer task to write something to 
 * the log at regular intervals.
 * @author BMB
 *
 */
public class BootDemoService extends Service {
 /**
  * Delay until first exeution of the Log task.
  */
 private final long mDelay = 0;
 /**
  * Period of the Log task.
  */
 private final long mPeriod = 500;
 /**
  * Log tag for this service.
  */ 
 private final String LOGTAG = "BootDemoService";
 /**
  * Timer to schedule the service.
  */
 private Timer mTimer;
 
 /**
  * Implementation of the timer task.
  */
 private class LogTask extends TimerTask {
  public void run() {
   Log.i(LOGTAG, "scheduled");
  }
 }
 private LogTask mLogTask; 
 
 @Override
 public IBinder onBind(final Intent intent) {
  return null;
 }
 
 @Override
 public void onCreate() {
  super.onCreate();
  Log.i(LOGTAG, "created");
  mTimer = new Timer();
  mLogTask = new LogTask();
 }
 
 @Override
 public void onStart(final Intent intent, final int startId) {
  super.onStart(intent, startId);
  Log.i(LOGTAG, "started");
  mTimer.schedule(mLogTask, mDelay, mPeriod);
 }
}

There is one more important thing to consider for this simple demo application and that is to add the correct intent-filters to the Android.xml file. We need to register for the BOOT_COMPLETED intent but also for the intent that will start the actual service.

< ?xml version="1.0" encoding="utf-8"?>
< manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.enea.oresund.training.bootdemo"
      android:versionCode="1"
      android:versionName="1.0">
      < uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    < application android:icon="@drawable/icon" android:label="@string/app_name">
       < service android:name=".BootDemoService">
       < intent-filter>
       < action
       android:name = "com.enea.training.bootdemo.BootDemoService">
       < /action>
       < /intent-filter>
       < /service>
       < receiver android:name=".BootDemoReceiver">
       < intent-filter>
       < action
       android:name ="android.intent.action.BOOT_COMPLETED">
       < /action>
       < /intent-filter>
       < /receiver>
    < /application>
    < uses-sdk android:minSdkVersion="3" />
< /manifest>

Summary - adding functionality at startup

With this post I think that we have covered the alternatives for adding functionality at some point during the boot process. To sum things up there is three possible places to do something like this:

Modifying the init.rc script for native services
Modifying the system server to include a separate thread
Writing a standard Android service and register to launch it through the BOOT_COMPLETED intent

There may be other tricks you could use but they are more far-fetched. Unless you are building your own hardware or playing with the open source project for fun the third alternative is the only possible option. This is useful to register alarms or maybe an IM-client running in the background.
I would however like to add a word of caution since running services in the background will take some resources from the system. Think carefully about if you really need to automatically launch your service every time the system has booted up. It may be better to let the user choose when to start your application in order to save some system resources.

/Mattias

The init process and init.rc

2009-08-28T09:55:00.001+02:00

In this post I will wrap up the analysis of what is going on at boot by looking at the Android init process and the init.rc file. If we start with the source you will find the code for the init process under /system/core/init in the source tree. The init process is what will set up all native services and this is similar to a regular Linux system boot. At this stage we are not executing in the actual android runtime. There is however some Android specifics going on already at this level. One example of this is that the init.rc script is written in a specific format called the Android init language. This is covered in the readme file that is kept in the same directory as the init source. Since I have not seen very much about it on the net though I will post some of the main concepts here. I will also give a small example on how to add your own native service at startup.

The Android init language
The language used by the init process has four classes of statements. These are actions, commands, services and options. Actions are associated to commands in the way that an action is a sequence of commands. An action also need something called a trigger in that the sequence of commands will be executed when the trigger event has occured. An exemple may look like:

on boot
ifup lo
hostname localhost
domainname localdomain

This action will run a command sequence to set up basic networking once it receives the boot trigger. The supported commands include export, chmod, chown and a few others. The complete list of available commands can be found in the readme file.
Services are programs that are launched by init. They are associated with options which control how they are started. The syntax for starting a service is:
service < name > < pathname > [< argument > ]*
< option >
< option >
...
There is a number of options available and a few of them are:
critical - this is a critical process and init will restart the device if it exists more than four times in four minutes
user < username > - change to this username before executing the service
group < groupname > [< groupname > ]* - change to groupname before executing the service
setenv < name > < value > - set environment variable < name > to < value > in the launched process
The init script is also the place where some important system properties are set. This is done with the setprop command and include things like the memory thresholds for applications, tcp buffer sizes etc.
The init.rc file itself is found in the root directory on a device and in the source tree it is kept under system/core/rootfs. The below example is the actual init.rc file that I have shortened significantly. The basic concepts are clearly illustrated. First there is an action on init where a long sequence of commands is run. As you can see it is accepted to use comments and they are preceded by #. A number of variables are setup during init and file systems are mounted. The next step is the boot action where networking is set up and properties assigned to the system. Then there is a list of services to be started by init.

on init
sysclktz 0
loglevel 3
# setup the global environment
export PATH /sbin:/system/sbin:/system/bin:/system/xbin
export LD_LIBRARY_PATH /system/lib
export ANDROID_BOOTLOGO 1
export ANDROID_ROOT /system
...
# mount mtd partitions
1. 
Mount /system rw first to give the filesystem a chance to save a checkpoint
mount yaffs2 mtd@system /system
mount yaffs2 mtd@system /system ro remount
2. 
We chown/chmod /data again so because mount is run as root + defaults
mount yaffs2 mtd@userdata /data nosuid nodev
chown system system /data
chmod 0771 /data
...
on boot
# basic network init
ifup lo
hostname localhost
domainname localdomain
# set RLIMIT_NICE to allow priorities from 19 to -20
setrlimit 13 40 40
# Define the oom_adj values for the classes of processes that can be
# killed by the kernel. These are used in ActivityManagerService.
setprop ro.FOREGROUND_APP_ADJ 0
setprop ro.VISIBLE_APP_ADJ 1
setprop ro.SECONDARY_SERVER_ADJ 2
setprop ro.BACKUP_APP_ADJ 2
setprop ro.HOME_APP_ADJ 4
setprop ro.HIDDEN_APP_MIN_ADJ 7
setprop ro.CONTENT_PROVIDER_ADJ 14
setprop ro.EMPTY_APP_ADJ 15
...
## Daemon processes to be run by init.
##
service console /system/bin/sh
console
# adbd is controlled by the persist.service.adb.enable system property
service adbd /sbin/adbd
disabled

Starting your own service at boot.
Normally there is not much need to do things in the init script and start services of your own. What is provided in the system goes a long way and often it may be better to add something to the Android runtime instead of using the native services. If you have a reason to add something or just what to try things out however it is relatively straight forward to add a native service to that init sequence. I have created a simple example that writes the time elapsed since it started to the log. It wakes up every three seconds. The code for exampleservice.c looks like:

#define LOG_TAG "Example Service"
#include < utils/log.h >
#include < unistd.h >
int main(int argc, char **argv)
{
    LOGI("Service started");
    int elapsed = 0;
    while(1)
    {
         sleep(3);
         elapsed += 3;
         LOGI("Service elapsed time is %d", elapsed);
    }
}

Place this somewhere in the platform build system and build as an executable. The build system will place the output in the /system/bin folder on the device. Now all that is needed is to add the following to the init.rc script:

service exampleservice /system/bin/exampleservice
user exampleservice
group exampleservice
oneshot

and your service will start on init. It is also possible to write your own file using the Android init language that enables your services and variables. Then just add a line to import the file in init.rc and you are done.
/Mattias

Back after the summer with some NDK comments

2009-08-25T23:41:00.003+02:00

Time to pick up on the blog again after a summer where parts of the team have been on vacation and others have been hard at work in a couple of projects. In the mean time the Android platform has continued to evolve and a few things can be mentioned here:

1. The kernel has been removed from the Android manifest file and now requires a separate git pull if you are interested in it:


git clone git://android.git.kernel.org/kernel/common.git

This will save some time when syncing the repo and since the kernel was built outside the Android build system anyway it makes sense to keep it separated.

2. The NDK (Native Development Kit) was released allowing some support for native code in Android applications.
Making it possible to use native functionality in applications have been on the wish list for a long time and this is the first step in that direction. The list of supported API:s is very short though. The NDK currently supports:

libc (C library) headers
libm (math library) headers
JNI interface headers
libz (Zlib compression) headers
liblog (Android logging) header
A Minimal set of headers for C++ support

A c library combined with math and some logging capabilities provide enough for a some powerful algorithm implementations but to be of broader interest some more API:s are probably necessary. Natural candidates would be graphics support (openGL) and maybe some codecs. Currently the NDK is a good way to experiment with native functionality without going through the hoops of learning all about the platform and build system. For some applications it may also be exactly what is needed.

It looks like things will be picking up for the Android team during the fall and we aim to keep posting interesting tidbits here.

/Mattias

The System Server in Android

2009-07-01T16:41:00.005+02:00

In this post I will add some more detail on the system server in Android. The system server is the core of the Android system and as described in the boot sequence post it is started as soon as Dalvik is initialized and running. The other system services will be running in the context of the System Server process. We will start by looking at the code that runs when the System Server starts. This code is found in the file frameworks/base/services/java/com/android/server/SystemServer.java (in the open source project tree) and we will start this discussion from the main entry point.


 /** 
     * This method is called from Zygote to initialize the system. This will cause the native 
     * services (SurfaceFlinger, AudioFlinger, etc..) to be started. After that it will call back
     * up into init2() to start the Android services.
     */ 
    native public static void init1(String[] args);

    public static void main(String[] args) {
        // The system server has to run all of the time, so it needs to be
        // as efficient as possible with its memory usage.
        VMRuntime.getRuntime().setTargetHeapUtilization(0.8f);
        
        System.loadLibrary("android_servers");
        init1(args);
    }

    public static final void init2() {
        Log.i(TAG, "Entered the Android system server!");
        Thread thr = new ServerThread();
        thr.setName("android.server.ServerThread");
        thr.start();
    }

The first thing that happens is that the server will load a native library called android_servers that provides interfaces to native functionality. Source files for this lib are placed in frameworks/base/services/jni/. Then the native init method that will setup native services is called, init1(args), and executed. The name of the function that implements this is system_init() and the it resides in frameworks/base/cmds/system_server/library/system_init.cpp. After setting up the native services there is a callback:


runtime->callStatic("com/android/server/SystemServer", "init2");

to init2() above to create the server thread. This thread will start the remaining services in the system according to the necessary start order. A snippet of the initial sequence gives:


 // Critical services...
        try {
            Log.i(TAG, "Starting Power Manager.");
            power = new PowerManagerService();
            ServiceManager.addService(Context.POWER_SERVICE, power);

            Log.i(TAG, "Starting Activity Manager.");
            context = ActivityManagerService.main(factoryTest);

            Log.i(TAG, "Starting telephony registry");
            ServiceManager.addService("telephony.registry", new TelephonyRegistry(context));

            AttributeCache.init(context);

            Log.i(TAG, "Starting Package Manager.");
            pm = PackageManagerService.main(context,
                    factoryTest != SystemServer.FACTORY_TEST_OFF);

            ActivityManagerService.setSystemProcess();

            mContentResolver = context.getContentResolver();

            Log.i(TAG, "Starting Content Manager.");
            ContentService.main(context,
                    factoryTest == SystemServer.FACTORY_TEST_LOW_LEVEL);

            Log.i(TAG, "Starting System Content Providers.");
            ActivityManagerService.installSystemProviders();

            Log.i(TAG, "Starting Battery Service.");
            BatteryService battery = new BatteryService(context);
            ServiceManager.addService("battery", battery);

            Log.i(TAG, "Starting Hardware Service.");
            hardware = new HardwareService(context);
            ServiceManager.addService("hardware", hardware);

            // only initialize the power service after we have started the
            // hardware service, content providers and the battery service.
            power.init(context, hardware, ActivityManagerService.getDefault(), battery);

            Log.i(TAG, "Starting Alarm Manager.");
            AlarmManagerService alarm = new AlarmManagerService(context);
            ServiceManager.addService(Context.ALARM_SERVICE, alarm);

...

We see that the power manager is started first, followed by the activity manager and the other services. There are a lot more services started after these initial and if you are interested take look in the SystemServer.java file. Each service is running in a separate Dalvik thread in the SystemServer process. To give some info on the components making up the system server we may have look at it using the DDMS tool:

We see that the main Android services such as the activity manager, package manager, alarm manager etc. are running in their separate threads but as parts of the system server process.

/Mattias

The Android boot process from power on

2009-06-11T10:56:00.010+02:00

Since mobile platforms and embedded systems has some differences compared to Desktop systems in how they initially start up and boot this post will discuss the initial boot stages of an Android phone in some detail. Since we have used the Beagle Board as reference in some previous examples any specifics here are related to a similar system.

1. Power on and boot ROM code execution
At power on the CPU will be in a state where no initializations have been done. Internal clocks are not set up and the only memory available is the internal RAM. When power supplies are stable the execution will start with the Boot ROM code. This is a small piece of code that is hardwired in the CPU ASIC. For more information on boot ROM and configurations study the initalization chapter in
the Omap 3530 TRM.

A. The Boot ROM code will detect the boot media using a system register that maps to some physical balls on the asic. This is to determine where to find the first stage of the boot loader.
B. Once the boot media sequence is established the boot ROM will try to load the first stage boot loader to internal RAM. Once the boot loader is in place the boot ROM code will perform a jump and execution continues in the boot loader.

2. The boot loader
The boot loader is a special program separate from the Linux kernel that is used to set up initial memories and load the kernel to RAM. On desktop systems the boot loaders are programs like GRUB and in embedded Linux uBoot is often the boot loader of choice. Device manufacturers often use their own proprietary boot loaders. The requirements on a boot loader for Linux running on an ARM system can be found in the Booting document under /Documentation/arm in the kernel source tree.

A. The first boot loader stage will detect and set up external RAM.
B. Once external RAM is available and the system is ready the to run something more significant the first stage will load the main boot loader and place it in external RAM.
C. The second stage of the boot loader is the first major program that will run. This may contain code to set up file systems, additional memory, network support and other things. On a mobile phone it may also be responsible for loading code for the modem CPU and setting up low level memory protections and security options.
D. Once the boot loader is done with any special tasks it will look for a Linux kernel to boot. It will load this from the boot media (or some other source depending on system configuration) and place it in the RAM. It will also place some boot parameters in memory for the kernel to read when it starts up.
E. Once the boot loader is done it will perform a jump to the Linux kernel, usually some decompression routine, and the kernel assumes system responsibility.

3. The Linux kernel
The Linux kernel starts up in a similar way on Android as on other systems. It will set up everything that is needed for the system to run. Initialize interrupt controllers, set up memory protections, caches and scheduling.

A. Once the memory management units and caches have been initialized the system will be able to use virtual memory and launch user space processes.
B. The kernel will look in the root file system for the init process (found under system/core/init in the Android open source tree) and launch it as the initial user space process.

4. The init process
The init process is the "grandmother" of all system processes. Every other process in the system will be launched from this process or one of its descendants.

A. The init process in Android will look for a file called init.rc. This is a script that describes the system services, file system and other parameters that need to be set up. The init.rc script is placed in system/core/rootdir in the Android open source project.
B. The init process will parse the init script and launch the system service processes.

5. Zygote and Dalvik
The Zygote is launched by the init process and will basically just start executing and and initialize the Dalvik VM.
6. The system server
The system server is the first java component to run in the system. It will start all the Android services such as telephony manager and bluetooth. Start up of each service is currently written directly into the run method of the system server. The system server source can be found in the file frameworks/base/services/java/com/android/server/SystemServer.java in the open source project.

7. Boot completed
Added this part to the post on 20090831 since it is very useful and something I should not have left out from the beginning. Once the System Server is up and running and the system boot has completed there is a standard broadcast action called ACTION_BOOT_COMPLETED. To start your own service, register an alarm or otherwise make your application perform some action after boot you should register to receive this broadcast intent.

The separate boot steps and possible places to add your own functionality are covered in more detail in separate posts.

/Mattias

A closer look at the Android project build system part II

2009-04-27T15:42:00.005+02:00

This is the second post on the build system where we will take a closer look at the Android.mk file and what options are available. An Android.mk file describes the build for any native module that should go in the platform. We will start by looking at the makefile for the external ping facility found in external/ping.


ifneq ($(TARGET_SIMULATOR),true)

LOCAL_PATH:= $(call my-dir)

include $(CLEAR_VARS)
LOCAL_SRC_FILES:= ping.c
LOCAL_MODULE := ping
LOCAL_STATIC_LIBRARIES := libcutils libc
include $(BUILD_EXECUTABLE)

endif  # TARGET_SIMULATOR != true

The first line is just a check if we are building for the (obsolete?) simulator. The next line sets the local path to the current directory (the directory of this Android.mk file). This is handled by a function called mydir that can be found in the definitions.mk file in the build system.

The next step is to include a makefile that will clear all local variables with the line include $(CLEAR_VARS). CLEAR_VARS is set in the build configuration in config.mk and will include the clear_vars.mk file at this point. The main purpose of this include is to make sure that we do not use any local variables set by another module.

After the two initial lines that basically prepares the build system to start with this module we set the build variables. These are


LOCAL_SRC_FILES - the source files that make up this module
LOCAL_MODULE - the name of the module
LOCAL_STATIC_LIBRARIES - libraries to statically link to this module

Since ping will be an executable command placed in /system/bin in the Android file system the make file for building an executable should be used. This done with the line:


include $(BUILD_EXECUTABLE)

There are makefiles available in the build system that can be used to build a number of different types of module. To include them you may use one of the variables set in the config.mk file. A few important ones are:


BUILD_EXECUTABLE - Build an executable module
BUILD_SHARED_LIBRARY - Build a shared library
BUILD_STATIC_LIBRARY - Build a static library
BUILD_PREBUILT - Add prebuilt components

There is also a number of local variables that are recognized by the build system and that needs to be set in order to build your module.


LOCAL_C_INCLUDES - path to include files needed by your module, e.g. ($KERNEL_HEADERS)
LOCAL_CFLAGS - Any additional flags to pass to the compiler
LOCAL_LDFLAGS - Any additional flags to pass to the linker
LOCAL_SHARED_LIBRARIES - Shared libraries that the module directly links against
LOCAL_SRC_FILES - The source files to compile
LOCAL_STATIC_LIBRARIES - Static libraries to include in the module

You may use one Android.mk to build several items. It is possible to build both a library and an executable using the same makefile. To illustrate how to write a makefile for some native functionality we will look at another example. This makefile will build a shared library and an executable. It links to a couple of shared libraries in the system.


LOCAL_PATH:= $(call my-dir)

include $(CLEAR_VARS)
#Name of target to build
LOCAL_MODULE:= libmylibrary
#Source files to compile
LOCAL_SRC_FILES:= mysrcfile.c mysothersrcfile.c
#The shared libraries to link against
LOCAL_SHARED_LIBRARIES := libcutils
#No special headers needed
LOCAL_C_INCLUDES +=
#Prelink this library, also need to add it to the prelink map
LOCAL_PRELINK_MODULE := true
include $(BUILD_SHARED_LIBRARY)

#Clear variables and build the executable
include $(CLEAR_VARS)
LOCAL_MODULE:= myinfocmd
LOCAL_SRC_FILES:= mycmdsrcfile.c
include $(BUILD_EXECUTABLE)

The output of the build system is put in the out folder in the Android project. Build output is directed to a subfolder based on the product. A default build is for the generic product and will output everything target related to that folder. A shared library ends up in /out/target/product/generic/system/lib. In the same way an executable will end up in /out/target/product/generic/system/bin. The object files and intermediates are kept in the obj folder. The root, system, and data folders will be used to generate the file system images needed for Android in the last build step.

/Mattias

A closer look at the Android project build system part I

2009-04-24T15:40:00.008+02:00

In this two part post we will take a closer look at the structure of the build system for native functionality. The build system is based on make and resides in the build folder in the project. The first part will look at what is found in this folder while the second part discusses the Android.mk file and options.

envsetup.sh
There is one important file in build directory itself. That is the envsetup.sh file. This shell script contains a lot of functionality that is nice to have when working with Android. To invoke it type


. build/envsetup.sh

in the android root directory. This will allow you to use a number of new commands including:


m - make from the top of the tree
mm - builds all modules in the current directory
cgrep - grep in all c-files
jgrep - grep in all java-files
mgrep - grep in all makefiles
lunch - choose build target

These shell commands are very useful when working with the platform. Whether you are looking for something specific in a source file or you just want to build the current module for a test.

build/target
The target directory contains make configurations for different boards and products. The target directory is where new products can be added as needed by a hardware manufacturer. In the current release there is a generic product description, and sdk product and some other files. The available boards are the emulator, a generic board and the simulator.

The board makefiles describe the hardware platform level and can be shared among a number of products. For example you can build both the generic product and the generic_with_google product to run on in the emulator.

The makefiles for different products are listed in the file AndroidProducts.h. To add a new product put the makefile in the build/target/product folder and add the product to AndroidProduct.h. It is possible for product makefiles to inherit from each other to reduce the need for copying. The generic_with_google products inherits the generic product that inherits the core product to make up a three level product specification.

build/core
The core folder is the location of the build system files. These files are used to set up the build system and to build all the different modules as configured in the individual Android.mk files. The main.mk file is the entry point to the build system and it is this files that is included in the top level makefile in the project root directory. The build system can also be invoked by the shell command mm with at subset of the makefiles

The include order and hierarchy of the makefiles is rather complicated but an attempt of illustration can be found in this figure.

Most of the build configuration is set in the config.mk file and the definitions.mk file contains the functions to be invoked for the different source types. In the above figure the build system is invoked to build a shared library. The Android makefile uses the BUILD_SHARED_LIBRARY variable set in the config.mk file. This will set the build chain for building a shared library in a number of steps using several other files.

JNI hands on

2009-04-01T10:44:00.007+02:00

In the demo setup at the seminar we hijacked the SMS application to send a LINX signal using JNI. In this post I'll describe more in detail how we implemented it.

First you need to create a Java-class that loads the C-library and declares the method (send(...))

public class NativeLib {
    static {
        try {
            Log.i("JNI", "Trying to load libNativeLib.so");
            System.loadLibrary("NativeLib");
        }
        catch (UnsatisfiedLinkError ule) {
            Log.e("JNI", "WARNING: Could not load libNativeLib.so");
        }
    }
    public static native long send(String number, String message);
}

Call the method somewhere appropriate from your activity:

long sum = NativeLib.send(...);

Next, you need to generate C-headers from the NativeLib Java-class:

cd <path to eclipse project dir>/bin
javah <class name>

Create a directory nativelib in the <android root>/external directory and move the header file to here.

Now, implement the C-file (and remember to include your recently generated header-file)

#include "com_android_mms_transaction_NativeSms.h"

JNIEXPORT jlong JNICALL Java_com_android_mms_transaction_NativeSms_send
  (JNIEnv *env, jclass class, jstring number, jstring message)
{
  //Get the native string from javaString
  const char *numString;
  const char *messageString;

  numString = (*env)->GetStringUTFChars(env, number, 0);
  messageString = (*env)->GetStringUTFChars(env, message, 0);

  /*code to handle the sms info in native context goes here*/

/*release resources when done*/
  (*env)->ReleaseStringUTFChars(env, number, numString);  (*env)->ReleaseStringUTFChars(env, message, messageString);

 return 0;
}

Next, we will construct a make-file: name it Android.mk and put it in <android root>/external/nativelib. Fill it up with the following:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_SRC_FILES := %lt;name of C-file%gt;

LOCAL_SHARED_LIBRARIES := libcutils

LOCAL_C_INCLUDES += $(JNI_H_INCLUDE)

LOCAL_MODULE := libNativeLib

include $(BUILD_SHARED_LIBRARY)

Open file prelink-linux-arm.map in <android root>/build/core and add the row:

libNativeLib.so 0x9F400000

under comment:

# libraries for specific apps or temporary libraries

This will add your library to the prelink map. Make sure that the address is not used by anything else.
Now type make in Android root dir to build. Hopefully everything goes well and voila! You have implemented your native C-library

/Sebastian

Android seminar in Lund

2009-03-31T13:18:00.007+02:00

Our initial project in the Android team was to prepare a demo were we integrated the Enea message passing methods available in Linx with the Android platform. This demo was presented at our Android seminar in Lund, Sweden on March 10. The seminar was a success with more than 200 attendees from different companies in the wireless industry, among them ST Ericsson and Sony Ericsson. The breakfast session included a short presentation of embedded Linux in general as well as an overview of the Android mobile technology platform.

Our demo setup is illustrated below. The hardware we used for this setup was a beagle board running Android using the patches made by Embinux. The Linx kernel modules and libraries were cross compiled for the platform and added to the Android init scripts. We also created some test libraries to handle the communication.

The setup allowed a user to write and send an SMS via the standard Android SMS application. When the user press "send" we catch the number and message and call a native C-routine via Java Native Interfaces. This routine creates and sends a Linx signal to a Linux PC with a phone attached to the COM-port, acting as a modem. Finally the message is sent via AT-commands.

This way we created a demo that interacts with the real world and with a obvious effect!

Getting started with LINX on Android

2009-03-26T17:19:00.006+01:00

Initial LINX tests on Android were made using a beagle board running Android with patches from Embinux. To get started with LINX the following steps are needed:
Download the LINX source from SourceForge. To get an initial cross compiled build we need a matchning kernel. Currently just pointing out the kernel in the Android distro will not work since LINX will produce some build errors. This should be checked and maybe fixed later on.
The way we worked around was to compile LINX against a standard kernel with Android patches. In this case a 2.6.27 OMAP kernel. I.e the build command will look something like:

cd <path>make ARCH=arm CROSS_COMPILE=<path>/arm-none-linux-gnu-eabi- KERNEL=<path>

At this point we took the generated kernel modules and copied them to a suitable place in the Android file system. The rest of LINX currently needs to be statically linked by adding -static to the makefile gcc options. This is because it is not built as part of the android build system and c library. Then copy the binaries to the /system/bin library of Android.
An ownership change is also needed to make the commands run on android

sudo chown root.root <file>
sudo chmod 777 <file>

After this it is just a matter of starting up android and doing insmods using the shell. Links can be created with mklink.

/Mattias

Howto build sdk and plugin - copy'n'paste version

2009-03-26T15:38:00.005+01:00

The following commands are needed when building your own sdk and eclipse plugin.
In your homedir:


mkdir ~/repodir ~/plugindir ~/eclipse-android

cd ~/repodir

repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake

repo sync

source ./build/envsetup.sh

lunch 1

make

ECLIPSE_HOME=~/eclipse-android

./development/tools/eclipse/scripts/build_server.sh ~/plugindir

make sdk

The output files are:
~/plugindir/android-eclipse-v200903261355.zip (or whatever date it is)
~/repodir/out/host/linux-x86/sdk/android-sdk_eng.user_linux-x86.zip (replace 'user' with your username)

Not much info about what they do at the moment. Execute the commands in the specified order and it should work. If it doesn't - please comment and I will try to clarify.
/Robert