Skill: aidankong/stm32-cubemx (version 1.0.3)

--- name: stm32-cubemx description: "STM32CubeMX CLI operations for configuring pins, peripherals, DMA, interrupts, and generating code. Use cases: (1) Add/modify STM32 peripheral configuration (2) Configure USART/SPI/I2C/ADC/TIM peripherals (3) Set up DMA and interrupts (4) Generate CMake/GCC project code. Default target MCU: STM32F103C8Tx." --- # STM32CubeMX CLI Operations ## Environment Setup ```bash # STM32CubeMX path (modify based on your installation) CUBEMX=/path/to/STM32CubeMX/STM32CubeMX # Project path (adjust for your project) PROJECT_DIR=/path/to/your/project IOC_FILE=$PROJECT_DIR/your_project.ioc SCRIPT_FILE=$PROJECT_DIR/cube_headless.txt ``` ## Core Workflow ``` 1. Modify IOC config file → 2. Run CLI to generate code → 3. CMake build verification ``` ### Step 1: Modify IOC File Edit the `.ioc` file to add/modify peripheral configuration. **Key Configuration Sections:** - `Mcu.IP0=XXX` - Peripheral IP list, `Mcu.IPNb` is the count - `Mcu.Pin0=PAx` - Pin list, `Mcu.PinsNb` is the count - `XXX.Signal=YYY` - Pin signal mapping - `ProjectManager.functionlistsort` - Initialization function list ### Step 2: Generate Code ```bash # Headless mode (recommended) $CUBEMX -q $SCRIPT_FILE # Script file content cat > $SCRIPT_FILE << 'EOF' config load /path/to/your/project/your_project.ioc project generate exit EOF ``` ### Step 3: Build Verification ```bash cd $PROJECT_DIR rm -rf build/Debug cmake --preset Debug cmake --build build/Debug ``` ## CLI Command Reference | Command | Purpose | Example | |------|------|------| | `config load <path>` | Load IOC configuration | `config load /path/to/project.ioc` | | `config save <path>` | Save IOC configuration | `config save /path/to/project.ioc` | | `project generate` | Generate complete project | `project generate` | | `project toolchain <name>` | Set toolchain | `project toolchain CMake` | | `project path <path>` | Set project path | `project path /path/to/project` | | `project name <name>` | Set project name | `project name MyProject` | | `load <mcu>` | Load MCU | `load STM32F103C8Tx` | | `setDriver <IP> <HAL\|LL>` | Set driver type | `setDriver ADC LL` | | `exit` | Exit program | `exit` | ## Common Peripheral Configuration Templates ### USART + DMA See [references/USART_DMA.md](references/USART_DMA.md) for detailed configuration ```ini # Add IP Mcu.IP6=USART2 Mcu.IPNb=7 # Pin configuration PA2.Signal=USART2_TX PA3.Signal=USART2_RX # USART2 parameters USART2.BaudRate=115200 USART2.Dmaenabledrx=1 USART2.Dmaenabledtx=1 # DMA configuration Dma.Request0=USART2_RX Dma.Request1=USART2_TX Dma.USART2_RX.0.Instance=DMA1_Channel6 Dma.USART2_TX.1.Instance=DMA1_Channel7 # Interrupts NVIC.USART2_IRQn=true\:0\:0\:false\:false\:true\:true\:true\:true ``` ### ADC Acquisition ```ini # Add ADC1 Mcu.IP0=ADC1 # ADC configuration ADC1.Channel-1\#ChannelRegularConversion=ADC_CHANNEL_5 ADC1.Rank-1\#ChannelRegularConversion=1 ADC1.SamplingTime-1\#ChannelRegularConversion=ADC_SAMPLETIME_1CYCLE_5 ADC1.NbrOfConversionFlag=1 ADC1.master=1 # Pin PA5.Signal=ADCx_IN5 SH.ADCx_IN5.0=ADC1_IN5,IN5 ``` ### TIM PWM ```ini # TIM3 configuration TIM3.Channel-PWM\ Generation1\ CH1=PWM_CHANNEL1 TIM3.Channel-PWM\ Generation2\ CH2=PWM_CHANNEL2 TIM3.IPParametersWithoutCheck=Prescaler,Period # Pins PA6.Signal=TIM3_CH1 PA7.Signal=TIM3_CH2 ``` ## STM32F103C8T6 Resource Mapping ### USART | Peripheral | TX | RX | DMA TX | DMA RX | |------|-----|-----|--------|--------| | USART1 | PA9 | PA10 | DMA1_Ch4 | DMA1_Ch5 | | USART2 | PA2 | PA3 | DMA1_Ch7 | DMA1_Ch6 | | USART3 | PB10 | PB11 | DMA1_Ch2 | DMA1_Ch3 | ### ADC Channels | Channel | Pin | Channel | Pin | |------|------|------|------| | IN0 | PA0 | IN5 | PA5 | | IN1 | PA1 | IN6 | PA6 | | IN2 | PA2 | IN7 | PA7 | | IN3 | PA3 | IN8 | PB0 | | IN4 | PA4 | IN9 | PB1 | ### TIM Channels | Timer | CH1 | CH2 | CH3 | CH4 | |--------|-----|-----|-----|-----| | TIM1 | PA8 | PA9 | PA10 | PA11 | | TIM2 | PA0/PA5/PA15 | PA1/PB3 | PA2 | PA3 | | TIM3 | PA6/PB4 | PA7/PB5 | PB0 | PB1 | | TIM4 | PB6 | PB7 | PB8 | PB9 | ## Troubleshooting ### Q1: CLI execution has no effect **Cause**: Paths must be absolute ```bash # Wrong ./STM32CubeMX -q script.txt # Correct /path/to/STM32CubeMX/STM32CubeMX -q /path/to/project/script.txt ``` ### Q2: Generated code missing initialization functions **Cause**: `functionlistsort` does not include the corresponding function ```ini # Add initialization function ProjectManager.functionlistsort=...,N-MX_XXX_Init-XXX-false-HAL-true ``` ### Q3: Peripheral code not generated **Checklist**: 1. Is IP in the `Mcu.IPx` list? 2. Is `Mcu.IPNb` count correct? 3. Is pin Signal configured? ### Q4: DMA not associated **Solution**: Enable peripheral DMA parameters ```ini USART2.Dmaenabledrx=1 USART2.Dmaenabledtx=1 ``` ## Quick Reference ```bash # Complete workflow cd /path/to/your/project # 1. Edit IOC file # 2. Generate code /path/to/STM32CubeMX/STM32CubeMX -q cube_headless.txt # 3. Build cmake --preset Debug && cmake --build build/Debug # 4. Check size arm-none-eabi-size build/Debug/your_project.elf ``` ## References - [references/USART_DMA.md](references/USART_DMA.md) - Complete USART + DMA configuration - [references/IOC_structure.md](references/IOC_structure.md) - Detailed IOC file structure - [UM1718 STM32CubeMX User Manual](https://www.st.com/resource/en/user_manual/um1718-stm32cubemx-description-stmicroelectronics.pdf)

path: references/IOC_structure.md
content: # IOC File Structure Reference

## Overview

The `.ioc` file is STM32CubeMX's project configuration file in INI format.

## Main Configuration Sections

### 1. MCU Basic Information

```ini
Mcu.Family=STM32F1
Mcu.IP0=ADC1
Mcu.IP1=DMA
Mcu.IP2=NVIC
Mcu.IP3=RCC
Mcu.IP4=SYS
Mcu.IPNb=5
Mcu.Name=STM32F103C(8)Tx
Mcu.Package=LQFP48
Mcu.Pin0=PA0
Mcu.Pin1=PA1
Mcu.PinsNb=10
Mcu.UserConstants=
Mcu.UserName=STM32F103C8Tx
```

### 2. Pin Configuration

```ini
# Basic pin configuration
PA0.GPIO_Label=LED_PIN
PA0.Locked=true
PA0.Signal=ADCx_IN0

# GPIO mode configuration
PA0.GPIO.Mode=AN
PA0.GPIO.Pull=_NOPULL
PA0.GPIO.Speed=GPIO_SPEED_FREQ_LOW

# Shared signals (e.g., ADC)
SH.ADCx_IN0.0=ADC1_IN0,IN0
SH.ADCx_IN0.ConfNb=1
```

### 3. Peripheral IP Configuration

```ini
# RCC (Clock configuration)
RCC.ADCFreqValue=12000000
RCC.AHBFreq_Value=72000000
RCC.APB1Freq_Value=36000000
RCC.APB2Freq_Value=72000000
RCC.HSE_VALUE=8000000
RCC.PLLM=8
RCC.PLLN=72
RCC.PLLP=RCC_PLLP_DIV2
RCC.PLLQ=3
RCC.PLLSourceVirtual=RCC_PLLSOURCE_HSE
RCC.SysCLKFreq_Value=72000000

# SYS
VP_SYS_VS_Systick.Mode=SysTick
VP_SYS_VS_Systick.Signal=SYS_VS_Systick
```

### 4. Peripheral Parameter Configuration

```ini
# USART example
USART2.BaudRate=115200
USART2.WordLength=WORDLENGTH_8B
USART2.StopBits=STOPBITS_1
USART2.Parity=PARITY_NONE
USART2.Mode=MODE_TX_RX
USART2.HwFlowControl=HWCONTROL_NONE
USART2.OverSampling=OVERSAMPLING_16
USART2.VirtualMode=VM_ASYNC
USART2.IPParameters=BaudRate,WordLength,StopBits,Parity,Mode,HwFlowControl,OverSampling,VirtualMode

# TIM example
TIM3.AutoReloadPreload=TIM_AUTORELOAD_PRELOAD_ENABLE
TIM3.CounterMode=TIM_COUNTERMODE_UP
TIM3.Period=999
TIM3.Prescaler=71
TIM3.IPParameters=CounterMode,Period,Prescaler,AutoReloadPreload
```

### 5. DMA Configuration

```ini
# DMA request list
Dma.Request0=USART2_RX
Dma.Request1=USART2_TX
Dma.RequestsNb=2

# Single DMA channel configuration
Dma.USART2_RX.0.Direction=DMA_PERIPH_TO_MEMORY
Dma.USART2_RX.0.Instance=DMA1_Channel6
Dma.USART2_RX.0.MemDataAlignment=DMA_MDATAALIGN_BYTE
Dma.USART2_RX.0.MemInc=DMA_MINC_ENABLE
Dma.USART2_RX.0.Mode=DMA_NORMAL
Dma.USART2_RX.0.PeriphDataAlignment=DMA_PDATAALIGN_BYTE
Dma.USART2_RX.0.PeriphInc=DMA_PINC_DISABLE
Dma.USART2_RX.0.Priority=DMA_PRIORITY_LOW
Dma.USART2_RX.0.RequestParameters=Instance,Direction,PeriphInc,MemInc,PeriphDataAlignment,MemDataAlignment,Mode,Priority
```

### 6. NVIC Interrupt Configuration

```ini
# Interrupt enable and priority
NVIC.USART2_IRQn=true\:0\:0\:false\:false\:true\:true\:true\:true
NVIC.DMA1_Channel6_IRQn=true\:0\:0\:false\:false\:true\:false\:true\:true
NVIC.EXTI0_IRQn=true\:1\:0\:true\:false\:true\:true\:true\:true

# Priority grouping
NVIC.PriorityGroup=NVIC_PRIORITYGROUP_4
```

### 7. Project Management Configuration

```ini
# Project manager
ProjectManager.AskForMigrate=true
ProjectManager.BackupPrevious=false
ProjectManager.CompilerOptimization=Optimization Level 1
ProjectManager.ComputerToolchain=Linux
ProjectManager.CoupleFileByIP=false
ProjectManager.CustomerFirmwarePackage=
ProjectManager.DefaultFWLocation=true
ProjectManager.DeletePrevious=true
ProjectManager.DeviceIdFromTool=true
ProjectManager.FirmwarePackage=STM32Cube FW_F1 V1.8.7
ProjectManager.FreePins=false
ProjectManager.HalAssertFull=false
ProjectManager.HeapSize=0x200
ProjectManager.KeepUserCode=true
ProjectManager.LibraryProject=Library
ProjectManager.MainLocation=Core/Src
ProjectManager.PreviousToolchain=SW4STM32
ProjectManager.ProjectBuild=false
ProjectManager.ProjectFileName=STM32F103C8T6_Template.ioc
ProjectManager.ProjectName=STM32F103C8T6_Template
ProjectManager.RegisterCallBack=
ProjectManager.StackSize=0x400
ProjectManager.TargetToolchain=CMake
ProjectManager.TemplatePair=
ProjectManager.ToolChainLocation=

# Initialization function list (important!)
ProjectManager.functionlistsort=1-SystemClock_Config-RCC-false-HAL-false,2-MX_GPIO_Init-GPIO-false-HAL-true,3-MX_DMA_Init-DMA-false-HAL-true,4-MX_USART2_UART_Init-USART2-false-HAL-true
```

### 8. Toolchain Configuration

```ini
# CMake configuration
Toolchain.CMake.Compiler.Location=
Toolchain.CMake.Compiler.Executable=
Toolchain.CMake.Make.Location=
Toolchain.CMake.Make.Executable=make
```

## Configuration Rules

### Steps to Add a New Peripheral

1. Add IP to `Mcu.IPx` list
2. Update `Mcu.IPNb` count
3. Add pin configuration `Mcu.Pinxx`
4. Update `Mcu.PinsNb` count
5. Configure peripheral parameters
6. Update `ProjectManager.functionlistsort`

### functionlistsort Format

```
Index-FunctionName-Peripheral-IsMSP-HAL/LL-GenerateWeakFunction
```

Example:
```
1-SystemClock_Config-RCC-false-HAL-false
2-MX_GPIO_Init-GPIO-false-HAL-true
3-MX_DMA_Init-DMA-false-HAL-true
4-MX_USART2_UART_Init-USART2-false-HAL-true
```

## Special Character Escaping

Special characters in IOC files must be escaped:

| Character | Escape Sequence |
|------|----------|
| `:` | `\:` |
| `#` | `\#` |
| `=` | `\=` |
| Space | `\ ` (in property names) |

Example:
```ini
ADC1.Channel-1\#ChannelRegularConversion=ADC_CHANNEL_5
NVIC.USART2_IRQn=true\:0\:0\:false\:false\:true\:true\:true\:true
```


path: references/USART_DMA.md
content: # USART + DMA Complete Configuration

## IOC File Configuration

```ini
# ============ IP List ============
Mcu.IP0=ADC1
Mcu.IP1=DMA
Mcu.IP2=NVIC
Mcu.IP3=RCC
Mcu.IP4=SYS
Mcu.IP5=USART2
Mcu.IPNb=6

# ============ Pin List ============
Mcu.Pin0=PA2
Mcu.Pin1=PA3
Mcu.Pin2=VP_SYS_VS_Systick
Mcu.PinsNb=3

# ============ USART2 Pin Configuration ============
PA2.Locked=true
PA2.Mode=Asynchronous
PA2.Signal=USART2_TX

PA3.Locked=true
PA3.Mode=Asynchronous
PA3.Signal=USART2_RX

# ============ USART2 Parameters ============
USART2.BaudRate=115200
USART2.Dmaenabledrx=1
USART2.Dmaenabledtx=1
USART2.IPParameters=BaudRate,Dmaenabledrx,Dmaenabledtx,Mode,VirtualMode
USART2.Mode=Asynchronous
USART2.VirtualMode=VM_ASYNC
USART2.WordLength=WORDLENGTH_8B
USART2.Parity=PARITY_NONE
USART2.StopBits=STOPBITS_1

# ============ DMA Configuration ============
Dma.Request0=USART2_RX
Dma.Request1=USART2_TX
Dma.RequestsNb=2

# DMA RX (USART2_RX -> DMA1_Channel6)
Dma.USART2_RX.0.Direction=DMA_PERIPH_TO_MEMORY
Dma.USART2_RX.0.Instance=DMA1_Channel6
Dma.USART2_RX.0.MemDataAlignment=DMA_MDATAALIGN_BYTE
Dma.USART2_RX.0.MemInc=DMA_MINC_ENABLE
Dma.USART2_RX.0.Mode=DMA_NORMAL
Dma.USART2_RX.0.PeriphDataAlignment=DMA_PDATAALIGN_BYTE
Dma.USART2_RX.0.PeriphInc=DMA_PINC_DISABLE
Dma.USART2_RX.0.Priority=DMA_PRIORITY_LOW
Dma.USART2_RX.0.RequestParameters=Instance,Direction,PeriphInc,MemInc,PeriphDataAlignment,MemDataAlignment,Mode,Priority

# DMA TX (USART2_TX -> DMA1_Channel7)
Dma.USART2_TX.1.Direction=DMA_MEMORY_TO_PERIPH
Dma.USART2_TX.1.Instance=DMA1_Channel7
Dma.USART2_TX.1.MemDataAlignment=DMA_MDATAALIGN_BYTE
Dma.USART2_TX.1.MemInc=DMA_MINC_ENABLE
Dma.USART2_TX.1.Mode=DMA_NORMAL
Dma.USART2_TX.1.PeriphDataAlignment=DMA_PDATAALIGN_BYTE
Dma.USART2_TX.1.PeriphInc=DMA_PINC_DISABLE
Dma.USART2_TX.1.Priority=DMA_PRIORITY_LOW
Dma.USART2_TX.1.RequestParameters=Instance,Direction,PeriphInc,MemInc,PeriphDataAlignment,MemDataAlignment,Mode,Priority

# ============ NVIC Interrupts ============
NVIC.USART2_IRQn=true\:0\:0\:false\:false\:true\:true\:true\:true
NVIC.DMA1_Channel6_IRQn=true\:0\:0\:false\:false\:true\:false\:true\:true
NVIC.DMA1_Channel7_IRQn=true\:0\:0\:false\:false\:true\:false\:true\:true

# ============ Initialization Function List ============
ProjectManager.functionlistsort=1-SystemClock_Config-RCC-false-HAL-false,2-MX_GPIO_Init-GPIO-false-HAL-true,3-MX_DMA_Init-DMA-false-HAL-true,4-MX_USART2_UART_Init-USART2-false-HAL-true
```

## NVIC Configuration Parameter Explanation

Format: `NVIC.<IRQn>=<enabled>\:<preemption>\:<sub>\:...`

```
NVIC.USART2_IRQn=true:0:0:false:false:true:true:true:true
              │       │  │    │     │     │    │    │    │
              │       │  │    │     │     │    │    │    └─ ???
              │       │  │    │     │     │    │    └─ check
              │       │  │    │     │     │    └─ enabled?
              │       │  │    │     │     └─ ???
              │       │  │    │     └─ ???
              │       │  │    └─ ???
              │       │  └─ sub priority
              │       └─ preemption priority
              └─ enabled (true/false)
```

## Generated Code

### Call Order in main.c

```c
int main(void) {
    // ...
    MX_DMA_Init();       // Must be before USART
    MX_USART2_UART_Init();
    // ...
}
```

### DMA Usage Example

```c
// Receive buffer
uint8_t rx_buffer[256];
uint8_t tx_buffer[] = "Hello";

// Start DMA receive
HAL_UART_Receive_DMA(&huart2, rx_buffer, sizeof(rx_buffer));

// Start DMA transmit
HAL_UART_Transmit_DMA(&huart2, tx_buffer, sizeof(tx_buffer));

// DMA receive complete callback
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    if (huart->Instance == USART2) {
        // Process received data
    }
}
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)