193 lines
15 KiB
Markdown
193 lines
15 KiB
Markdown
---
|
|
name: BMSv4_pincfg
|
|
description: 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.
|
|
metadata:
|
|
author: bowei-local
|
|
version: "2.1"
|
|
compatibility: 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.
|