This guide will help you understand how to build native Android applications that leverage Dynamix 2’s new features and streamlined development model. Using Dynamix, you can quickly and easily create next generation IoT applications that fluidly interact with the physical world through advanced sensing, control and actuation plug-ins that can be installed into the user’s device on-demand. Android apps interact with Dynamix through a simple AIDL-based interface, which provides easy-access to Dynamix methods and events. The following sections describe how to integrate Dynamix into your next Android project.

To clone the Dynamix API into your next project, use the following GIT command:

Or you can download the complete example used throughout this guide by checking out the Dynamix 2 Android Logger project, as follows:

If you’re using Eclipse, import the example project using “Import Existing Android Code into Workspace”, as shown below.



Download Dynamix!

Grab the latest Dynamix Framework.

Dynamix Integration

Once you’ve imported the example code, take a look at the project’s Java build path. Note that the Dynamix API JAR is listed on the build path along with several datatype JARs. The Dynamix API JAR allows the application to communicate to Dynamix over AIDL, and the data-type JARs allow the application to interpret context data coming from the various plug-ins. If you’re creating your own project, simply copy the Dynamix API JAR to your project and include it on your build path. You should also download any needed plug-in context data type JARs and include them on your build path as well, making sure that the Dynamix API JAR and any context data type JARs are exported with your project. If you’re JARs are included outside of “libs”, make sure all JARs are checked under “Order and Export”, as shown below:


Time-saving tip: If you’re using Eclipse, drop the Dynamix JAR and data-type JARs into your project’s “libs” folder and you’re done! No library import or export settings are necessary when using the “libs” folder.

Note that it’s not required to include the data-type JARs in your projects; however, it’s much more convenient since your app will be able to access data coming from plug-ins using native objects rather then strings. Take a look at each Dynamix plug-in’s documentation page for details on how to download its data-type JAR and interpret it’s string-based data representations (if supported).

Connect to Dynamix

To connect your app with the local Dynamix service, use the DynamixConnector (included in the API JAR) as follows:

By using the SessionCallback (shown above), it’s easy to handle asynchronous calls to Dynamix. Note that most methods for interacting with Dynamix include similar callbacks. There are several variants of the ‘openConnection’ method. In the method above, we pass a boolean ‘true’ as the second argument, which automatically opens a session with Dynamix. In addition, we also pass in a ‘sessionListener’ as the third argument, allowing our app to receive events related to its Dynamix session.  The session listener can be defined as follows.

Create a Context Handler

Once your app is connected to Dynamix and has an open session, the next step is to create a Context Handler, which is an object that can be used to setup, control and remove Context Support from a connected Dynamix instance. Context Support performs the actual work of sensing, actuation and/or control within the connected Dynamix instance (discussed next). You can use multiple Context Handlers to logically group the Context Support needed by your application, or use a single Context Handler for simplicity or experimentation. The example below shows how to use the ‘dynamix’ facade object (see the code snippet above) to create a Context Handler.

Add Context Support

Once you’ve created a Context Handler in your app, it’s time to start interacting with your physical environment using Dynamix! The first step is to use your newly created Context Handler to install Context Support, such as the ability to detect heart rate, calculate indoor location using iBeacons, or control nearby devices. Browse the Dynamix plug-ins using this link to find Context Support for your app (note down the plug-in id and context type strings you’d like to use). You can install Context Support through a single method call (see code below); Dynamix automatically handles the discovery, installation, and runtime behavior of requested plug-ins. To add Context Support to your application, reference the plug-in id and context type strings you noted down previously by utilizing your previously created Context Handler, as shown below.

Once Context Support is installed for your application, you are now ready to use Dynamix to interact with the physical world. Before we move on, here’s the complete example of connecting to Dynamix, adding a Context Handler, and installing Context Support for detecting the device’s battery level (using callback chaining to simplify asynchronous interactions with Dynamix).

Interacting with Context Support

After Context Support has been installed, your application can now receive context events and/or control connected devices. The way you interact with Context Support depends on the specified plug-in (see each plug-in’s documentation for details). Some plug-ins run autonomously in the background broadcasting events as needed, whereas others require the app to trigger sensing or control operations. In the example above, the battery level plug-in will start sending context results to the provided ‘batteryLevelListener’ whenever the device’s battery level changes. Take a look at the ‘batteryLevelListener’ below for information on how to extra both general metadata about the results (e.g., the source plug-in) as well as specific result data (e.g., the result data itself).

The battery level plug-in can also be triggered to take a reading at any time by calling ‘contextRequest’ on the Context Handler, passing in the string-based id of the plug-in and requested context type string (these are the same in this case), as shown below.

Note that some plug-ins support the ‘configuredContextRequest’ method, which allows plug-in-specific arguments to be provided to control the specified sensing or control operation. See each plug-in’s documentation for details.

Other Methods

Your app can use a number of methods to find out information from Dynamix. For example, to discover the Dynamix Framework version, use the following:

To log all plug-ins that Dynamix has discovered, use:

You can restrict the results to installed plug-ins only by using:

Your app may also access a Context Handler’s registered Context Support, as follows:

Clean up

When a Context Handler is finished using Context Support, you can remove all Context Support as follows:

You can remove specific Context Support from a Context Handler as follows:

You can also close the connection with Dynamix, which closes the app’s session by removing all registered Context Handlers and associated Context Support. In the example below, we use the DynamixConnector to close the Dynamix connection in an Activity’s onDestroy method (although closeConnection may be used from anywhere in your code).

API Reference

For details on all of the methods, events and data types available to apps, see the “org.ambientdynamix.api.application” package in the JavaDocs: