API Documentation

GyroNorm()

Constructor function. Instantiate a new GyroNorm instance.

Syntax

var gn = new GyroNorm();

init()

Returns a promise object that resolves when GyroNorm is ready. (Attempt to add events to Window object is complete). If extra arguments are provided overwrites the default options (see above).

Make sure to call all other function after this promise resolves.

Syntax

gn.init(args);

Parameters

args - object (optional) - Passes the values to overwrite the default option values. See README for usage.

start()

Starts returning values via the callback function. The callback function is called every many milliseconds defined by the frequency option. See README on how to set the frequency. The default frequency is 50ms.

Syntax

gn.start(callback);

Parameters

callback - function(data) - Function that returns values via the data object. The available values via data are listed above.

isAvailable()

Tells the availability of device orientation or device motion values on the device+browser combination.

Syntax

gn.isAvailable(valueType);

// or

gn.isAvailable();

Parameters

valueType - string - optional - If passed, the method returns true or false, depending on the availablity of the specified value. Possible values are GyroNorm.DEVICE_ORIENTATION,GyroNorm.ACCELERATION,GyroNorm.ACCELERATION_INCLUDING_GRAVITY or GyroNorm.ROTATION_RATE

When called without a parameter returns availibility for all values.

Example

var gn = new GyroNorm();
gn.init().then(ongnReady);
var ongnReady = function(){
	var doAvailable = gn.isAvailable(GyroNorm.DEVICE_ORIENTATION);
	// Parameter can also be GyroNorm.DEVICE_ORIENTATION, GyroNorm.ACCELERATION, GyroNorm.ACCELERATION_INCLUDING_GRAVITY or GyroNorm.ROTATION_RATE
	// This example returns true if deviceorientation is available. Returns false if not.
	
	var gnAvailable = gn.isAvailable();
	/* Returns the following object
		{
			deviceOrientationAvailable : <true or false>,		
			accelerationAvailable : <true or false>,
			accelerationIncludingGravityAvailable : <true or false>,
			rotationRateAvailable : <true or false>,
			compassNeedsCalibrationAvailable : <true or false>
		}
	*/
}

IMPORTANT:

If a certain set of sensor values (e.g. DeviceOrientation) is not supported by the device, the first gn.init(...) promise will catch this. You will receive an error message, for instance DeviceOrientaion not supported and you can handle it at that point.

But in some old devices, although the values seem to be supported they return null, or does not return at all. So gn.init() resolves properly but the values are not as expected.

isAvailable function aims to checks these cases. The availability conditions are not documented in the standards. So the check I have implemented is from the learnings and self experience, and can be incomplete or buggy.

I suggest you use this function only for debugging certain old devices.

normalizeGravity()

Changes the value of the gravityNormalized option. Even when GyroNorm is running.

Syntax

gn.normalizeGravity(flag);

Parameters

flag - boolean - true sets the option gravityNormalized on, false set it to off.

Example

var gn = new GyroNorm();
gn.init().then(ongnReady);
var ongnReady = function(){
	gn.start(function(){
		// Process return values here
	});
}

// At this point callback function returns normalized gravity-related values.

gn.normalizeGravity(false);

// At this point callback function returns native gravity-related values as provided by the device.		

setHeadDirection()

Must be called after the start() method. This can only be used if GyroNorm is tracking game-based and not-screen-adjusted values.

When called, the callback function starts returning the do.alpha value relative to the current head direction of the device.

It will return true if head direction is set successfully; false if not.

Syntax

gn.setHeadDirection();

Example

var gn = new GyroNorm();
gn.init().then(ongnReady);
var ongnReady = function(){
	gn.start(function(){
		// Process return values here
	});
}

// At this point callback function returns do.alpha values relative to the initial position of the device

gn.setHeadDirection();

// At this point callback function starts to return do.alpha values relative to the position of the device when the above line is called

stop()

Stops executing the callback function, that was started by the start() method. It does not remove the event listeners. If you want to remove the event listeners you should call end() method.

Syntax

gn.stop();

end()

Stops executing the callback function, that was started by the start() method. Also removes the event listeners.

Syntax

gn.end();

isRunning()

Returns boolean value showing if the gn object is running. It starts running when gn.start() is called and returns values to the callback function. It stops when gn.stop() or gn.end() is called.

Syntax

gn.isRunning();
// Returns true or false