MPPT Power System Firmware (STM32G031F8Px)

Application-layer firmware for the MCU/IC-based solar MPPT power system board (see mppt-mcu-src/ for the schematic/PCB generator). Implements P&O MPPT, a CC/CV battery charge state machine, and the arbitration between them, driving the LM5175 buck-boost stage's FB summing node through a single PWM+RC-filtered analog reference (PA4).

What's here vs. what CubeMX generates

This directory holds the application layer only — the control algorithms, sensor scaling, and the state machine. It is meant to be dropped into an STM32CubeIDE project generated from STM32CubeMX (.ioc file), which supplies the boilerplate this code assumes exists: main.h, SystemClock_Config(), peripheral init functions, HAL/CMSIS, the linker script, and startup code. None of that is regenerated here since it's mechanically produced by CubeMX from the pin configuration below, not something worth hand-authoring or duplicating.

To build: create a new STM32CubeIDE project for STM32G031F8Px, import an .ioc configured per the table below, copy this repo's Core/Inc/*.h and Core/Src/*.c (except don't overwrite CubeMX's own generated main.c) into the project, and add one line to CubeMX's generated main.c inside the while (1) loop:

#include "app_main.h"   /* or just declare `void app_main(void);` */
...
int main(void) {
    /* ...CubeMX-generated init calls... */
    app_main();   /* never returns */
}

CubeMX pin/peripheral configuration

ADC1: continuous=off, scan conversion mode=enabled, 3 ranks as above, 12-bit resolution, software trigger (started explicitly each control-loop iteration in adc_sense_read(), not free-running — the control loop's own 20ms cadence is the sample clock).

Unused pins (tied off per the schematic's S.noconn() calls, no CubeMX configuration needed): PB7/PB8, PB9/PC14, PC15, PF2, PA3, PA5.

Architecture

app_main() [20ms loop]
  |
  +-- adc_sense_read()        -> sensor_frame_t {vbatt, iin, ichg, pgood x2}
  +-- charge_control_update() -> commanded VBATT setpoint
  |     |
  |     +-- state machine: BULK -> ABSORPTION -> FLOAT (-> back to BULK on load)
  |     +-- BULK: CC current-limit trim + P&O MPPT perturbation, arbitrated
  |     |         by taking the MOST RESTRICTIVE (lowest) candidate setpoint
  |     +-- hard panel-side IIN overcurrent backoff, any state
  |
  +-- pwm_ref_set_vbatt_setpoint() -> PA4 PWM duty -> RC filter -> LM5175 FB
  +-- status_led_update()          -> LED1/LED2
  |
  +-- (every 500ms) uart_telemetry_send() -> USART1 CSV line

Why MPPT tracks ICHG, not panel power (V x I) directly

The board's ADC set is VBATT, IIN (panel current) and ICHG (charge current) — there's no VIN (panel voltage) sense divider on this board revision, so true P&O power tracking (P = Vin * Iin) on the input side isn't directly computable. Since the battery bus voltage moves slowly compared to a single P&O perturb-and-settle interval, maximizing ICHG into that near-constant bus is an accepted proxy for maximizing extracted panel power, and is what charge_control.c's mppt_perturb() implements. IIN is still used directly for the hard panel-side overcurrent backoff (PANEL_IIN_MAX_A). A future board revision could add a VIN divider (e.g. reusing the now-unused PA3 or PA5 pin) for true input-side power tracking; see the comparison doc for this noted as a possible follow-up.

FB summing-node transfer function (why R13/R15 were corrected)

The LM5175's FB pin is driven by three resistors summing VBATT, GND and the PWM+RC-filtered MCU reference. Working through the KCL at that node during firmware bring-up revealed the schematic's original R13=46.4k/R15=10k values could only reach a 10.28V ceiling — physically incapable of ever reaching the 14.2V CV target regardless of what the MCU commands. Corrected to R13=120k/R15=68k (R14 unchanged at 10k), giving a 14.76V ceiling down to an 8.94V floor across the PWM's full 0-3.3V range, comfortably bracketing 14.2V. See board_config.h for the exact transfer function and mppt-mcu-src/generator-scripts/build.py's comment at the R13 placement for the schematic-side fix. This was caught and fixed before it reached hardware — worth calling out in the design-calculations doc as a real example of why the FB network needs to be solved algebraically, not just pattern-matched from a similar reference design.

Battery charge profile

12V SLA/AGM, matching the old discrete-analog board for a direct comparison:

• Bulk: CC at 2.0A (BATT_CC_BULK_LIMIT_A) until VBATT reaches 14.2V
• Absorption: CV at 14.2V (BATT_CV_ABSORPTION_V) until current tapers below 0.1A for at least 10 minutes
• Float: CV at 13.6V (BATT_CV_FLOAT_V) indefinitely; returns to Bulk if load pulls current back above half the bulk limit

Verification

Two things can be checked without hardware, a CubeMX install or an STM32 toolchain licence, and make runs both:

make test    # host build of the control layer + simulated panel/converter/battery
make arm     # cross-compile every source for Cortex-M0+ under strict warnings

make arm builds all six application sources with -Wall -Wextra -Wconversion -Wshadow -Wdouble-promotion against test/arm-stub/main.h, a stand-in for the header CubeMX generates. It is not a HAL and cannot be linked into a real image; its job is to make the application layer compile for the real part so that type errors, HAL signature drift and accidental double-precision maths are caught. That last one matters here: the STM32G031 has no FPU, so a single double creeping into the control maths would pull in soft-float routines and cost both flash and loop time. The build fails if any appear. Current cost: 3,096 bytes of flash, 0 bytes of RAM — all controller state lives in caller-provided structs, so there are no statics to initialise or to race on.

make test compiles charge_control.c for the host and runs it against a simulated panel, converter and battery (test/plant.c). The plant is deliberately simple — no switching ripple, no parasitics — because its job is not to be a circuit simulator but to reproduce the one relationship the controller actually steers by: charge current as a function of commanded battery-bus voltage, with a genuine maximum in the middle of the range. It models the panel collapsing past that maximum, which is the entire reason MPPT exists; a model that pins the panel at its peak makes a broken tracker look fine.

The suite asserts properties, not outputs: that no current limit is exceeded once settled, that the CV ceiling holds, that P&O finds and holds the peak, and that a dead sensor is detected rather than acted upon. Transient peaks after a step are scored separately from sustained ones, because a limiter running on a 20 ms cadence cannot prevent a sub-cycle transient — what it must do is not sustain an overshoot.

What the tests found

Every item below was a real defect in the first version of this firmware, found by running it rather than by reading it, and each is now covered by a test that fails without the fix.

Two further changes came out of the test runs rather than from inspection:

• The protection limiters now read the unfiltered current, while MPPT keeps the exponentially-filtered one. The filter that makes the MPPT gradient readable also delays it, and a limiter acting on a delayed signal permits a real overshoot proportional to that delay — measured as 2.13 A against a 2.0 A limit, which fell to 2.08 A once protection moved to the fast signal. Optimise on the smooth signal, protect on the fast one.
• The MPPT step size is adapted against the dead-band, not against reversals. An intermediate version shrank the step on every reversal, which let it fall until one perturbation moved the current by less than the dead-band. At that point every reading said "no change", the direction froze, and the tracker walked steadily off the peak — from 9.16 W to 1.19 W of an available 9.18 W — without ever detecting that it was losing power. The step now grows whenever the observed change is too small to steer by, which makes that failure structurally impossible.

What this does not cover

The plant is a control model, not a circuit: no switching ripple, no converter dynamics, no ESR, no temperature. Loop stability across the MPPT/CC/CV transitions, the RC filter's interaction with the LM5175's own compensation, and the real panel's I-V curve all remain bench items. These tests establish that the control logic is correct on its own terms; they say nothing about whether the analogue loop around it is stable.

Known follow-ups (not blocking, tracked here rather than silently dropped)

• R16/R17 (LM5175 VOSNS overvoltage-protection divider) reused the original (since-corrected) R13/R14 ratio without an independent derivation against the real VOSNS threshold in the LM5175 datasheet — flagged in build.py at the R16 placement, not yet re-derived.
• No VIN (panel voltage) sense channel on this board revision — see the MPPT design note above.
• MPPT holds ~93% of available panel power in simulation, not ~99%. The only control handle firmware has is the battery-bus setpoint, and a battery is a stiff voltage source, so the usable span between "no charge current" and "panel collapsed" is a few hundred millivolts wide. P&O therefore limit-cycles across a sharp, asymmetric peak. Tracking closer would need either a VIN sense channel (so power could be maximised directly rather than inferred from charge current) or a smarter search than fixed-direction P&O. Both are future-board items, recorded here because the number is a property of the control architecture, not a tuning failure.