Be more specific with BHY2Host and ESLOV Handler

Author: aliphys

src/Arduino_BHY2Host.h

@@ -45,12 +45,12 @@ class Arduino_BHY2Host {
 
   // Necessary API. Update function should be continuously polled if PASSTHORUGH is ENABLED
     /**
-   * @brief Initialise the BHY2 functionality on the host board, for a given @ref NiclaWiring configuration.
+   * @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 NiclaWiring Defining I2C configuration (NICLA_VIA_ESLOV, NICLA_AS_SHIELD or NICLA_VIA_BLE). @see NiclaWiring 
+   * @param niclaConnection Defining I2C configuration (NICLA_VIA_ESLOV, NICLA_AS_SHIELD or NICLA_VIA_BLE). @see NiclaWiring 
    * 
    * Configuring for operation as a Shield:
    * @code 
@@ -59,17 +59,21 @@ class Arduino_BHY2Host {
    */
   bool begin(bool passthrough = false, NiclaWiring niclaConnection = NICLA_VIA_ESLOV);
     /**
-   *  @brief Update sensor data by reading the FIFO buffer on the BHI260 and then pass it to a suitable parser. 
+   *  @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 Configure a virtual sensor on the BHI260 to have a set sample rate (Hz) and latency (milliseconds)
-   * This can be achieved 
+   * @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
    * 
@@ -90,52 +94,51 @@ class Arduino_BHY2Host {
    */
   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 The amount of data in bytes
+   * @return uint8_t Amount of bytes.
    */
   uint8_t availableSensorData();
   /**
    * @brief Return available long sensor data within the FIFO buffer queue
    *
-   * @return uint8_t The amount of data in bytes
+   * @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 Structure including sensorID, sampleRate and latency
+   * @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 Structure including sensorID, sampleRate and latency
+   * @param data SensorDataPacket object including SensorID, size , and data payload
    */
   bool readSensorLongData(SensorLongDataPacket &data);
   /**
-   * @brief Parse XYZ Cartesian data from a given data packet
+   * @brief Parse XYZ Cartesian data from `SensorDataPacket` and store within `DataXYZ` vector
    *
-   * @param data data packet including SensorID
-   * @param vector vector with XYZ
+   * @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 from a given data packet
+   * @brief Parse orientation data from `SensorDataPacket` and store within `DataOrientation` vector. Optional argument for scale factor
    *
-   * @param data Data packet including SensorID
-   * @param vector Vector with heading, pitch and roll
+   * @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);
-  /**
-   * @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();

src/EslovHandler.h

@@ -14,7 +14,7 @@
 #define I2C_INT_PIN (0)
 
 /**
- * @brief Enumerator for ESLOV operational state
+ * @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 {
@@ -24,6 +24,10 @@ enum EslovOpcode {
   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,
@@ -66,16 +70,16 @@ class EslovHandler {
    */
   void update();
   /**
-   * @brief Write a DFU (Device Firmware Update) packet to the Nicla Board over ESLOV
+   * @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 (uint8_t)
-   * @param length length of the data to be written to the Nicla in bytes (int)
+   * @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 enumeration of EslovState to be written over ESLOV to the Nicla
+   * @param state State value sent to Nicla Sense ME based on @ref EslovState enumerator.
    */
   void writeStateChange(EslovState state);
   /**