1. Java APIs

MetaSensors are supported on Android and Windows. Developers can create their own Android Apps using Java.

Here is a tutorial to install Java+Android libs, and Android Studio on Windows.

We will be using Android Studio so you should be comfortable with this IDE. You should be familiar with the Java language and know how to deploy Apps before starting the Android Java tutorials.

Warning

We have NOT tested Android Studio with our APIs on Linux or MAC.

1.1. Installation

You will need to consider the following before starting the installation:

  • Make sure your OS and supporting tools are up to date.
  • Make sure your Android test device (such as an Samsung tablet or Google Pixel) supports Bluetooth4.0+
  • Make sure your Android device is running at least Android 4.3+ (numerous bug fixes in 4.4+)

1.1.1. Android Studio

_images/studio-homepage-hero.jpg

If you are new to Android development, download the latest version of Android Studio and enable debugging over USB on your Android device.

To install Android Studio on Windows, proceed as follows:

  1. If you downloaded an .exe file (recommended), double-click to launch it.

    If you downloaded a .zip file, unpack the ZIP, copy the android-studio folder into your Program Files folder, and then open the android-studio > bin folder and launch studio64.exe (for 64-bit machines) or studio.exe (for 32-bit machines).

  2. Follow the setup wizard in Android Studio and install any SDK packages that it recommends.

That’s it. The following video shows each step of the setup procedure when using the recommended .exe download.

As new tools and other APIs become available, Android Studio tells you with a pop-up, or you can check for updates by clicking Help > Check for Update.

Note

Java is installed with Android Studio

1.2. Dependencies

Please checkout the latest from the Android developer site regarding Bluetooth Low Energy support: https://developer.android.com/guide/topics/connectivity/bluetooth-le

A minimum of Android 4.3 (SDK 18) is required to use this library, however for the best results, it is recommended that users be on Android 4.4 (SDK 19) or higher.

Also please check your hardware, some Android phone and tablets do NOT support Bluetooth Low Energy or may do so, but not reliably. There is lots of device variation across Android tablets. Not all of them come with Bluetooth Low Energy so it’s important to check.

Most phones that were made in the pre Ice Cream Sandwich Android era offered minimal or no BLE support. For example, the Galaxy S3 does not support BLE. Save yourself a headache and develop your Android App on a reliable new BLE compliant smartphone.

_images/android-studio-0.jpg

1.2.1. Developer Program

Google provides a great tutorial to publish, manage, and distribute your app worldwide: https://developer.android.com/distribute/best-practices/launch

_images/android-studio-1.png

1.3. MetaWear

You need to add MetaWear to your compile dependencies.

To add the library to your project, first, update the repositories closure to include the MbientLab Ivy Repo in the project’s build.gradle file.

repositories {
    ivy {
        url "https://mbientlab.com/releases/ivyrep"
        layout "gradle"
    }
}

Then, add the compile element to the dependencies closure in the module’s build.gradle file.

dependencies {
    compile 'com.mbientlab:metawear:3.4.0'
}

If you are using SDK v3.3 or newer, you will need to enable Java 8 feature support the module’s build.gradle file.

1.4. Usage

Once your project has synced with the updated Gradle files, declare the MetaWear Bluetooth LE service in the module’s AndroidManifest.xml file.

<application
    android:allowBackup="true"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >

    <service android:name="com.mbientlab.metawear.android.BtleService" />
    <!-- Other application info below i.e. activity definitions -->
</application>

Lastly, bind the service in your application and retrain a reference to the service’s LocalBinder class. This can be done in any activity or fragment that needs access to a MetaWearBoard object.

import android.app.Activity;
import android.content.*;
import android.os.Bundle;
import android.os.IBinder;

import com.mbientlab.metawear.android.BtleService;

public class ExampleActivity extends Activity implements ServiceConnection {
    private BtleService.LocalBinder serviceBinder;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        ///< Bind the service when the activity is created
        getApplicationContext().bindService(new Intent(this, BtleService.class),
                this, Context.BIND_AUTO_CREATE);
    }

    @Override
    public void onDestroy() {
        super.onDestroy();

        ///< Unbind the service when the activity is destroyed
        getApplicationContext().unbindService(this);
    }

    @Override
    public void onServiceConnected(ComponentName name, IBinder service) {
        ///< Typecast the binder to the service's LocalBinder class
        serviceBinder = (BtleService.LocalBinder) service;
    }

    @Override
    public void onServiceDisconnected(ComponentName componentName) { }
}

1.4.1. Download API Repository

Head over to our Java Github page: https://github.com/mbientlab/MetaWear-SDK-Android

You can clone the repository or simply download as a ZIP file:

>>>  git clone https://github.com/mbientlab/MetaWear-SDK-Android.git

1.4.2. About Java APIs

The Java APIs are native.

When you download our Repository, you will find:

  1. wrapper -> Scripts
  2. library -> This is where the main MetaWear Java source code resides
  3. Gradle files -> Gradle is an open-source build-automation system

We also have Java API documentation here. Please keep this documentation handy.

1.5. Template App

For those who want to build a simple MetaWear app or are new to Android development, we have provided a template for creating MetaWear apps which we will be using in this guide.

Download the Android template.

Import the project into Android Studio. All the code on this page will be added to the starter module.

1.5.1. Modules

MetaWear modules are sensors or peripherals that are on the board. Modules are represented by the Module interface and you retrieve references to them with the getModule function. The function may return null if the module is unsupported however all MetaWear boards have an accelerometer so we can safely assume the return value is non-null in this example.

In the onServiceConnected function, retrieve a reference to the Accelerometer module and configure the sensor.

private Accelerometer accelerometer;

@Override
public void onServiceConnected(ComponentName name, IBinder service) {
    metawear = ((BtleService.LocalBinder) service).getMetaWearBoard(settings.getBtDevice());

    accelerometer= metawear.getModule(Accelerometer.class);
    accelerometer.configure()
           .odr(25f)       // Set sampling frequency to 25Hz, or closest valid ODR
           .commit();
}

1.5.1.1. UI Elements

Next, add a start and stop button to the fragment layout defined in the fragment_device_setup.xml file.

<Button android:layout_width="wrap_content" android:layout_height="wrap_content"
    android:text="Start" android:id="@+id/acc_start"
    android:layout_alignParentTop="true"
    android:layout_alignParentStart="true"
    android:layout_alignParentEnd="true" />

<Button android:layout_width="wrap_content" android:layout_height="wrap_content"
    android:text="Stop" android:id="@+id/acc_stop"
    android:layout_below="@+id/acc_start"
    android:layout_alignParentStart="true"
    android:layout_alignParentEnd="true" />

1.5.1.2. Data Stream

Switching back to the DeviceSetupActivityFragment class, override the onViewCreated function to add listeners for the start and stop buttons. The start button will setup a data route, subscribe to the data stream, and start the sensor. The stop button will stop the sensor and remove the data route.

@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);

    view.findViewById(R.id.acc_start).setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            accelerometer.acceleration().addRouteAsync(new RouteBuilder() {
                @Override
                public void configure(RouteElement source) {
                    source.stream(new Subscriber() {
                        @Override
                        public void apply(Data data, Object... env) {
                            Log.i("MainActivity", data.value(Acceleration.class).toString());
                        }
                    });
                }
            }).continueWith(new Continuation<Route, Void>() {
                @Override
                    public Void then(Task<Route> task) throws Exception {
                        accelerometer.acceleration().start();
                        accelerometer.start();
                        return null;
                    }
            });
        }
    });
    view.findViewById(R.id.acc_stop).setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            accelerometer.stop();
            accelerometer.acceleration().stop();
            metawear.tearDown();
        }
    });
}

1.5.1.3. Test the App

Load the app onto your Android device and connect to your board. Press the start button to see the acceleration data in Logcat.

When are you want learn more about the inner workings of the APIs and advanced functionalities of the MetaWear, go to the Next Steps.

1.6. Next Steps

Go over to our Java Developers Section to learn more about the Swift development.