Desbravando todo o potencial do STM32CubeProgrammer

Saudações! Se você está aqui, é provável que já tenha se familiarizado com o universo dos microcontroladores da STMicroelectronics, especialmente com a renomada série STM32. Então pegue o seu café e se conforte na cadeira que hoje vou te apresentar uma poderosa ferramenta de programação de microcontroladores desenvolvida pela ST, o STM32CubeProgrammer.

Neste artigo, cobrirei o essencial para que você possa utilizar a CLI (Interface de Linha de Comando, do inglês, Command Line Interface) da ferramenta. Essa interface expande as possibilidades para a programação dos microcontroladores, abrindo espaço para a criatividade e automação dos processos de gravação dos dispositivos. Além disso, mostrarei como desenvolver scripts de gravação, uma integração com a linguagem Python e com o renomado Visual Studio Code.

Todo o conteúdo apresentado neste artigo foi elaborado com base na documentação da ferramenta, disponibilizada pela empresa desenvolvedora. Sendo assim, para informações ou detalhes adicionais, confira o seguinte manual do usuário: STM32CubeProgrammer software description – User manual

Esta é uma ferramenta gratuita que pode ser baixada diretamente do site do fabricante-desenvolvedor, por meio do seguinte link: STM32CubeProg – STM32CubeProgrammer software for all STM32 – STMicroelectronics

NOTA: Para utilizar a interface de linha de comando da ferramenta, é necessário ter instalado no seu computador o STM32CubeProgrammer ou o STM32CubeIDE (que inclui uma instância do STM32CubeProgrammer que pode ser utilizada).

O que é o ST32CubeProgrammer

Conforme mencionado anteriormente, o STM32CubeProgrammer é um conjunto de ferramentas desenvolvidas especificamente para a programação dos Microcontroladores da linha de 32 bits da ST, o STM32. Este software oferece um método simples e intuitivo para realizar a programação das memórias internas ao microcontrolador, tais como Flash, RAM e OTP, bem como das memórias externas, como EEPROM, Flash e RAM externas.  

O acesso das memórias externas é efetuado por meio do uso dos external loaders, que são ferramentas poderosas que podem ser desenvolvidas para otimizar o processo de gravação. Sendo muito úteis nas etapas de programação e montage.
Para viabilizar todas essas funcionalidades, o microcontrolador pode ser acessado tanto pelas interfaces de depuração JTAG e SWD quanto pelas interfaces disponíveis no bootloader¹ (como UART, USB DFU, I²C, SPI e CAN).
As ferramentas são disponibilizadas em dois formatos: GUI, uma interface de usuário gráfica e intuitiva; e CLI, uma interface de linha de comandos que oferece ao usuário maior flexibilidade durante a utilização da ferramenta.

¹ A programação e leitura de memórias externas estão restritas às interfaces de debug e bootloaders customizados ou proprietários. Portanto, não é viável acessá-las pelo bootloader interno de fábrica presente na memória do microcontrolador.

Primeiros passos com o CLI

Antes de darmos início a utilização da ferramenta, é importante mencionar que todos os comandos estão listados no manual de usuário (apresentado no início do artigo) e também podem ser acessados ao iniciar a ferramenta sem nenhum parâmetro, como demonstrado a seguir.

Para iniciar a utilização da interface de linha de comando (CLI) do STM32CubeProgrammer, comece abrindo o seu terminal preferido e navegue até a pasta “bin” no diretório onde o software foi instalado. No caso do Windows, o software é geralmente instalado na seguinte pasta por padrão:

Se você possui apenas o STM32CubeIDE instalado em seu computador, é possível utilizar o STM32CubeProgrammer através do seguinte caminho:

Tomando como base o terminal de comandos do Windows, para navegar até a pasta bin, é necessário aplicar o seguinte comando:

Ao entrar na pasta do programador, insira o comando STM32_Programmer_CLI para invocar a ferramenta. Isso permitirá que você verifique se está na pasta correta, bem como a versão do STM32CubeProgrammer, juntamente com os comandos disponíveis para uso com a ferramenta.

O STM32_Programmer_CLI serve como a base para as chamadas do CLI. Acompanhando esse comando, você deve fornecer as instruções e parâmetros necessários, de acordo com o processo que deseja executar. Continue lendo este artigo, pois apresentaremos a seguir os comandos mais comuns, suas sintaxes e exemplos de aplicação.

Conexão com o Microcontrolador:

Para estabelecer a conexão com o microcontrolador, você utilizará o comando connect. Esse comando inclui vários parâmetros que variam conforme o tipo de conexão desejada (SWD, UART, SPI, etc.). Portanto, é importante consultar o manual do STM32CubeProgrammer para obter mais detalhes sobre esses parâmetros.

A sintaxe base deste comando é apresentada a seguir:

O atributo do parâmetro port é selecionado de acordo com o tipo de comunicação, por exemplo, COMx (para VCOM no Windows), /dev/ttySx (para VCOM no Linux), USBx (interface usb), SWD, SPI, I2C e CAN. Veja o exemplo a seguir para abertura de uma comunicação via SWD:

Leitura de dados

A fim de ler os valores de endereços específicos de alguma memória do microcontrolador, utiliza-se o comando read. A sintaxe deste comando é apresentada a seguir:

O comando realizará a leitura em blocos de 32 bits, começando a partir de um endereço inicial (start_address) pelo tamanho especificado (size).

Aqui está um exemplo de como utilizar este comando. Lembre-se de que, antes de executar o comando de leitura, é necessário estabelecer a conexão com o microcontrolador usando o comando de conexão. 

Extração da memória para um arquivo

Utilizando o CLI, é possível extrair o conteúdo da memória do microcontrolador e exportar para um arquivo .bin. Para realizar este processo, o comando upload é utilizado. A sua sintaxe é dada da seguinte forma:

Aqui está um exemplo de como usar este comando, juntamente com o resultado correspondente. Todos os exemplos apresentados a partir deste ponto serão executados na Placa Franzininho C0, utilizando conexões através da Virtual COM:

Escrita na memória

Neste tópico é apresentado o comando write, ele pode ser utilizado para gravar dados no formato 32 ou 64 bits, conforme a sintaxe abaixo:

É fundamental lembrar que, antes de escrever na memória flash, o setor/página que você pretende escrever deve ser previamente apagado. Caso contrário, ao tentar executar o comando de escrita, ocorrerá um erro.

Quando você precisa gravar vários pacotes de dados sequenciais, basta inseri-los no comando, conforme o exemplo a seguir:

Executando o comando acima, serão escritos os valores 0x12345678 0xAABBCCFF 0x12AB34CD na memória FLASH a partir do endereço 0x08000000.

A seguir é apresentado um exemplo de utilização deste comando para a gravação de um pacote de 32 bits no endereço inicial da memória FLASH (0x08000000) do microcontrolador. 

Apagamento de setores da memória:

Para apagar setores da memória, o comando erase é utilizado. Sua sintaxe é apresentada a seguir:

Como mencionado anteriormente, este comando pode ser utilizado de duas maneiras. Na primeira, você especifica os setores de memória que deseja apagar. Veja o exemplo a seguir, que demonstra o apagamento dos setores 0, 2 e 7 da memória.

A segunda forma de utilizar o comando, é especificando um intervalo de setores a serem apagados. No exemplo a seguir, os setores 0º ao 3º setor (setores 0, 1, 2 e 3) serão apagados.

Apagamento total da memória:

Para executar um apagamento completo da memória (mass erase), também é necessário usar o comando erase. No entanto, nesse caso, é feita uma alteração no parâmetro dos setores que serão apagados:

Veja um exemplo a seguir da utilização deste comando:

Gravação um firmware na memória

Para gravar uma imagem (arquivo binário) na memória, utilize o comando download. Sua sintaxe é a seguinte:

O primeiro parâmetro deste comando deve indicar o diretório no qual o arquivo binário está armazenado em seu computador. O segundo parâmetro, por sua vez, deve fazer referência ao endereço inicial para a gravação da imagem, uma vez que os arquivos binários não contêm informações de endereço de gravação. Confira o exemplo a seguir:

Leitura dos Option Bytes

Para realizar a leitura dos Option Bytes do microcontrolador o seguinte comando pode ser utilizado:

Este comando efetua a leitura dos valores de todos os Option Bytes disponíveis no microcontrolador e os apresenta em forma de lista. Veja o exemplo a seguir para ver a execução deste comando:

Escrita dos Option Bytes

Além da leitura dos valores dos Option Bytes, também é possível alterá-los. Para isso o seguinte comando é utilizado:

Veja a seguir um exemplo de utilização deste comando para a alteração do valor de RDP para 0x11:

Adicionando a CLI às variáveis de ambiente do windows

Conforme apresentado no tópico anterior, é necessário navegar até a pasta de instalação da ferramenta para utilizá-la. No entanto, podemos otimizar esse procedimento ao eliminando este passo do processo.
Uma abordagem para isso envolve adicionar o caminho do diretório onde o STM32_Programmer_CLI está localizado às variáveis de ambiente do Windows. Dessa maneira, a ferramenta pode ser chamada de qualquer local, pois o sistema operacional será capaz de localizá-la automaticamente
Para adicionar o caminho nas variáveis de ambiente, abra o menu iniciar e pesquise por “environment variables” (ou variáveis de ambiente, caso o seu sistema operacional esteja em português).

Na janela aberta, abra o menu “Environment Variables…”.

No menu aberto, adicione o caminho da pasta “bin” no conjunto de variáveis “Path”:

Após concluir esses passos, você poderá usar a CLI sem a necessidade de navegar até a pasta de instalação da ferramenta, conforme apresentado na Figura 15.

Criação de scripts de gravação

Em muitos processos de gravação, frequentemente é necessário executar uma série de comandos de maneira repetitiva. Nessas situações, é possível construir um script contendo todas as instruções e comandos essenciais para o processo de gravação. 

A grande vantagem de usar o script está na capacidade de empregar operações matemáticas (soma, subtração, e etc.), operações lógicas (lógica AND, lógica XOR, bitwise OR, e etc.), macros (Write(…), Read(…), Display(…) e Delay(…)), variáveis, estruturas de decisão e loops. 

Nos tópicos a seguir, exploraremos esses recursos, juntamente com a sua sintaxe,e também fornecerei alguns exemplos de aplicação. Isso demonstrará como construir um arquivo com as instruções necessárias para implementar um processo de gravação mais complexo.

Macros

O STM32CubeProgrammer CLI inclui um conjunto de cinco grupos de macros que podem ser empregadas para a construção dos scripts. Cada macro deve ser precedida pelo símbolo ‘ # ’ seguido pelo nome da macro.

O primeiro grupo abrange as macros de escrita, as quais permitem gravar um valor específico de 8/16/32 bits em uma memória do dispositivo conectado. A sintaxe para utilização é a seguinte:

A segunda macro efetua a leitura das memórias do microcontrolador. Essa macro é restrita a ler um conteúdo de 32 bits e possui a seguinte sintaxe:

A terceira macro é empregada para escrever mensagens, dados, mensagens de erro e o conteúdo de variáveis presentes no script. A sintaxe dessa macro é a seguinte:

A quarta macro permite que o usuário coloque o sistema em standby por um período definido em milissegundos, com a seguinte sintaxe:

E finalmente, a quinta macro possibilita ao usuário desconectar da placa, permitindo posterior reconexão na mesma placa ou em outra, tudo dentro do mesmo script. A sintaxe para essa macro é a seguinte:

É válido ressaltar que também é possível incluir comentários no script, utilizando a seguinte sintaxe:

Variáveis

A ferramenta permite a criação de variáveis para o armazenamento de dados durante a execução do script. Essas variáveis podem ser utilizadas em conjunto com as macros, em operações lógicas e matemáticas, em estruturas de decisão e em laços de repetição. A sintaxe para utilizar esse recurso é apresentada a seguir:

Aqui vão alguns exemplos de utilização de variável com as macros:

Mais exemplos envolvendo variáveis serão fornecidos mais adiante, juntamente com a exploração dos demais recursos disponíveis.

Operações matemáticas

Como já apresentado anteriormente, é possível realizar algumas operações matemáticas nos scripts. As operações permitidas incluem adição (+), subtração (-), multiplicação (*) e divisão (/). E seguem a sintaxe abaixo:

Um exemplo de operação matemática é apresentado a seguir:

Operações lógicas

Além das operações matemáticas, é possível efetuar operações lógicas. As operações aceitas incluem “e” lógico (AND), “ou” lógico (OR), bitwise “e” (&), bitwise “ou” (|) “ou exclusivo” (XOR) e deslocamento à direita e à esquerda (shift left e shift right, << >>). A sintaxe dessas operações é semelhante à das operações matemáticas:

E seguem alguns exemplos:

Estruturas de decisão

Para complementar, é possível utilizar a estrutura if-else para a tomada de decisões dentro do script. A sintaxe dessa estrutura é exibida a seguir:

Um exemplo de aplicação:

Laços de repetição

Por fim, as últimas estruturas aceitas pelo script são os laços de repetição. Entre os laços disponíveis, você pode utilizar o while e o for, da seguinte maneira:

While:

For:

Exemplo de utilização do laço While:

Exemplo de utilização do laço for:

Criação do arquivo e chamada no CLI

Agora que você está familiarizado com os principais comandos do CLI (conforme apresentado no tópico 3) e os recursos disponíveis para a criação de um script (conforme apresentado no tópico 4), já é possível criar o arquivo de script a ser executado pelo STM32CubeProgrammer.

Para isso, abra o seu editor de texto preferido, construa o script desejado e salve o arquivo com a extensão .PRG. Depois disso, você pode executá-lo a partir de um terminal com o seguinte comando:

Lembre-se de modificar o parâmetro “myScript.prg” para o caminho onde você salvou o seu script.

Para uma execução mais ágil, você pode criar um arquivo .bat, contendo o seguinte código:

Dessa forma, você estará criando um arquivo executável que permitirá a chamada do seu script, eliminando a necessidade de usar o terminal para sua execução. Essa abordagem possibilitará a execução de várias linhas de comando com apenas dois cliques no arquivo executável!

Integração com VScode

Há várias maneiras de integrar o STM32CubeProgrammer CLI com o VSCode. Você pode usar os recursos apresentados até o momento de várias maneiras para executar uma rotina de programação diretamente do VSCode. No entanto, neste tópico, vamos focar em demonstrar como invocar os comandos por meio do Python no VSCode.

A partir deste ponto, pressupõe-se que você já esteja familiarizado com a importação de um projeto STM32 no VSCode, utilizando a extensão desenvolvida pela STMicroelectronics.

Na época em que este artigo foi escrito, a mencionada extensão possuía uma limitação quanto à gravação de microcontroladores. Essa limitação restringe a gravação do microcontrolador somente à abertura de uma sessão de depuração por meio da conexão SWD. No entanto, com o recurso a ser apresentado neste tópico, você será capaz de programar seu dispositivo por meio de qualquer interface de programação. Adicionalmente, será possível incorporar diversas outras etapas ao processo de programação, utilizando os recursos discutidos neste artigo.

Para começar, após ter importado um projeto no VSCode, crie um arquivo com a extensão .py na mesma pasta do seu projeto. Isso será utilizado para criar um script em Python.

Você pode utilizar o seguinte script em Python para executar a gravação do seu código por meio do VSCode. Será necessário apenas ajustar os parâmetros dentro da seção USER SETTINGS, de acordo com as especificações do seu projeto. Sinta-se à vontade para personalizar o script conforme suas necessidades:

Após salvar o script em Python, execute-o pelo VSCode e veja o resultado!

Programando a Franzininho C0 pelo VSCode

Dado que a placa Franzininho C0 não inclui um gravador ST-LINK, ela utiliza o bootloader interno do microcontrolador para a programação. Por consequência, a extensão da ST para o VSCode não suportará a programação dessa placa. Como discutido previamente, a criação de um script Python torna-se uma solução prática para realizar essa tarefa.

Para prosseguir, basta seguir os passos apresentados no tópico anterior para criar um arquivo em Python preenchido com o script fornecido, com uma alteração importante. Originalmente, o script foi elaborado para estabelecer uma conexão via SWD com o alvo a ser programado. No entanto, a Franzininho C0 estabelece uma conexão via UART com o computador. Por esse motivo, é essencial modificar o parâmetro “connection_string” no script, a fim de estabelecer a conexão via UART.

Alteração da string para conexão via UART:

Lembre-se de atualizar o número da porta conforme a porta aberta em seu computador.

Após ajustar o script, conecte a Franzininho C0 em seu computador via USB e a coloque em modo de gravação via bootloader. Após esta etapa, clique em build no VSCode e, em seguida, execute o arquivo Python.

Com isso, concluímos o nosso artigo sobre a interface de linha de comando do STM32CubeProgrammer. Espero sinceramente que este conteúdo tenha enriquecido seu conhecimento no campo de sistemas embarcados e que ele se revele valioso em seus projetos atuais e futuros envolvendo a família STM32.

Desejo a você sucesso e realização em suas empreitadas com STM32.

Referências

Aqui vai alguns links de materiais e referências que foram utilizados para a composição deste artigo e que também trazem mais informações acerca dos assuntos tratados neste documento.

STM32CubeProgrammer software description – User manual

STM32CubeProg – STM32CubeProgrammer software for all STM32 

STMicroelectronics provides full STM32 support for Microsoft Visual Studio Code 

Placa Franzininho C0 | Franzininho