Add more documentation

gfurtadoalmeida · Oct 28, 2023 · ef191ba · ef191ba
1 parent 2c4f1b4
commit ef191ba
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -61,25 +61,28 @@ void app_main(void)
 
     // Add the device to the SPI bus.
     mcp320x_t *mcp320x_handle = mcp320x_install(&mcp320x_cfg);
-    
+
     // Occupy the SPI bus for multiple transactions.
     mcp320x_acquire(mcp320x_handle, portMAX_DELAY);
-    
+
     uint16_t voltage = 0;
 
-    // Read voltage, sampling 1000 times.
-    mcp320x_read_voltage(mcp320x_handle, 
-                         MCP320X_CHANNEL_0, 
-                         MCP320X_READ_MODE_SINGLE,
-                         1000, 
-                         &voltage);
-
+    for (size_t i = 0; i < 10; i++)
+    {
+        // Read voltage, sampling 1000 times.
+        mcp320x_read_voltage(mcp320x_handle,
+                             MCP320X_CHANNEL_0,
+                             MCP320X_READ_MODE_SINGLE,
+                             1000,
+                             &voltage);
+
+        ESP_LOGI("mcp320x", "Voltage: %d mV", voltage);
+    }
+
     // Unoccupy the SPI bus.
     mcp320x_release(mcp320x_handle);
-    
+
     // Free resources.
     mcp320x_delete(mcp320x_handle);
-
-    ESP_LOGI("mcp320x", "Voltage: %d mV", voltage);
 }
 ```
diff --git a/components/esp32_driver_mcp320x/include/esp32_driver_mcp320x/mcp320x.h b/components/esp32_driver_mcp320x/include/esp32_driver_mcp320x/mcp320x.h
@@ -106,15 +106,17 @@ extern "C"
 
     /**
      * @brief Occupy the SPI bus for continuous readings.
+     * @note The bus must be released using the @ref mcp320x_release function.
      * @note This function is not thread safe when multiple tasks access the same SPI device.
      * @param[in] handle MCP320X handle.
-     * @param[in] timeout Time to wait before the bus is occupied by the device. Currently MUST set to portMAX_DELAY.
+     * @param[in] timeout Time to wait before the bus is occupied by the device. Currently MUST BE set to portMAX_DELAY.
      * @return MCP320X_OK when success, otherwise any MCP320X_ERR* code.
      */
     mcp320x_err_t mcp320x_acquire(mcp320x_t *handle, TickType_t timeout);
 
     /**
      * @brief Release the SPI bus occupied by the ADC. All other devices on the bus can start sending transactions.
+     * @note The bus must be acquired using the @ref mcp320x_acquire function.
      * @note This function is not thread safe when multiple tasks access the same SPI device.
      * @param[in] handle MCP320X handle.
      * @return MCP320X_OK when success, otherwise any MCP320X_ERR* code.
@@ -132,8 +134,8 @@ extern "C"
 
     /**
      * @brief Read a digital code from 0 to 4096 (MCP320X_RESOLUTION).
+     * @note For high \p sample_count it's recommended to aquire the SPI bus using the @ref mcp320x_acquire function.
      * @note This function is not thread safe when multiple tasks access the same SPI device.
-     * @note For high \p sample_count it's recommended to aquire the SPI bus through @ref mcp320x_acquire.
      * @param[in] handle MCP320X handle.
      * @param[in] channel Channel to read from.
      * @param[in] read_mode Read mode.
@@ -148,7 +150,7 @@ extern "C"
                                uint16_t *value);
 
     /**
-     * @brief Read a voltage in millivolts.
+     * @brief Read a voltage, in millivolts.
      * @note This function is not thread safe when multiple tasks access the same SPI device.
      * @param[in] handle MCP320X handle.
      * @param[in] channel Channel to read from.

diff --git a/main/main.c b/main/main.c
@@ -38,18 +38,21 @@ void app_main(void)
 
     uint16_t voltage = 0;
 
-    // Read voltage, sampling 1000 times.
-    mcp320x_read_voltage(mcp320x_handle,
-                         MCP320X_CHANNEL_0,
-                         MCP320X_READ_MODE_SINGLE,
-                         1000,
-                         &voltage);
+    for (size_t i = 0; i < 10; i++)
+    {
+        // Read voltage, sampling 1000 times.
+        mcp320x_read_voltage(mcp320x_handle,
+                             MCP320X_CHANNEL_0,
+                             MCP320X_READ_MODE_SINGLE,
+                             1000,
+                             &voltage);
+
+        ESP_LOGI("mcp320x", "Voltage: %d mV", voltage);
+    }
 
     // Unoccupy the SPI bus.
     mcp320x_release(mcp320x_handle);
 
     // Free resources.
     mcp320x_delete(mcp320x_handle);
-
-    ESP_LOGI("mcp320x", "Voltage: %d mV", voltage);
 }