boards/nucleo-l452re: add doxygen doc to ADC

krzysztof-cabaj · krzysztof-cabaj · commit 02ecded5ae5c · 2024-07-06T12:27:51.000+02:00
diff --git a/boards/nucleo-l452re/include/periph_conf.h b/boards/nucleo-l452re/include/periph_conf.h
@@ -120,7 +120,36 @@ static const spi_conf_t spi_config[] = {
 #define SPI_NUMOF           ARRAY_SIZE(spi_config)
 /** @} */
 
-static const adc_conf_t adc_config[] = { 
+/**
+ * @brief ADC configuration
+ *
+ * Note that we do not configure all ADC channels,
+ * and not in the STM32L452RE order. Instead, we
+ * just define 6 ADC channels, for the Nucleo
+ * Arduino header pins A0-A5 and the internal VBAT channel.
+ *
+ * To find appropriate device and channel find in the
+ * board manual, table showing pin assignments and
+ * information about ADC - a text similar to ADC[X]_IN[Y],
+ * where:
+ * [X] - describes used device - indexed from 0,
+ * for example ADC1_IN10 is device 0,
+ * [Y] - describes used channel - indexed from 1,
+ * for example ADC1_IN10 is channel 10
+ *
+ * For Nucleo-L452RE this information is in board manual,
+ * Table 22, page 51, or STM32L452RE MCU datasheet,
+ * Table 16, page 63.
+ *
+ * VBAT is connected ADC1_IN18 or ADC3_IN18 and a voltage divider
+ * is used, so that only 1/3 of the actual VBAT is measured. This
+ * allows for a supply voltage higher than the reference voltage.
+ *
+ * For STM32L452RE more information is provided in MCU datasheet,
+ * in section 3.15.3 - Vbat battery voltage monitoring, page 40.
+ * @{
+ */
+static const adc_conf_t adc_config[] = {
     { .pin = GPIO_PIN(PORT_A, 0), .dev = 0, .chan =  5 }, /* A0  ADC1_IN5  */
     { .pin = GPIO_PIN(PORT_A, 1), .dev = 0, .chan =  6 }, /* A1  ADC1_IN6  */
     { .pin = GPIO_PIN(PORT_A, 4), .dev = 0, .chan =  9 }, /* A2  ADC1_IN9  */
@@ -130,10 +159,18 @@ static const adc_conf_t adc_config[] = {
     { .pin = GPIO_UNDEF, .dev = 0, .chan = 18 },
 };
 
+/**
+ * @brief Number of ADC devices
+ */
 #define ADC_NUMOF           ARRAY_SIZE(adc_config)
 
+/**
+ * @brief VBAT ADC line
+ */
 #define VBAT_ADC            ADC_LINE(6)
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
