Overview

This guide will help you understand how to build Web 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. Dynamix Web apps interact with Dynamix through a simple REST-based interface, which provides easy-access to Dynamix methods and events from Web browsers or other Web agents. The following sections describe how to integrate Dynamix into your next Web project.

To clone the Dynamix JavaScript 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 Web Logger project, as follows:

Once complete, you can update the Web logger project’s html files and Dynamix JavsScript independently. To update the html, simply issue a ‘git pull’ from the root of the example directory (probably dynamix-2-web-logger). To update the Dynamix JavaScript within the example, issue a ‘git pull’ from the dynamix subdirectory within the example directory (probably dynamix-2-web-logger/dynamix).

Downloads

Download Dynamix!

Grab the latest Dynamix Framework.
Downloads

Dynamix Integration

After downloading the Dynamix JavaScript file, simply include it in your Web project as follows.

For non-browser projects wishing to use a Dynamix instance over the local network, please take a look at our remote pairing guide here. Note that you can use the same Dynamix Javascript file; however, you’ll need to modify the target IP address and generate a pairing token. (Coming soon!)

Connect to Dynamix

To connect your app with the local Dynamix service, use the ‘Dynamix.bind’ call, as shown below.

As shown above, we pass a ‘bindListener’ into the ‘Dynamix.bind’ call, which enables our app to receive feedback about the status of the binding process. Once the ‘bindListener’ receives status ‘BOUND’, we can then open a Dynamix session as shown below.

As shown above, we pass an ‘openSessionCallback’ into the ‘Dynamix.openDynamixSession’ call, which is raised once the session opened. We also pass a ‘sessionListener’ into the ‘Dynamix.openDynamixSession’ call, which enables our app to receive feedback about the status of the session during runtime.

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.

As shown above, we pass a ‘createNewHandlerCallback’ into the ‘Dynamix.createContextHandler’ call, which enables our app to receive feedback about the status of the handler creation process.

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 for the battery level context type.

As shown above, we pass a ‘batteryLevelCallback’ into the ‘Dynamix.addContextSupport’ call, which enables our app to receive feedback about the status of the installation process.

Note that some plug-ins allow configuration options to be included when Context Support is added (see each plug-in’s documentation for details). In the example below, we add configured context support for the hue plug-in (network-enabled lighting) with an initial value for the switch of “on”.

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’ above 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.

As shown above, we pass a ‘batteryLevelCallback’ into the ‘contextRequest’ call, which enables our app to receive the results in the callback.

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. In the example below, we add use the configured context request to turn the hue plug-in (network-enabled lighting) “off”.

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 making the following small change in the above code:

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 ‘Dynamix.unbind’ call to close the connection with Dynamix. Note that Dynamix will be automatically unbound when a Web page unloads (for HTML-based apps).

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: