Merge pull request #104 from arduino/aliphys/sebCommentsBHY2

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

Author: sebromero

src/Arduino_BHY2Host.h

@@ -21,34 +21,123 @@
 #endif
 
 
-
+/** 
+ *  @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 = 0,
-  NICLA_AS_SHIELD,
-  NICLA_VIA_BLE
+  NICLA_VIA_ESLOV = 0,      /*!< Host connects to Nicla board via ESLOV */
+  NICLA_AS_SHIELD,          /*!< Host connects to Nicla board as a Shield */
+  NICLA_VIA_BLE             /*!< Host connects to Nicla board via BLE */
 };
 
 
+/**
+ * @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_BHY2Host {
 public:
   Arduino_BHY2Host();
   virtual ~Arduino_BHY2Host();
 
   // Necessary API. Update function should be continuously polled if PASSTHORUGH is ENABLED
+    /**
+   * @brief Establishes a connection with the client (Nicla Sense ME) using the given type of communication (ESLOV/BLE/As shield).
+   * 
+   * @note When called without input parameters, I2C communication is over ESLOV by default.
+   * 
+   * @param passthrough Define passthrough state. Disabled by default
+   * @param niclaConnection Defining I2C configuration (NICLA_VIA_ESLOV, NICLA_AS_SHIELD or NICLA_VIA_BLE). @see NiclaWiring 
+   * 
+   * Configuring for operation as a Shield:
+   * @code 
+   * BHY2Host.begin(NICLA_VIA_BLE);
+   * @endcode
+   */
   bool begin(bool passthrough = false, NiclaWiring niclaConnection = NICLA_VIA_ESLOV);
+    /**
+   *  @brief Requests new sensor data from the client (Nicla Sense ME) and saves it locally so it can be retrieved via `Sensor` objects.
+   * 
+   *  @param ms (optional) Time (in milliseconds) to wait before returning data. 
+   */
   void update();
+  /**
+   * @brief Requests new sensor data from the client (Nicla Sense ME) and saves it locally so it can be retrieved via `Sensor` objects. The Nicla Sense ME's sensors are then put to sleep for the given amount of milliseconds.
+   * 
+   * @param ms (optional) time to set Nicla Sense ME to sleep in milliseconds
+   */
   void update(unsigned long ms); // Update and then sleep
 
   // Functions for controlling the BHY when PASSTHROUGH is DISABLED
+  /**
+   * @brief  Configures a sensor to be read using a given sample rate and latency. The configuration is packaged up in a `SensorConfigurationPacket` object. 
+   * 
+   * @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  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>
+   * 
+   */
   void configureSensor(SensorConfigurationPacket& config);
   void configureSensor(uint8_t sensorId, float sampleRate, uint32_t latency);
+  /**
+   * @brief Recieve acknowledgement from Nicla board over ESLOV
+   * 
+   * @return uint8_t One byte of data read from the I2C bus.
+   */
   uint8_t requestAck();
+  /**
+   * @brief Return available sensor data within the FIFO buffer queue
+   *
+   * @return uint8_t Amount of bytes.
+   */
   uint8_t availableSensorData();
+  /**
+   * @brief Return available long sensor data within the FIFO buffer queue
+   *
+   * @return uint8_t Returns the amount of 16 bit chunks of the available sensor data.
+   */
   uint8_t availableSensorLongData();
+  /**
+   * @brief Read sensor data from the top element of the queue
+   *
+   * @param data SensorDataPacket object including SensorID, size, and data payload
+   */
   bool readSensorData(SensorDataPacket &data);
+   /**
+   * @brief Read long sensor data from the top element of the queue
+   *
+   * @param data SensorDataPacket object including SensorID, size , and data payload
+   */
   bool readSensorLongData(SensorLongDataPacket &data);
-
+  /**
+   * @brief Parse XYZ Cartesian data from `SensorDataPacket` and store within `DataXYZ` vector
+   *
+   * @param data SensorDataPacket object including SensorID, size, and data payload
+   * @param vector DataXYZ vector with XYZ values stores as int16_t
+   */
   void parse(SensorDataPacket& data, DataXYZ& vector);
+  /**
+   * @brief Parse orientation data from `SensorDataPacket` and store within `DataOrientation` vector. Optional argument for scale factor
+   *
+   * @param data SensorDataPacket object including SensorID, size, and data payload
+   * @param vector DataOrientation vector with heading, pitch and roll stored as float
+   * @param scaleFactor (optional) scale factor for vector. Defined by format "Euler". See section 15.1.2 in datasheet.
+   */
   void parse(SensorDataPacket& data, DataOrientation& vector);
   void parse(SensorDataPacket& data, DataOrientation& vector, float scaleFactor);
 

src/BLEHandler.h

@@ -10,11 +10,29 @@ class BLEHandler {
 public:
   BLEHandler();
   virtual ~BLEHandler();
-
+  /**
+   * @brief Initialise BLE for DFU and sensor data transfer and connect to Nicla device
+   * 
+   * @return true successful connection to Nicla over BLE
+   * 
+   */
   bool begin();
+  /**
+   * @brief Read data from the Nicla over BLE to the host device.
+   * 
+   */
   void update();
+  /**
+   * @brief Disconnected Nicla from host and close BLE connection 
+   * 
+   */
   void end();
 
+  /**
+   * @brief Write a configuration packet to the Nicla over BLE. First byte sets the opcode
+   * 
+   * @param config Instance of @see SensorConfigurationPacket class, with sensorID, sampleRate and latency
+   */
   void writeConfigPacket(SensorConfigurationPacket& config);
 
 private:

src/EslovHandler.h

@@ -13,13 +13,21 @@
 
 #define I2C_INT_PIN (0)
 
+/**
+ * @brief Enumerator for ESLOV operational state. Defines what state the I2C protocol of the ESLOV device should be in. Used to set DFU (Device Firmware Update) mode in the ANNA-B112 and BHY260 of the Nicla Sense ME.
+ * 
+ */
 enum EslovOpcode {
-  ESLOV_DFU_INTERNAL_OPCODE,
-  ESLOV_DFU_EXTERNAL_OPCODE,
-  ESLOV_SENSOR_CONFIG_OPCODE,
-  ESLOV_SENSOR_STATE_OPCODE
+  ESLOV_DFU_INTERNAL_OPCODE,  /*!< ESLOV DFU ANNA-B112 */
+  ESLOV_DFU_EXTERNAL_OPCODE,  /*!< ESLOV DFU BHY260 */
+  ESLOV_SENSOR_CONFIG_OPCODE, /*!< ESLOV Sensor Configuration */
+  ESLOV_SENSOR_STATE_OPCODE   /*!< ESLOV Sensor State */
 };
 
+/**
+ * @brief Enumeration for the host device operational status. 
+ * 
+ */
 enum HostOpcode {
   HOST_DFU_INTERNAL_OPCODE = ESLOV_DFU_INTERNAL_OPCODE,
   HOST_DFU_EXTERNAL_OPCODE = ESLOV_DFU_EXTERNAL_OPCODE,
@@ -28,31 +36,89 @@ enum HostOpcode {
   HOST_READ_LONG_SENSOR_OPCODE
 };
 
+/**
+ * @brief Enumeration for various states over ESLOV
+ * 
+ */
 enum EslovState {
   ESLOV_AVAILABLE_SENSOR_STATE = 0x00,
   ESLOV_READ_SENSOR_STATE = 0x01,
   ESLOV_DFU_ACK_STATE = 0x02,
   ESLOV_SENSOR_ACK_STATE = 0x03,
   ESLOV_AVAILABLE_LONG_SENSOR_STATE = 0x04,
   ESLOV_READ_LONG_SENSOR_STATE = 0x05
-
 };
 
+/**
+ * @brief Class to manage communication over ESLOV
+ * 
+ */
 class EslovHandler {
 public:
   EslovHandler();
   virtual ~EslovHandler();
 
+  /**
+   * @brief Start I2C communication over ESLOV between host board and Nicla
+   * 
+   * @return true I2C communication initialised successfully. 
+   */
   bool begin(bool passthrough);
+  /**
+   * @brief Reads incoming data to the host board based on the opcode @see EslovState.
+   * 
+   */
   void update();
-
+  /**
+   * @brief Write a DFU (Device Firmware Update) packet to the Nicla Board over ESLOV. On the last packet, the built-in LED is pulled down.
+   * 
+   * @param data pointer to data to be uploaded to Nicla board as a byte array
+   * @param length amount of data to be written to the Nicla in bytes (int)
+   */
   void writeDfuPacket(uint8_t *data, uint8_t length);
+  /**
+   * @brief Waits for the ESLOV interrupt pin to be pulled high, then sends a packet with the @see ESLOV_SENSOR_STATE_OPCODE to over I2C
+   * 
+   * @param state State value sent to Nicla Sense ME based on @ref EslovState enumerator.
+   */
   void writeStateChange(EslovState state);
+  /**
+   * @brief Write a configuration packet to the Nicla over ESLOV. First byte sets the opcode
+   * 
+   * @param config Instance of @see SensorConfigurationPacket class, with sensorID, sampleRate and latency
+   */
   void writeConfigPacket(SensorConfigurationPacket& config);
+  /**
+   * @brief Requests an acknowledgment packet from the Nicla over ESLOV.
+   * 
+   * @return uint8_t acknowledge packet recieved from the Nicla over ESLOV
+   */
   uint8_t requestPacketAck();
+  /**
+   * @brief Change `EslovState` of Nicla to `ESLOV_AVAILABLE_SENSOR_STATE` and wait for the interrupt pin to go high. Then read the avaliable sensor data over I2C.
+   * 
+   * @return uint8_t Number of available sensor data packets.
+   */
   uint8_t requestAvailableData();
+  /**
+   * @brief Change `EslovState` of Nicla to `ESLOV_AVAILABLE_SENSOR_STATE` and wait for the interrupt pin to go high. Then read the avaliable long sensor data over I2C.
+   * 
+   * @return uint8_t Number of available long sensor data packets.
+   */
   uint8_t requestAvailableLongData();
+  /**
+   * @brief Change `EslovState` of Nicla to `ESLOV_READ_SENSOR_STATE` and wait for the interrupt pin to go high. Then read the avaliable sensor data over I2C.
+   * 
+   * @param sData data packet containing sensorID, payload size and data payload
+   * @return true Successful request of sensor data
+   */
   bool requestSensorData(SensorDataPacket &sData);
+  /**
+   * @brief Change `EslovState` of Nicla to `ESLOV_READ_SENSOR_STATE` and wait for the interrupt pin to go high. Then read the avaliable long sensor data over I2C.
+   * 
+   * @param sData data packet containing sensorID, payload size and data payload
+   * @return true Successful request of sensor data
+   */
   bool requestSensorLongData(SensorLongDataPacket &sData);
 
 protected: