|
|
# How to create and run an AmbientTalk applications on Android.
|
|
|
|
|
|
# Introduction
|
|
|
|
|
|
This page details the steps to create and run an AmbientTalk application for Android.
|
|
|
|
|
|
Before starting you should have installed the Android SDK and the Android Development Tools (ADT) plugin for Eclipse [(instructions available in the Android developers site )](http://developer.android.com).
|
|
|
|
|
|
# Creating an AmbientTalk Android Project
|
|
|
|
|
|
Currently we don't have integrated support for creating AmbientTalk Android projects within Eclipse directly.
|
|
|
An AmbientTalk application consists of an Android Project containing the Android GUI code and the AmbientTalk script as an asset. In addition, the Android project must include the android-core library which is a wrapper around IAT to be able to setup the interpreter and run your AmbientTalk script. In what follows we detail the steps involved in this process.
|
|
|
|
|
|
- Checkout the "android-core" project located at https://ambienttalk.googlecode.com/svn/android-core/trunk . It will automatically configure itself.
|
|
|
- You may need to clean the project, as the SVN checkout overwrites some java compiler options.
|
|
|
- Create a new Android project for your AmbientTalk application.
|
|
|
- Add the jars of android-core to the classpath of your newly created project.
|
|
|
- Create an atlib folder under assets and store your AmbientTalk files there. For example, an AmbientTalk file loaded as `/.demo.weScribble` should be stored under `assets/atlib/demo/weScribble.at`.
|
|
|
- In order for your application to access the standard AmbientTalk library, you will need to subclass the `AssetInstaller` activity (provided by the android-core library) and start it in one of your Android activities.
|
|
|
As an example, consider the `AssetInstaller` activity for the WeScribble application.
|
|
|
```
|
|
|
public class WeScribbleAssetInstaller extends AssetInstaller {
|
|
|
public WeScribbleAssetInstaller() {
|
|
|
super();
|
|
|
development = true;
|
|
|
}
|
|
|
```
|
|
|
The default `AssetInstaller` will first copy the standard atlib (if necessary) and then your AmbientTalk files stored under `/assets/atlib`.
|
|
|
By setting the `development` flag to `true` in the constructor, the assets gets copied every time the application is run. This is useful while developing the application, but it is recommend to turn it off before releasing the application in the market.
|
|
|
Another activity can then start this asset installer as follows:
|
|
|
```
|
|
|
Intent i = new Intent(this, WeScribbleAssetInstaller.class);
|
|
|
startActivityForResult(i, 0);
|
|
|
```
|
|
|
|
|
|
If you would like to distribute your own atlib in the application:
|
|
|
1. Put your custom atlib under `assets/atlib`.
|
|
|
1. Make the constructor call the `AssetInstaller` constructor passing false, i.e. `super(false)`. This will copy your custom atlib over every time the application starts.
|
|
|
|
|
|
- Register your `AssetInstaller` activity in the manifest of the project.
|
|
|
- Add the following permissions in the manifest of the project.
|
|
|
```
|
|
|
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
|
|
|
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
|
|
|
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE"></uses-permission>
|
|
|
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
|
|
|
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"></uses-permission>
|
|
|
```
|
|
|
|
|
|
- Start IAT within your Android application. We strongly recommend you to do so in a different thread than the UI thread. You can use a AsyncTask to launch IAT as follows:
|
|
|
|
|
|
```
|
|
|
public class WeScribbleActivity extends Activity implements JWeScribble {
|
|
|
public static IATAndroid iat_;
|
|
|
|
|
|
public class StartIATTask extends AsyncTask<Void, Void, Void> {
|
|
|
@Override
|
|
|
protected Void doInBackground(Void... arg0) {
|
|
|
try {
|
|
|
iat_ = IATAndroid.create(WeScribbleActivity.this);
|
|
|
ATWeScribble atws = (ATWeScribble) iat_.evalAndWrap("/.demo.weScribble.weScribble.return", ATWeScribble.class);
|
|
|
atws.handshake(WeScribbleActivity.this);
|
|
|
} catch (Exception e) {
|
|
|
Log.d("portal-pong", "Could not create IAT", e);
|
|
|
}
|
|
|
return null;
|
|
|
}
|
|
|
}
|
|
|
...
|
|
|
```
|
|
|
|
|
|
In this snippet, ATWeScribble is a Java interface that is wrapped around an AmbientTalk object called `return`, which is defined as follows:
|
|
|
```
|
|
|
def return() {
|
|
|
def localInterface := object: {
|
|
|
def handshake(act) {
|
|
|
androidActivity := act;
|
|
|
};
|
|
|
// methods specific to the functionality of your application
|
|
|
....
|
|
|
};
|
|
|
};
|
|
|
```
|
|
|
|
|
|
`return` must give back the local interface of the AmbientTalk methods that can be called from Android code.
|
|
|
Using the `handshake` method, the AmbientTalk code can obtain a reference to the Android Activity.
|
|
|
Please look at [ http://soft.vub.ac.be/amop/tutorial Java symbiosis tutorial page] for further details.
|
|
|
|
|
|
|
|
|
# Running your AmbientTalk application
|
|
|
|
|
|
- Open the android SDK and AVD Manager. You will see its icon at the menu bar. Otherwise, go to Window -> Android SDK and AVD Manager.
|
|
|
|
|
|
![android/androidAVDManager](android/androidAVDManager.png)
|
|
|
|
|
|
- Go to the Virtual Devices view and click the button "New.." to create a new AVD (Android Virtual Device). Set the target to at least Android 2.2. We recommend 2.3 or higher, as they introduced a JIT compiler in that release.
|
|
|
|
|
|
![android/androidNewAVD](android/androidNewAVD.png)
|
|
|
|
|
|
- If you now click 'run' on your project, either an emulator will be launched or the application will be installed and run on your connected phone. Congratulations!
|
|
|
- If you want to force a specific run configuration to a specific device:
|
|
|
1. Add a new run configuration for the AmbientTalk android application. Select the menu item "Run -> Run Configurations.." then double-click "Android Application".
|
|
|
1. Go to the Target tab menu of the run configuration, click on "Automatic", and select your newly created AVD from the list.
|
|
|
1. Note: If a real device is connected, Android will try to deploy the application on the real device. Otherwise, it deploys the application on one of the AVD devices already running. If no AVD is already running it chooses one AVD of the list of available AVD in the system. If you have selected a preferred AVD device in the Target menu, it will chose this one.
|
|
|
|
|
|
# Making two instances of your AmbientTalk application running on the emulator discover each other
|
|
|
|
|
|
Dries modified the android sdk so that emulators can see each other in the network. However, not all of these patches have been accepted in the master branch yet.
|
|
|
|
|
|
In the meantime, you can set it up as follows:
|
|
|
|
|
|
- Instead of downloading the SDK starter from google, dowload the modified SDK at [here](http://soft.vub.ac.be/~dharnie/Files/modified-android-10.zip). It has libraries for both the newest API level 10 (Android 2.3.3).
|
|
|
|
|
|
- Create two AVDs (or more), make sure to pick the **latest version** (2.3.3 at the time of writing). Make sure they both have the sdcard with the AmbientTalk files.
|
|
|
|
|
|
- Create a run configuration for each AVD you intend to use: (You might have to make the window a bit bigger)
|
|
|
|
|
|
![android/androidRunConfig](android/androidRunConfig.png)
|
|
|
|
|
|
The `-shared-net-id` option determines which IP address the emulator will get in the shared network. Make sure the IDs are unique!
|
|
|
|
|
|
- That's it. You should be able to ping 10.1.2.X (X being the ID) and get a response from the other emulator.
|
|
|
|
|
|
# Troubleshooting
|
|
|
|
|
|
Here comes a list of common things to try when something goes wrong:
|
|
|
|
|
|
- Verify your application's permissions on the manifest.
|
|
|
- Clean your project (yes, sometimes that works :D).
|
|
|
- Check out the Android logcat.
|
|
|
- Check out the AmbientTalk interpreter log file. You can access it as follows:
|
|
|
```
|
|
|
/path-to-android-sdk/platform-tools/adb shell 'cat /sdcard/Android/data/edu.vub.at.android.atlib/files/at.log'
|
|
|
```
|
|
|
- Use the debugger. It even allows you to debug on the device itself!
|
|
|
- When things go wrong while running on a real device:
|
|
|
- Check that the phone/tablet has the "USB debugging connected" option enabled so that you can install application via USB. Remember also to enable the "Unknown resources" option so that you can install applications that have not been downloaded from the market.
|
|
|
- If you have a phone working with an external sdcard, remember not to mounted it since the application stores the AmbientTalk files under the assets folder on the sdcard.
|
|
|
- You may get an application launch cancelled if the application was already installed on the phone but using a different application signature (i.e. you install it using a different computer). You just need to uninstall it on the phone, and try again.
|
|
|
- Some older phones (e.g. HTC hero) may experience problems when they run without SIM card. Most of the times it is solved by a reset, and reinstalling the application.
|
|
|
|
|
|
|
|
|
|
|
|
|