---- INTRODUCTION ----

This document contains instructions on how to use the GBAccelerometer.

Included with this document are source code examples for HAM and devkitPro that demonstrate
how to use the GBAccelerometer.


---- ABOUT THE GBACCELEROMETER ----

 * Description

The GBAccelerometer is a Kionix KXP74 tri-axis accelerometer that can be connected to the 
Gameboy Advance (GBA) through the EXT1 port.  It can be used to create tilt/motion sensitive games
and applications.

The KXP74 accelerometer measures acceleration in the +/- 2 g range.  1 g is earth's gravitational
acceleration, which is equal to 9.8 meters per second squared.  The KXP74 communicates the
acceleration that it measures using Serial Peripheral Interface (SPI).

 * Axis Directions

On the GBA SP, the X-axis is to the right (same as LCD X-axis), the Y-axis is up (negative of LCD Y-axis), 
and the Z-axis is perpendicular to the LCD pointing towards you.

On the GBA, the X-axis is to the left (negative of LCD X-axis), the Y-axis is up (negative of LCD Y-axis),
and the Z-axis is perpendicular to the LCD pointing away from you.


---- SOURCE CODE ----

The source code example shows how to communicate with the GBAccelerometer.  It initializes the
communication, turns on (enables) the GBAccelerometer, reads the acceleration, and displays it on the screen.

The files called spitest.c and spitest.h contain all the functions necessary for communicating with
the GBAccelerometer, including a function to determine whether or not the GBAccelerometer is present.

There are two examples, one for the HAM toolchain and the other for devkitPro.  Because devkitPro
creates programs that runs faster than programs created by HAM, there are some places where extra
loops are needed to achieve a necessary 40 microsecond delay.


---- CREATING GAMES WITH THE GBACCELEROMETER ----

To create games with the GBAccelerometer, include spitest.c and spitest.h in your project so you
can use the functions that communicate with the GBAccelerometer.  Following the example, first
initialize the communication, then turn on (enable) the GBAccelerometer.  Every frame of your game,
read the X, Y, and Z accelerations, and use them to control your game.


---- INTERPRETING DATA FROM THE GBACCELEROMETER ----

The GBAccelerometer outputs the acceleration as a 12 bit number, from 0 to 4095.  The midpoint, 2048,
represents zero acceleration.  Positive accelerations increase the output of the GBAccelerometer, and
negative accelerations decrease the output.  The sensitivity of the GBAccelerometer is 819 counts/g,
which means that the output changes by 819 counts when the acceleration changes by one g.  For example, with
the GBA SP sitting flat on a table, the X-axis and Y-axis experience zero acceleration, so the X-axis and
Y-axis outputs are both 2048.  The Z-axis experiences one g of acceleration, so the Z-axis output is 2867
(2048 + 819).

The value that the accelerometer outputs at zero acceleration is called the zero g offset, and is nominally
2048.  The amount that the output changes with acceleration is called the sensitivity, and is nominally 819
counts/g.  Each axis has its own zero g offset and sensitivity, and they vary slightly from part to part.

To calculate acceleration from the the output, use the following equation, which is included in the source code:

acceleration = (output - zero g offset)/sensitivity.


---- FOR MORE INFORMATION ----

For detailed specifications on the KXP74 and SPI communication, refer to the KXP74 product
specification located at http://www.kionix.com/Product-Index/product-index.htm

For games that use the GBAccelerometer, more source code, and news about the GBAccelerometer, visit
http://www.kionix.com/gbaccelerometer.

For questions about the GBAccelerometer, visit and search the gbadev forums at http://forum.gbadev.org,
or email Keith Epstein at kepstein@kionix.com

