Merge pull request #104 from arduino/aliphys/sebCommentsBHY2

[AE-28][AE-51] Merged improvements to Arduino_BHY2 and Arduino_BHY2Host

Author: sebromero

Arduino_BHY2/docs/readme.md

@@ -1,10 +1,9 @@
 # Bosch BHY2 Sensor Library for Arduino
 
-The Bosch BHY2 Sensor Library provides an interface with the [Bosch BHY2-Sensor-API](https://github.com/BoschSensortec/BHY2-Sensor-API) for communicating with the BHI260AP and a custom library for the BME688 sensors of the Nicla Sense ME.
-
+This library allows the Nicla Sense ME to interface with the onboard 6-axis IMU (BHI260AP) and environmental sensor (BME688).
 ## Features
 
-- Easy access to data from Nicla Sense ME sensors
+- Easy access to data from Nicla Sense ME sensors using sensor ID
 - Wrapper for [Bosch BHY2-Sensor-API](https://github.com/BoschSensortec/BHY2-Sensor-API)
 - DFU (Device Firmware Update) of the ANNA-B112 and the BHI260AP
 - All functionality avaliable over both ESLOV and BLE
@@ -31,18 +30,16 @@ A UML diagram of the main library classes are provided in the diagram below, pro
 
 For additional information on the Arduino_BHY2 library (including a list of Sensor IDs) and how you can use it with the Nicla Sense ME, see the [Arduino Nicla Sense ME Cheat Sheet](https://docs.arduino.cc/tutorials/nicla-sense-me/cheat-sheet) page.
 
-
-
 ## Examples
 
 - [App](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/App/App.ino) : Control Nicla Sense ME from an external device acting as a host via I2C or ESLOV
 - [AppLowDelay](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/AppLowDelay/AppLowDelay.ino) : Control Nicla Sense ME from an external device acting as a host via I2C or ESLOV with a lower delay
-- [BHYFirmwareUpdate](https://github.com/arduino-libraries/Arduino_BHY2/tree/main/examples/BHYFirmwareUpdate) : Update ANNA-B112 and BHI260 firmware
-- [Fail_Safe_flasher](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/Fail_Safe_flasher/Fail_Safe_flasher.ino) : Fail Safe flashing of a RGB blink sketch
-- [ReadSensorConfiguration](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/ReadSensorConfiguration/ReadSensorConfiguration.ino) : Read motion, temperature and gas data and send over Serial
+- [BHYFirmwareUpdate](https://github.com/arduino-libraries/Arduino_BHY2/tree/main/examples/BHYFirmwareUpdate) : Update BHI260 firmware to latest version. Can also be used to upload custom firmware binary.
+- [Fail_Safe_flasher](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/Fail_Safe_flasher/Fail_Safe_flasher.ino) : Fail Safe flashing of a RGB blink sketch. Writes binary file to the SPI flash, then peforms CRC to ensure successful writing of binary file to flash memory. 
+- [ReadSensorConfiguration](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/ReadSensorConfiguration/ReadSensorConfiguration.ino) : Send sample rate, latency and range for accelerator, gyroscope, rotation, temperature and gas sensor over Serial
 - [ShowSensorList](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/ShowSensorList/ShowSensorList.ino) : List sensors of the Nicla Sense ME board
 - [Standalone](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/Standalone/Standalone.ino) : Read motion, temperature and gas data and send over Serial
-- [StandaloneFlashStorage](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/StandaloneFlashStorage/StandaloneFlashStorage.ino) : Read motion, temperature and gas data and send over and save on Flash storage  
+- [StandaloneFlashStorage](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/examples/StandaloneFlashStorage/StandaloneFlashStorage.ino) : Save accelerator, gryoscope, temperature, gas and rotation sensor values to the onboard SPI flash in a .CSV file.
 
 ## License
 

Arduino_BHY2/src/Arduino_BHY2.h

@@ -16,175 +16,203 @@
 #include "sensors/SensorID.h"
 
 /** 
- *  @brief Enumeration for defining wiring configuration over ESLOV or Shield.
+ *  @brief Enumeration for defining wiring configuration between host board and Nicla client. We can select between an I2C connection over ESLOV (NICLA_VIA_ESLOV) or as a Shield for the MKR boards (NICAL_AS_SHIELD). 
  * 
  *  For NICLA_AS_SHIELD configuration, see https://docs.arduino.cc/tutorials/nicla-sense-me/use-as-mkr-shield
  *  
  */
 enum NiclaWiring {
-  NICLA_VIA_ESLOV = 0x10,
-  NICLA_AS_SHIELD = 0x20
+  NICLA_VIA_ESLOV = 0x10,                 /*!< Host connects to Nicla board via ESLOV */
+  NICLA_AS_SHIELD = 0x20                  /*!< Host connects to Nicla board as a Shield */
 };
 
 /** 
- *  @brief Enumeration for defining I2C or BLE communication configuration.
+ *  @brief Enumeration for defining I2C (wired) or BLE communication configuration between host board and Nicla client. Alternatively, the Nicla Sense ME can also run in a standalone configuration.  
+ * 
+ *  @note Both ESLOV and Shield should be considered as implementations of I2C communication (NICLA_I2C)
  * 
- *  @see Arduino_BHY2::begin()
  */
 enum NiclaConfig {
-  NICLA_I2C = 0x1,                          /*!< I2C */
-  NICLA_BLE = 0x2,                          /*!< Bluetooth via ANNA-B112 module */
-  NICLA_BLE_AND_I2C = NICLA_I2C | NICLA_BLE, /*!< Enable I2C and BLE simultaneously */
+  NICLA_I2C = 0x1,                          /*!< I2C Configuration, relavent for both ESLOV and Shield configurations  */
+  NICLA_BLE = 0x2,                          /*!< Bluetooth via the onboard ANNA-B112 module */
+  NICLA_BLE_AND_I2C = NICLA_I2C | NICLA_BLE,/*!< Enable I2C (ESLOV/Shield) and BLE simultaneously */
   NICLA_STANDALONE = 0x4                    /*!< Operate in standalone, without external data transfer */
 };
 
 /**
- * @brief Class for storing Nicla state
+ * @brief Class for configuring the host-client communication, based on the @ref NiclaConfig enumeration.
+ * 
+ * Example:
+ * @code
+ * NiclaSettings niclaSettings(NICLA_I2C);
+ * @endcode
  * 
+ * @ref Arduino_BHY2::NiclaConfig Arduino_BHY2::NiclaWiring
+ *
  */
-class NiclaSettings {
+class NiclaSettings
+{
 public:
-  NiclaSettings(uint8_t conf1 = 0, uint8_t conf2 = 0, uint8_t conf3 = 0, uint8_t conf4 = 0) {
+  NiclaSettings(uint8_t conf1 = 0, uint8_t conf2 = 0, uint8_t conf3 = 0, uint8_t conf4 = 0)
+  {
     conf = conf1 | conf2 | conf3 | conf4;
   }
 
-  uint8_t getConfiguration() const {
+  uint8_t getConfiguration() const
+  {
     return conf;
   }
+
 private:
   uint8_t conf = 0;
 };
 
 /**
- * @brief Main class for initialising communication with sensors
+ * @brief Class to interface with the Bosch BHI260 sensor hub on the Nicla Sense ME.
+ * Provides functionality for reading/configuring sensors based on sensor ID and accessing debug features. 
 */
 class Arduino_BHY2 {
+
 public:
   Arduino_BHY2();
   virtual ~Arduino_BHY2();
 
-  // Necessary API. Update function should be continuously polled 
+  // Necessary API. Update function should be continuously polled
   /**
-   * @param config Configuration for set @ref NiclaConfig state
-   * @param niclaConnection Configuration for set @ref NiclaWiring state
+   * @brief Initialise the BHY2 functionality for the Nicla Sense ME, for a given @ref NiclaSettings configuration.
    * 
-  */
-  bool begin(NiclaConfig config = NICLA_BLE_AND_I2C, NiclaWiring niclaConnection = NICLA_VIA_ESLOV);
-  bool begin(NiclaSettings& settings);
-  /**
-   *  @brief  Pings sensor
+   * @note When called without input parameters, I2C and BLE are enabled by default. I2C communication is over ESLOV.
+   * 
+   * @param NiclaConfig Define communication configuration (NICLA_I2C, NICLA_BLE, NICLA_BLE_AND_I2C or NICLA_STANDALONE). @see NiclaConfig
+   * @param NiclaWiring Defining I2C configuration (NICLA_VIA_ESLOV or NICLA_AS_SHIELD). @see NiclaWiring 
    * 
-   *  @note Sensor must be continuously polled to prevent sleep
+   * Configuring for operation as a Shield:
+   * @code 
+   * BHY2.begin(NICLA_I2C, NICLA_AS_SHIELD);
+   * @endcode
    */
-  void update(); // remove this to enforce a sleep
+  bool begin(NiclaConfig config = NICLA_BLE_AND_I2C, NiclaWiring niclaConnection = NICLA_VIA_ESLOV);
+  bool begin(NiclaSettings &settings);
   /**
-   *  @brief  Pings sensor and then sleep
+   *  @brief Update sensor data by reading the FIFO buffer on the BHI260 and then pass it to a suitable parser. 
    * 
-   *  @note Delay does not stall microcontroller to sleep. See https://docs.arduino.cc/built-in-examples/digital/BlinkWithoutDelay
+   *  @param ms (optional) Time (in milliseconds) to wait before returning data. 
    */
+  void update(); // remove this to enforce a sleep
   void update(unsigned long ms); // Update and then sleep
   /**
-  *   @brief delay method to be used instead of Arduino delay().
+  *   @brief Delay method to be used instead of Arduino delay().
+  * 
+  *   @note Unlike the standard Arduino delay, this modified delay method uses a function to check if the elapsed time has passed.
+  * This does not stall the microprocessor. 
+  * 
+  *   @param ms Time (in milliseconds) to enforce delay.
+  * 
+  *   @code 
+  *   BHY2.delay(100);
+  *   @endcode
   */
   void delay(unsigned long ms); // to be used instead of arduino delay()
 
-  // API for using the bosch sensortec from sketch
+  // API for using the Bosch sensortec from sketch
   /**
-   * @brief Poll Bosch method 
+   * @brief Configure a virtual sensor on the BHI260 to have a set sample rate (Hz) and latency (milliseconds)
+   * This can be achieved 
    * 
-   * @param config Sensor configuration
-   */
-  void configureSensor(SensorConfigurationPacket& config);
-  /**
-   * @brief Setup virtual sensors on the BHI260
+   * @param config Instance of @see SensorConfigurationPacket class, with sensorID, sampleRate and latency
+   * 
+   * @code
+   * #set virtual sensor SENSOR_ID_DEVICE_ORI_WU to have sample rate of 1 Hz and latency of 500 milliseconds
+   * SensorConfigurationPacket config(70, 1, 500);
+   * BHY2.configureSensor(config)
+   * @endcode
+   * 
+   * @note Alternatively, we can directly configure the virtual sensor without creating a SensorConfigurationPacket class
    * 
-   * @param sensorId  Sensor ID for sensor
-   * @param sampleRate Polling rate for sensor
-   * @param latency   Latency in milliseconds
+   * @param sensorId  SensorID for virtual sensor
+   * @param sampleRate Polling rate for sensor in Hz
+   * @param latency   Latency in milliseconds 
+   * 
+   * @note For list of SensorID, see src/SensorID.h. Or see Table 79 in the <a href="https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bhi260ab-ds000.pdf">BHI260 datasheet</a>
    * 
-   * @note For list of SensorID, see src/SensorID.h
    */
+  void configureSensor(SensorConfigurationPacket& config);
   void configureSensor(uint8_t sensorId, float sampleRate, uint32_t latency);
   /**
-   * @brief Handlo FIFO of data queue
+   * @brief Extract data from the FIFO buffer for a specific SensorID and save into an instance of the SensorDataPacket struct. Eliminate oldest data when sensor queue is full.
    * 
-   * @param sensorData Data packet from sensor
+   * @param sensorData Struct containing SensorID (uint8_t), data payload size (uint8_t) and data corresponding to SensorID (uint8_t).
    */
   void addSensorData(SensorDataPacket &sensorData);
   /**
-   * @brief Handlo FIFO of data queue for long sensor data
-   * 
-   * @param sensorData Data packet from sensor
+   * @brief Extract data from the FIFO buffer for a specific SensorID and save into an instance of the SensorLongDataPacket struct. Eliminate oldest data when sensor queue is full.
+   *
+   * @param sensorData Struct containing SensorID (uint8_t), long data payload size (uint8_t) and data corresponding to SensorID (uint8_t).
    */
   void addLongSensorData(SensorLongDataPacket &sensorData);
   /**
-   * @brief Return available sensor data
-   * 
-   * @return uint8_t 
+   * @brief Return available sensor data within the FIFO buffer queue
+   *
+   * @return uint8_t The amount of data in bytes
    */
   uint8_t availableSensorData();
   /**
-   * @brief Return available long sensor data
-   * 
-   * @return uint8_t 
+   * @brief Return available long sensor data within the FIFO buffer queue
+   *
+   * @return uint8_t The amount of data in bytes
    */
   uint8_t availableLongSensorData();
   /**
-   * @brief Read sensor data
-   * 
-   * @param data 
-   * @return true 
-   * @return false 
+   * @brief Read sensor data from the top element of the queue
+   *
+   * @param data Structure including sensorID, sampleRate and latency
    */
   bool readSensorData(SensorDataPacket &data);
   /**
-   * @brief Read long sensor data
-   * 
-   * @param data 
-   * @return true 
-   * @return false 
+   * @brief Read long sensor data from the top element of the queue
+   *
+   * @param data Structure including sensorID, sampleRate and latency
    */
   bool readLongSensorData(SensorLongDataPacket &data);
   /**
-   * @brief Check existence of sensor
-   * 
-   * @param sensorId Selected virtual sensor
-   * @return true - Sensor is present
-   * @return false - Sensor is not present
+   * @brief Check existence of a given sensorID
+   *
+   * @param sensorID Selected virtual sensor
+   * @return True Sensor is present
    */
   bool hasSensor(uint8_t sensorId);
   /**
-   * @brief Parse XYZ Cartesian data
-   * 
-   * @param data Data packet including SensorID
+   * @brief Parse XYZ Cartesian data from a given data packet
+   *
+   * @param data data packet including SensorID
    * @param vector vector with XYZ
    */
-  void parse(SensorDataPacket& data, DataXYZ& vector);
+  void parse(SensorDataPacket &data, DataXYZ &vector);
   /**
-   * @brief Parse orientation
-   * 
+   * @brief Parse orientation from a given data packet
+   *
    * @param data Data packet including SensorID
    * @param vector Vector with heading, pitch and roll
    */
-  void parse(SensorDataPacket& data, DataOrientation& vector);
+  void parse(SensorDataPacket &data, DataOrientation &vector);
   /**
    * @brief Parse orientation with scale factor
-   * 
+   *
    * @param data Data packet including SensorID
    * @param vector Vector with heading, pitch and roll
    * @param scaleFactor scale factor for vector
    */
-  void parse(SensorDataPacket& data, DataOrientation& vector, float scaleFactor);
+  void parse(SensorDataPacket &data, DataOrientation &vector, float scaleFactor);
   /**
    * @brief Define LDO regulator timeout time
-   * 
+   *
    * @param time in milliseconds. 120000 ms by default.
    */
   void setLDOTimeout(int time);
   /**
-   * @brief Stream
-   * 
-   * @param stream 
+   * @brief Prints debug stream of multiple library components to the specified stream object. 
+   *
+   * @param Stream object that implements the Print() function. 
    */
   void debug(Stream &stream);
 
@@ -203,7 +231,7 @@ class Arduino_BHY2 {
 
 /**
  * @brief The Arduino_BHY2 class can be externally linked to as BHY2 in your sketch
- * 
+ *
  */
 extern Arduino_BHY2 BHY2;
 

Arduino_BHY2/src/BLEHandler.h

@@ -22,15 +22,15 @@ class BLEHandler {
   /**
    * @brief Set advertised local name and initialise BLE advertising for DFU and sensor data transfer
    * 
-   * @return true   Successful initialisation of BLE device
-   * @return false  Failure in initialisation of BLE device
+   * @return true Successful initialisation of BLE device
    */
   bool begin();
   /**
-   * @brief Poll data over Bluetooth and read data to FIFO buffer.
-   * 
+   *  @brief Update sensor data by reading the FIFO buffer on the BHI260 and then pass it to a suitable parser. 
+   *  
    */
   void update();
+  
   /**
    * @brief Poll BLE data
    * 
@@ -61,29 +61,29 @@ class BLEHandler {
    * @brief Method for reading and processing DFU packet. Prints size of DFU packet to debug output
    * 
    * @param dfuType         Selects device to update firmware. DFU_INTERNAL for the ANNA-B112 and DFU_EXTERNAL for the BHY2 sensor.
-   * @param characteristic  Selected BLE characteristic
+   * @param characteristic  Selected BLE characteristic. See https://reference.arduino.cc/reference/en/libraries/arduinoble/blecharacteristic/
    */
   void processDFUPacket(DFUType dfuType, BLECharacteristic characteristic);
 
   /**
-   * @brief Method for recieving BLE packet to ANNA-B112 module
+   * @brief Method for receiving and forwarding BLE packet to ANNA-B112 module
    * 
    * @param central         Instance of BLEDevice
-   * @param characteristic  Selected BLE characteristic
+   * @param characteristic  Selected BLE characteristic. See https://reference.arduino.cc/reference/en/libraries/arduinoble/blecharacteristic/
    */
   static void receivedInternalDFU(BLEDevice central, BLECharacteristic characteristic);
   /**
-   * @brief Method for recieving BLE packet to BHI260AP sensor
+   * @brief Method for receiving and forwarding BLE packet to BHI260AP sensor
    * 
    * @param central         Instance of BLEDevice
-   * @param characteristic  Selected BLE characteristic
+   * @param characteristic  Selected BLE characteristic. See https://reference.arduino.cc/reference/en/libraries/arduinoble/blecharacteristic/
    */
   static void receivedExternalDFU(BLEDevice central, BLECharacteristic characteristic);
   /**
    * @brief Read sensor configuration data and output to debug
    * 
    * @param central         Instance of BLEDevice
-   * @param characteristic  Selected BLE characteristic
+   * @param characteristic  Selected BLE characteristic. See https://reference.arduino.cc/reference/en/libraries/arduinoble/blecharacteristic/
    */
   static void receivedSensorConfig(BLEDevice central, BLECharacteristic characteristic);
 };

Arduino_BHY2/src/BoschParser.h

@@ -41,7 +41,7 @@ class BoschParser {
    * @brief Parse Meta Events from the Bosch BHI260 Sensor
    * 
    * @param callback_info Pointer containing information to be parsed
-   * @param callback_ref 
+   * @param callback_ref Reserved for future use
    */
   static void parseMetaEvent(const struct bhy2_fifo_parse_data_info *callback_info, void *callback_ref);
   /**
@@ -52,7 +52,7 @@ class BoschParser {
    */
   static void parseGeneric(const struct bhy2_fifo_parse_data_info *callback_info, void *callback_ref);
   /**
-   * @brief Print out debug message
+   * @brief Parse debug message
    * 
    * @param callback_info Pointer containing information to be parsed
    * @param callback_ref  Reserved for future use