[AE-51] Add documentation for BHY2Host

Arduino_BHY2Host/src/Arduino_BHY2Host.h

@@ -21,35 +21,121 @@
 #endif
 
 
-
+/** 
+ *  @brief Enumeration for defining wiring configuration over ESLOV, Shield or BLE.
+ * 
+ *  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
 };
 
-
+/**
+ * @brief Main class for initialising communication with sensors
+*/
 class Arduino_BHY2Host {
 public:
   Arduino_BHY2Host();
   virtual ~Arduino_BHY2Host();
 
   // Necessary API. Update function should be continuously polled if PASSTHORUGH is ENABLED
+  /**
+   * @brief 
+   * 
+   * @param passthrough Enable Serial port at 115200 bps
+   * @param niclaConnection Configuration for set @ref NiclaWiring state
+   * @return true   Connection successful to the Nicla board
+   * @return false  Connection unsuccessful to the Nicla board
+   */
   bool begin(bool passthrough = false, NiclaWiring niclaConnection = NICLA_VIA_ESLOV);
+  /**
+   *  @brief  Pings sensor
+   * 
+   *  @note Sensor must be continuously polled to prevent sleep
+   */
   void update();
+  /**
+   *  @brief  Pings sensor and then sleep
+   * 
+   *  @note Delay does not stall microcontroller to sleep. See https://docs.arduino.cc/built-in-examples/digital/BlinkWithoutDelay
+   */
   void update(unsigned long ms); // Update and then sleep
 
   // Functions for controlling the BHY when PASSTHROUGH is DISABLED
+  /**
+   * @brief Poll Bosch method 
+   * 
+   * @param config Sensor configuration
+   */
   void configureSensor(SensorConfigurationPacket& config);
+    /**
+   * @brief Setup virtual sensors on the BHI260
+   * 
+   * @param sensorId  Sensor ID for sensor
+   * @param sampleRate Polling rate for sensor
+   * @param latency   Latency in milliseconds
+   * 
+   * @note For list of SensorID, see src/SensorID.h
+   */
   void configureSensor(uint8_t sensorId, float sampleRate, uint32_t latency);
+  /**
+   * @brief Recieve acknowledgement from Nicla board over ESLOV
+   * 
+   * @return uint8_t Data read from I2C bus
+   */
   uint8_t requestAck();
+  /**
+   * @brief Return available sensor data
+   * 
+   * @return uint8_t 
+   */
   uint8_t availableSensorData();
+  /**
+   * @brief Return available long sensor data
+   * 
+   * @return uint8_t 
+   */
   uint8_t availableSensorLongData();
+  /**
+   * @brief Read sensor data
+   * 
+   * @param data 
+   * @return true 
+   * @return false 
+   */
   bool readSensorData(SensorDataPacket &data);
+  /**
+   * @brief Read long sensor data
+   * 
+   * @param data 
+   * @return true 
+   * @return false 
+   */
   bool readSensorLongData(SensorLongDataPacket &data);
-
+  /**
+   * @brief Parse XYZ Cartesian data
+   * 
+   * @param data Data packet including SensorID
+   * @param vector vector with XYZ
+   */
   void parse(SensorDataPacket& data, DataXYZ& vector);
+   /**
+   * @brief Parse orientation
+   * 
+   * @param data Data packet including SensorID
+   * @param vector Vector with heading, pitch and roll
+   */
   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);
 
   NiclaWiring getNiclaConnection();

Arduino_BHY2Host/src/BLEHandler.h

@@ -6,18 +6,45 @@
 #include "DFUTypes.h"
 #include "ArduinoBLE.h"
 
+/**
+ * @brief Class for handling BLE communication for both sensor data transfer and DFU
+ * 
+ */
+
 class BLEHandler {
 public:
   BLEHandler();
   virtual ~BLEHandler();
 
+  /**
+   * @brief Start BLE connection to the Nicla board
+   * 
+   * @return true Connection successful to the Nicla board
+   * @return false Connection unsuccessful to the Nicla board
+   */
   bool begin();
+  /**
+   * @brief Poll data over Bluetooth 
+   * 
+   */
   void update();
+  /**
+   * @brief Disconnect BLE connection between host and Nicla board
+   * 
+   */
   void end();
-
+  /**
+   * @brief Specify which sensor to poll data from on the Nicla Sense ME
+   * 
+   * @param config Configuration for the Sensor including sensor ID, sample rate and latency
+   */
   void writeConfigPacket(SensorConfigurationPacket& config);
 
 private:
+  /**
+   * @brief The Arduino_BHY2Host class can accces both private and public methods of BLEHandler
+   * 
+   */
   friend class Arduino_BHY2Host;
 
   static void receivedSensorData(BLEDevice central, BLECharacteristic characteristic);

Arduino_BHY2Host/src/EslovHandler.h

@@ -13,13 +13,22 @@
 
 #define I2C_INT_PIN (0)
 
+/**
+ * @brief Enumerator for ESLOV operational state
+ * 
+ */
 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 Host-Nicla configuration
+ * 
+ */
 enum HostOpcode {
   HOST_DFU_INTERNAL_OPCODE = ESLOV_DFU_INTERNAL_OPCODE,
   HOST_DFU_EXTERNAL_OPCODE = ESLOV_DFU_EXTERNAL_OPCODE,
@@ -28,6 +37,11 @@ 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,
@@ -43,19 +57,80 @@ class EslovHandler {
   EslovHandler();
   virtual ~EslovHandler();
 
+   /**
+   * @brief Start I2C communication with Nicla Sense ME Board
+   * 
+   * @param passthrough Enable Serial port at 115200 bps
+   * 
+   * @return true   I2C communication initialised successfully. 
+   * @return false  Failure in starting communication over ESLOV protocol.
+   */
   bool begin(bool passthrough);
+  /**
+   * @brief When Serial port is avaliable, then based on the defined opcode write data 
+   * 
+   */
   void update();
 
+  /**
+   * @brief Send DFU data over ESLOV. On the last packet, the built-in LED is pulled down.
+   * 
+   * @param data    data to be send for DFU
+   * @param length  total length of data to be sent
+   */
   void writeDfuPacket(uint8_t *data, uint8_t length);
+  /**
+   * @brief Configure the Nicla device to run in a specific state
+   * 
+   * @param state Configuration passed to Nicla based on @ref EslovState enumerator
+   */
   void writeStateChange(EslovState state);
+  /**
+   * @brief Specify which sensor to poll data from on the Nicla Sense ME
+   * 
+   * @param config Configuration for the Sensor including sensor ID, sample rate and latency
+   */
   void writeConfigPacket(SensorConfigurationPacket& config);
+  /**
+   * @brief Recieve acknowledgement from Nicla board over ESLOV
+   * 
+   * @return uint8_t Data read from I2C bus
+   */
   uint8_t requestPacketAck();
+  /**
+   * @brief Obtain data sent over ESLOV to the host board
+   * 
+   * @return uint8_t Data read from I2C bus
+   */
   uint8_t requestAvailableData();
+  /**
+   * @brief Obtain long data sent over ESLOV to the host board
+   * 
+   * @return uint8_t Data read from I2C bus
+   */
   uint8_t requestAvailableLongData();
+  /**
+   * @brief Request data from the Nicla board
+   * 
+   * @param sData 
+   * @return true   Request successful
+   * @return false  Request unsuccessful
+   */
   bool requestSensorData(SensorDataPacket &sData);
+  /**
+   * @brief Request long data from the Nicla board
+   * 
+   * @param sData 
+   * @return true  Request successful
+   * @return false Request unsuccessful
+   */
   bool requestSensorLongData(SensorLongDataPacket &sData);
 
 protected:
+  /**
+   * @brief Nicla Sense ME is mounted as a Shield
+   * 
+   */
   void niclaAsShield();
 
 private:
@@ -68,6 +143,10 @@ class EslovHandler {
   bool _dfuLedOn;
 
 private:
+  /**
+   * @brief The Arduino_BHY2Host class can accces both private and public methods of EslovHandler
+   * 
+   */
   friend class Arduino_BHY2Host;
 
   void flushWire();