drivers/staging/iio/imu/inv_mpu/README

   1 Kernel driver inv-mpu-iio
   2 Author: Invensense <http://invensense.com>
   3
   4 Table of Contents:
   5 ==================
   6 - Description
   7 - Integrating the Driver in the Linux Kernel
   8 - Board and Platform Data
   9     > Interrupt Pin
  10     > Platform Data
  11 - Board File Modifications for Secondary I2C Configuration
  12     > MPU-6050 + AKM8963 on the secondary I2C interface
  13     > MPU-6500 + AKM8963 on the secondary I2C interface
  14     > MPU-9150
  15     > MPU-9250
  16     > MPU-3050 + BMA250 on the secondary I2C interface
  17 - Board File Modifications for Invensense Devices
  18     > MPU-3050
  19     > ITG-3500
  20     > MPU-6050
  21     > MPU-6500
  22     > MPU-6XXX
  23     > MPU-9150
  24     > MPU-9250
  25 - IIO Subsystem
  26     > Communicating with the Driver in Userspace
  27     > ITG-3500
  28     > MPU-6050 and MPU-6500
  29     > MPU-9150
  30     > MPU-9250
  31     > MPU-3050 + BMA250 on the secondary I2C interface
  32 - Suspend and Resume
  33 - DMP Event
  34 - Motion Event
  35 - Streaming Data to an Userspace Application
  36 - Recommended Sysfs Entry Setup Sequence
  37     > With DMP Firmware
  38     > Without DMP Firmware
  39 - Test Applications
  40     > Running Test Applications with MPU-9150/MPU-6050/MPU-6500/MPU-9250
  41     > Running Test Applications with MPU-3050/ITG-3500
  42
  43
  44 Description
  45 ===========
  46 This document describes how to install the Invensense device driver into a
  47 Linux kernel. The Invensense driver currently supports the following sensors:
  48 - ITG-3500
  49 - MPU-6050
  50 - MPU-9150
  51 - MPU-6500
  52 - MPU-9250
  53 - MPU-3050
  54 - MPU-6XXX(either MPU6050 or MPU6500, driver to do auto detection)
  55
  56 The slave address of each device is either 0x68 or 0x69, depending on the AD0
  57 pin value of the device. Please refer to the appropriate product specification
  58 document for further information regarding the AD0 pin. The driver supports both
  59 addresses.
  60
  61 The following files are included in this package:
  62 - Kconfig
  63 - Makefile
  64 - inv_mpu_core.c
  65 - inv_mpu_misc.c
  66 - inv_mpu_trigger.c
  67 - inv_mpu3050_iio.c
  68 - inv_mpu_iio.h
  69 - inv_mpu_ring.c
  70 - inv_slave_bma250.c
  71 - dmpDefaultMPU6050.c
  72 - dmpkey.h
  73 - dmpmap.h
  74 - mpu.h
  75
  76
  77 Integrating the Driver in the Linux Kernel
  78 ==========================================
  79 Please add the files as follows:
  80 - Add mpu.h to "kernel/include/linux".
  81 - Add all other files to drivers/staging/iio/imu/inv_mpu
  82 (another directory is acceptable, but this is the recommended destination)
  83
  84 In order to see the driver in menuconfig when building the kernel, please
  85 make modifications as shown below:
  86
  87     modify "drivers/staging/iio/imu/Kconfig" with:
  88     >> source "drivers/staging/iio/imu/inv_mpu/Kconfig"
  89
  90     modify "drivers/staging/iio/imu/Makefile" with:
  91     >> obj-y += inv_mpu/
  92
  93
  94 Board and Platform Data
  95 =======================
  96 In order to recognize the Invensense device on the I2C bus, the board file must
  97 be modified.
  98 The i2c_board_info instance must be defined as shown below.
  99
 100 Interrupt Pin
 101 -------------
 102 The hardcoded value of 140 corresponds to the GPIO input pin connected to the
 103 Invensense device's interrupt pin.
 104 This pin will most likely be different for your platform, and the value should
 105 be changed accordingly.
 106
 107 Platform Data
 108 -------------
 109 The platform data (orientation matrix and secondary bus configurations) must be
 110 modified as show below, according to your particular platform configuration.
 111
 112 Please note that the MPU-9150 it is treated as a MPU-6050 with AKM8975 on the
 113 device's secondary I2C interface. Thus the secondary I2C address must be
 114 provided.
 115
 116 Please note that the MPU-9250 it is treated as a MPU-6500 with AKM8963 on the
 117 device's secondary I2C interface. Thus the secondary I2C address must be
 118 provided.
 119
 120 Board File Modifications for Secondary I2C Configuration
 121 ========================================================
 122 For the Panda Board, the board file can be found at
 123 arch/arm/mach-omap2/board-omap4panda.c.
 124 Please modify the pertinent baord file in your system according to the examples
 125 shown below:
 126
 127 MPU-6050 + AKM8963 on the secondary I2C interface
 128 -------------------------------------------------
 129 static struct mpu_platform_data gyro_platform_data = {
 130         .int_config  = 0x00,
 131         .level_shifter = 0,
 132         .orientation = {  -1,  0,  0,
 133                            0,  1,  0,
 134                            0,  0, -1 },
 135         .sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 136         .sec_slave_id   = COMPASS_ID_AK8963,
 137         .secondary_i2c_addr = 0x0E,
 138         .secondary_orientation = { 0,  1, 0,
 139                                    1,  0,  0,
 140                                    0,  0, -1 },
 141 };
 142
 143 MPU-6500 + AKM8963 on the secondary I2C interface
 144 -------------------------------------------------
 145 static struct mpu_platform_data gyro_platform_data = {
 146         .int_config  = 0x00,
 147         .level_shifter = 0,
 148         .orientation = {  -1,  0,  0,
 149                            0,  1,  0,
 150                            0,  0, -1 },
 151         .sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 152         .sec_slave_id   = COMPASS_ID_AK8963,
 153         .secondary_i2c_addr = 0x0E,
 154         .secondary_orientation = { 0,  1, 0,
 155                                    1,  0,  0,
 156                                    0,  0, -1 },
 157 };
 158
 159 MPU-9150
 160 --------
 161 For MPU-9150, please provide the following secondary I2C bus information.
 162
 163 static struct mpu_platform_data gyro_platform_data = {
 164         .int_config  = 0x10,
 165         .level_shifter = 0,
 166         .orientation = {   1,  0,  0,
 167                            0,  1,  0,
 168                            0,  0,  1 },
 169         .sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 170         .sec_slave_id   = COMPASS_ID_AK8975,
 171         .secondary_i2c_addr = 0x0C,
 172         .secondary_orientation = { 0,  1, 0,
 173                                    1,  0,  0,
 174                                    0,  0, -1 },
 175 };
 176
 177 MPU-9250
 178 --------
 179 For MPU-9250, please provide the following secondary I2C bus information.
 180
 181 static struct mpu_platform_data gyro_platform_data = {
 182         .int_config  = 0x00,
 183         .level_shifter = 0,
 184         .orientation = {   1,  0,  0,
 185                            0,  1,  0,
 186                            0,  0, 1 },
 187         .sec_slave_type = SECONDARY_SLAVE_TYPE_COMPASS,
 188         .sec_slave_id   = COMPASS_ID_AK8963,
 189         .secondary_i2c_addr = 0x0C,
 190         .secondary_orientation = { 0,  1, 0,
 191                                    -1, 0,  0,
 192                                    0,  0,  1 },
 193 };
 194
 195 MPU-3050 + BMA250 on the secondary I2C interface
 196 ------------------------------------------------
 197 For BMA250 on the secondary I2C bus, please provide the following information.
 198
 199 static struct mpu_platform_data gyro_platform_data = {
 200         .int_config  = 0x10,
 201         .level_shifter = 0,
 202         .orientation = {  -1,  0,  0,
 203                            0,  1,  0,
 204                            0,  0, -1 },
 205         .sec_slave_type = SECONDARY_SLAVE_TYPE_ACCEL,
 206         .sec_slave_id   = ACCEL_ID_BMA250,
 207         .secondary_i2c_addr = 0x18,
 208         .secondary_orientation = {   -1,  0,   0,
 209                                                                  0,  -1,   0,
 210                                                                  0,  0,   1 },
 211 };
 212
 213
 214 Board File Modifications for Invensense Devices
 215 ===============================================
 216 For Invensense devices, please provide the i2c init data as shown in the
 217 examples below.
 218
 219 In the _i2c_init function, the device is registered in the following manner:
 220
 221     // arch/arm/mach-omap2/board-omap4panda.c
 222     // in static int __init omap4_panda_i2c_init(void)
 223     omap_register_i2c_bus(4, 400,
 224                           single_chip_board_info,
 225                           ARRAY_SIZE(single_chip_board_info));
 226
 227 MPU-3050
 228 --------
 229 static struct i2c_board_info __initdata single_chip_board_info[] = {
 230         {
 231                 I2C_BOARD_INFO("mpu3050", 0x68),
 232                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 233                 .platform_data = &gyro_platform_data,
 234         },
 235 };
 236
 237 ITG-3050
 238 --------
 239 static struct i2c_board_info __initdata single_chip_board_info[] = {
 240         {
 241                 I2C_BOARD_INFO("itg3500", 0x68),
 242                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 243                 .platform_data = &gyro_platform_data,
 244         },
 245 };
 246
 247 MPU6050
 248 -------
 249 static struct i2c_board_info __initdata single_chip_board_info[] = {
 250         {
 251                 I2C_BOARD_INFO("mpu6050", 0x68),
 252                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 253                 .platform_data = &gyro_platform_data,
 254         },
 255 };
 256
 257 MPU6500
 258 -------
 259 static struct i2c_board_info __initdata single_chip_board_info[] = {
 260         {
 261                 I2C_BOARD_INFO("mpu6500", 0x68),
 262                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 263                 .platform_data = &gyro_platform_data,
 264         },
 265 };
 266
 267 MPU6XXX
 268 -------
 269 static struct i2c_board_info __initdata single_chip_board_info[] = {
 270         {
 271                 I2C_BOARD_INFO("mpu6xxx", 0x68),
 272                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 273                 .platform_data = &gyro_platform_data,
 274         },
 275 };
 276
 277 MPU9150
 278 -------
 279 arch/arm/mach-omap2/board-omap4panda.c
 280 static struct i2c_board_info __initdata single_chip_board_info[] = {
 281         {
 282                 I2C_BOARD_INFO("mpu9150", 0x68),
 283                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 284                 .platform_data = &gyro_platform_data,
 285         },
 286 };
 287
 288 MPU9250
 289 -------
 290 arch/arm/mach-omap2/board-omap4panda.c
 291 static struct i2c_board_info __initdata single_chip_board_info[] = {
 292         {
 293                 I2C_BOARD_INFO("mpu9250", 0x68),
 294                 .irq = (IH_GPIO_BASE + MPUIRQ_GPIO),
 295                 .platform_data = &gyro_platform_data,
 296         },
 297 };
 298
 299 IIO subsystem
 300 =============
 301 A successful installation will create the following two new directories under
 302 /sys/bus/iio/devices:
 303     - iio:device0
 304     - trigger0
 305
 306 Also, a new file, "iio:device0", will be created in the /dev/ diretory.
 307 (if you have more than one IIO device, the file will be named "iio:deviceX",
 308 where X is a number)
 309
 310
 311 Communicating with the Driver in Userspace
 312 ------------------------------------------
 313 The driver generates several files in sysfs upon installation.
 314 These files are used to communicate with the driver. The files can be found
 315 at /sys/bus/iio/devices/iio:device0 (or ../iio:deviceX as shown above).
 316
 317 A brief description of the pertinent files for each Invensense device is shown
 318 below:
 319
 320 ITG-3500
 321 --------
 322 temperature (Read-only)
 323 --Read temperature data directly from the temperature register.
 324
 325 sampling_frequency (Read/write)
 326 --Configure the ADC sampling rate and FIFO output rate.
 327
 328 sampling_frequency_available(read-only)
 329 --show commonly used frequency
 330
 331 clock_source (Read-only)
 332 --Check which clock-source is used by the chip.
 333
 334 power_state (Read/write)
 335 --turn on/off the power supply
 336
 337 self_test (read-only)
 338 --read this entry trigger self test. The return value is D.
 339 D is the success/fail.
 340 For different chip, the result is different for success/fail.
 341 1 means success 0 means fail. The LSB of D is for gyro; the bit
 342 next to LSB of D is for accel. The bit 2 of D is for compass result.
 343
 344 key (read-only)
 345 --show the key value of this driver. Used by MPL.
 346
 347 gyro_matrix (read-only)
 348 --show the orientation matrix obtained from the board file.
 349
 350 MPU-6050 and MPU-6500
 351 ---------------------
 352 MPU-6050 and MPU-6500 have all sysfs files belonging to ITG-3500 (shown above).
 353 In addition, it has the files below:
 354
 355 gyro_enable (read/write)
 356 --enable/disable gyro functionality. Affects raw_gyro. Turning this off this
 357   will shut down gyro and save power.
 358
 359 accl_enable (read/write)
 360 --enable/disable accelerometer functionality. Affects raw_accl.
 361 Turning this off this will shut down accel and save power.
 362
 363 firmware_loaded (read/write)
 364 --Flag indicating the whether firmware is loaded or not in the DMP engine.
 365 0 means no firmware loaded. 1 means firmware is already loaded . This
 366 flag can only be written as 0. It internally updates to 1.
 367
 368 dmp_on(read/write)
 369 --This entry controls whether to run DMP or not.
 370 Write 1 to enable DMP and write 0 to disable dmp.
 371 Please note that firmware_loaded must be 1 in order to enable DMP.
 372
 373 dmp_int_on(read/write)
 374 --This entry controls whether dmp interrupt is on/off.
 375 Please note that firmware_loaded must be 1.
 376 Also, we'd like to remind you that it is sometimes advantageous to
 377 turn interrupts off while the DMP is running.
 378
 379 dmp_output_rate
 380 --control dmp output rate when dmp is on.
 381
 382 dmp_event_int_on(read/write)
 383 --This entry controls whether dmp event interrupt is on/off.
 384 Please note that turning this on will turn off the data interrupt.
 385 Interrupts will be generated only when events occur.
 386 This is useful for saving power when the system is waiting for a special event
 387 to wake up.
 388
 389 dmp_firmware (write only binary file)
 390 --DMP firmware code is loaded into this entry.
 391 If loading is successful, the firmware_loaded flag will be updated to 1.
 392 In order to load new firmware, the firmware_loaded flag must be first set to 0.
 393
 394 accel_matrix
 395 --orientation matrix for accelerometer.
 396
 397 quaternion_on
 398 --Turn on/off quaterniion data output. DMP is required for this feature.
 399
 400 pedometer_time
 401 pedometer_steps,
 402 --Pedometer related entries
 403
 404 event_tap
 405 event_display_orientation
 406 event_accel_motion
 407 event_smd
 408 --Event related entries.
 409 Please poll these entries to read their values. Direct reads will yield
 410 meaningless results.
 411 Further details are provided in the DMP Events section of this README.
 412
 413 tap_on
 414 --Controls tap function of DMP
 415
 416 tap_time
 417 tap_min_count
 418 tap_threshold
 419 --Tap related entries. Controls various parameters of tap function.
 420
 421 display_orientation_on
 422 --Turn on/off display orientation function of DMP.
 423
 424 smd_enable
 425 enable SMD(Significant Motion Detection) detection.
 426
 427 smd_threshold
 428 This set the threshold of the motion when SMD start to be triggered. The
 429 value is in acclerometer counts.
 430
 431 smd_delay_threshold
 432 This sets the threshold of time after which SMD can be triggered.
 433 The value is in seconds.
 434
 435 smd_delay_threshold2
 436 This sets the threshold of time during which SMD can be triggered (after the
 437 smd_delay_threshold timer has expired).
 438 The value is in seconds.
 439
 440 quaternion_on
 441 --Turn on/off quaterniion data output. DMP is required for this feature.
 442
 443 Low power accel motion interrupt related settings.
 444 if motion_lpa_on is set, this will disable all engines except accel. Accel will
 445 enter low power mode and the whole chip will be turned on/off at specific frequency.
 446 -----------------------------------------------------------------------------
 447 motion_lpa_duration
 448 --set motion duration. in ms. This means filtered out all the motino interrupts
 449   during this period.
 450
 451 motion_lpa_threshold
 452 --set motion threshold. in mg. The maximum is 1020mg and resolution is 32mg.
 453
 454 motion_lpa_on
 455 --turn on/off motion function.
 456
 457 motion_lpa_freq
 458 --motion lpa frequency. which determines power on/off frequency.
 459 ------------------------------------------------------------------------------
 460 MPU-9150
 461 --------
 462 MPU-9150 has all of MPU-6050's entries. It also has two additional entries,
 463 described below.
 464
 465 compass_enable (read/write)
 466 --Enables compass function.
 467
 468 compass_matrix (read-only)
 469 --Compass orientation matrix
 470
 471 MPU-3050 with BMA250 on secondary I2C interface
 472 -----------------------------------------------
 473 MPU-3050 with BMA250 on the secondary I2C interface has ever ITG-3500 entry.
 474 It also has two additional entries, shown below:
 475
 476 accl_matrix
 477
 478 accl_enable
 479
 480 Suspend and Resume
 481 ===================================================
 482 The suspend and resume functions are call backs registered to the system
 483 and executed when the system goes in suspend and resumes.
 484 It is enabled when CONFIG_PM is defined.
 485 The current behavior is simple:
 486 - suspend will turn off the chip
 487 - resume will turn on the chip
 488
 489 However, it is possible for the driver to do more complex things;
 490 for example, leaving pedometers running when system is off. This can save whole
 491 system power while letting pedometer working. Other behaviors are possible
 492 too.
 493
 494 DMP Event
 495 =========
 496 A DMP Event is an event that is output by the DMP unit within the Invensense
 497 device (MPU).
 498 Only the MPU-6050, MPU-6500, MPU-9250, MPU-9150, MPU-9250 feature the DMP.
 499
 500 There are four sysfs entries for DMP events:
 501 - event_tap
 502 - event_display_orientation
 503 - event_accel_motion
 504 - event_smd
 505
 506 These events must be polled before reading.
 507
 508 The proper method to poll sysfs is as follows:
 509 1. open file.
 510 2. dummy read.
 511 3. poll.
 512 4. once the poll passed, use fopen and fread to read the sysfs entry.
 513 5. interpret the data.
 514
 515 Streaming Data to an Userspace Application
 516 ==========================================
 517 When streaming data to an userspace application, we recommend that you access
 518 gyro/accel/compass data via /dev/iio:device0.
 519
 520 Please follow the steps below to read data at a constant rate from the driver:
 521
 522 1. Write a 1 to power_state to turn on the chip. This is the default setting
 523    after installing the driver.
 524 2. Write the desired output rate to fifo_rate.
 525 3. Write 1 to enable to turn on the event.
 526 4. Read /dev/iio:device0 to get a string of gyro/accel/compass data.
 527 5. Parse this string to obtain each gyro/accel/compass element.
 528 6. If dmp firmware code is loaded, use "dmp_on" to enable/disable dmp.
 529 7. If compass is enabled, the output will contain compass data.
 530
 531
 532 Recommended Sysfs Entry Setup Senquence
 533 =======================================
 534
 535 Without DMP Firmware
 536 --------------------
 537 1. Set "power_state" to 1,
 538 2. Set the scale and fifo rate values according to your needs.
 539 3. Set gyro_enable, accel_enable, and compass_enable according to your needs.
 540    For example:
 541     - If you only want gyro data, set accel_enable to 0 (and compass_enable to
 542       0, if applicable).
 543     - If you only want accel data, set gyro_enable to 0 (and compass_enable to
 544       0, if applicable).
 545     - If you only want compass data, set gyro_enable to 0 and accel_enable to 0.
 546 4. Set "enable" to 1.
 547 5. You will now get the output that you want.
 548
 549 With DMP Firmware
 550 -----------------
 551 1. Set "power_state" to 1.
 552 2. Write "0" to firmware_loaded if it is not zero already.
 553 3. Load firmware into "dmp_firmware" as a whole. Don't split the DMP firmware
 554    image.
 555 4. Make sure firmware_loaded is 1 after loading the DMP image.
 556 5. Make appropriate configurations as shown above in the "without DMP firmware"
 557    case.
 558 6. Set dmp_on to 1.
 559 7. Set "enable" to 1.
 560
 561 Please note that the enable function uses the enable entry under
 562 "/sys/bus/iio/devices/iio:device0/buffer"
 563
 564 Test Applications
 565 =================
 566 A test application is located under software/simple_apps/mpu_iio.
 567 This application is stand-alone in that it cannot be run concurrently with other
 568 entities trying to access the device node(s) or sysfs entries; in particular,
 569 the
 570
 571 Running Test Applications with MPU-9150/MPU-6050/MPU-6500/MPU-9250
 572 ---------------------------------------------------------
 573 To run test applications with MPU-9150, MPU-9250, MPU-6050, or MPU-6500 devices,
 574 please use the following commands:
 575
 576 1. For tap/display orientation events:
 577    mpu_iio -c 10 -l 3 -p
 578
 579 2. In addition, to test the motion interrupt (and no_motion on MPU6050) use:
 580    mpu_iio -c 10 -l 3 -p -m
 581
 582 3. For printing data normally:
 583    mpu_iio -c 10 -l 3 -r
 584
 585 Running Test Applications with MPU-3050/ITG-3500
 586 ------------------------------------------------
 587 To run test applications with MPU-3050 or ITG-3500 devices,
 588 please use the following command:
 589
 590 1. For printing data normally:
 591    mpu_iio -c 10 -l 3 -r
 592
 593 Please use mpu_iio.c and iio_utils.h as example code for your development
 594 purposes.
 595
 596 Stress test application
 597 =================================
 598 A stress test application is located under software/simple_apps/stress_iio.
 599 This application simulates HAL's usage calls to the driver. It creates three
 600 threads. One for data read; one for event read; one for sysfs control.
 601 It can run without any parameters or run with some control parameters. Please
 602 see README in the same directories for details.
 603