Using the Plugin Quickstart Maven Archetype

This tutorial assumes that you have a basic understanding of maven and the underlying principals and that maven is installed on your machine and accessible from the command line. If you need some more information about maven, you can get an overview here: Maven geting started guide I also assume you have read through the plugin development tutorial and are familiar with the general concepts of dynamix plugin development. I assume Dynamix is installed and running on your phone

Generating a Sample Plugin Project:

Open a command line interface in the location you want to create the new project and enter the following line:

mvn archetype:generate -DarchetypeGroupId=org.ambientdynamix.contextplugins -DarchetypeArtifactId=DynamixPluginQuickStart-Archetype -DarchetypeVersion=2.1.5 -DarchetypeCatalog=http://dynamix.io/dynamix/maven/

You will be queried to provide a group id (we use "org.ambientdynamix.contextplugins"), an artifactid which will be the name of your plugin, a version number and a package, which will be the package all your java classes will be generated into (we use "org.ambientdynamix.contextplugins.[plugin name]").

Confirm with 'Y' and maven generates a sample plugin project for you which reads out the battery level and makes it available through dynamix

Let's take a look at the generated Project structure:

The generated project is composed out of three maven modules:

The Core

The Core module contains all the plugins business logic, such as the plugin factory and the actual plugin implementation

The Datatypes

The Datatypes module contains all the Data classes associated with the context types provided by the plugin as well as the corresponding aidl files. This has to be in a separate module, so other native dynamix apps that support these context types can import them as a dependency.

The Testapp

The Testapp module is a very simple native Dynamix android app, that allows you a quick and simple way to invoke your plugin and query for the context types it provides. This will be explained later.

You can now import the generated plugin project to your favorite IDE by using its respective maven project import methods and maven should take care of all the dependency management, build path settings etc. but you can also stay on the command line to perform the following steps to deploy and run your generated plugin.

Compiling and deploying the plugin:

To compile and deploy the project to a phone, make sure you have a single device connected to your computer via USB execute the mvn install goal on the root project, by using your IDE features or byu simply typing it into a command line interface in your projects root directory. This will compile and package the project and will also deploy the plugin jar to the phone, into the /dynamix directory. It also generates the necessary OSGI Manifest and plugin descriptor for you.

Using the TestApp to invoke the plugin:

The testapp provides a simple configurable framework to invoke any number of context plugins. It consists of two classes, the bindDynamixActivity, which handles all the connecting to dynamix and the gui. You should not touch this class, but feel free to have a look at the source code to understand the underlying connection procedure of native apps. The second class "PluginInvoker" is managing which plugins are to be invoked by the TestApp.

A context request in dynamix consists of three parameters, A plugin id, a context type and an optional configuration bundle.

To configure a context request to be performed by the invoker, call the addPluginInvocation(String pluginId, String contextType, Bundle configuration) method in the PluginInvoker's constructor.

public PluginInvoker() {
        pluginInvocations = new Vector<PluginInvocation>();

//        Add plugin invocations by calling addPluginInvocation(pluginId,context type, configuration)
        addPluginInvocation("org.ambientdynamix.contextplugins.quickstart","org.ambientdynamix.contextplugins.quickstart.mybatterylevel",null);

    }

The BindDynamixActivity will execute all the configured pluginInvocations and call the PluginInvoker's "invokeOnResponse(ContextEvent event)" methos if it receives a response that corresponds to a request type configured by you.

You can run the TestApp by either navigating into the TestApp directory on your commandline and execute mvn android:deploy android:run or by using the support functions of your IDE. After startup you should see the test app application screen. Press connect to connect to dynamix on your phone. The connect Event will uninstall all installed plugins, so you always start from a clean slate with the newly uploaded plugin version. Pressing "invoke plugin" will send all the plugin requsts you configured in the PluginInvolker's constructor and call the "invokeOnResponse(ContextEvent event)" method if a response was received. Make sure to also observe the Android logging console to see what's going on.

The TestApp also has an "experimental" option to run the invocations without human interaction. To do so set the

public static final boolean AUTOMATIC_EXECUTION = false;

variable to true. If you do so you will only see a black screen on startup and all the connection and invocation will be performed automatically. However this approach does not work in all cases due to timing issues.

If you have made it this far, congratulations, you are ready to start developing your new dynamix plugin.