1/*
2 * Copyright (C) 2016-2017 STMicroelectronics
3 *
4 * Author: Denis Ciocca <denis.ciocca@st.com>
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 *    http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19    <---------- Introduction ---------->
20
21In order to build the driver for a platform some macros (see Macros list) must
22be defined into variant.h file. [variant/{VARIANT_NAME}/inc/variant/variant.h]
23Those macros define specific configuration that is platform dependent (SPI bus,
24SPI frequency, etc).
25
26Optional FLAGS (FLAGS list) can be used to enable specific features using
27variant makefile. [variant/{VARIANT_NAME}/{VARIANT_NAME}.mk]
28Those flags modify @ compile time the behavior of the driver enabling for
29example i2c master support or calibration libraries.
30
31
32    <---------- Macros list ---------->
33
34#define LSM6DSM_SPI_SLAVE_BUS_ID                    1                           /* SPI bus ID, on STM32F4xx indicate SPI2 */
35#define LSM6DSM_SPI_SLAVE_FREQUENCY_HZ              8000000                     /* SPI frequency in Hz */
36#define LSM6DSM_SPI_SLAVE_CS_GPIO                   GPIO_PB(12)                 /* SPI NSS pin, on STM32F4xx indicate NSS of SPI2 */
37
38#define LSM6DSM_INT_IRQ                             EXTI2_IRQn
39#define LSM6DSM_INT1_GPIO                           GPIO_PB(6)                  /* LSM6DSM INT1 is required, here connected to STM32F4xx PB6 */
40
41#define LSM6DSM_ACCEL_GYRO_ROT_MATRIX               1, 0, 0, 0, 1, 0, 0, 0, 1   /* Accelerometer and gyroscope axis orientation */
42#define LSM6DSM_MAGN_ROT_MATRIX                     1, 0, 0, 0, 1, 0, 0, 0, 1   /* Magnetometer axis orientation [MUST be set if a magn sensor is enabled] */
43
44#define LSM6DSM_LIS3MDL_I2C_ADDRESS                 0x1e                        /* STM LIS3MDL I2C address */
45#define LSM6DSM_LPS22HB_I2C_ADDRESS                 0x5d                        /* STM LPS22HB I2C address */
46
47
48    <---------- FLAGS list ---------->
49
50- LSM6DSM_DBG_ENABLED                       /* Enable debug messages */
51- LSM6DSM_ACCEL_CALIB_ENABLED               /* Enable accelerometer bias calibration */
52- LSM6DSM_GYRO_CALIB_ENABLED                /* Enable gyroscope bias calibration */
53- LSM6DSM_OVERTEMP_CALIB_ENABLED            /* Enable gyroscope over temperature bias calibration [Require LSM6DSM_GYRO_CALIB_ENABLED] */
54- LSM6DSM_MAGN_CALIB_ENABLED                /* Enable magnetometer offset calibration */
55
56- LSM6DSM_I2C_MASTER_USE_INTERNAL_PULLUP    /* Use internal pull-up resistors for I2C master interface */
57
58/* Magnetometer sensor (only one per time can be used) */
59- LSM6DSM_I2C_MASTER_LIS3MDL                /* Enable STM LIS3MDL magn sensor */
60- LSM6DSM_I2C_MASTER_LSM303AGR              /* Enable STM LSM303AGR magn sensor */
61- LSM6DSM_I2C_MASTER_AK09916                /* Enable AKM AK09916 magn sensor */
62
63/* Barometer sensor (only one per time can be used) */
64- LSM6DSM_I2C_MASTER_LPS22HB                /* Enable STM LPS22HB pressure sensor */
65
66Example: variant/nucleo/nucleo.mk
67
68FLAGS += -DLSM6DSM_DBG_ENABLED -DLSM6DSM_ACCEL_CALIB_ENABLED -DLSM6DSM_GYRO_CALIB_ENABLED -DLSM6DSM_OVERTEMP_CALIB_ENABLED
69FLAGS += -DLSM6DSM_I2C_MASTER_LSM303AGR -DLSM6DSM_I2C_MASTER_USE_INTERNAL_PULLUP -DLSM6DSM_MAGN_CALIB_ENABLED
70
71
72    <---------- ROT_MATRIX macro explanation ---------->
73
74Sensors orientation can be modified through rotation matrices. Accelerometer and gyroscope are sharing same
75configuration (LSM6DSM_ACCEL_GYRO_ROT_MATRIX), magnetometer sensor different one (LSM6DSM_MAGN_ROT_MATRIX).
76It is following standard rule of matrices moltiplications.
77Here an example:
78
79                       [r11 r12 r13]
80[x" y" z"] = [x y z] * [r21 r22 r23] = [(x*r11 + y*r21 + z*r31) (x*r12 + y*r22 + z*r32) (x*r13 + y*r23 + z*r33)]
81                       [r31 r32 r33]
82
83where x,y,z are sensors output and x",y",z" are android coordinate system data.
84Matrix is so defined:
85#define LSM6DSM_ACCEL_GYRO_ROT_MATRIX                   r11,r12,r13,r21,r22,r23,r31,r32,r33
86
87r** can only be: 0 or 1 or -1.
88
89
90    <---------- Supported features ---------->
91
92> Accel & Gyro data;
93> Accel bias calibration through accel_cal lib;
94> Gyro bias calibration through gyro_cal & gyro_stillnes_detect libs;
95> Step detector & counter;
96> Significant motion;
97> Magnetometer sensor connected through I2C master interface (LIS3MDL, LSM303AGR, AK09916);
98> Magnetometer calibration though mag_cal lib;
99> Pressure sensor connected through I2C master interface (LPS22HB);
100