STM32 펌웨어 (CubeMX/HAL + PlatformIO, ST-Link)
코딩 표준, 아키텍처, 단위 테스트 및 일반 디버깅을 위해 embedded-c-cpp도 함께 로드하세요. 이 스킬은 STM32 특화 부분을 다룹니다.
먼저, 프로젝트를 식별하세요
코드를 작성하기 전에 저장소를 읽으십시오. 다음 사실들은 답변을 바꿉니다:
| 찾는 항목 | 위치 |
|---|---|
| 정확한 부품 번호(예: STM32G431KBT6)와 제품군(F0/F1/F4/G0/G4/L4/H7/U5...) | .ioc (Mcu.UserName), platformio.ini board =, 시동 파일 이름 |
| 프로젝트 유형 | .ioc + .project/.cproject → CubeIDE; .ioc + CMakeLists.txt/CMakePresets.json → CubeMX CMake; platformio.ini → PlatformIO |
| HAL vs LL vs 레지스터 | Drivers/STM32xx_HAL_Driver, #include "stm32xx_ll_*.h", 주변장치별 CubeMX "고급 설정(Advanced settings)" |
| RTOS | Middlewares/Third_Party/FreeRTOS, cmsis_os.h |
| 클럭 | main.c의 SystemClock_Config(), .ioc RCC 섹션; Nucleo 보드는 일반적으로 ST-Link에서 HSE 8MHz를 공급받음(HSE 바이패스) |
| 프로브 | ST-Link (Nucleo/Discovery에 온보드, 또는 ST-Link V2/V3 독립형) |
제품군은 매우 중요합니다: 코어(M0+/M3/M4F/M7/M33), FPU 유무, 플래시 쓰기 세분성(F1은 하프워드, G4/L4는 더블워드, H7은 플래시워드), DMA(G0/G4/L4+/H7은 DMAMUX), 캐시(F7/H7) 등이 다릅니다. 레지스터나 주변장치 세부 사항에 대해 확신이 없으면 추측 대신 참조 매뉴얼(RM)에서 확인할 항목을 알려주세요.
작업 내용을 잃지 않는 CubeMX 규칙
CubeMX는 main.c, stm32xx_it.c, stm32xx_hal_msp.c 및 초기화 파일을 매번 재생성합니다. /* USER CODE BEGIN x */와 /* USER CODE END x */ 사이의 텍스트만 유지됩니다.
- 애플리케이션 로직은 별도 파일(
App/app.c,App/app.h, 또는 C++의 경우app.cpp)에 작성하고,USER CODE BEGIN 2와while (1)USER CODE 블록에서app_init()/app_loop()를 호출하세요. - 핀, 클럭, DMA, 인터럽트 및 주변장치 파라미터는
.ioc에서 변경한 후 재생성하세요 —MX_xxx_Init()를 직접 편집하지 마십시오(덮어쓰여지고.ioc가 코드와 일치하지 않게 됩니다). .ioc파일을 커밋하세요. 이 파일이 하드웨어 구성의 소스 오브 트루스(진실 공급원)입니다.- 프로젝트 관리자(Project Manager) → 코드 생성기(Code Generator)에서 "주변장치 초기화를 주변장치별 .c/.h 파일 쌍으로 생성"을 활성화하세요:
main.c가 더 작아지고, diff가 더 깔끔해집니다. - 자세한 내용 및 C++ 통합:
references/cubemx-hal.md.
빌드, 플래싱, 디버깅
프로젝트에 맞는 경로를 선택하세요. 전체 명령어는 references/build-flash-debug.md에 있습니다.
| 프로젝트 | 빌드 | 플래싱 (ST-Link) | 디버깅 |
|---|---|---|---|
| CubeIDE | IDE, 또는 헤드리스 stm32cubeide ... -build | IDE, 또는 STM32_Programmer_CLI -c port=SWD -w app.elf -v -rst | CubeIDE 디버거 (ST-LINK GDB 서버) |
| CubeMX CMake (VS Code) | cmake --preset Debug && cmake --build --preset Debug | STM32_Programmer_CLI 또는 OpenOCD | VS Code STM32 확장 / OpenOCD + GDB |
| PlatformIO | pio run -e <env> | pio run -e <env> -t upload (upload_protocol = stlink) | pio debug / VS Code (debug_tool = stlink) |
플래싱은 보드를 변경합니다: 업로드를 실행하기 전에 사용자에게 어떤 보드/프로브가 연결되어 있는지 확인하고, 명시적인 확인 없이 대량 소거(mass erase), 옵션 바이트(option-byte) 또는 읽기 보호(read-protection) 명령을 절대 실행하지 마십시오 (RDP 레벨 2는 영구적입니다).
HAL 사용 — 가장 많은 시간을 낭비하는 실수들
- I2C 주소는 왼쪽으로 시프트하여 전달합니다:
HAL_I2C_Master_Transmit(&hi2c1, 0x76 << 1, ...). - HAL 콜백은 인터럽트 컨텍스트에서 실행됩니다 (
HAL_UART_RxCpltCallback,HAL_GPIO_EXTI_Callback,HAL_TIM_PeriodElapsedCallback): 콜백을 짧게 유지하고,HAL_Delay나 블로킹 전송을 사용하지 마십시오. HAL_Delay/HAL_GetTick은 SysTick이 필요합니다: 우선순위가 더 높은 ISR에서 호출하거나 인터럽트가 비활성화된 상태에서 호출하면 멈춥니다. FreeRTOS를 사용하는 경우 CubeMX에서 SYS → Timebase Source를 기본 타이머(TIM6/TIM7)로 설정하세요.- UART 수신:
HAL_UARTEx_ReceiveToIdle_DMA(가변 길이 프레임) 또는 인터럽트 모드(링 버퍼 사용)를 사용하고, 콜백과HAL_UART_ErrorCallback에서 수신을 재시작하십시오 (오버런이 발생하면 수신이 조용히 중단됩니다). - F7/H7의 DMA 버퍼 (데이터 캐시): TX 전에 클린(clean), RX 후에 무효화(invalidate)하고, 32바이트 정렬 및 크기를 유지하세요. H7에서 DMA1/2는 DTCM RAM에 접근할 수 없습니다 — 버퍼를 D2/AXI SRAM에 배치하세요.
- 모든 HAL 호출의 반환값을 확인하세요 (
HAL_OK,HAL_ERROR,HAL_BUSY,HAL_TIMEOUT).HAL_BUSY는 일반적으로 이전 전송이 완료되지 않았음을 의미합니다. - 타임아웃: 프로덕션 경로에서는 절대
HAL_MAX_DELAY를 사용하지 마십시오. - 더 많은 패턴 (UART DMA, ADC DMA, 타이머/PWM, EXTI, 저전력, 플래시 쓰기, 워치독, 리셋 원인):
references/cubemx-hal.md.
크래시가 나거나 시작되지 않을 때
- HardFault / MemManage / BusFault / UsageFault →
references/faults-and-recovery.md(CFSR/HFSR 읽기, 스택 PC 추적,addr2line으로 디코딩). - ST-Link 연결 불가 ("No target found", "DEV_TARGET_HELD_UNDER_RESET") → 리셋 상태에서 연결 시도;
.ioc에서 SWD 핀이 GPIO로 재구성되지 않았는지 확인; BOOT0; RDP 레벨 →references/faults-and-recovery.md. SystemClock_Config에서 멈춤 → HSE 미존재/바이패스 불일치, 잘못된 PLL, 플래시 레이턴시 너무 낮음.- 주변장치가 동작하지 않음 → 클럭 활성화되었는가? 핀 AF가 올바른가?
MX_xxx_Init가 실제로 호출되었고 올바른 순서로 호출되었는가 (DMA 초기화는 이를 사용하는 주변장치보다 먼저)?
참조 파일
| 파일 | 언제 읽을 것인가 |
|---|---|
references/cubemx-hal.md | CubeMX 프로젝트 코드 작성/검토 시, C++ 통합, 주변장치 패턴, 저전력, 플래시/EEPROM 에뮬레이션, 워치독, 리셋 원인 |
references/build-flash-debug.md | 툴체인 설치, CLI에서 빌드, STM32용 PlatformIO 설정, 플래싱, GDB/OpenOCD, printf/SWV 로깅, 크기 분석 |
references/faults-and-recovery.md | HardFault 및 기타 폴트, 보드 연결 안 됨, 옵션 바이트 및 읽기 보호, 벽돌처럼 보이는 보드 복구 |