README.MD overhaul

BNO08x.cpp

@@ -183,7 +183,7 @@ bool BNO08x::wait_for_data()
     // check to see receive operation has finished
     if (xEventGroupWaitBits(evt_grp_spi, EVT_GRP_SPI_RX_DONE_BIT, pdTRUE, pdTRUE, HOST_INT_TIMEOUT_MS / portTICK_PERIOD_MS))
     {
-        // wait until processing is done
+        // wait until processing is done, this should never go to timeout; however, it will be set slightly after EVT_GRP_SPI_RX_DONE_BIT
         if (xEventGroupWaitBits(evt_grp_spi, EVT_GRP_SPI_RX_VALID_PACKET | EVT_GRP_SPI_RX_INVALID_PACKET, pdFALSE, pdFALSE,
                     HOST_INT_TIMEOUT_MS / portTICK_PERIOD_MS))
         {

README.md

@@ -10,17 +10,11 @@
     <ul>
     <li><a href="#wiring">Wiring</a></li>
     <li><a href="#adding-to-project">Adding to Project</a></li>
+    <li><a href="#Examples">Examples</a></li>
     </ul>
 </li>
-<li><a href="#example">Example</a></li>
 <li><a href="#documentation">Documentation</a></li>
-<li>
+<li><a href="#program-flowcharts">Program Flowcharts</a></li>
-    <a href="#program-flowcharts">Program Flowcharts</a>
-    <ul>
-    <li><a href="#sending-case">Sending Case</a></li>
-    <li><a href="#receiving-case">Receiving Case</a></li>
-    </ul>
-</li>
 <li><a href="#acknowledgements">Acknowledgements</a></li>  <!-- Added this line -->
 <li><a href="#license">License</a></li>
 <li><a href="#contact">Contact</a></li>
@@ -28,10 +22,11 @@
 
 ## About
 
-esp32_BNO08x is a C++ esp-idf v5.x component, intended to serve as a driver for both the BNO080 and BNO085 IMUs.  
+esp32_BNO08x is a C++ component for esp-idf v5.x, serving as a driver for both BNO080 and BNO085 IMUs.  
-This library is heavy influenced by the  SparkFun BNO080 Arduino Library, it is more or less a port. It supports access to all the same data that the BNO08x provides.    
+
-Currently, only SPI is supported, there is no plans to support I2C (esp32 has I2C driver silicone bug, leading to unpredictable behavior).   
+Originally based on the SparkFun BNO080 Arduino Library, it has since diverged significantly in implementation while retaining all original features and more, including callback functions enabled by its multi-tasked approach.
-I may implement UART at some point in the future.
+
+Currently, only SPI is supported. There are no plans to support I2C due to unpredictable behavior caused by an esp32 I2C driver silicon bug. UART support may be implemented in the future.
 
 ## Getting Started
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -64,7 +59,20 @@ The default wiring is depicted below, it can be changed at driver initialization
    ```
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-### Example
+### Examples
+There are two ways data returned from the BNO08x can be accessed with this library:
+
+1. Polling Method with `data_available()` Function:
+  - Use the `data_available()` function to poll for new data, similar to the SparkFun library.
+  - Behavior: It is a blocking function that returns `true` when new data is received or `false` if a timeout occurs.
+  - See the **Polling Example** below.
+
+2. Callback Registration with `register_cb()` Function:
+  - Register callback functions that automatically execute upon receiving new data.
+  - Behavior: The registered callback will be invoked whenever new data is available.
+  - See the **Call-Back Function Example** below. 
+  
+#### Polling Example
 ```cpp  
 #include <stdio.h>
 #include "BNO08x.hpp"
@@ -72,6 +80,7 @@ The default wiring is depicted below, it can be changed at driver initialization
 extern "C" void app_main(void)
 {
     BNO08x imu; //create IMU object with default wiring scheme
+    float x, y, z = 0;
 
     //if a custom wiring scheme is desired instead of default:
 
@@ -95,13 +104,70 @@ extern "C" void app_main(void)
         //print absolute heading in degrees and angular velocity in Rad/s
         if(imu.data_available())
         {
-            ESP_LOGW("Main", "Velocity: x: %.3f y: %.3f z: %.3f", imu.get_gyro_calibrated_velocity_X(), imu.get_gyro_calibrated_velocity_Y(), imu.get_gyro_calibrated_velocity_Z());
+            x = imu.get_gyro_calibrated_velocity_X();
-            ESP_LOGI("Main", "Euler Angle: x (roll): %.3f y (pitch): %.3f z (yaw): %.3f", imu.get_roll_deg(), imu.get_pitch_deg(), imu.get_yaw_deg());
+            y = imu.get_gyro_calibrated_velocity_Y();
+            z = imu.get_gyro_calibrated_velocity_Z();
+            ESP_LOGW("Main", "Velocity: x: %.3f y: %.3f z: %.3f", x, y, z);
+
+            x = imu.get_roll_deg();
+            y = imu.get_pitch_deg();
+            z = imu.get_yaw_deg();
+            ESP_LOGI("Main", "Euler Angle: x (roll): %.3f y (pitch): %.3f z (yaw): %.3f", x, y, z);
         }
     }
 
 }
 ```
+
+#### Call-Back Function Example
+```cpp
+#include <stdio.h>
+#include "BNO08x.hpp"
+
+extern "C" void app_main(void)
+{
+    BNO08x imu; // create IMU object with default wiring scheme
+
+    // if a custom wiring scheme is desired instead of default:
+
+    /*
+    bno08x_config_t imu_config;     //create config struct
+    imu_config.io_mosi = GPIO_NUM_X; //assign pin
+    imu_config.io_miso = GPIO_NUM_X; //assign pin
+    //etc...
+    BNO08x imu(imu_config); //pass config to BNO08x constructor
+    */
+
+    imu.initialize(); // initialize IMU
+
+    // enable gyro & game rotation vector
+    imu.enable_game_rotation_vector(100000UL); // 100,000us == 100ms report interval
+    imu.enable_gyro(150000UL);                 // 150,000us == 150ms report interval
+
+    // register a callback function (in this case a lambda function, but it doesn't have to be)
+    imu.register_cb(
+        [&imu]()
+        {
+            // callback function contents, executed whenever new data is parsed
+            // print absolute heading in degrees and angular velocity in Rad/s
+            float x, y, z = 0;
+            x = imu.get_gyro_calibrated_velocity_X();
+            y = imu.get_gyro_calibrated_velocity_Y();
+            z = imu.get_gyro_calibrated_velocity_Z();
+            ESP_LOGW("Main", "Velocity: x: %.3f y: %.3f z: %.3f", x, y, z);
+
+            x = imu.get_roll_deg();
+            y = imu.get_pitch_deg();
+            z = imu.get_yaw_deg();
+            ESP_LOGI("Main", "Euler Angle: x (roll): %.3f y (pitch): %.3f z (yaw): %.3f", x, y, z);
+        });
+
+    while (1)
+    {
+        vTaskDelay(300 / portTICK_PERIOD_MS); // delay here is irrelevant, we just don't want to trip cpu watchdog
+    }
+}
+```
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## Documentation
@@ -110,18 +176,11 @@ API documentation generated with doxygen can be found in the documentation direc
 
 ## Program Flowcharts
 The following charts illustrate the program flow this library implements for sending and receiving data from BNO08x.  
-These are here to aid development for anyone looking to modify, fork, or contribute. 
+These are here to aid development for anyone looking to modify, fork, or contribute.  
+
+![image](esp32_BNO08x_flowchart.png)
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-### Receiving Case
-This assumes the user as initialized the imu and has sent a command to enable a report (for ex. enable_game_rotation_vector).
-![image](esp32_BNO08x_receieve_flowchart.png)
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-
-### Sending Case
-![image](esp32_BNO08x_send_flowchart.png)
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## Acknowledgements
 Special thanks to the original creators of the sparkfun BNO080 library. Developing this without a reference would have been much more time consuming.