diff --git a/README.md b/README.md index e4e6c35..32c1ed7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ +[![Documentation](https://readthedocs.org/projects/esp32-mpu-driver/badge/?version=dev "Documentation Status")](https://esp32-mpu-driver.readthedocs.io/en/dev) +[![Build Status](https://travis-ci.org/natanaeljr/esp32-MPU-driver.svg?branch=dev)](https://travis-ci.org/natanaeljr/esp32-MPU-driver) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + ![MPU Driver][Banner] [Banner]: docs/source/_static/MPUdriver.jpg -[![Documentation](http://esp32-mpu-driver.readthedocs.io/en/latest/?badge=latest "Documentation Status")](http://esp32-mpu-driver.readthedocs.io/en/latest/?version=latest) - A library for _Invensense_ MPU chips. It is written in C++ and designed for working with **[ESP32]** microcontroller _[esp-idf]_ framework. Supports both SPI and I2C protocols interchangeably, selectable bus port, and even multiple connected MPUs. @@ -53,6 +55,8 @@ Supports both SPI and I2C protocols interchangeably, selectable bus port, and ev - [ ] Pedometer - [ ] Gyroscope calibrated data +# Getting Started + ## Prerequisites MPU driver depends on the following protocol libraries to communicate with the chip with ease: [ [I2Cbus] | [SPIbus] ]. @@ -65,62 +69,58 @@ SPIbus: git clone https://github.com/natanaeljr/esp32-SPIbus.git SPIbus **_Note:_** At least one of these libraries must be installed as components for the MPU library to work. It won't work otherwise. -[I2Cbus]: https://github.com/natanaeljr/I2Cbus-esp32 -[SPIbus]: https://github.com/natanaeljr/SPIbus-esp32 +[I2Cbus]: https://github.com/natanaeljr/esp32-I2Cbus +[SPIbus]: https://github.com/natanaeljr/esp32-SPIbus ## Installation -Download the repository [here](https://github.com/natanaeljr/esp32-MPU-driver/archive/master.zip), +Download the repository [here](https://github.com/natanaeljr/esp32-MPU-driver/archive/dev.zip), or clone it right into your project components directory with the following command. ``` -git clone https://github.com/natanaeljr/esp32-MPU-driver.git MPU +git clone https://github.com/natanaeljr/esp32-MPU-driver.git MPU-driver ``` This way you can easily update the library with `git pull` whenever a update is available. -## Getting Started +## Usage -### Usage +First of all, make sure MPU Driver is a component in you project, then run `make menuconfig`, select your chip model and communication protocol you'll use browsing through to `Component config` -> `MPU Driver`. -First all, run `make menuconfig` in your project and select your chip model and communication protocol you'll use browsing to `Component config` -> `MPU Driver`. +![Menuconfig](docs/source/_static/menuconfig_mpu-driver.png "Menuconfig -> MPU Driver") -![Menuconfig](docs/source/_static/menuconfig_mpu-driver.jpg "Menuconfig -> MPU Driver") - -Now, in your source code, include the communication library and initialize it. +Now, in your source code, include the mpu main header `MPU.hpp`, the communication library `I2Cbus.hpp` or `SPIbus.hpp` and any other mpu headers that you'll use. Then get the bus ready as shown below. ```C++ +#include "MPU.hpp" // main file, provides the class itself +#include "mpu/math.hpp" // math helper for dealing with MPU data +#include "mpu/types.hpp" // MPU data types and definitions #include "I2Cbus.hpp" // ... -i2c0.begin(SDA, SCL, CLOCK); +i2c0.begin(SDA, SCL, CLOCK); // initialize the I2C bus ``` -or for SPI: +And for SPI: ```C++ +#include "MPU.hpp" // main file, provides the class itself +#include "mpu/math.hpp" // math helper for dealing with MPU data +#include "mpu/types.hpp" // MPU data types and definitions #include "SPIbus.hpp" // ... -hspi.begin(MOSI, MISO, SCLK); +hspi.begin(MOSI, MISO, SCLK); // initialize the SPI bus spi_device_handle_t mpu_spi_handle; hspi.addDevice(SPIMODE, CLOCK, CS_PIN, &mpu_spi_handle); ``` -Include the mpu main header `MPU.hpp` and any other mpu headers that you'll use as shown below. - -```C++ -#include "MPU.hpp" // main file, provides the class itself -#include "mpu/math.hpp" // math helper for dealing with MPU data -#include "mpu/types.hpp" // MPU data types and definitions - -using namespace emd; // embedded motion driver, contains mpu namespace -``` +**Note**: You can initialize/configure the bus through the _esp-idf_ API normally, it should work just fine too. Create a MPU object, setup and initialize it. ```C++ MPU_t MPU; // create an object -MPU.setBus(i2c0); // set communication bus, for spi: pass 'hspi' -MPU.setAddr(mpu::MPU_I2CADDRESS_AD0_LOW); // set address or handle, for spi: pass 'mpu_spi_handle' +MPU.setBus(i2c0); // set communication bus, for SPI -> pass 'hspi' +MPU.setAddr(mpud::MPU_I2CADDRESS_AD0_LOW); // set address or handle, for SPI -> pass 'mpu_spi_handle' MPU.initialize(); // this will initialize the chip and set default configurations ``` @@ -128,17 +128,17 @@ Call `set` functions to configure the chip as needed. ```C++ MPU.setSampleRate(250); // in (Hz) -MPU.setAccelFullScale(mpu::ACCEL_FS_4G); -MPU.setGyroFullScale(mpu::GYRO_FS_500DPS); -MPU.setDigitalLowPassFilter(mpu::DLPF_42HZ); // smoother data -MPU.setInterruptEnabled(mpu::INT_EN_RAWDATA_READY); // enable INT pin +MPU.setAccelFullScale(mpud::ACCEL_FS_4G); +MPU.setGyroFullScale(mpud::GYRO_FS_500DPS); +MPU.setDigitalLowPassFilter(mpud::DLPF_42HZ); // smoother data +MPU.setInterruptEnabled(mpud::INT_EN_RAWDATA_READY); // enable INT pin ``` Read sensor data: ```C++ -mpu::raw_axes_t accelRaw; // holds x, y, z axes as int16 -mpu::raw_axes_t gyroRaw; // holds x, y, z axes as int16 +mpud::raw_axes_t accelRaw; // holds x, y, z axes as int16 +mpud::raw_axes_t gyroRaw; // holds x, y, z axes as int16 MPU.acceleration(&accelRaw); // fetch raw data from the registers MPU.rotation(&gyroRaw); // fetch raw data from the registers printf("accel: %+d %+d %+d\n", accelRaw.x, accelRaw.y, accelRaw.z); @@ -148,15 +148,16 @@ printf("gyro: %+d %+d %+d\n", gyroRaw[0], gyroRaw[1], gyroRaw[2]); Convert to more readable formats. ```C++ -mpu::float_axes_t accelG = mpu::accelGravity(accelRaw, mpu::ACCEL_FS_4G); // raw data to gravity -mpu::float_axes_t gyroDPS = mpu::gyroDecPerSec(gyroRaw, mpu::GYRO_FS_500DPS); // raw data to º/s +mpud::float_axes_t accelG = mpud::accelGravity(accelRaw, mpud::ACCEL_FS_4G); // raw data to gravity +mpud::float_axes_t gyroDPS = mpud::gyroDecPerSec(gyroRaw, mpud::GYRO_FS_500DPS); // raw data to º/s printf("accel: %+.2f %+.2f %+.2f\n", accelG[0], accelG[1], accelG[2]); printf("gyro: %+.2f %+.2f %+.2f\n", gyroDPS.x, gyroDPS.y, gyroDPS.z); ``` -The API provides many other functions to manage and operate the sensor in its full potencial. See the **[API Reference]** for more details. - -[API Reference]: https://natanaeljr.github.io/esp32-mpu-driver +The API provides many other functions to manage and operate the sensor in its full potencial. See + +API Reference +. ## Tests @@ -168,6 +169,6 @@ See [MPU Unit Test] for more information. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ---- - Copyright © 2017-2018, Natanael Josue Rabello [_natanael.rabello@outlook.com_] + +--- diff --git a/docs/source/_static/menuconfig_mpu-driver.jpg b/docs/source/_static/menuconfig_mpu-driver.jpg deleted file mode 100644 index 72b55bb..0000000 Binary files a/docs/source/_static/menuconfig_mpu-driver.jpg and /dev/null differ diff --git a/docs/source/_static/menuconfig_mpu-driver.png b/docs/source/_static/menuconfig_mpu-driver.png new file mode 100644 index 0000000..67d0916 Binary files /dev/null and b/docs/source/_static/menuconfig_mpu-driver.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 5ed8913..0fb5575 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,13 +13,19 @@ Introduction `MPU Driver` is a C++ library developed for ESP32 Microcontroller. It is meant to provide a complete interface for working with Invensense MPU chips. -Reference -========= +API Reference +============= -* :ref:`genindex` -* :ref:`search` +|api_reference_link|. -Test -==== +.. |api_reference_link| raw:: html + + Click Here + +.. * :ref:`genindex` +.. * :ref:`search` + +Test Section +============ .. doxygentypedef:: MPU_t \ No newline at end of file