chore: Swan Init and Clean-up

Author: zfields

variants/STM32L4xx/L4R5Z(G-I)Y_L4R9Z(G-I)Y_L4S5ZIY_L4S9ZIY/PeripheralPins_SWAN_R5.c

@@ -11,9 +11,8 @@
  *******************************************************************************
  */
 /*
- * Automatically generated from STM32L4R5Z(G-I)Yx.xml, STM32L4R9Z(G-I)Yx.xml
- * STM32L4S5ZIYx.xml, STM32L4S9ZIYx.xml
- * CubeMX DB release 6.0.21
+ * Manually generated by Blues with knowledge of the SWAN_R5 schematic
+ * https://github.com/blues/note-hardware/blob/master/Swan/v3.0/Feather/Swan%20Feather%20schematic%20v3.0.pdf
  */
 #if defined(ARDUINO_SWAN_R5)
 #include "Arduino.h"

variants/STM32L4xx/L4R5Z(G-I)Y_L4R9Z(G-I)Y_L4S5ZIY_L4S9ZIY/variant_SWAN_R5.cpp

@@ -10,6 +10,7 @@
  *
  *******************************************************************************
  */
+
 #if defined(ARDUINO_SWAN_R5)
 #include "pins_arduino.h"
 
@@ -122,81 +123,112 @@ WEAK void initVariant(void)
 {
   /* All pins set to high-Z (floating) initially */
   /* DS12023 Rev 5, Section 3.10.5 - Reset mode: */
-  /* In order to improve the consumption under reset, the I/Os state under and after reset is
-   * “analog state” (the I/O schmitt trigger is disable). In addition, the internal reset pull-up is
-   * deactivated when the reset source is internal.
+  /* In order to improve the consumption under reset, the I/Os state under
+   * and after reset is "analog state" (the I/O schmitt trigger is disabled).
+   * In addition, the internal reset pull-up is deactivated when the reset
+   * source is internal.
    */
 
-  /* Turn on the 3V3 regulator */
-  __HAL_RCC_GPIOE_CLK_ENABLE();
-  GPIO_InitTypeDef  GPIO_InitStruct;
-  GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
-  GPIO_InitStruct.Speed = GPIO_SPEED_LOW;
-  GPIO_InitStruct.Pin = GPIO_PIN_4 | GPIO_PIN_6;
-  HAL_GPIO_Init(GPIOE, &GPIO_InitStruct);
-  HAL_GPIO_WritePin(GPIOE, GPIO_InitStruct.Pin, GPIO_PIN_SET);
+  /* Configure the 3V3 regulator */
+  {
+    __HAL_RCC_GPIOE_CLK_ENABLE();
+    GPIO_InitTypeDef  GPIO_InitStruct = {};
+    GPIO_InitStruct.Speed = GPIO_SPEED_LOW;
+
+    /* PE4 is ENABLE_3V3 */
+    GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
+    GPIO_InitStruct.Pin = GPIO_PIN_4;
+    HAL_GPIO_Init(GPIOE, &GPIO_InitStruct);
+
+    /* PE6 is DISCHARGE_3V3 */
+    GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_OD;
+    GPIO_InitStruct.Pin = GPIO_PIN_6;
+    HAL_GPIO_Init(GPIOE, &GPIO_InitStruct);
+
+    /* Enable 3V3 regulator and disable discharging */
+    HAL_GPIO_WritePin(GPIOE, (GPIO_PIN_4 | GPIO_PIN_6), GPIO_PIN_SET);
+  }
 }
 
 /**
-  * @brief  System Clock Configuration – High-performance STM32L4R5xx with PLL from MSI
-  *
-  * Key features:
-  *   • SYSCLK = 120 MHz from PLL (MSI Range 11 /6 × 30 /2 via PLLR)
-  *   • USB FS uses MSI Range 11 as CLK48 source ("The MSI clock can be selected as clock source for the USB FS device, SDMMC1 and RNG when the MSI is in Range 11 (48 MHz)", RM0432 Rev 9 §6.2.10)
-  *   • OSPI clocked from SYSCLK (120 MHz)
-  *   • ADC clocked from SYSCLK (120 MHz)
-  *   • LSE enabled for RTC timing
-  *   • Voltage Scale 1 Boost required for 120 MHz ("In Range 1 boost mode (R1MODE = 0), the maximum system clock frequency is 120 MHz", RM0432 §5.3.11)
-  *   • MSI PLL-mode enabled ("The MSI PLL-mode can be used to obtain a more accurate MSI frequency when the device wakes up from Stop mode", RM0432 §6.3.16)
-  *
-  * References:
-  *   • RM0432 Rev 9 – STM32L4+ Series advanced Arm-based 32-bit MCUs (www.st.com/resource/en/reference_manual/rm0432-stm32l4-series-advanced-armbased-32bit-mcus-stmicroelectronics.pdf)
-  *   • RM0432 §6.2.5 – PLL characteristics: VCO frequency range 64-344 MHz
-  *   • RM0432 §6.4.4 – PLL configuration: PLLM divides input to 4-16 MHz range
-  *   • RM0432 §6.2.14 – "PLLR clock output is used to generate the system clock"
-  *   • RM0432 Table 15 – Flash latency 5 wait states at 120 MHz in Range 1 Boost
-  *   • RM0432 Table 31 – LSEDRV[1:0] = 01 for medium low drive capability
-  *   • STM32CubeL4 v1.18.0 (07 Jun 2023) – USB_Device examples for NUCLEO-L4R5ZI (www.st.com/en/embedded-software/stm32cubel4.html)
-  *   • AN2867 Rev 23 (Jan 2025) – Guidelines for oscillator design on STM32 MCUs/MPUs (www.st.com/resource/en/application_note/an2867-guidelines-for-oscillator-design-on-stm8afals-and-stm32-mcusmpus-stmicroelectronics.pdf)
-  */
+ * @brief  System Clock Configuration - High-performance STM32L4R5xx with PLL from MSI
+ *
+ * Key features:
+ *   - SYSCLK = 120 MHz from PLL (MSI Range 11 /6 x 30 /2 via PLLR)
+ *   - USB FS uses MSI Range 11 as CLK48 source (48 MHz, RM0432 s.6.2.3)
+ *   - OSPI clocked from SYSCLK (120 MHz)
+ *   - ADC clocked from SYSCLK (120 MHz)
+ *   - LSE enabled for RTC timing and MSI auto-calibration (MSIPLLEN)
+ *   - Voltage Scale 1 Boost required for 120 MHz (RM0432 s.5.1.8)
+ *   - MSI PLL-mode (MSIPLLEN) enabled after peripheral clocks to avoid premature MSIRDY deassertion during PeriphCLKConfig
+ *
+ * References:
+ *   - RM0432 Rev 9 - STM32L4+ Series advanced Arm-based 32-bit MCUs
+ *     (www.st.com/resource/en/reference_manual/rm0432-stm32l4-series-advanced-armbased-32bit-mcus-stmicroelectronics.pdf)
+ *   - RM0432 s.5.1.8 - Dynamic voltage scaling management: Range 1 boost mode up to 120 MHz
+ *   - RM0432 s.6.2.3 - MSI clock: MSI as CLK48 source for USB FS in Range 11; MSI PLL-mode (MSIPLLEN)
+ *   - RM0432 s.6.2.5 - PLL: source input range 4-16 MHz
+ *   - RM0432 s.6.4.4 - PLL configuration register (RCC_PLLCFGR): PLLM/PLLN/PLLR fields;
+ *                      VCO input 2.66-8 MHz; VCO output 64-344 MHz; PLLR drives SYSCLK
+ *   - RM0432 Table 12 - Flash latency: 5 wait states at 120 MHz in Range 1 Boost
+ *   - RM0432 s.6.4.29 - RCC_BDCR: LSEDRV[1:0] = 01 for medium low drive capability
+ *   - AN2867 Rev 23 (Jan 2025) - Guidelines for oscillator design on STM32 MCUs/MPUs
+ *     (www.st.com/resource/en/application_note/an2867-guidelines-for-oscillator-design-on-stm8afals-and-stm32-mcusmpus-stmicroelectronics.pdf)
+ */
 WEAK void SystemClock_Config(void)
 {
   RCC_OscInitTypeDef RCC_OscInitStruct = {};
   RCC_ClkInitTypeDef RCC_ClkInitStruct = {};
   RCC_PeriphCLKInitTypeDef PeriphClkInit = {};
 
-  /* -------------------------------------------------------------------------
-   * 1. Voltage scaling – Scale 1 Boost for SYSCLK up to 120 MHz
-   *    "Range 1 boost mode is selected by setting the BOOSTEN bit … and allows to reach 120 MHz"
-   *    (RM0432 Rev 9 §5.3.11 Voltage regulator)
-   * ------------------------------------------------------------------------- */
+  /** Enable PWR peripheral clock
+  *
+  * RM0432 s.6.4.19: PWREN (RCC_APB1ENR1 bit 28) resets to 0, so this call
+  * is required before accessing any PWR register (e.g.,
+  * HAL_PWREx_ControlVoltageScaling below).
+  * CubeMX generates this unconditionally for all STM32L4 projects.
+  */
+  __HAL_RCC_PWR_CLK_ENABLE();
+
+  /* Voltage scaling - Scale 1 Boost required for SYSCLK = 120 MHz
+   * RM0432 s.5.1.8: "In Range 1 boost mode (R1MODE = 0), the maximum system
+   * clock frequency is 120 MHz"
+   */
   if (HAL_PWREx_ControlVoltageScaling(PWR_REGULATOR_VOLTAGE_SCALE1_BOOST) != HAL_OK) {
     Error_Handler();
   }
 
-  /* -------------------------------------------------------------------------
-   * 2. LSE drive capability – medium low (LSEDRV[1:0] = 01)
-   *    "LSEDRV[1:0] = 01: medium low drive capability"
-   *    (RM0432 Rev 9 Table 31 LSE drive capability)
-   *    See AN2867 Rev 23 §5.2 for STM32-compatible low-speed resonators
-   * ------------------------------------------------------------------------- */
+  /** Configure LSE Drive Capability
+  *
+  * Use MEDIUMLOW (not LOW): RCC_LSEDRIVE_LOW risks marginal LSE startup on units
+  * near the crystal ESR tolerance limit and degrades MSI PLL mode (MSIPLLEN) lock
+  * quality. ST recommends MEDIUMLOW as the minimum when MSIPLLEN is in use.
+  * (RM0432 s.6.4.29; AN2867 Rev 23)
+  *
+  * Backup domain access must be enabled before configuring LSE, as RCC->BDCR
+  * is write-protected after reset and silently ignores writes until the lock
+  * is cleared.
+  */
   HAL_PWR_EnableBkUpAccess();
   __HAL_RCC_LSEDRIVE_CONFIG(RCC_LSEDRIVE_MEDIUMLOW);
 
-  /* -------------------------------------------------------------------------
-   * 3. Oscillator configuration
-   *     • MSI = ON, Range 11 (48 MHz) – PLL source and USB CLK48
-   *     • LSE = ON – for RTC
-   *     • PLL = ON – MSI /6 ×30 /2 (PLLR) = 120 MHz SYSCLK
-   *       PLL input = 48 /6 = 8 MHz (4-16 MHz range, RM0432 §6.4.4)
-   *       VCO = 8 ×30 = 240 MHz (64-344 MHz range, RM0432 §6.2.5)
-   *       SYSCLK from PLLR /2 = 120 MHz (RM0432 §6.2.14)
-   *     • HSI not included (off by default)
-   * ------------------------------------------------------------------------- */
-  RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_LSE | RCC_OSCILLATORTYPE_MSI;
+  /** Initializes the RCC Oscillators according to the specified parameters
+  * in the RCC_OscInitTypeDef structure.
+  *
+  * Oscillator configuration summary:
+  *   - MSI: MSIRANGE_11 (48 MHz) -- PLL source and USB CLK48 (RM0432 s.6.2.3)
+  *   - LSE: ON -- for RTC and MSI auto-calibration (MSIPLLEN)
+  *   - PLL: ON (MSI 48 MHz / PLLM=6 x PLLN=30 / PLLR=2 = 120 MHz)
+  *     - PLL source: 48 MHz (4-16 MHz range, RM0432 s.6.2.5)
+  *     - PLL input (after PLLM): 48/6 = 8 MHz (2.66-8 MHz range, RM0432 s.6.4.4)
+  *     - VCO: 8x30 = 240 MHz (64-344 MHz range, RM0432 s.6.4.4)
+  *     - SYSCLK from PLLR/2 = 120 MHz (RM0432 s.6.4.4)
+  */
+  RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_LSE
+                                     | RCC_OSCILLATORTYPE_MSI;
   RCC_OscInitStruct.LSEState = RCC_LSE_ON;
   RCC_OscInitStruct.MSIState = RCC_MSI_ON;
-  RCC_OscInitStruct.MSICalibrationValue = 0;
+  RCC_OscInitStruct.MSICalibrationValue = RCC_MSICALIBRATION_DEFAULT;
   RCC_OscInitStruct.MSIClockRange = RCC_MSIRANGE_11;
   RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
   RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_MSI;
@@ -209,47 +241,51 @@ WEAK void SystemClock_Config(void)
     Error_Handler();
   }
 
-  /* -------------------------------------------------------------------------
-   * 4. System clock mux and bus dividers
-   *    SYSCLK = PLLR = 120 MHz, no AHB/APB dividers
-   *    Flash latency = 5 WS ("5 wait states" at 120 MHz, Range 1 Boost, RM0432 Table 15)
-   * ------------------------------------------------------------------------- */
+  /** Initializes the CPU, AHB and APB buses clocks
+  *
+  * SYSCLK = PLLCLK (120 MHz). No AHB/APB dividers.
+  */
   RCC_ClkInitStruct.ClockType      = RCC_CLOCKTYPE_HCLK    | RCC_CLOCKTYPE_PCLK1
                                      | RCC_CLOCKTYPE_PCLK2 | RCC_CLOCKTYPE_SYSCLK;
   RCC_ClkInitStruct.AHBCLKDivider  = RCC_SYSCLK_DIV1;
   RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV1;
   RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1;
   RCC_ClkInitStruct.SYSCLKSource   = RCC_SYSCLKSOURCE_PLLCLK;
-
+  /* FLASH_LATENCY_5: required for 120 MHz at Range 1 Boost (RM0432 Table 12) */
   if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_5) != HAL_OK) {
     Error_Handler();
   }
 
-  /* -------------------------------------------------------------------------
-   * 5. Peripheral clock selection
-   *     • USB → MSI (48 MHz, valid in Range 11, RM0432 §6.2.10)
-   *     • OSPI → SYSCLK (120 MHz)
-   *     • ADC → SYSCLK (120 MHz)
-   *     • SDMMC1 not selected
-   *    (RM0432 §6.3.2: Peripheral clocks set after SYSCLK)
-   * ------------------------------------------------------------------------- */
+  /** Initializes the Peripheral clocks
+  *
+  * USB clock: MSI Range 11 (48 MHz). RM0432 s.6.2.3: "The MSI clock can be
+  * selected as clock source for the USB FS device, SDMMC1 and RNG when the
+  * MSI is in Range 11 (48 MHz)."
+  * OSPI and ADC clocked from SYSCLK (120 MHz).
+  */
   PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_ADC
                                        | RCC_PERIPHCLK_OSPI
-                                      //  | RCC_PERIPHCLK_SDMMC1
-                                       | RCC_PERIPHCLK_USB
+                                       | RCC_PERIPHCLK_USB;
   PeriphClkInit.AdcClockSelection = RCC_ADCCLKSOURCE_SYSCLK;
   PeriphClkInit.OspiClockSelection = RCC_OSPICLKSOURCE_SYSCLK;
   PeriphClkInit.UsbClockSelection = RCC_USBCLKSOURCE_MSI;
-  // PeriphClkInit.Sdmmc1ClockSelection = RCC_SDMMC1CLKSOURCE_NONE;
   if (HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit) != HAL_OK) {
     Error_Handler();
   }
 
-  /* -------------------------------------------------------------------------
-   * 6. MSI PLL-mode enable
-   *    "The MSI PLL-mode can be used to obtain a more accurate MSI frequency when the device wakes up from Stop mode"
-   *    (RM0432 Rev 9 §6.3.16 MSI PLL-mode)
-   * ------------------------------------------------------------------------- */
+  /** Enable MSI Auto calibration (MSIPLLEN, RCC_CR[2])
+  *
+  * RM0432 s.6.2.3: setting MSIPLLEN causes the MSI hardware to automatically
+  * trim itself against LSE as a phase reference. LSE must already be stable
+  * (LSERDY=1) before the bit is set -- guaranteed here because
+  * HAL_RCC_OscConfig() waited for LSERDY before returning.
+  *
+  * This call must come AFTER HAL_RCCEx_PeriphCLKConfig() -- setting MSIPLLEN
+  * causes MSIRDY to deassert transiently while MSI re-synchronises to LSE.
+  * Because SYSCLK is PLLCLK (120 MHz), SysTick is decoupled from MSI and
+  * HAL_GetTick() remains reliable; the concern is HAL routines that check
+  * MSIRDY as a readiness flag, all of which must complete before this call.
+  */
   HAL_RCCEx_EnableMSIPLLMode();
 }
 

variants/STM32L4xx/L4R5Z(G-I)Y_L4R9Z(G-I)Y_L4S5ZIY_L4S9ZIY/variant_SWAN_R5.h

@@ -156,10 +156,41 @@
   #define DISABLE_DISCHARGING     HIGH
   #define ENABLE_DISCHARGING      LOW
 #endif
-#ifndef BATTERY_VOLTAGE
-  #define BATTERY_VOLTAGE         PA0
+
+// Macro functions for 3V3 regulator management
+#ifndef ENABLE_3V3_REGULATOR
+#  define ENABLE_3V3_REGULATOR()  do { \
+     digitalWrite(DISCHARGE_3V3, DISABLE_DISCHARGING); \
+     digitalWrite(ENABLE_3V3, HIGH); \
+   } while (0)
+#endif
+#ifndef DISABLE_3V3_REGULATOR
+#  define DISABLE_3V3_REGULATOR() do { \
+     digitalWrite(ENABLE_3V3, LOW); \
+   } while (0)
+#endif
+#ifndef DRAIN_3V3_REGULATOR_MS
+#  define DRAIN_3V3_REGULATOR_MS(ms) do { \
+     if (digitalRead(ENABLE_3V3)) { break; } \
+     digitalWrite(DISCHARGE_3V3, ENABLE_DISCHARGING); \
+     delay(ms); \
+     digitalWrite(DISCHARGE_3V3, DISABLE_DISCHARGING); \
+   } while (0)
+#endif
+
+// Dedicated board pins
+#ifndef VMAIN_ADC
+  #define VMAIN_ADC               PA0
+  #define VMAIN_ADC_DIV_BOT_R     4.3f
+  #define VMAIN_ADC_DIV_TOP_R     10.0f
+  #define VMAIN_ADC_DIV_K         ((double)((VMAIN_ADC_DIV_TOP_R + VMAIN_ADC_DIV_BOT_R) / VMAIN_ADC_DIV_BOT_R))
+#endif
+#ifndef VMAIN_MV
+#  define VMAIN_MV() ({ \
+     __HAL_ADC_CALC_DATA_TO_VOLTAGE(__LL_ADC_CALC_VREFANALOG_VOLTAGE(analogRead(AVREF), LL_ADC_GetResolution(ADC1)), analogRead(VMAIN_ADC), LL_ADC_GetResolution(ADC1)) * VMAIN_ADC_DIV_K; \
+   })
 #endif
-// Charge detection is not supported on the Swan
+// Charge detection is not implemented on the Swan hardware
 // #ifndef CHARGE_DETECT
 //   #define CHARGE_DETECT
 // #endif