Updates to BHY2Host

Author: aliphys

src/Arduino_BHY2Host.h

@@ -21,35 +21,121 @@
 #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 Initialise the BHY2 functionality on the host board, for a given @ref NiclaWiring configuration.
+   * 
+   * @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 
+   * 
+   * Configuring for operation as a Shield:
+   * @code 
+   * BHY2Host.begin(NICLA_VIA_BLE);
+   * @endcode
+   */
   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. 
+   * 
+   *  @param ms (optional) Time (in milliseconds) to wait before returning data. 
+   */
   void update();
   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 
+   * 
+   * @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);
   uint8_t requestAck();
+  /**
+   * @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 within the FIFO buffer queue
+   *
+   * @return uint8_t The amount of data in bytes
+   */
   uint8_t availableSensorLongData();
+  /**
+   * @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 from the top element of the queue
+   *
+   * @param data Structure including sensorID, sampleRate and latency
+   */
   bool readSensorLongData(SensorLongDataPacket &data);
-
+  /**
+   * @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);
+  /**
+   * @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);
+  /**
+   * @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/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,11 +13,15 @@
 
 #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 */
 };
 
 enum HostOpcode {
@@ -28,31 +32,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
+   * 
+   * @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)
+   */
   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
+   */
   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 state 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 state 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 state 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 state 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: