title	description
Cyclometer	Access cyclometer data.

cordova-plugin-cyclometer

This plugin is a re-write of the device-motion plugin for ios and android platforms.

It has added functionality to determine if the device has been shaken.

Access is via a global navigator.cyclometer object.

Installation

cordova plugin add cordova-plugin-cyclometer

Supported Platforms

• Android
• Browser
• iOS

Methods

• navigator.cyclometer.getCurrentAcceleration
• navigator.cyclometer.watchAcceleration
• navigator.cyclometer.clearWatch

Objects

• Acceleration

navigator.cyclometer.getCurrentAcceleration

Get the current acceleration along the x, y, and z axes.

These acceleration values are returned to the accelerometerSuccess callback function.

navigator.accelerometer.getCurrentAcceleration(accelerometerSuccess, accelerometerError);

Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
}

function onError() {
    alert('onError!');
}

navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);

Browser Quirks

Values for X, Y, Z motion are all randomly generated in order to simulate the accelerometer.

Android Quirks

The accelerometer is called with the SENSOR_DELAY_UI flag, which limits the maximum readout frequency to something between 20 and 60 Hz, depending on the device. Values for period corresponding to higher frequencies will result in duplicate samples. More details can be found in the Android API Guide.

iOS Quirks

• iOS doesn't recognize the concept of getting the current acceleration at any given point.

• You must watch the acceleration and capture the data at given time intervals.

• Thus, the getCurrentAcceleration function yields the last value reported from a watchAccelerometer call.

navigator.accelerometer.watchAcceleration

Retrieves the device's current Acceleration at a regular interval, executing the accelerometerSuccess callback function each time. Specify the interval in milliseconds via the acceleratorOptions object's frequency parameter.

The returned watch ID references the accelerometer's watch interval, and can be used with navigator.accelerometer.clearWatch to stop watching the accelerometer.

var watchID = navigator.accelerometer.watchAcceleration(accelerometerSuccess,
                                                       accelerometerError,
                                                       accelerometerOptions);

• accelerometerOptions: An object with the following optional keys:
  • frequency: requested frequency of calls to accelerometerSuccess with acceleration data in Milliseconds. (Number) (Default: 10000)

Example

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
}

function onError() {
    alert('onError!');
}

var options = { frequency: 3000 };  // Update every 3 seconds

var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

iOS Quirks

The API calls the success callback function at the interval requested, but restricts the range of requests to the device between 40ms and 1000ms. For example, if you request an interval of 3 seconds, (3000ms), the API requests data from the device every 1 second, but only executes the success callback every 3 seconds.

navigator.accelerometer.clearWatch

Stop watching the Acceleration referenced by the watchID parameter.

navigator.accelerometer.clearWatch(watchID);

• watchID: The ID returned by navigator.accelerometer.watchAcceleration.

Example

var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

// ... later on ...

navigator.accelerometer.clearWatch(watchID);

Acceleration

Contains Accelerometer data captured at a specific point in time. Acceleration values include the effect of gravity (9.81 m/s^2), so that when a device lies flat and facing up, x, y, and z values returned should be 0, 0, and 9.81.

Properties

• x: Amount of acceleration on the x-axis. (in m/s^2) (Number)
• y: Amount of acceleration on the y-axis. (in m/s^2) (Number)
• z: Amount of acceleration on the z-axis. (in m/s^2) (Number)
• timestamp: Creation timestamp in milliseconds. (DOMTimeStamp)

The Shared Library

The Cyclometer plugin uses code from cordova-plugin-hello-c in order to process the acceleration logs for callbacks on both platforms. That help is currently reproduced below, and will need slight modification.

It illustrates how to use platform-specific (either Android or iOS) C code and how to share C code cross-platform (between Android and iOS).

For Android it utilizes the Android NDK to compile architecture-specific libraries and a JNI wrapper to expose the C functions to the Java plugin API.

For iOS it uses the pure C source code in place alongside the Objective-C plugin wrapper, as well as an example cross-platform library compiled as a static library for iOS.

usage example

• Clone the test project
• Add Android and iOS platforms: cordova platform add android && cordova platform add ios
• Run: cordova run android / cordova run ios

Plugin structure

• plugin.xml - Specifies the plugin's source files and libraries to copy to the platforms of the Cordova project into which the plugin is installed
• compile-android and compile-android.cmd - Script to recompile C source code as a shared library for use with Android platform
• compile-ios - Script to recompile cross-platform C library as static library for use with iOS platform
• src/ - C source code and build scripts
  • common/ - cross-platform C source code to run on both Android and iOS
    • mylib/ - example cross-platform C library
  • android/ - source code and build scripts for Android platform
    • build-extras.gradle - Gradle build script to link up the NDK make file for debugging C code in Android Studio
    • HelloCPlugin.java - Provides the native Java implementation for Android of the Cordova plugin
    • HelloCJni.java - Provides the Java interface to the underlying JNI C implementation
      • jni/ - JNI C implementation and build script
        • HelloJni.c - C implementation of the JNI interface defined by HelloCJni.java, including
          • Android-specific implementation to get current CPU architecture
          • interfaces to cross-platform C functionality
        • Android.mk - NDK Make script to build the C source code into architecture-specific shared libraries
      • libs/ - contains folders for the various architecture-specific shared libraries built by the NDK Make script
  • ios/ - source code and build scripts for iOS platform
    • c_getArch.c & c_getArch.h - iOS-specific implementation to get current CPU architecture
    • HelloCPlugin.c & HelloCPlugin.h - Provides the native Objective-C implementation for iOS of the Cordova plugin
    • ios_compile.sh - Script to compile the cross-platform example library in src/common/mylib/ as a static library
    • Makefile - Make script invoked by the above script to perform the C compilation.
    • libs/ - the compiled cross-platform library
      • libmylib.a - the compiled cross-platform library as a multi-architecture static library
      • headers/ - the header files of the cross-platform library (static libraries require the headers externally)

Recompiling libraries

If you modify the C source files, be sure to re-build the compiled libraries.

Android

You can re-build the libhelloc.so binaries using the ndk-build script.

To do so:

• Install Android NDK as instructed here
• Add the NDK install path to your path environment variable
  • By default it's installed under $ANDROID_SDK_HOME/ndk-bundle
  • e.g. export PATH=$PATH;$ANDROID_SDK_HOME/ndk-bundle
• Set the ANDROID_NDK_HOME environment variable to your NDK install path
  • e.g. export ANDROID_NDK_HOME=$ANDROID_SDK_HOME/ndk-bundle
• Open terminal in plugin root folder
• Run ./compile-android (compile-android.cmd on Windows)

If you are editing the C source code of the plugin in place in the example project:

• Modify the C source in plugins/cordova-plugin-hello-c/src/android/jni or plugins/cordova-plugin-hello-c/src/common
• Open terminal in plugins/cordova-plugin-hello-c
• Run compile-android (compile-android.cmd on Windows)
• From the project root, remove and re-add the android platform to apply the plugin changes to the project cordova platform rm android && cordova platform add android

iOS

If you modify the C source code in common/mylib/ you'll need to rebuild the static library and headers in src/ios/libs.

• Open terminal in plugin root folder
• Run ./compile-ios

If you are editing the C source code of the plugin in place in the example project:

• Modify the C source in plugins/cordova-plugin-hello-c/src/ios/ or plugins/cordova-plugin-hello-c/src/common
• Open terminal in plugins/cordova-plugin-hello-c
• Run ./compile-ios
• From the project root, remove and re-add the platform to apply the plugin changes to the project cordova platform rm ios && cordova platform add ios

Debugging C source code

Android

• The Android NDK enables C/C++ source code to be debugged in Android Studio alongside Java.
• To do so, the source code must be included but not the compiled libraries.
• To debug this plugin in Android Studio do the following:
  • Edit plugin.xml and in the <platform name="android"> block, comment out the source-file lines in the PRODUCTION block which include the compiled libraries
  • Remove/re-add the plugin or Android platform in your project to update the plugin files in the platform project
  • Open the Android platform project (platforms/android) in Android Studio
  • Connect an Android device for debugging
  • Use the Project Explorer to find and open one of the .c source files
  • Place a breakpoint, for example on a return statement
  • Select "Run" > "Debug ..." from the menu

iOS

• Since iOS is a C-based platform, C debugging is inherently supported in the Xcode IDE
• However, to debug the C code in the static library src/ios/libs/libmylib.a, you'll need to comment out the library files and comment in the source code for it:
• Edit plugin.xml and in the <platform name="ios"> block
  • comment out the lines in the PRODUCTION block which include the compiled library and headers.
  • comment in the the commented-out lines in the DEBUG block which will include the uncompiled C source code for the library
• Remove/re-add the plugin or iOS platform in your project to update the plugin files in the platform project
• Use the OSX Finder to browse to platforms/ios/ in your Cordova project and double-click the .xcodeproj file to open it in Xcode.