Merge pull request #5 from stephendpmurphy/dev

Release dev into master branch

Author: stephendpmurphy

README.md

@@ -1,14 +1,27 @@
 # ICM-20948 9-Axis MEMS Motion Tracking Sensor Driver
 [![Release](https://img.shields.io/github/release/stephendpmurphy/icm20948.svg?style=flat-square)](https://github.com/stephendpmurphy/icm20948/releases/latest)
 ![CI](https://github.com/stephendpmurphy/icm20948/workflows/CI/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+C Driver for the IC-20948 9-Axis Telemetry sensor. This driver can be included directly into a developers source or a static library can be created and then linked against. Development is done on the **dev** branch, and official releases can be found on the **master** branch. Releases will be made on a ~monthly basis assuming no driver breaking bugs are found. Otherwise, a fix will be released to **master** ASAP.
+
+## Currently supported features
+The currently supported features are below. The API is written to greatly simplify the implementation of this IC, and thus only a small amount of control is given to the end-user. In the future, settings/config will be added to allow a user to change sample rates, resolution and more for each sensor in this part. 
 </br>
-C Driver for the IC-20948 9-Axis Telemetry sensor. This driver can be included directly into a developers source or a static library can be created and then linked against.
-</br></br>
-Development is done on the *dev* branch, and official releases can be found on the *master* branch. Releases will be made on a ~monthly basis assuming no driver breaking bugs are found. Otherwise, a fix will be released to *master* ASAP.
+Currently supported features:
+* Accel
+    * +-2G
+    * +-4G
+    * +-8G
+    * +-16G
+* Gyro
+    * +-250DPS
+    * +-500DPS
+    * +-1000DPS
+    * +-2000DPS
 
 ## Retrieving the Source
-The source is located on Github and can be either downloaded and included directly into a developers source directoriy or the developer can add this repo as a submodule into their source (The latter is the preferred method).
+The source is located on Github and can be either downloaded and included directly into a developers source OR the developer can add this repo as a submodule into their project directory (The latter is the preferred method).
 
 To include the driver as a git submodule
 ```bash
@@ -18,7 +31,13 @@ $ git submodule add https://github.com/stephendpmurphy/icm20948.git
 
 ## Integration
 #### Creating & Linking against a static library
-To create a static library to link against, you must first source your build environment and ensure the **CC** environment variable is set to your desired toolchain. Once your cross-compiler is properly setup. Execute the following commands:
+To create a static library to link against, you must first source your build environment and ensure the **CC** environment variable is set to your desired toolchain. Below is an example of sourcing the **AVR** toolchain before compiling.
+```bash
+$ export CC=/usr/bin/avr-gcc
+$ export CXX=/usr/bin/avr-g++
+```
+
+Once your cross-compiler is properly setup. Execute the following commands:
 ```bash
 $ mkdir build && cd build
 $ cmake ..
@@ -53,15 +72,15 @@ Example application and main can be found below:
 
 int8_t usr_write(uint8_t addr, uint8_t *data, uint32_t len) {
     icm20948_return_code_t ret = ICM20948_RET_OK;
-    
+
     // Assert the CS
 
     // Write the address
 
     // Write the data from the provided data buffer
 
     // De-assert the CS
-    
+
     return ret;
 }
 
@@ -80,7 +99,7 @@ int8_t usr_read(uint8_t addr, uint8_t *data, uint32_t len) {
 }
 
 void usr_delay_us(uint32_t period) {
-    // Delay for the requested period
+    // uS Delay for the requested period
 }
 
 int main(void) {
@@ -92,19 +111,25 @@ int main(void) {
     // Init the device function pointers
     ret = icm20948_init(usr_read, usr_write, usr_delay_us);
 
+    // Check if we successfully stored the function poiners provided
     if( ret == ICM20948_RET_OK ) {
-        // Enable the gyro
-        settings.gyro_en = ICM20948_GYRO_ENABLE;
-        // Enable the accelerometer
-        settings.accel_en = ICM20948_ACCEL_ENABLE;
-        // Apply the settings
+        // Enable the Gyro
+        settings.gyro.en = ICM20948_MOD_ENABLED;
+        // Select the +-20000dps range
+        settings.gyro.fs = ICM20948_GYRO_FS_SEL_2000DPS;
+        // Enable the Accel
+        settings.accel.en = ICM20948_MOD_ENABLED;
+        // Select the +-2G range
+        settings.accel.fs = ICM20948_ACCEL_FS_SEL_2G;
         ret = icm20948_applySettings(&settings);
     }
 
     while(1) {
-        // Retireve the Gyro data and store it in our gyro_data struct
+        // Retrieve the Gyro data and store it in our gyro_data struct
+        // Output is in dps (Degress per second)
         ret |= icm20948_getGyroData(&gyro_data);
         // Retrieve the Accel data and store it in our accel_data struct
+        // Output is in mG
         ret |= icm20948_getAccelData(&accel_data);
     }
 
@@ -113,4 +138,5 @@ int main(void) {
 ```
 
 ## License
-MIT License
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) </br>
+License has been provided with this source and can be found in the [License](./LICENSE) file.

inc/icm20948_api.h

@@ -32,15 +32,6 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-#define ICM20948_GYRO_ENABLE    (true)
-#define ICM20948_GYRO_DISABLE   (false)
-
-#define ICM20948_ACCEL_ENABLE   (true)
-#define ICM20948_ACCEL_DISABLE  (false)
-
-#define ICM20948_MAG_ENABLE     (true)
-#define ICM20948_MAG_DISABLE    (false)
-
 typedef int8_t(*icm20948_read_fptr_t)(const uint8_t addr, uint8_t *data, const uint32_t len);
 typedef int8_t(*icm20948_write_fptr_t)(const uint8_t addr, const uint8_t *data, const uint32_t len);
 typedef void(*icm20948_delay_us_fptr_t)(uint32_t period);
@@ -54,10 +45,43 @@ typedef enum {
     ICM20948_RET_TIMEOUT   = -5
 } icm20948_return_code_t;
 
+typedef enum {
+    ICM20948_MOD_DISABLED = 0x00,
+    ICM20948_MOD_ENABLED
+} icm20948_mod_enable_t;
+
+typedef enum {
+    ICM20948_GYRO_FS_SEL_250DPS = 0x00,
+    ICM20948_GYRO_FS_SEL_500DPS = 0x01,
+    ICM20948_GYRO_FS_SEL_1000DPS = 0x02,
+    ICM20948_GYRO_FS_SEL_2000DPS = 0x03
+} icm20948_gyro_full_scale_select_t;
+
+typedef struct {
+    icm20948_mod_enable_t en;
+    icm20948_gyro_full_scale_select_t fs;
+} icm20948_gyro_settings_t;
+
+typedef enum {
+    ICM20948_ACCEL_FS_SEL_2G = 0x00,
+    ICM20948_ACCEL_FS_SEL_4G = 0x01,
+    ICM20948_ACCEL_FS_SEL_8G = 0x02,
+    ICM20948_ACCEL_FS_SEL_16G = 0x03
+} icm20948_accel_full_scale_select_t;
+
 typedef struct {
-    bool gyro_en;
-    bool accel_en;
-    bool mag_en;
+    icm20948_mod_enable_t en;
+    icm20948_accel_full_scale_select_t fs;
+} icm20948_accel_settings_t;
+
+typedef struct {
+    icm20948_mod_enable_t en;
+} icm20948_mag_settings_t;
+
+typedef struct {
+    icm20948_gyro_settings_t gyro;
+    icm20948_accel_settings_t accel;
+    icm20948_mag_settings_t mag;
 } icm20948_settings_t;
 
 typedef struct {
@@ -78,9 +102,45 @@ typedef struct {
     int16_t z;
 } icm20948_mag_t;
 
+/*!
+ * @brief This API initializes the ICM20948 comms interface, and then does a read from the device
+ * to verify working comms
+ *
+ * @param[in] r: Function pointer to the developers SPI read function
+ * @param[in] w: Function pointer to the developers SPI write function
+ * @param[in] delay: Function pointer to the developers micro-second delay function
+ *
+ * @return Returns the status of initialization
+ */
 icm20948_return_code_t icm20948_init(icm20948_read_fptr_t r, icm20948_write_fptr_t w, icm20948_delay_us_fptr_t delay);
+
+/*!
+ * @brief This API applys the developers settings for configuring the ICM20948 components
+ *
+ * @param[in] newSettings: Pointer to the new ICM20948 settings to be applied
+ *
+ * @return Returns the status of applying settings
+ */
 icm20948_return_code_t icm20948_applySettings(icm20948_settings_t *newSettings);
+
+/*!
+ * @brief This API retrieves the current gyro data from the device
+ *
+ * @param[in] gyro: Pointer to the gyro data struct where the new samples
+ * should be placed
+ *
+ * @return Returns the status of reading gyro data
+ */
 icm20948_return_code_t icm20948_getGyroData(icm20948_gyro_t *gyro);
+
+/*!
+ * @brief This API retrieves the current accel data from the device
+ *
+ * @param[in] accel: Pointer to the accel data struct where the new samples
+ * should be placed
+ *
+ * @return Returns the status of reading accel data
+ */
 icm20948_return_code_t icm20948_getAccelData(icm20948_accel_t *accel);
 
 #endif // _ICM20948_API_H_