drivers/iio/magnetometer/inv_compass/README

   1 Kernel driver
   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     > Platform Data
  10 - Board File Modifications for compass
  11     > AMI306
  12     > YAS530/532/533
  13 - IIO Subsystem
  14     > Communicating with the Driver in Userspace
  15 - Streaming Data to an Userspace Application
  16 - Test Applications
  17     > Running Test Applications with AMI306 or YAS53x
  18
  19 Description
  20 ===========
  21 This document describes how to install the Invensense device driver for AMI306
  22 and YAS53x series compass chip into a Linux kernel. The Invensense driver
  23 currently supports the following sensors:
  24 - AMI306
  25 - YAS530
  26 - YAS532
  27 - YAS533
  28
  29 Please refer to the appropriate product specification
  30 document for further information regarding the slave address.
  31
  32 The following files are included in this package:
  33 - Kconfig
  34 - Makefile
  35 - inv_ami306_core.c
  36 - inv_ami306_ring.c
  37 - inv_ami306_trigger.c
  38 - inv_ami306_iio.h
  39 - inv_yas53x_core.c
  40 - inv_yas53x_ring.c
  41 - inv_yas53x_trigger.c
  42 - inv_yas53x_iio.h
  43
  44 Integrating the Driver in the Linux Kernel
  45 ==========================================
  46 Please add the files as follows:
  47 - Add all above files to drivers/staging/iio/magnetometer/inv_compass
  48 (another directory is acceptable, but this is the recommended destination)
  49
  50 In order to see the driver in menuconfig when building the kernel, please
  51 make modifications as shown below:
  52
  53     modify "drivers/staging/iio/magnetometer/Kconfig" with:
  54     >> source "drivers/staging/iio/magnetometer/inv_compass/Kconfig"
  55
  56     modify "drivers/staging/iio/magnetometer/Makefile" with:
  57     >> obj-y += inv_compass/
  58
  59
  60 Board and Platform Data
  61 =======================
  62 In order to recognize the Invensense device on the I2C bus, the board file must
  63 be modified.
  64 The i2c_board_info instance must be defined as shown below.
  65
  66 Platform Data
  67 -------------
  68 The platform data (orientation matrix and secondary bus configurations) must be
  69 modified as show below, according to your particular platform configuration.
  70
  71 Board File Modifications for Secondary I2C Configuration
  72 ========================================================
  73 For the Panda Board, the board file can be found at
  74 arch/arm/mach-omap2/board-omap4panda.c.
  75 Please modify the pertinent baord file in your system according to the examples
  76 shown below:
  77
  78 AMI306
  79 -------------------------------------------------
  80 static struct mpu_platform_data compass_data = {
  81         .orientation = {   0,  0,  1,
  82                            0,  1,  0,
  83                            1,  0,  0 },
  84 };
  85
  86 static struct i2c_board_info __initdata chip_board_info[] = {
  87         {
  88                 I2C_BOARD_INFO("ami306", 0x0E),
  89                 .platform_data = &compass_data,
  90         },
  91 };
  92
  93 YAS53x(Use YAS532 as an example)
  94 -------------------------------------------------
  95 static struct mpu_platform_data compass_data = {
  96         .orientation = {   0,  -1, 0,
  97                            1,  0,  0,
  98                            0,  0,  1 },
  99 };
 100
 101 static struct i2c_board_info __initdata compass_board_info[] = {
 102         {
 103                 I2C_BOARD_INFO("yas532", 0x2E),
 104                 .platform_data = &compass_data,
 105         },
 106 };
 107
 108 IIO subsystem
 109 =============
 110 A successful installation will create the following two new directories under
 111 /sys/bus/iio/devices:
 112     - iio:device0
 113     - trigger0
 114
 115 Also, a new file, "iio:device0", will be created in the /dev/ diretory.
 116 (if you have more than one IIO device, the file will be named "iio:deviceX",
 117 where X is a number)
 118
 119
 120 Communicating with the Driver in Userspace
 121 ------------------------------------------
 122 The driver generates several files in sysfs upon installation.
 123 These files are used to communicate with the driver. The files can be found
 124 at /sys/bus/iio/devices/iio:device0 (or ../iio:deviceX as shown above).
 125
 126 A brief description of the pertinent files for each Invensense device is shown
 127 below:
 128
 129 AMI306
 130 --------
 131 compass_matrix (read-only)
 132 --show the orientation matrix obtained from the board file.
 133
 134 sampling_frequency(read and write)
 135 --show and change the sampling rate of the sensor.
 136
 137 YAS53x
 138 ---------------------
 139 YAS53x has all the attributes AMI306 has. It has one more additional attribute:
 140
 141 overunderflow(read-only)
 142 --value 1 shows an overflow or underflow happens. Need to write into it to make
 143   it zero.
 144
 145 Streaming Data to an Userspace Application
 146 ==========================================
 147 When streaming data to an userspace application, we recommend that you access
 148 compass data via /dev/iio:device0.
 149
 150 Please follow the steps below to read data at a constant rate from the driver:
 151
 152 1. Write the desired output rate to sampling_frequency.
 153 2. Write 1 to enable to turn on the event.
 154 3. Read /dev/iio:device0 to get a string of gyro/accel/compass data.
 155 4. Parse this string to obtain each compass element.
 156
 157 Test Applications
 158 =================
 159 A test application is located under software/simple_apps/mpu_iio.
 160 This application is stand-alone in that it cannot be run concurrently with other
 161 entities trying to access the device node(s) or sysfs entries; in particular,
 162 the
 163
 164 Running Test Applications
 165 ---------------------------------------------------------
 166 To run test applications with AMI306 or YAS53x devices,
 167 please use the following commands:
 168
 169 1. for ami306:
 170    mpu_iio -n ami306 -c 10 -l 3
 171
 172 2. for yas532:
 173    mpu_iio -n yas532 -c 10 -l 3
 174
 175 Please use mpu_iio.c and iio_utils.h as example code for your development
 176 purposes.