drivers/staging/iio/imu/mpu/README - kernel/tegra - Git at Google

 Kernel driver inv-mpu-iio
 Author: Invensense <http://invensense.com>

 Description
 -----------
 This document describes how to install the Invensense device driver into a
 Linux kernel. At the moment, this driver supports the ITG3500/MPU6050/MPU9150/MPU3050. The slave
 address of these four chips are 0x68. However, the actual slave address depends on the board
 configuration. The driver does not assume anything about it.

 Files included in this package:
 Kconfig
 Makefile
 inv_mpu_core.c
 inv_mpu_misc.c
 inv_mpu_trigger.c
 inv_mpu3050_iio.c
 inv_mpu_iio.h
 inv_mpu_ring.c
 inv_slave_bma250.c
 dmpDefaultMPU6050.c
 dmpkey.h
 dmpmap.h
 mpu.h
 Including the driver in the Linux kernel
 ----------------------------------------
 mpu.h should be added to "kernel/include/linux".
 Other files listed should be added to the drivers/staging/iio/imu/mpu directory (or another
 directory of your choosing). When building the kernel, the driver will not
 appear in menuconfig without modifications similar to those below:

 modify "drivers/staging/iio/imu/Kconfig" like
 source "drivers/staging/iio/imu/mpu/Kconfig"

 modify "drivers/staging/iio/imu/Makefile"
 obj-y += mpu/

 Board and Platform Data
 -----------------------
 The board file needs to be modified to register the device on an I2C bus. An
 i2c_board_info instance must be defined as seen below. The hardcoded value of
 140 corresponds to the GPIO input pin wired to the device's interrupt pin.
 This pin will most likely be different for your platform.
 platform data is for orientation matrix,  and secondary bus situations.
 For MPU9150, it regarded as a MPU9150 and AKM8975 in the secondary.
 So the secondary i2c address must be filled.
 -----------------------------------------------------------------
 The board file is arch/arm/mach-omap2/board-omap4panda.c or
 modify the board file in your system as below:
 --------------------------------------------------------
 For AKM8963 in the secondary i2c bus of MPU6050,
 static struct mpu_platform_data gyro_platform_data = {
 	.int_config  = 0x00,
 	.level_shifter = 0,
 	.orientation = {  -1,  0,  0,
 			   0,  1,  0,
 			   0,  0, -1 },
 	.sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 	.sec_slave_id   = COMPASS_ID_AK8963,
 	.secondary_i2c_addr = 0x0E
 };
 -----------------------------------------------------------
 For MPU9150, the secondary i2c bus address must be filled as below.
 static struct mpu_platform_data gyro_platform_data = {
 	.int_config  = 0x00,
 	.level_shifter = 0,
 	.orientation = {  -1,  0,  0,
 			   0,  1,  0,
 			   0,  0, -1 },
 	.sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 	.sec_slave_id   = COMPASS_ID_AK8975,
 	.secondary_i2c_addr = 0x0E
 };
 -----------------------------------------------------------
 for BMA250 in the secondary, please use the platform data as:
 static struct mpu_platform_data gyro_platform_data = {
 	.int_config  = 0x00,
 	.level_shifter = 0,
 	.orientation = {  -1,  0,  0,
 			   0,  1,  0,
 			   0,  0, -1 },
 	.sec_slave_type = SECONDARY_SLAVE_TYPE_ACCEL,
 	.sec_slave_id   = ACCEL_ID_BMA250,
 	.secondary_i2c_addr = 0x18,
 };
 ---------------------------------------------------------------
 the i2c init data is:
 ----------------------------------------------------------------
 For MPU3050,
 static struct i2c_board_info __initdata single_chip_board_info[] = {
 	{
 		I2C_BOARD_INFO("mpu3050", 0x68),
 		.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 		.platform_data = &gyro_platform_data,
 	},
 };
 ----------------------------------------------------------------
 for ITG3500:
 static struct i2c_board_info __initdata single_chip_board_info[] = {
 	{
 		I2C_BOARD_INFO("itg3500", 0x68),
 		.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
                 .platform_data = &gyro_platform_data,
 	},
 };
 for MPU6050
 static struct i2c_board_info __initdata single_chip_board_info[] = {
 	{
 		I2C_BOARD_INFO("mpu6050", 0x68),
 		.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 		.platform_data = &gyro_platform_data,
 	},
 };
 for MPU9150
 arch/arm/mach-omap2/board-omap4panda.c
 static struct i2c_board_info __initdata single_chip_board_info[] = {
 	{
 		I2C_BOARD_INFO("mpu9150", 0x68),
 		.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 		.platform_data = &gyro_platform_data,
 	},
 };

 In the _i2c_init function, the device is registered in the following manner:

 arch/arm/mach-omap2/board-omap4panda.c
     in static int __init omap4_panda_i2c_init(void)
 omap_register_i2c_bus(4, 400, single_chip_board_info, ARRAY_SIZE(single_chip_board_info));

 IIO subsystem
 ----------------------------------------------
 successful installation will create two directories under /sys/bus/iio/devices
 iio:device0
 trigger0
 Under /dev/ diretory, a file "iio:device0" will also be created(or iio:deviceX, if
 you have more than one iio devices).
 Communicating with the driver in userspace
 ------------------------------------------
 Upon installation, the driver generates several files in sysfs. If your
 platform is configured as detailed above, navigate to the following path to
 find these files:
 /sys/bus/iio/devices/iio:device0

 The list below provides a brief description for each file.
 --------------------------------------
 For ITG3500:
 temperature (Read-only)
 Read temperature data directly from the temperature register.

 sampling_frequency (Read/write)
 Configure the ADC sampling rate and FIFO output rate.

 sampling_frequency_available(read-only)
 show commonly used frequency

 clock_source (Read-only)
 Check which clock-source is used by the chip.

 power_state (Read/write)
 turn on/off the power supply

 self_test (read-only)
 read this entry trigger self test. The return value is D.
 D is the success/fail.
 For different chip, the result is different for success/fail.
 1 means success 0 means fail. The LSB of D is for gyro; the bit
 next to LSB of D is for accel. The bit 2 of D is for compass result.

 key (read-only)
 show the key value of this driver. Used by MPL.

 gyro_matrix (read-only)
 show the orient matrix obtained from board file.

 -------------------------------------------------------------
 For MPU6050:
 MPU6050 has all the sysfs files that ITG3500 has. It has additional files list below:

 gyro_enable (read/write)
 enable/disable gyro functionality. affect raw_gyro. turn off this will shut down gyro and save power.

 accl_enable (read/write)
 enable/disable accelerometer functionality. affect raw_accl. turn off this will shut down accel and save power.

 firmware_loaded (read/write)
 Flag indicate the whether firmware is loaded or not in the DMP engine. 0 means no firmware loaded.
 1 means firmware is already loaded . This flag can only be written as 0. 1 is updated
 internally.

 dmp_on(read/write)
 This entry controls whether to run DMP or not. To enable DMP , firmware_loaded must be 1. write 1 to enable
 DMP and write 0 to disable dmp.

 dmp_in_on(read/write)
 This entry controls whether dmp interrupt is on/off. firmware_loaded must be 1. sometimes, it is desirable
 that interrupt is off while DMP is running.

 dmp_firmware (write only binary file)
 This is the entry that firmware code is loaded into. If the action is succeful, firmware_loaded will
 be updated as 1. In order to load new firmware, firmware_loaded flag should be set 0.

 lpa_mode(read-write)
 Low power  accelerometer mode
 lpa_freq(read-write)
 low power acceleromter frequency.

 accel_matrix
 orient matrix for accel

 flick_lower,
 flick_upper,
 flick_counter,
 flick_message_on,
 flick_int_on,
 flick_axis,
 Flick related entry

 pedometer_time
 pedometer_steps,
 Pedometer related entry

 event_flick
 event_tap
 event_orientation
 event_display_orientation
 event related entry

 tap_on
 control tap function of DMP

 tap_time
 tap_min_count
 tap_threshold
 tap related entries. control various parameters of tap function.

 orientation_on
 turn on/off orientation function of DMP.

 display_orientation_on
 turn on/off display orientation function of DMP.

 quaternion_on
 turn on/off quaterniion data output. must use DMP.
 -------------------------------------------------------------------
 for MPU9150 and secondary compass
 MPU9150 has every entry MPU6050 has. It has additional entries:

 compass_enable (read/write)
 enable this will enable compass function.

 compass_matrix (read-only)
 compass orient matrix
 ---------------------
 for MPU3050 and secondary accelerometer(only BMA250 is supported right now)
 It has every entry ITG3500 has and has two addiontal entries.
 accl_matrix
 accl_enable
 ----------------------------------------------------------------------------------
 low power accelerometer mode
 Lower power accelerometer mode is a special mode. It works only for accelerometer.
 It has two entries, lpa_mode and lpa_freq. Only MPU6050 and MPU9150 has this mode.
 To run low power accel mode, set lpa_mode to 1, set lpa_freq to 0~3, which corresponds
 to 1.25Hz, 5Hz, 20Hz, 40Hz. "gyro_enable" and "compass_enable" must be zero. "dmp_on"
 must be zero.
 -----------------------------------------------------------------------------------
 dmp event.
 dmp event is event out by the DMP unit inside MPU. Only MPU6050 and MPU9150 supports this.
 There are four sysfs entreis, event_flick, event_tap and event_orientation and
 event_display_orientation. These four events must
 be polled before read. The proper method to poll sysfs is:
 1. open file.
 2. dummy read.
 3. poll.
 4. once the poll passed, use fopen and fread to read the sysfs entry.
 5. interpret the data.
 ------------------------------------------------------------------------------
 If streaming to a userspace application, the recommended way to access gyro/accel/compass
 data is via /dev/iio:device0. Follow these steps to get constant readings from
 the driver:

 1. Write a 1 to power_state to turn on the chip. This is the default setting
    after installing the driver.
 2. Write the desired output rate to fifo_rate.
 3. write 1 to enable to turn on the event.
 4. Read /dev/iio:device0 to get a string of gyro/accel/compass data.
 5. Parse this string to obtain each gyro/accel/compass element.
 6. If dmp firmware code is loaded, using "dmp_on" to enable/disable dmp .
 7. If compass is enabled, output will have compass data.
 ===========================================================================
                     Recommended sysfs entry setup senquence
 1. without DMP firmware
 1.1 set "power_state" to 1,
 1.2 change scale and fifo rate value to your need.
 1.3 change gyro_enable and accle_enable and compass_enable to your needs. For example,
 if you want gyro only, set accl_enable to 0 or set accl_enable to zero and compass_enable to zero.
 If you want accel only, set gyro_enable to 0 or set gyro_enable to zero and compass_enable to zero.
 If you want compass only, disable gyro and accel.
 1.4 set "enable" to 1. you will get output you want.

 2. With DMP firmware
 2.1 set "power_state" to 1,
 2.2 write "0" to firmware_loaded if it is not zero already.
 2.3 load firmware into "dmp_firmware" as a whole. Don't split the DMP firmware image.
 2.4 make sure firmware_loaded is 1 after loading.
 2.5 make other configurations similar to the situation as without DMP firmware.
 2.6 set dmp_on to 1.
 2.7 set "enable" to 1.
 =======================================================
 The enable function is using enable entry under "/sys/bus/iio/devices/iio:device0/buffer"
 ==========================================================
 test applications:
 Test application is under ARTHROPOD/trunk/software/simple_apps/mpu_iio
 ------------------------------------------
 To run with MPU9150/MPU6050:
 using the following command:
 for orientation/tap/flick/display orientation event:
 mpu_iio  -c 10 -l 3 -p
 for normal data print
 mpu_iio  -c 10 -l 3
 ----------------------------------------
 To run with MPU3050/ITG3500:
 mpu_iio -c 10 -l 3 -r
 -----------------------------------------
 Please use mpu_iio.c and iio_utils.h as the sample code for your development.
	Kernel driver inv-mpu-iio
	Author: Invensense <http://invensense.com>

	Description
	-----------
	This document describes how to install the Invensense device driver into a
	Linux kernel. At the moment, this driver supports the ITG3500/MPU6050/MPU9150/MPU3050. The slave
	address of these four chips are 0x68. However, the actual slave address depends on the board
	configuration. The driver does not assume anything about it.

	Files included in this package:
	Kconfig
	Makefile
	inv_mpu_core.c
	inv_mpu_misc.c
	inv_mpu_trigger.c
	inv_mpu3050_iio.c
	inv_mpu_iio.h
	inv_mpu_ring.c
	inv_slave_bma250.c
	dmpDefaultMPU6050.c
	dmpkey.h
	dmpmap.h
	mpu.h
	Including the driver in the Linux kernel
	----------------------------------------
	mpu.h should be added to "kernel/include/linux".
	Other files listed should be added to the drivers/staging/iio/imu/mpu directory (or another
	directory of your choosing). When building the kernel, the driver will not
	appear in menuconfig without modifications similar to those below:

	modify "drivers/staging/iio/imu/Kconfig" like
	source "drivers/staging/iio/imu/mpu/Kconfig"

	modify "drivers/staging/iio/imu/Makefile"
	obj-y += mpu/

	Board and Platform Data
	-----------------------
	The board file needs to be modified to register the device on an I2C bus. An
	i2c_board_info instance must be defined as seen below. The hardcoded value of
	140 corresponds to the GPIO input pin wired to the device's interrupt pin.
	This pin will most likely be different for your platform.
	platform data is for orientation matrix, and secondary bus situations.
	For MPU9150, it regarded as a MPU9150 and AKM8975 in the secondary.
	So the secondary i2c address must be filled.
	-----------------------------------------------------------------
	The board file is arch/arm/mach-omap2/board-omap4panda.c or
	modify the board file in your system as below:
	--------------------------------------------------------
	For AKM8963 in the secondary i2c bus of MPU6050,
	static struct mpu_platform_data gyro_platform_data = {
	.int_config = 0x00,
	.level_shifter = 0,
	.orientation = { -1, 0, 0,
	0, 1, 0,
	0, 0, -1 },
	.sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
	.sec_slave_id = COMPASS_ID_AK8963,
	.secondary_i2c_addr = 0x0E
	};
	-----------------------------------------------------------
	For MPU9150, the secondary i2c bus address must be filled as below.
	static struct mpu_platform_data gyro_platform_data = {
	.int_config = 0x00,
	.level_shifter = 0,
	.orientation = { -1, 0, 0,
	0, 1, 0,
	0, 0, -1 },
	.sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
	.sec_slave_id = COMPASS_ID_AK8975,
	.secondary_i2c_addr = 0x0E
	};
	-----------------------------------------------------------
	for BMA250 in the secondary, please use the platform data as:
	static struct mpu_platform_data gyro_platform_data = {
	.int_config = 0x00,
	.level_shifter = 0,
	.orientation = { -1, 0, 0,
	0, 1, 0,
	0, 0, -1 },
	.sec_slave_type = SECONDARY_SLAVE_TYPE_ACCEL,
	.sec_slave_id = ACCEL_ID_BMA250,
	.secondary_i2c_addr = 0x18,
	};
	---------------------------------------------------------------
	the i2c init data is:
	----------------------------------------------------------------
	For MPU3050,
	static struct i2c_board_info __initdata single_chip_board_info[] = {
	{
	I2C_BOARD_INFO("mpu3050", 0x68),
	.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
	.platform_data = &gyro_platform_data,
	},
	};
	----------------------------------------------------------------
	for ITG3500:
	static struct i2c_board_info __initdata single_chip_board_info[] = {
	{
	I2C_BOARD_INFO("itg3500", 0x68),
	.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
	.platform_data = &gyro_platform_data,
	},
	};
	for MPU6050
	static struct i2c_board_info __initdata single_chip_board_info[] = {
	{
	I2C_BOARD_INFO("mpu6050", 0x68),
	.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
	.platform_data = &gyro_platform_data,
	},
	};
	for MPU9150
	arch/arm/mach-omap2/board-omap4panda.c
	static struct i2c_board_info __initdata single_chip_board_info[] = {
	{
	I2C_BOARD_INFO("mpu9150", 0x68),
	.irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
	.platform_data = &gyro_platform_data,
	},
	};

	In the _i2c_init function, the device is registered in the following manner:

	arch/arm/mach-omap2/board-omap4panda.c
	in static int __init omap4_panda_i2c_init(void)
	omap_register_i2c_bus(4, 400, single_chip_board_info, ARRAY_SIZE(single_chip_board_info));

	IIO subsystem
	----------------------------------------------
	successful installation will create two directories under /sys/bus/iio/devices
	iio:device0
	trigger0
	Under /dev/ diretory, a file "iio:device0" will also be created(or iio:deviceX, if
	you have more than one iio devices).
	Communicating with the driver in userspace
	------------------------------------------
	Upon installation, the driver generates several files in sysfs. If your
	platform is configured as detailed above, navigate to the following path to
	find these files:
	/sys/bus/iio/devices/iio:device0

	The list below provides a brief description for each file.
	--------------------------------------
	For ITG3500:
	temperature (Read-only)
	Read temperature data directly from the temperature register.

	sampling_frequency (Read/write)
	Configure the ADC sampling rate and FIFO output rate.

	sampling_frequency_available(read-only)
	show commonly used frequency

	clock_source (Read-only)
	Check which clock-source is used by the chip.

	power_state (Read/write)
	turn on/off the power supply

	self_test (read-only)
	read this entry trigger self test. The return value is D.
	D is the success/fail.
	For different chip, the result is different for success/fail.
	1 means success 0 means fail. The LSB of D is for gyro; the bit
	next to LSB of D is for accel. The bit 2 of D is for compass result.

	key (read-only)
	show the key value of this driver. Used by MPL.

	gyro_matrix (read-only)
	show the orient matrix obtained from board file.

	-------------------------------------------------------------
	For MPU6050:
	MPU6050 has all the sysfs files that ITG3500 has. It has additional files list below:

	gyro_enable (read/write)
	enable/disable gyro functionality. affect raw_gyro. turn off this will shut down gyro and save power.

	accl_enable (read/write)
	enable/disable accelerometer functionality. affect raw_accl. turn off this will shut down accel and save power.

	firmware_loaded (read/write)
	Flag indicate the whether firmware is loaded or not in the DMP engine. 0 means no firmware loaded.
	1 means firmware is already loaded . This flag can only be written as 0. 1 is updated
	internally.

	dmp_on(read/write)
	This entry controls whether to run DMP or not. To enable DMP , firmware_loaded must be 1. write 1 to enable
	DMP and write 0 to disable dmp.

	dmp_in_on(read/write)
	This entry controls whether dmp interrupt is on/off. firmware_loaded must be 1. sometimes, it is desirable
	that interrupt is off while DMP is running.

	dmp_firmware (write only binary file)
	This is the entry that firmware code is loaded into. If the action is succeful, firmware_loaded will
	be updated as 1. In order to load new firmware, firmware_loaded flag should be set 0.

	lpa_mode(read-write)
	Low power accelerometer mode
	lpa_freq(read-write)
	low power acceleromter frequency.

	accel_matrix
	orient matrix for accel

	flick_lower,
	flick_upper,
	flick_counter,
	flick_message_on,
	flick_int_on,
	flick_axis,
	Flick related entry

	pedometer_time
	pedometer_steps,
	Pedometer related entry

	event_flick
	event_tap
	event_orientation
	event_display_orientation
	event related entry

	tap_on
	control tap function of DMP

	tap_time
	tap_min_count
	tap_threshold
	tap related entries. control various parameters of tap function.

	orientation_on
	turn on/off orientation function of DMP.

	display_orientation_on
	turn on/off display orientation function of DMP.

	quaternion_on
	turn on/off quaterniion data output. must use DMP.
	-------------------------------------------------------------------
	for MPU9150 and secondary compass
	MPU9150 has every entry MPU6050 has. It has additional entries:

	compass_enable (read/write)
	enable this will enable compass function.

	compass_matrix (read-only)
	compass orient matrix
	---------------------
	for MPU3050 and secondary accelerometer(only BMA250 is supported right now)
	It has every entry ITG3500 has and has two addiontal entries.
	accl_matrix
	accl_enable
	----------------------------------------------------------------------------------
	low power accelerometer mode
	Lower power accelerometer mode is a special mode. It works only for accelerometer.
	It has two entries, lpa_mode and lpa_freq. Only MPU6050 and MPU9150 has this mode.
	To run low power accel mode, set lpa_mode to 1, set lpa_freq to 0~3, which corresponds
	to 1.25Hz, 5Hz, 20Hz, 40Hz. "gyro_enable" and "compass_enable" must be zero. "dmp_on"
	must be zero.
	-----------------------------------------------------------------------------------
	dmp event.
	dmp event is event out by the DMP unit inside MPU. Only MPU6050 and MPU9150 supports this.
	There are four sysfs entreis, event_flick, event_tap and event_orientation and
	event_display_orientation. These four events must
	be polled before read. The proper method to poll sysfs is:
	1. open file.
	2. dummy read.
	3. poll.
	4. once the poll passed, use fopen and fread to read the sysfs entry.
	5. interpret the data.
	------------------------------------------------------------------------------
	If streaming to a userspace application, the recommended way to access gyro/accel/compass
	data is via /dev/iio:device0. Follow these steps to get constant readings from
	the driver:

	1. Write a 1 to power_state to turn on the chip. This is the default setting
	after installing the driver.
	2. Write the desired output rate to fifo_rate.
	3. write 1 to enable to turn on the event.
	4. Read /dev/iio:device0 to get a string of gyro/accel/compass data.
	5. Parse this string to obtain each gyro/accel/compass element.
	6. If dmp firmware code is loaded, using "dmp_on" to enable/disable dmp .
	7. If compass is enabled, output will have compass data.
	===========================================================================
	Recommended sysfs entry setup senquence
	1. without DMP firmware
	1.1 set "power_state" to 1,
	1.2 change scale and fifo rate value to your need.
	1.3 change gyro_enable and accle_enable and compass_enable to your needs. For example,
	if you want gyro only, set accl_enable to 0 or set accl_enable to zero and compass_enable to zero.
	If you want accel only, set gyro_enable to 0 or set gyro_enable to zero and compass_enable to zero.
	If you want compass only, disable gyro and accel.
	1.4 set "enable" to 1. you will get output you want.

	2. With DMP firmware
	2.1 set "power_state" to 1,
	2.2 write "0" to firmware_loaded if it is not zero already.
	2.3 load firmware into "dmp_firmware" as a whole. Don't split the DMP firmware image.
	2.4 make sure firmware_loaded is 1 after loading.
	2.5 make other configurations similar to the situation as without DMP firmware.
	2.6 set dmp_on to 1.
	2.7 set "enable" to 1.
	=======================================================
	The enable function is using enable entry under "/sys/bus/iio/devices/iio:device0/buffer"
	==========================================================
	test applications:
	Test application is under ARTHROPOD/trunk/software/simple_apps/mpu_iio
	------------------------------------------
	To run with MPU9150/MPU6050:
	using the following command:
	for orientation/tap/flick/display orientation event:
	mpu_iio -c 10 -l 3 -p
	for normal data print
	mpu_iio -c 10 -l 3
	----------------------------------------
	To run with MPU3050/ITG3500:
	mpu_iio -c 10 -l 3 -r
	-----------------------------------------
	Please use mpu_iio.c and iio_utils.h as the sample code for your development.