Notch: Developer Program

To start developing applications for Notch, do the following:

  1. Purchase a Notch kit from our website
  2. Download the Notch Demo App and pair your Notch devices.
  3. Create an account on our developer site: https://wearnotch.com/developers/. Make sure you use the same account as you have used in your Demo App (Facebook, Google etc).
  4. On the developer site click Go to my applications. You will see the SandboxApplication listed as your only application. Click on View details and select the Credentials tab. Here you will find the API key and the Maven repository credentials. These grant you access to our REST API and to the Notch Android SDK.
  5. On the Licences tab you will find an automatically generated developer license key which you can use for your app development. Later on you can generate more developer license keys to imitate other users. These license keys have restriction on the number of notch activations in a given time period. For more details press the Demo backend tab.

Template App

The Template App is a bare-bone app to review the necessary workflow and the usage of Notch Android SDK functions. In this chapter you will learn how to use the SDK’s public interface methods, for example how to manage the users and notch devices, how to set up and perform a measurement and how to visualize the recording.

Setting up the Template App

Make sure you obtain the latest Android Studio and Gradle build tools.

After registering on our developer site and activating your account, you can download the source of the Template App and extract it to an arbitrary folder. On the Android Studio start-up panel choose Import project (Eclipse ADT, Gradle, etc) and locate the Template App folder to import the project.

Go to the build.gradle file of the NotchTutorial project and specify the username and password based on your previously acquired Maven repository credentials.

maven {
url 'https://wearnotch.com/maven/notch/'
    credentials {
        username 'your_username'
        password 'your_password'
    }

}

At this point you can build and run the Template App on any Android devices.

Note: Internet connection is required in order to download the Notch Android SDK from the Maven repo.

In the following chapters we will guide you through the workflow and the main functions of our SDK. At this point we encourage you to explore the Demo App, because it contains animations and graphical solutions needed to understand some of the features.

Structure of the Template App

The Template App initiates the MainActivity which will bind the NotchService to it:

    Intent controlServiceIntent = new Intent(this,
          NotchAndroidService.class);
    startService(controlServiceIntent);
    bindService(controlServiceIntent, this, BIND_AUTO_CREATE);

It also instantiates the MainFragment which is the only fragment in this activity. From the MainFragment most of the Notch SDK features can be called by a separate button to help you understand the functionality of the SDK.

For visualisation we use a separate activity ( VisualiserActivity ), and these activities and the service must be declared in the AndroidManifest.xml (these are already set u3 if you import the project):

<activity
  android:name="com.wearnotch.notchdemo.MainActivity"
  android:label="@string/app_name" >
    <intent-filter>
      <action android:name="android.intent.action.MAIN"/>
      <category android:name=
        "android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity
  android:name=
    "com.wearnotch.notchdemo.visualiser.VisualiserActivity" />

<service
     android:name=
     "com.wearnotch.service.network.NotchAndroidService" />

Build Variants

Template App has several build variants and is set at Mock build by default which will allow you to develop the UI without Notches. If you intend to use actual Notches in development, please switch to another build.

The build settings panel is located at the bottom left of the Android Studio.

Calling SDK methods

Most of the SDK methods will return with an async callback NotchCallback , which is an interface for handling notch operations. We provide a sample implementation with EmptyCallback, which only overrides the @OnSuccess and @OnFailure methods of NotchCallback with simple UI operations.

Users and Licenses

The license key is a unique identifier of the user and her notches. All SDK features require a valid license key. Developers are expected to build a backend for their application to keep track of the users and their license keys. License keys can be obtained via an API call. For developing an app, however, a single license key is enough, so called developer license, which is provided when activating the account. For more information about license keys and API calls see the API documentation.

In the Template App you can directly enter a license key (SET LICENSE). You can also set your developer license as the default license key in MainFragment ; this way you do not need to enter it at every start-up:

public static final String DEFAULT_USER_LICENSE = "";

Device management

Pairing notch devices

In order to use notch devices for recording, you have to pair them with your license key (PAIR NEW DEVICE) one-by-one. During the pairing process notches will be registered and activated in the Notch backend with the given license. On successful pairing, the notch device will be saved to a local database (NotchDataBase) and will be listed in the Device list

Note: PAIR NEW DEVICE, SYNC DEVICE and REMOVE ALL DEVICE features require internet connection.

Try it: Turn on only one notch and tap PAIR NEW DEVICES. Wait for the pairing process, which may take up to 30 seconds. The notch will turn pink and will shut down in the end of pairing. Repeat the process with the rest of your notches.

Sync paired devices

This feature becomes handy when you want to use paired notch devices in a new phone / tablet without manually pairing them. All previously paired devices’ data will sync to your local database.

Try it: Download the Notch Template App to another Android device. Sign in with the same account. By tapping the SYNC PAIRING your notches should appear under the device list.

Delete paired devices

You can also delete one or more notches from your database (and from the Notch server) if necessary. Pressing REMOVE ALL DEVICE will delete all your paired notches.

Initialize notch network

Once you have paired your notches, you can establish a communication network so called notch network to connect the Android BLE service to the notch devices. The network must be established and available in order to initiate further SDK methods. INIT n NOTCHES will initialize n devices. UNCHECKED INIT will scan longer, return all discovered devices and becomes handy when we don’t know how many notches the user will turn on.

Note: A notch network can consist of 1-18 devices in the same channel and you can only establish one connection at a time.

Try it: Turn on a few notches and tap UNCHECKED INIT to connect to your devices. On successful attempt the notches will appear under the Current Network in the top main menu.

Shutdown notch network

When the NotchService is connected to a notch network, using SHUTDOWN will turn off all devices within. We recommend you to provide a Shut Down button in the UI to simplify the turn of process.

Try it: Turn on your notches and tap UNCHECKED INIT to connect to the network. Tap SHUTDOWN to shut down your devices.

Erase all devices

Notches come with an onboard memory that can store several hours of motion data. When the memory of the device is full, it will pulse on dimmed green. Pressing ERASE will erase the memory of all notches in the network and you may initiate it at any time.

Try it: Turn on your notches and tap UNCHECKED INIT to connect to the network. By tapping ERASE DEVICES the notches will shine white while they are erasing their memory.

Capturing motion

Now that you are familiar with the device management, we will guide you through how to capture and visualize your motion data. The general workflow of capturing your motion is the following:
Device Calibration > Steady > Capture > Visualization

Device Calibration

All notches need device calibration prior to capture to guarantee the precision of the sensors. Calibration is recommended to perform at every day or at significant environment change (going indoor from outdoor), or when the sensors are possibly affected by magnetic objects.

The following workflow is required for the calibration process: Initialize Network > Configure Calibration > Start Calibration > Get Calibration Data

Initialize Network for Calibration

To prepare for calibration we recommended you to use the uncheckedInit(...) .

Try it: Pressing the UNCHECKED INIT button will initialize the notch network and active devices will be listed under the Current network list..

Configure Calibration

CONFIGURE CALIBRATION will configure the notches for the calibration process and these notches will light up yellow.

Tip: The configuring calibration can be called automatically upon a successful network initialization. We separated these to represent the NotchService interface.

Try it: Tap on the CONFIGURE CALIBRATION. The notches will turn yellow.

Start Calibration

The user needs to place the yellow notches into the dock and start the calibration process by pressing START CALIBRATION. After a 3 sec countdown the notches start to capture and the user must rotate the dock around all 3 major axes as shown in the animation. Notches will automatically stop after 7 seconds.

Try it: Tap on the START CALIBRATION and follow the animation in the App. You may only continue if the calibration succeeded.

Get Calibration Data

To obtain the calibration data, initiate GET CALIBRATION DATA.

Try it: Tap on the GET CALIBRATION DATA and wait for it to return. On successful calibration the devices light up green, otherwise the notches light up red.

Steady

Steady is needed to associate the notches with user’s body parts and to align the devices orientation to the user’s bones.

The following workflow is required for the steady process: Initialize network > Configure Steady > Start Steady > Get Steady Data

Initialize network for steady

To prepare for steady we recommended you to use the init(...) function and specify the amount of notches you intend to use for the capture.

Try it: Tap on the 3 NOTCH INIT.

Configure Steady

Any steady measurements require a configuration to specify which bones are measured, what color corresponds to each notch, what frequency setting are to be used, etc. and can be set in the config file. In the Template App there are 2 built-in example configurations: 3 notch config (right upper arm, right forearm, chest) for regular measurement and a 2 notch config for real-time measurements (chest, hip).

For more information on the config file see the How to configure a measurement paragraph.

Tip: The configuring steady can be called automatically upon a sucessful network initialization. We separated these to represent the NotchService interface.

Try it: Tap CONFIGURE STEADY and 3 active notches will turn blue, red and green. By using the notch straps, place them on your body according to the App’s instructions.

Start Steady

To start the steady process, initiate START STEADY. After a 3 sec countdown the user must stand still in the steady pose while the measurement lasts (2 seconds). The user’s posture needs to match the droid’s posture as closely as possible, any difference will be the initial offset at 3D reconstruction.

Try it: Tap on the START STEADY. Make sure you stand still and your arms are straight through the countdown.

Get Steady Data

Initiate GET STEADY DATA to obtain the steady data.

Try it: Tap on the GET STEADY DATA and wait for it to return Success.

Capture

Capture is the actual process of recording and acquiring motion data using the notch devices. The capture can regular, where the motion data is downloaded from the devices after the capture, and can be real-time, where the data is captured and visualized real-time. For regular capture you can use 1-18 notches (up to 500Hz each) and the download time varies based on the number of devices in the notch network, sampling frequency of devices and the length of recording. Real-time capture is feasible with one or two notches (1 notch - up to 100Hz, 2 notches - up to 40Hz - 40Hz). These configurations will vary based on the user scenario.

Regular Capture

Similarly to the steady and calibration measurements, this operation has the following workflow: Initialize network > Configure capture > Capture > Download

Initialize Network for Regular Capture

This operation is exactly the same as the steady initialization as the config is the same. This step can be skipped unless the notch network is disconnected.

Note: Capture can only be initiated if the calibration and steady was successful.

Configure Capture

Regular capture is the default capture method. Capture length defines how long the devices will capture motion data. By default, the devices record until stop(...) is initiated. This can be configured by calling the configureCapture(...) method. You can also configure the notches to stop automatically after a specific time, so called fixed timed capture, and can be initiated by the configureTimedCapture(...)method.

Try it: Tap CONFIGURE 2 SEC CAPTURE to configure your notches for a regular, 2 seconds long capture.

Capture

Calling timedCapture(...) will set the notches to record until the configured time. Calling capture(...) will set the devices to record until a stop operation is called stop(...).

Try it: Tap CAPTURE 2 SEC to start recording your motion data. Time for an exercise!

Download

When the devices are not recording, the latest measurement data can be downloaded from the devices by calling the download(...) method. After the download finished the processed data will be saved to the (notch_library) folder. The zip files contains all the necessary data to visualize the measurement.

Try it: Tap DOWNLOAD and the notches will start downloading your motion data. Wait for it to finish.

Visualization

The latest measurement can be visualized by selecting VISUALIZE. The visualization will run in a separate activity (VisualiserActivity). This activity can be customized by the developers. You can obtain many useful data calculated from the measurement. For more details check out the Data class.

Try it: Tap VISUALIZE to review the reconstructed motion in 3D. Use your finger to navigate in the 3D space and explore the built-in functions.

Real-time Capture

As mentioned before, it is possible to record your motion in real-time with one or two sensors. During the measurement the data is passed to the VisualiserActivity using an EventBus which is a simple way of handling data transfer between activities, but there are several other ways to handle this problem.

Try it: Check the Real-time option in the Capture menu.

Initialize Real-time Capture

Try it: Turn on 2 Notches and tap INIT 2 NOTCHES and wait for it to return Success.

Configure Real-time Capture

CONFIGURE REAL-TIME will prepare the notches for real-time measurement. The color of notches will respond with the placement on the body.

Try it: Tap CONFIGURE REAL-TIME and the notches will shine blue and cyan. Place the notches on your body according to the App’s instructions.

Start / Stop Real-time Capture

START REAL-TIME will start the recording and after about 1 sec the visualizer activity will start to show the real-time reconstruction. By exiting the visualizer activity the real-time recording will not stop; the user must finish it by pressing STOP REAL-TIME.

Try it: Tap START REAL-TIME and wait for the visualizer to load. Bend your back and reach for your feet. You may press STOP REAL-TIME when you touched the floor without bending your knees.

Useful

How to configure a measurement

The configuration file is a JSON file which is parsed during the measurement initialization. Here is the 3 notch measurement’s config file:

{
"bones": [
    {
        "name": "ChestBottom",
        "color1": "Blue",
        "color2": "Blue",
        "frequency": 20
    },
    {
        "name": "RightUpperArm",
        "color1": "Red",
        "color2": "Red",
        "frequency": 20
    },
    {
        "name": "RightForeArm",
        "color1": "Green",
        "color2": "Green",
        "frequency": 20
    }
],
"master_bone": "ChestBottom",
"special": {
    "bone": "ChestBottom",
    "orientation": "Front"
},
"constraints": [
    {
        "type": "INTERP",
        "target": "Tummy",
        "source": "ChestBottom",
        "f": 0.5
    },
    {
        "type": "INTERP",
        "target": "ChestTop",
        "source": "Hip",
        "f": -0.42
    }
]
}

The following objects are obligatory:

  1. bones represent the bone-notch connections. You must specify which bone is measured by its name(see the skeleton_male.js file for the default skeleton we use), set up the corresponding notch’s color (color1, color2 will alternately light up) and the frequency of the recording.
  2. master_bone is one of the measured bones, which directly connects to the phone/tablet and manages the communication with the other devices. It is recommended to select a notch with good ‘visibility’ to the other notches for good connection, for example the the notch on the Chest if measured.
  3. special_bone is one of the measured bones which indicates the initial oriantation of the person in the steady pose. Along with the steady measurement this is required to determine to exact placement of the notches on your body. The notch should be placed on the selected body part (bone) with a pre-defined orientation. This can be one of the following: Front, Back, Left, Right which means that the notches top (white) side faces to the persons front, left, etc. side in the steady, and there is also an option for using LEDFront, LEDLeft, LEDBack, LEDRight which means that the LED of the notches faces to the corresponding direction.

There are other optional parts of the config which will be discussed in a more detailed documentation.