example: add example for IMU sensor range settings (#65)

* example: add example for IMU sensor range settings

* Reduce Serial transfer -> Solve garble serial out

* Add comments to `IMURangeSettings.ino`

* Add missing `;`

* Add option to print values in g

---------

Co-authored-by: zg guo <[email protected]>
Co-authored-by: Ali Jahangiri <[email protected]>

Author: 3 people

examples/IMURangeSettings/IMURangeSettings.ino

@@ -0,0 +1,73 @@
+/* 
+ * IMURangeSettings
+ * 
+ * This sketch demonstrates how to configure the acceleration (SENSOR_ID_ACC) and gyroscope (SENSOR_ID_GYRO) range values.
+ * In the setup function, the default ranges are printed to the serial for the acceleration and gravity (+/-8g).
+ * Then, the range is modified to +/-4g, and is confirmed by printing the value of .range method to the Serial monitor. Finally,
+ * the setup function prints the default range value for the gyroscope (+/-2000 dps) and then modifies this to +/-1000 dps.
+ * 
+ * Every second, the loop function prints out acceleration and gyroscope values to the Serial port.
+ * 
+ * 
+*/
+
+#include "Arduino_BHY2.h"
+
+// declare 3D sensor instances
+// default ADC range is -32768 to 32767 (16 bit)
+SensorXYZ accel(SENSOR_ID_ACC);
+SensorXYZ gyro(SENSOR_ID_GYRO);
+SensorXYZ gravity(SENSOR_ID_GRA);
+
+void setup() {
+  Serial.begin(9600);
+  while(!Serial);
+
+  BHY2.begin();
+
+  accel.begin();
+  gyro.begin();
+
+  delay(1000);
+
+  SensorConfig cfg = accel.getConfiguration();
+
+  Serial.println("Default Range values:");
+  Serial.println(String("range of accel: +/-") + cfg.range + String("g"));
+  cfg = gravity.getConfiguration();
+  Serial.println(String("range of gravity: +/-") + cfg.range + String("g"));
+
+  accel.setRange(4);    //this sets the range of accel to +/-4g, 
+  Serial.println("Modified Range values:");
+  cfg = accel.getConfiguration();
+  Serial.println(String("range of accel: +/-") + cfg.range + String("g"));
+  cfg = gravity.getConfiguration();
+  Serial.println(String("range of gravity: +/-") + cfg.range + String("g"));
+
+  cfg = gyro.getConfiguration();
+  Serial.println(String("range of gyro: +/-") + cfg.range + String("dps"));  
+  gyro.setRange(1000);  //this sets the range of gyro to +/-1000dps, 
+  cfg = gyro.getConfiguration();
+  Serial.println(String("range of gyro: +/-") + cfg.range + String("dps"));
+}
+
+void loop() {
+  static auto printTime = millis();
+
+  // Update function should be continuously polled
+  BHY2.update();
+
+  // print gyroscope/acceleration data once every second
+  if (millis() - printTime >= 1000) {
+    printTime = millis();
+    Serial.print(String("acceleration (raw): ") + accel.toString());
+
+    float accelX = ((float)accel.x() / 32768.0) *4;
+    float accelY = ((float)accel.y() / 32768.0) *4;
+    float accelZ = ((float)accel.z() / 32768.0) *4;
+    String accelInG = String("X: ") + String(accelX) + String(" Y: ") + String(accelY) + String(" Z: ") + String(accelZ);
+
+    Serial.println(String("acceleration (g): ") + accelInG);
+    Serial.println(String("gyroscope: ") + gyro.toString());
+  }
+}

examples/Standalone/Standalone.ino

@@ -26,6 +26,18 @@ void setup()
   temp.begin();
   gas.begin();
   rotation.begin();
+
+  SensorConfig cfg = accel.getConfiguration();
+  Serial.println(String("range of accel: +/-") + cfg.range + String("g"));
+  accel.setRange(2);    //this sets the range of accel to +/-4g, 
+  cfg = accel.getConfiguration();
+  Serial.println(String("range of accel: +/-") + cfg.range + String("g"));
+
+  cfg = gyro.getConfiguration();
+  Serial.println(String("range of gyro: +/-") + cfg.range + String("dps"));  
+  gyro.setRange(1000);    
+  cfg = gyro.getConfiguration();
+  Serial.println(String("range of gyro: +/-") + cfg.range + String("dps"));
 }
 
 void loop()

src/sensors/SensorClass.h

@@ -21,6 +21,25 @@ class SensorClass {
    */
   bool begin(float rate = 1000, uint32_t latency = 1);
   void configure(float rate, uint32_t latency);
+  /*
+   * parameter range:
+   * for accelerometer, the range parameter is in the units of g (1g = ~9.80665 m/s^2)
+   * valid values:
+   * 2 (+/-2g), 4 (+/-4g), 8 (+/-8g), 16 (+/-16g),
+   *
+   * for gyroscope, the range parameter is in the units of dps (degrees per second)
+   * valid values:
+   *    125 (+/-125 dps)
+   *    250 (+/-250 dps)
+   *    500 (+/-500 dps)
+   *    1000 (+/-1000 dps)
+   *    2000 (+/-2000 dps)
+   *
+   * for other sensors, the range is defined based on the physical driver implementation
+   * please note that: changing the range of one virtual sensor might affect the other virtual sensors which share the same underlying physical sensor, e.g.:
+   * changing the accelerometer range will at the same time impact the sensing range for the gravity virtual sensor,
+   * for more details please refer to the datasheet of BHI260AP, section "Change Sensor Dynamic Range"
+   */
   int setRange(uint16_t range);
   const SensorConfig getConfiguration();
   void end();