skills-win/BMSv4_pincfg/SKILL.md

name, description, metadata, compatibility

name	description	metadata	compatibility
BMSv4_pincfg	Modify an existing STM32CubeMX project for BMSv4 hardware pin and peripheral settings. Use when a CubeMX `.ioc` project already exists and BMSv4 SPI3, SPISW_nCSx / SPIADC_nCSx GPIO outputs, PWM outputs, CUR_poly ADC2 inputs, and specific ADC3 inputs must be configured, code regenerated, and the build re-verified.	author version bowei-local 2.1	Requires an existing STM32CubeMX project, local STM32CubeMX installation, and a working CMake build in the target workspace.

BMSv4 Pin Configuration

Apply the BMSv4 hardware pin/peripheral configuration to an existing STM32CubeMX project. Update the .ioc, regenerate code with the locally installed CubeMX, then verify the project still builds.

This skill is for modifying an existing CubeMX project only. Do not create a new project when using this skill.

Preconditions

• Confirm the target workspace already contains a CubeMX .ioc file and generated STM32 project structure.
• Confirm CubeMX exists locally and detect the installed CubeMX version before editing .ioc metadata.
• Keep the existing project name, MCU, clock tree, toolchain, and user code sections unless the user explicitly asks to change them.
• Preserve ProjectManager.KeepUserCode=true.
• Treat the existing project as the baseline. Only change configuration items explicitly described in this skill or explicitly requested by the user.
• If the user asks to modify this skill itself, update only the skill file in that turn. Do not also modify any target STM32 project or .ioc unless the user separately asks to apply the updated skill.

Required BMSv4 configuration

SPI3

• Enable SPI3.
• Configure SPI3 as Half-Duplex Master.
• Use PC10 as SPI3_SCK.
• Use PC12 as SPI3_MOSI.
• Disable hardware NSS and use software NSS.
• Parameters:
  • Frame format: Motorola
  • Data size: 8 Bits
  • First bit: MSB First
  • Prescaler: 2
  • CPOL: Low
  • CPHA: 1 Edge
  • CRC calculation: Disabled

Battery switch decoder chip selects

Configure these pins as GPIO_Output, label them exactly as listed, and default them to inactive high unless the user explicitly requests another reset state:

• PE14 -> SPISW_nCS1
• PE12 -> SPISW_nCS2
• PE10 -> SPISW_nCS3
• PE8 -> SPISW_nCS4
• PG1 -> SPISW_nCS5
• PF15 -> SPISW_nCS6

Battery voltage ADC decoder chip selects

Configure these pins as GPIO_Output, label them exactly as listed, and default them to inactive high unless the user explicitly requests another reset state:

• PE13 -> SPIADC_nCS1
• PE11 -> SPIADC_nCS2
• PE9 -> SPIADC_nCS3
• PE7 -> SPIADC_nCS4
• PG0 -> SPIADC_nCS5
• PF14 -> SPIADC_nCS6

Current-sense ADC inputs

Configure the following six pins as ADC2 analog inputs and label them exactly as listed:

• PB1 -> ADC2_IN9 -> CUR_poly1
• PB0 -> ADC2_IN8 -> CUR_poly2
• PC5 -> ADC2_IN15 -> CUR_poly3
• PC4 -> ADC2_IN14 -> CUR_poly4
• PA7 -> ADC2_IN7 -> CUR_poly5
• PA6 -> ADC2_IN6 -> CUR_poly6

Requirements for these ADC inputs:

• Configure each listed pin as Analog.
• Use No pull-up and no pull-down.
• Apply the exact labels CUR_poly1..6.
• Use ADC2 for all six channels.
• Preserve any existing ADC peripheral configuration unless the user explicitly asks to change sampling sequences, trigger sources, DMA, scan mode, or conversion timing.
• If the target project does not yet enable an ADC instance for these channels, add the minimum ADC configuration required for CubeMX to keep the pin-to-channel mapping valid, without altering unrelated peripherals.
• Do not stop at pin signal mapping plus regular channel/rank fields. Add whatever CubeMX metadata the installed version requires so the ADC GUI actually shows the channels as selected.

Required ADC2 parameters for these inputs:

• Clock Prescaler: PCLK2 divided by 4
• Resolution: 12 bits
• Data Alignment: Right alignment
• Scan Conversion Mode:
  • keep Disabled when only one CUR_poly channel is configured into the ADC2 regular group
  • set Enabled when multiple CUR_poly channels are configured into the ADC2 regular group
• Continuous Conversion Mode: Disabled
• Discontinuous Conversion Mode: Disabled
• DMA Continuous Requests: Disabled
• End Of Conversion Selection: EOC flag at the end of single channel conversion
• Number Of Conversion: set this to the number of CUR_poly channels actually configured into the ADC2 regular group
• External Trigger Conversion Source: Regular Conversion launched by software
• External Trigger Conversion Edge: None
• Rank:
  • when one CUR_poly channel is configured, use Rank = 1
  • when multiple CUR_poly channels are configured, assign sequential regular ranks starting at 1
• Injected Number Of Conversions: 0
• Enable ADC1, ADC2 and ADC3 global interrupts in NVIC with preemption priority 0 and sub priority 0

Additional ADC3 inputs

Configure the following two pins as analog ADC3 inputs and label them exactly as listed:

• PA3 -> ADC3_IN3 -> lt3763_cur
• PF5 -> ADC3_IN15 -> ADC_VBAT_TMP

Requirements for these ADC inputs (BMSv31-style ADC3 workflow):

• Configure each listed pin as Analog.
• Use No pull-up and no pull-down.
• Apply the exact labels lt3763_cur and ADC_VBAT_TMP.
• Use ADC3 for both channels.
• Preserve any existing ADC3 configuration unless the user explicitly asks to change sampling sequences, trigger sources, DMA, scan mode, or conversion timing.
• If the target project does not yet enable an ADC3 instance for these channels, add the minimum ADC configuration required for CubeMX to keep the pin-to-channel mapping valid, without altering unrelated peripherals.
• Keep pin mapping for both channels, but do not require both channels to be simultaneously configured in the ADC3 regular group.
• Treat ADC3_IN15 specially on STM32F407ZGTx: PF5 -> ADC3_IN15 is a valid ADC3-only pin mapping in the device database, and it must not be modeled using the same shared-signal metadata pattern as ADC2_IN15 on PC5.
• Do not reuse SH.ADCx_IN15 entries that belong to ADC1/ADC2 when configuring PF5 -> ADC3_IN15. If the installed CubeMX version uses a different metadata representation for ADC3-only IN15, preserve or generate that exact representation instead of forcing it into the ADC1/ADC2 shared-signal format.
• ADC3 working mode must follow BMSv31 style:
  • initialize ADC3 as single regular conversion (Scan Conversion Mode = Disabled, Number Of Conversion = 1, Rank = 1)
  • keep Continuous Conversion Mode = Disabled
  • keep Discontinuous Conversion Mode = Disabled
  • keep DMA Continuous Requests = Disabled
  • keep End Of Conversion Selection = EOC flag at the end of single channel conversion
  • use software trigger (External Trigger Conversion Source = Regular Conversion launched by software, External Trigger Conversion Edge = None)
  • do channel selection at runtime by reconfiguring sConfig.Channel before each conversion (e.g. switch between ADC_CHANNEL_3 and ADC_CHANNEL_15)

Execution steps

1. Detect the local CubeMX version and confirm the project .ioc header is not stamped with a newer version than the installed tool.
2. Open the existing .ioc project. Do not replace it with a newly created project.
3. Compare the existing project configuration against the configuration explicitly listed in this skill.
4. Modify only the listed configuration items that differ:
   • the SPI3 mode and parameters listed above
   • the twelve named GPIO output definitions listed above
   • the six PWM pin assignments, timer channel mappings, timer base settings, and default duty-cycle settings listed above
   • the six CUR_poly ADC input pin assignments, analog modes, labels, required ADC2 channel mappings, and ADC parameters listed above
   • the two additional ADC3 input pin assignments, analog modes, labels, and required ADC3 channel mappings listed above
   • when configuring ADC inputs, also add the CubeMX shared-signal metadata required by the installed version so the ADC page shows the intended INx entries as selected
   • when configuring PF5 -> ADC3_IN15, verify against the local device database that the mapping is ADC3-only and do not alias it to the ADC1/ADC2 IN15 shared-signal entry used by PC5
   • for ADC3, keep the two pin mappings but configure ADC3 peripheral as single-conversion runtime-switch mode (BMSv31 style), not fixed multi-channel scan sequence
5. Keep every other existing project configuration unchanged if it is not explicitly covered by this skill, including unrelated peripherals, clocks, middleware, pins, NVIC settings, DMA settings, and user code.
6. If any requested pin conflicts with an existing peripheral assignment, stop and report the conflict instead of silently remapping the hardware.
7. Regenerate code using the installed CubeMX while preserving user code sections.
   • This is mandatory after any .ioc change. Do not skip regeneration.
8. Validate the generated result before finishing:
   • Core/Src/spi.c contains MX_SPI3_Init() with SPI_DIRECTION_1LINE, master mode, prescaler 2, SPI_POLARITY_LOW, SPI_PHASE_1EDGE, software NSS, and CRC disabled.
   • Core/Src/gpio.c initializes the required GPIOE, GPIOF, and GPIOG chip-select pins as outputs.
   • Core/Inc/main.h exports the requested pin names and ports.
   • Core/Src/tim.c contains MX_TIM1_Init() and MX_TIM3_Init() with a 10 kHz PWM base derived from the project timer clocks.
   • The generated compare values default to 50% duty cycle for pwm_polyctl1..6.
   • The generated GPIO/pin metadata maps PA9, PA8, PC9, PC8, PC7, and PC6 to the requested timer channels.
   • The generated GPIO/pin metadata maps PB1, PB0, PC5, PC4, PA7, and PA6 to ADC2_IN9, ADC2_IN8, ADC2_IN15, ADC2_IN14, ADC2_IN7, and ADC2_IN6 with labels CUR_poly1..6.
   • The generated GPIO/pin metadata maps PA3 and PF5 to ADC3_IN3 and ADC3_IN15 with labels lt3763_cur and ADC_VBAT_TMP.
   • The generated ADC configuration matches the required ADC2 settings: PCLK2/4, 12-bit, right alignment, continuous disabled, discontinuous disabled, DMA continuous requests disabled, single-channel EOC, software trigger, trigger edge none, and injected conversions 0.
   • The ADC2 regular group explicitly includes the requested CUR_poly channels rather than only setting the pins to analog input mode.
   • Scan Conversion Mode, Number Of Conversion, and the regular channel Rank values are adjusted to match the number of CUR_poly channels actually configured in ADC2.
   • The .ioc contains the CubeMX shared ADC signal metadata needed for the locally installed version to render the requested ADC2 inputs as selected in the GUI, not just low-level regular channel fields.
   • Re-open or re-load the .ioc with the installed CubeMX and confirm the ADC GUI shows the expected ADC2 input selections instead of leaving the INx list unchecked.
   • The .ioc contains the CubeMX shared ADC signal metadata needed for the locally installed version to render the requested ADC3 inputs as selected in the GUI, not just low-level pin signal fields.
   • Re-open or re-load the .ioc with the installed CubeMX and confirm PA3 -> ADC3_IN3 and PF5 -> ADC3_IN15 pin mappings are preserved without pin-level conflict warnings.
   • Core/Src/adc.c (or generated ADC3 init code) uses single regular conversion style for ADC3: scan disabled and number-of-conversion = 1.
   • ADC3 channel usage follows runtime channel reconfiguration style instead of fixed two-channel scan sequence.
   • ADC3 IN15 metadata must not overwrite or corrupt the existing ADC2_IN15 representation used for PC5.
   • The generated GPIO settings for the six ADC pins remain Analog mode with No pull-up and no pull-down.
   • The generated GPIO settings for PA3 and PF5 remain Analog mode with No pull-up and no pull-down.
   • The NVIC enables ADC1, ADC2 and ADC3 global interrupts with preemption priority 0 and sub priority 0.
   • If CubeMX generated or updated ADC init code, it does not silently remove unrelated existing ADC settings outside the channels required for CUR_poly1..6, lt3763_cur, and ADC_VBAT_TMP.
   • The .ioc still opens in the locally installed CubeMX version.
9. Run cmake --preset Debug.
10. Run cmake --build --preset Debug.
11. Confirm the expected ELF exists under build/Debug/.
12. Treat the task as failed if code generation was not executed or if build is not successful. Do not report completion in that case.

Notes & guardrails

• Do not infer CubeMX compatibility from memory. Detect the installed version each time.
• Do not hand-edit generated C source first and then try to backfill the .ioc; the .ioc is the source of truth.
• Do not treat missing detail in this skill as permission to normalize or simplify the rest of the project.
• Do not remove or rewrite existing project configuration that is outside the explicit scope of this skill.
• Do not rename the GPIO labels. They must remain SPISW_nCS1..6 and SPIADC_nCS1..6.
• Do not rename the ADC labels. They must remain CUR_poly1..6.
• Do not rename the additional ADC3 labels. They must remain lt3763_cur and ADC_VBAT_TMP.
• Do not guess PWM frequency parameters from screenshots alone. Derive PSC/ARR/CCR from the actual timer clock in the target project.
• Do not invent ADC parameters that are not explicitly shown or requested; keep unspecified ADC timing details at the generated or pre-existing values unless the user later constrains them.
• Do not leave ADC2 half-configured. It is not sufficient to set only pin analog mode and ADC2_INx signal mapping; the required regular ADC2 channels must also be present in the ADC2 configuration.
• Do not leave ADC3 half-configured. It is not sufficient to set only pin analog mode and ADC3_INx signal mapping; add the minimum ADC3 configuration and metadata needed for CubeMX to keep and display the requested channels.
• Do not force ADC3 into fixed multi-channel scan mode for these two channels when BMSv31-style behavior is requested.
• Do not assume ADCx_IN15 metadata is interchangeable across ADC instances on this MCU family. ADC2_IN15 on PC5 and ADC3_IN15 on PF5 may require different .ioc representations.
• Do not add extra ADC channels, sampling logic, or conversion sequencing beyond what is needed to preserve the requested CUR_poly1..6, lt3763_cur, and ADC_VBAT_TMP pin mappings.
• For _nCS lines, prefer reset state high so external devices stay deselected after boot.
• If CubeMX generation removes or rewrites required user code outside the modified peripherals, stop and report before making manual source patches.
• If the project uses a non-Debug preset name, keep the workspace's existing preset strategy, but still verify a full configure + build path before finishing.
• Do not mark the task complete unless both conditions are met: CubeMX code generation completed successfully, and the project build completed successfully.