STM32 Programmer CLI: от установки до автоматизации прошивки микроконтроллеров

Прошивка микроконтроллеров STM32 через командную строку (CLI) — это не просто альтернатива графическим интерфейсам вроде STM32CubeIDE или Keil, а часто единственный способ автоматизировать процессы в производстве, CI/CD-пайплайнах или при работе с headless-системами. CLI-утилиты типа STM32CubeProgrammer, OpenOCD или st-flash позволяют прошивать STM32 с точностью до байта, интегрироваться со скриптами на Python/Bash, и даже восстанавливать "кирпичи" через SWJ-DP или JTAG.

Однако переход на CLI сопряжён с подводными камнями: от неочевидных флагов команд (например, --verify vs --verify=read в STM32CubeProgrammer) до проблем с драйверами ST-Link в Linux или конфликтов версий OpenOCD. В этом руководстве мы разберём все этапы — от установки инструментов до отладки типичных ошибок типа Error: failed to read memory или Cannot connect to target, а также покажем, как ускорить прошивку на 30% за счёт оптимизации параметров CLI.

1. Выбор инструмента: STM32CubeProgrammer vs OpenOCD vs st-flash

Три основных CLI-утилиты для работы с STM32 решают одни задачи, но подходят для разных сценариев. Выбор зависит от протокола (SWD/JTAG), ОС (Windows/Linux/macOS) и целей (отладка, массовая прошивка, восстановление).

• 🔧 STM32CubeProgrammer — официальный инструмент от STMicroelectronics с поддержкой всех семейств STM32 (от STM32F0 до STM32H7). Поддерживает SWD, JTAG, UART и даже I2C/SPI для bootloader-прошивки. Минус — закрытый исходный код и иногда избыточный функционал.
• 🐧 OpenOCD — открытый отладчик с поддержкой STM32 через SWD/JTAG. Гибкий, но требует ручной настройки конфигурационных файлов (.cfg). Идеален для Linux и интеграции с GDB.
• ⚡ st-flash — минималистичная утилита из проекта texane/stlink. Работает только с ST-Link (v1/v2/v3), но прошивает быстрее конкурентов за счёт оптимизированного протокола. Нет поддержки отладки.

Для производства чаще выбирают STM32CubeProgrammer из-за стабильности, для Linux-разработки — OpenOCD, а для быстрой прошивки тестовых плат — st-flash. Ниже сравнение ключевых параметров:

Критическое отличие: только STM32CubeProgrammer поддерживает прошивку через UART с использованием встроенного bootloader-а STM32 (актуально для восстановления "кирпичей" без отладчика).

2. Установка и настройка инструментов

Процесс установки зависит от ОС и выбранной утилиты. На Windows проще всего работать с STM32CubeProgrammer (есть установщик), а на Linux придётся собирать OpenOCD или st-flash из исходников.

2.1. STM32CubeProgrammer (Windows/Linux/macOS)

Официальные инструкции от ST часто устаревают, поэтому вот актуальные шаги для установки:

1. Скачайте последнюю версию с официального сайта (на момент написания — v2.15.0).
2. На Windows запустите установщик с правами администратора. На Linux/macOS распакуйте архив и добавьте путь к bin/ в PATH:

   export PATH=$PATH:/путь/до/STM32CubeProgrammer/bin

3. Проверьте установку командой:

   STM32_Programmer_CLI --version

2.2. OpenOCD (Linux/WSL)

В репозиториях дистрибутивов часто лежат устаревшие версии. Для STM32 рекомендуется версия 0.12.0+:

# Установка зависимостей (Ubuntu/Debian)
sudo apt install autoconf libtool pkg-config libusb-1.0-0-dev

# Клонирование и сборка
git clone https://git.code.sf.net/p/openocd/code openocd
cd openocd
./bootstrap
./configure --enable-stlink
make -j$(nproc)
sudo make install

Важно: для работы с ST-Link v3 добавьте флаг --enable-stlink при конфигурации.

2.3. st-flash (Linux/Windows)

Утилита из проекта texane/stlink устанавливается через pip или из исходников:

# Через pip (рекомендуется)
pip install stlink

# Или сборка из исходников
git clone https://github.com/texane/stlink.git
cd stlink
make release
sudo make install

После установки проверьте обнаружение отладчика:

st-info --probe
# Пример вывода:
Found 1 stlink programmers
version:    V3J9M3
serial:     066EFF555051848687234512
flash:      2048 KiB
sram:       192 KiB
chipid:     0x0413 (STM32F103C8)

3. Основные команды для прошивки

Разберём базовые команды для каждой утилиты, а также нюансы их использования. Все примеры приведены для микроконтроллера STM32F407G-DISC1 (отладочная плата Discovery).

3.1. STM32CubeProgrammer

Утилита поддерживает два режима работы: CLI (командная строка) и GUI. Для автоматизации используем CLI:

• 📌 Подключение к устройству:

  STM32_Programmer_CLI -c port=SWD -c connect

• 📤 Прошивка файла (например, firmware.hex):

  STM32_Programmer_CLI -c port=SWD -c connect -w "firmware.hex" 0x08000000 -v -r

  Флаги:
  • -w — запись файла по адресу 0x08000000 (начало Flash).
  • -v — верификация после записи.
  • -r — сброс микроконтроллера после прошивки.
• 🔍 Чтение памяти (например, первых 256 байт Flash):

  STM32_Programmer_CLI -c port=SWD -c connect -r32 0x08000000 0x100 -d "dump.bin"

3.2. OpenOCD

OpenOCD требует конфигурационного файла (.cfg) для работы с STM32. Пример для ST-Link v2:

# stm32f4_discovery.cfg
source [find interface/stlink-v2.cfg]
source [find target/stm32f4x.cfg]
reset_config srst_only

Основные команды:

• 🔌 Запуск сервера:

  openocd -f stm32f4_discovery.cfg

• 📤 Прошивка через Telnet (в другом терминале):

  telnet localhost 4444
  > reset halt
  > flash write_image erase firmware.bin 0x08000000
  > reset run
  > exit

3.3. st-flash

Самый простой синтаксис среди всех утилит:

# Прошивка файла .bin
st-flash write firmware.bin 0x08000000

# Чтение Flash в файл
st-flash read dump.bin 0x08000000 0x10000

# Стирание всего чипа
st-flash erase

Нюанс: st-flash не поддерживает формат .hex — только .bin. Для конвертации используйте objcopy:

arm-none-eabi-objcopy -O binary firmware.elf firmware.bin

Убедитесь, что ST-Link обнаружен (st-info --probe)|Проверьте формат файла (для st-flash только .bin)|Отключите защиту Flash (если есть) через STM32_Programmer_CLI -c ob rdp=0|Сохраните резервную копию текущей прошивки-->

4. Типичные ошибки и их решения

Даже опытные разработчики сталкиваются с ошибками при прошивке через CLI. Разберём самые частые и неочевидные способы их решения.

4.1. "Cannot connect to target" / "No ST-Link detected"

Причины и решения:

• 🔌 Отсутствует питание на плате. Проверьте 3.3V или 5V на контактах STM32.
• 🖥️ Конфликт драйверов (актуально для Windows). Удалите старые драйвера ST-Link через Диспетчер устройств и установите последние с сайта ST.
• 🐧 Права доступа в Linux. Добавьте правило для udev:

  echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="0666"' | sudo tee /etc/udev/rules.d/99-stlink.rules
  sudo udevadm control --reload-rules

4.2. "Error: failed to erase memory"

Ошибка возникает при:

• 🔒 Включённой защите Flash. Снимите защиту командой:

  STM32_Programmer_CLI -c port=SWD -c connect -c ob rdp=0

• ⚡ Нестабильном питании. Подключите внешний источник 5V/2A.
• 🕳️ Повреждённых секторах Flash. Попробуйте прошить другой файл или используйте --force в st-flash.

⚠️ Внимание: если после снятия защиты (ob rdp=0) микроконтроллер перестал отвечать, это означает, что ранее был установлен уровень защиты RDP2 (необратимое стирание Flash). Восстановить данные невозможно — требуется полная перепрошивка через bootloader.

4.3. "Verification failed" после прошивки

Проблема чаще всего связана с:

• 📡 Неправильной скоростью SWD. Уменьшите частоту:

  STM32_Programmer_CLI -c port=SWD -c freq=4000 -c connect -w firmware.hex 0x08000000

• 🔄 Конфликтом версий прошивки и конфигурации. Проверьте, что адрес загрузки (0x08000000) совпадает с вектором сброса в .hex-файле.

5. Оптимизация скорости прошивки

Скорость прошивки через CLI можно увеличить в 2–3 раза, правильно настроив параметры. Разберём ключевые оптимизации.

5.1. Выбор протокола и частоты

Протокол SWD обычно быстрее JTAG, но для STM32H7 или STM32F7 разница минимальна. Оптимальные частоты:

• 📈 ST-Link v2: до 4 MHz (по умолчанию 1.8 MHz).
• 📈 ST-Link v3: до 24 MHz (но стабильно работает до 12 MHz).

Пример для STM32CubeProgrammer:

STM32_Programmer_CLI -c port=SWD -c freq=12000 -c connect -w firmware.hex 0x08000000

5.2. Параллельное стирание и запись

STM32CubeProgrammer поддерживает флаг --multi для параллельного стирания и записи секторов. Это ускоряет процесс на 20–30%:

STM32_Programmer_CLI -c port=SWD -c connect --multi -w firmware.hex 0x08000000

5.3. Использование буфера

OpenOCD позволяет настроить размер буфера для передачи данных. Добавьте в конфиг (.cfg):

adapter driver stlink
stlink_usb_vid_pid 0x0483 0x3748
adapter speed 4000
adapter swd
transport select swd
stlink flash_bank stm32f4x 0x08000000 0x100000 0 0 0

Результат: прошивка 1 МБ занимает ~10 секунд вместо ~25 при дефолтных настройках.

6. Автоматизация прошивки: скрипты и CI/CD

CLI-утилиты идеально подходят для автоматизации — от прошивки партии устройств до интеграции в GitHub Actions или Jenkins.

6.1. Bash-скрипт для массовой прошивки

Пример скрипта для прошивки 10 плат подряд с проверкой:

#!/bin/bash
FIRMWARE="firmware.hex"
LOG_FILE="flash_log.txt"

for i in {1..10}; do
echo "Прошивка устройства #$i..." | tee -a $LOG_FILE
STM32_Programmer_CLI -c port=SWD -c connect -w $FIRMWARE 0x08000000 -v >> $LOG_FILE 2>&1

if [ $? -eq 0 ]; then
echo "Успешно! Сброс..." | tee -a $LOG_FILE
STM32_Programmer_CLI -c port=SWD -c connect -c reset
else
echo "ОШИБКА! Проверьте подключение." | tee -a $LOG_FILE
exit 1
fi
done

6.2. Интеграция с GitHub Actions

Пример workflow для автоматической прошивки при пуше в репозиторий:

name: STM32 Flash CI

on: [push]

jobs:
build-and-flash:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Установка STM32CubeProgrammer
run: |
wget https://www.st.com/content/ccc/resource/technical/software/sw_development_suite/group0/5a/6a/9f/6d/55/1e/47/94/stm32cubeprog_v2-15-0_linux.zip/jcr:content/translations/en.stm32cubeprog_v2-15-0_linux.zip
unzip stm32cubeprog*.zip
sudo ./SetupSTM32CubeProgrammer-2.15.0.linux --headless
- name: Сборка прошивки
run: make
- name: Прошивка
run: STM32_Programmer_CLI -c port=SWD -c connect -w firmware.hex 0x08000000 -v

Преимущество: каждый коммит автоматически прошивается на тестовую плату, что исключает регрессии.

7. Восстановление "кирпичей" через CLI

Если STM32 перестал отвечать на SWD/JTAG (например, из-за неверной прошивки или включённого RDP2), его можно восстановить через встроенный bootloader по UART или USB DFU.

7.1. Восстановление через UART

Потребуется: STM32CubeProgrammer, USB-UART адаптер (например, FT232) и правильное подключение:

• 🔌 Подключите PA9 (TX) и PA10 (RX) к адаптеру.
• 🔄 Замкните BOOT0 на 3.3V и сбросьте плату.
• 📤 Запустите прошивку:

  STM32_Programmer_CLI -c port=UART -c connect -w firmware.hex 0x08000000 -v

7.2. Восстановление через USB DFU

Если ваш STM32 поддерживает USB DFU (например, STM32F103 или STM32F4), используйте:

# Перевод в режим DFU (BOOT0=1, сброс)
dfu-util -a 0 -D firmware.bin --dfuse-address 0x08000000:leave

⚠️ Внимание: если был активирован уровень защиты RDP2 (необратимое стирание), восстановление данных невозможно. Единственный выход — полная перепрошивка через bootloader с потерей всех данных во Flash.

8. Продвинутые техники: отладка и работа с памятью

CLI-утилиты позволяют не только прошивать, но и отлаживать STM32 на низком уровне — от чтения регистров до дампа памяти.

8.1. Чтение и запись памяти через OpenOCD

Примеры команд для отладки:

# Чтение регистра PC (Program Counter)
telnet localhost 4444
> reg pc
pc (/32): 0x08001A4C

# Запись в память (например, изменение переменной по адресу 0x20000000)
> mww 0x20000000 0xDEADBEEF

# Дамп памяти
> dump_image dump.bin 0x08000000 0x1000

8.2. Работа с Option Bytes

Option Bytes в STM32 управляют защитой, тактированием и другими критичными параметрами. Пример чтения и записи через STM32CubeProgrammer:

# Чтение Option Bytes
STM32_Programmer_CLI -c port=SWD -c connect -ob read

# Разблокировка защиты (RDP=0)
STM32_Programmer_CLI -c port=SWD -c connect -ob rdp=0

# Настройка уровня защиты (RDP=1)
STM32_Programmer_CLI -c port=SWD -c connect -ob rdp=1

Предупреждение: установка RDP=2 (полная блокировка) необратимо стирает Flash и делает восстановление данных невозможным.

FAQ: Частые вопросы по STM32 Programmer CLI

st-flash --reset write firmware.bin 0x08000000