Gyronorm.js E-book

I started to prepare an e-book for gyronorm.js. It covers the the basis of gyroscope and accelerometer data in JavaScript, as well as details on the gyronorm.js library.

I would like to get as many feedback as possible to finalize it. You can download a free full version from the following link. Gyronorm.js E-book

Your feedback will help me make it more useful.

gyronorm.js

Accesses the gyroscope and accelerometer data from the web browser and combines them in one JS object.

It returns consistent values across different devices. It has options to return game-based or world-based alpha values (rotation around z-axis), and normalize the gravity-related values. You can find more about the differences across devices in the e-book

Installation

You can clone from this GitHub repository, use Bower or NPM.

$ bower install gyronorm

$ npm install gyronorm

This version of gyronorm.js is built on top of the FullTilt project which uses JavaScript Promises. You do not need to install them seperately. Both the FullTilt library and the polyfill for JS Promises will come as dependencies of gyronorm.js

How to add

For production, add the minified complete version of gyronorm.js which is under the /dist folder.

<script src="<path_to_js_files>/gyronorm.complete.min.js"></script>

If you want to use the un-minified version (for instance for development), then you need to add the FullTilt and the Promises polyfill.

<script src="<path_to_js_files>/promise.min.js"></script>
<script src="<path_to_js_files>/fulltilt.min.js"></script>
<script src="<path_to_js_files>/gyronorm.js"></script>

How to use

Initialize the gn object by calling the gn.init() function which returns a promise. Start the gn object when this promise resolves.

Access the values in the callback function of the gn.start()

<script src="<path_to_js_files>/gyronorm.complete.min.js"></script>

<script type="text/javascript">
    var gn = new GyroNorm();

    gn.init().then(function(){
    	gn.start(function(data){
	   		// Process:
			// data.do.alpha	( deviceorientation event alpha value )
			// data.do.beta		( deviceorientation event beta value )
			// data.do.gamma	( deviceorientation event gamma value )
			// data.do.absolute	( deviceorientation event absolute value )

			// data.dm.x		( devicemotion event acceleration x value )
			// data.dm.y		( devicemotion event acceleration y value )
			// data.dm.z		( devicemotion event acceleration z value )

			// data.dm.gx		( devicemotion event accelerationIncludingGravity x value )
			// data.dm.gy		( devicemotion event accelerationIncludingGravity y value )
			// data.dm.gz		( devicemotion event accelerationIncludingGravity z value )

			// data.dm.alpha	( devicemotion event rotationRate alpha value )
			// data.dm.beta		( devicemotion event rotationRate beta value )
			// data.dm.gamma	( devicemotion event rotationRate gamma value )
		});
	}).catch(function(e){
	  // Catch if the DeviceOrientation or DeviceMotion is not supported by the browser or device
	});
</script>

Backward compatibility

There are some breaking changes from 1.x to 2.x versions. You can find the details here.

Options

You can pass arguments as an object to the init() function. The values you pass overwrites the default values. Below is the list of available options and their default values.

var args = {
	frequency:50,					// ( How often the object sends the values - milliseconds )
	gravityNormalized:true,			// ( If the garvity related values to be normalized )
	orientationBase:GyroNorm.GAME,		// ( Can be GyroNorm.GAME or GyroNorm.WORLD. gn.GAME returns orientation values with respect to the head direction of the device. gn.WORLD returns the orientation values with respect to the actual north direction of the world. )
	decimalCount:2,					// ( How many digits after the decimal point will there be in the return values )
	logger:null,					// ( Function to be called to log messages from gyronorm.js )
	screenAdjusted:false			// ( If set to true it will return screen adjusted values. )
};

var gn = new GyroNorm();

gn.init(args).then( ... );

Older devices

In some of the older devices the polyfill for the JS Promises does not work properly. This might cause all or a part of your JavaScript code to break. Try adding the following line before you instantiate GyroNorm.

var Promise = Promise || ES6Promise.Promise;

API Documentation

gyronorm.js API Documentation

Error handling

gyronorm.js can return error and log messages. You need to define a function to handle those message. If a handler function is not defined, those messages will be ignored silently.

You can do this with the options when initializing the object.

var args = {
	logger:function(data){
		// Do something with the data
	}
};

var gn = new GyroNorm();

gn.init(args).then( ... );

You can also set the log listener function at a later point using the startLogging() function.

var gn = new GyroNorm();

gn.init().then( ... );

gn.startLogging(function(data){
	// Do something with the data
});

At any point you can call the stopLogging() function to stop logging.

var args = {
	logger:function(data){
		// Do something with the data
	}
};

var gn = new GyroNorm();

gn.init(args).then( ... );

gn.stopLogging();

The return value of the callback function (data in the above examples) is an object with two parameters

data.code

A machine-readable code.

0: Errors thrown by the system and caugth by gyronorm.js
1: You get this if you try to call gn.start() before gn.init(). It means GyroNorm object is started before proper event listeners are added.

data.message

A human-readable text message.

Compatibility

I have tested with most Android and iOS phones of the last 2-3 years and the demo/index.html worked out of the box. Let me know if you have issues with a specific device+browser and I will try to find out.

Contact

You can find me on Twitter @dorukeker or check my web site http://dorukeker.com

Mad-Thanos/gyronorm.js