Objetivo da Seção

Apresentar uma visão geral do papel do Linker no processo de construção de firmware, destacando:

• O que é o Linker e qual sua função;
• Como ele é usado para posicionar variáveis e trechos de código em regiões específicas da memória;
• A diferença entre seu uso em plataformas STM32 e ESP32;
• A importância dos arquivos .ld e partitions.csv no projeto embarcado.

Conceito Básico

Durante a compilação, o código-fonte (em C ou C++) é transformado em arquivos objeto .o. O Linker pega esses arquivos e os combina, resolvendo endereços de funções, referências cruzadas entre variáveis globais e posicionando tudo de acordo com o layout de memória definido pelo script .ld. Esse script age como um mapa da memória, especificando as regiões onde devem ser colocados:

• Código (.text);
• Dados inicializados (.data);
• Dados não inicializados (.bss);
• Pilha e heap;
• Tabelas de vetores de interrupção e memória de inicialização.

Plataformas em Destaque

• STM32: Usa arquivos .ld customizados que refletem a memória RAM e Flash, com seções bem definidas para bootloaders, vetores de interrupção, código principal, etc.
• ESP32: Usa também arquivos .ld, mas sua complexidade aumenta com a presença de múltiplas CPUs, caches e particionamento de memória Flash definido pelo partitions.csv.

Estrutura de um Arquivo LD: seções e símbolos

O script do Linker, geralmente com extensão .ld, descreve como o firmware será disposto na memória do dispositivo. Ele segue a sintaxe da linguagem de scripts do GNU Linker (ld) e define regiões de memória física e a atribuição de seções do programa nessas regiões. Essa estrutura garante que o código e os dados sejam colocados em áreas apropriadas da RAM e Flash.

Definindo a Memória

No início do arquivo .ld, define-se o layout físico da memória com a diretiva MEMORY. Essa seção especifica os nomes, tamanhos e endereços base da RAM, Flash e outras regiões, como SRAM2 ou CCM no STM32, ou RTC_SLOW na RAM do ESP32.

Exemplo – STM32:

MEMORY
{
  FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 512K
  RAM (xrw)  : ORIGIN = 0x20000000, LENGTH = 128K
}

Exemplo – ESP32:

MEMORY
{
  iram0_0_seg (RX) : org = 0x40080000, len = 0x20000
  dram0_0_seg (RW) : org = 0x3FFAE000, len = 0x20000
}

Seções Padrão

A diretiva SECTIONS define como as seções do código objeto (geradas pelo compilador) são mapeadas nas regiões de memória definidas anteriormente.

Principais seções:

• .isr_vector: Vetor de interrupções (normalmente colocado no início da Flash).
• .text: Código do programa.
• .rodata: Dados somente leitura (constantes).
• .data: Dados inicializados na RAM.
• .bss: Variáveis globais não inicializadas (zeradas na inicialização).
• .heap / .stack: Reservas para alocação dinâmica e pilha de execução.

Trecho típico:

SECTIONS
{
  .text :
  {
    KEEP(*(.isr_vector))
    *(.text*)
    *(.rodata*)
  } > FLASH

  .data : AT (ADDR(.text) + SIZEOF(.text))
  {
    *(.data*)
  } > RAM

  .bss :
  {
    *(.bss*)
    *(COMMON)
  } > RAM
}

Símbolos Especiais

Os scripts .ld frequentemente definem símbolos que serão usados no código C para indicar, por exemplo, o início e fim da RAM, do stack, ou a posição de carga de dados:

_end = .;
_estack = ORIGIN(RAM) + LENGTH(RAM);

No código C, podem ser declarados como:

extern uint32_t _estack;
extern uint32_t _end;

Observações Importantes

• A ordem das seções é essencial: o que estiver listado primeiro será posicionado primeiro na memória.
• A diretiva KEEP() impede que o Linker remova seções não referenciadas, comum em vetores de interrupção.
• A diretiva AT() é usada para indicar onde os dados residem na Flash antes de serem copiados para a RAM.

Diferenças entre os arquivos LD no STM32 e no ESP32

Embora tanto o STM32 quanto o ESP32 utilizem scripts .ld para definir o mapeamento de memória, existem diferenças estruturais e conceituais importantes entre essas plataformas. Essas diferenças são motivadas pelas arquiteturas distintas de hardware, modelos de inicialização e tipos de memória disponíveis.

STM32 – Arquitetura Simples e Direta

O STM32, baseado na arquitetura ARM Cortex-M, segue uma abordagem linear e previsível no mapeamento de memória. A memória Flash normalmente começa em 0x08000000, e a RAM em 0x20000000. A posição do vetor de interrupções (reset vector) é crucial, pois a CPU começa a executar a partir desse ponto após o reset.

Características:

• O arquivo .ld do STM32 é quase sempre dividido em FLASH e RAM;
• Contém o vetor de interrupções na primeira posição (.isr_vector);
• Define símbolos como _estack para controle da pilha;
• Permite personalizações simples para bootloaders ou seções específicas de RAM (como DTCM, SRAM2, CCMRAM, etc.);
• Ferramentas como STM32CubeIDE geram .ld automaticamente com base no modelo selecionado.

Exemplo típico de layout:

MEMORY
{
  FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 512K
  RAM   (xrw) : ORIGIN = 0x20000000, LENGTH = 128K
}

ESP32 – Arquitetura Multinível e Particionada

O ESP32 é mais complexo: possui múltiplos tipos de RAM (DRAM, IRAM, RTC RAM), cache externa e bootloader configurável. A memória Flash é externa e compartilhada entre o bootloader, partições de aplicativo, sistema de arquivos (SPIFFS/FFat) e NVS (armazenamento não-volátil).

Características:

• Utiliza vários arquivos .ld para diferentes segmentos (esp32.ld, memory.ld, sections.ld, etc.);
• Define múltiplas regiões: iram0, dram0, rtc_slow, rtc_fast, etc.;
• Utiliza a diretiva INCLUDE para modularizar o layout;
• Integra o conceito de partições, definidas no arquivo partitions.csv;
• O bootloader da Espressif localiza a partição de aplicação na Flash e carrega o código para a IRAM ou executa diretamente da Flash (via cache).

Trecho exemplo de esp32.ld:

MEMORY
{
  iram0_0_seg : org = 0x40080000, len = 0x20000
  dram0_0_seg : org = 0x3FFAE000, len = 0x20000
  rtc_slow_seg : org = 0x50000000, len = 0x2000
}

Principais Diferenças Resumidas

Entendendo o partitions.csv no ESP32

Resumo

O arquivo partitions.csv é um componente essencial nos projetos com ESP32. Ele define como a memória Flash externa será particionada para armazenar diferentes partes do firmware, como o bootloader, a aplicação principal, o sistema de arquivos (SPIFFS, FATFS, LittleFS), armazenamento de chaves criptográficas, dados de calibragem de RF, entre outros. É o que garante que o firmware saiba onde cada bloco de dados deve ser gravado e lido na memória externa.

O que é o partitions.csv?

É um arquivo de texto, em formato CSV (Comma-Separated Values), que define as partições da Flash para uso pelo bootloader e sistema operacional (no caso do ESP-IDF). Ele é convertido em um binário de tabela de partições que o bootloader carrega durante a inicialização.

Formato do Arquivo

Cada linha do partitions.csv define uma partição com os seguintes campos:

nome, tipo, subtipo, endereço, tamanho, flags

Exemplo comum:

# Nome      Tipo     Subtipo  Endereço   Tamanho    Flags
nvs         data     nvs      0x9000     0x5000
otadata     data     ota      0xe000     0x2000
app0        app      ota_0    0x10000    1M
app1        app      ota_1    0x110000   1M
spiffs      data     spiffs   0x210000   0xF0000

Campos Explicados

• nome: Identificador da partição (pode ser usado no código C, por exemplo para montar SPIFFS).
• tipo:
  • app: usado para partições de firmware.
  • data: para armazenamento persistente (ex: NVS, SPIFFS).
• subtipo:
  • factory, ota_0, ota_1: partições de aplicação.
  • nvs, spiffs, fat, ota, etc.: tipos específicos de dados.
• endereço: onde na memória Flash essa partição começa (em hexadecimal).
• tamanho: em bytes ou usando sufixos (K, M).
• flags: parâmetros opcionais (ex: encrypted para criptografia).

Como o partitions.csv é usado

1. Durante a compilação, o arquivo é processado e gera um binário chamado partition_table.bin.
2. Durante a gravação (flash), esse binário é gravado em um endereço fixo (tipicamente 0x8000).
3. Durante o boot, o bootloader do ESP32 lê essa tabela para saber onde está cada partição.
4. No código, você pode montar sistemas de arquivos ou acessar partições diretamente com base nos nomes definidos no CSV.

Customização

Você pode modificar o partitions.csv para incluir, por exemplo:

• Mais partições OTA para atualizações em lote;
• Uma partição para armazenamento FAT montado via esp_vfs_fat_mount;
• Uma partição para arquivos estáticos com LittleFS;
• Tamanhos reduzidos para aplicações mínimas.

Exemplo com FAT:

storage     data     fat      0x300000   512K

Estratégias de Construção de Arquivos LD: práticas e ferramentas

Resumo

A criação e manutenção de arquivos .ld pode ser feita manualmente ou gerenciada por ferramentas automáticas. Em sistemas embarcados, a escolha da estratégia depende da complexidade da aplicação, do ambiente de desenvolvimento e da necessidade de controle sobre o uso da memória. Nesta seção, exploramos como construir e adaptar arquivos de Linker para STM32 e ESP32, além das ferramentas que auxiliam no processo.

Construção Manual de Arquivos .ld

A escrita manual é útil em projetos onde se deseja controle total sobre a organização de memória — especialmente para bootloaders, realocação de código crítico em RAM, ou para usar áreas especiais como DTCM, CCM ou RTC.

Dicas práticas:

• Sempre comece definindo corretamente as regiões com MEMORY.
• Use SECTIONS para mapear precisamente o conteúdo dos binários.
• Defina símbolos auxiliares (_end, _stack_start) para controle no código C.
• Use KEEP() para evitar que o Linker remova trechos importantes como vetores de interrupção.
• Comente abundantemente o arquivo .ld — erros silenciosos podem causar falhas difíceis de depurar.

Uso de Ferramentas:

Para STM32:

• STM32CubeIDE / STM32CubeMX:
  • Gera automaticamente arquivos .ld com base no modelo do microcontrolador selecionado.
  • Permite configuração de áreas específicas de memória (ex: RAM2, CCMRAM).
  • Reorganiza o linker script ao incluir bibliotecas HAL ou FreeRTOS.
• GNU Arm Toolchain (arm-none-eabi-ld):
  • O script .ld é passado na linha de comando usando -T.
  • Pode ser usado em Makefiles ou CMake para projetos personalizados.

Para ESP32:

• ESP-IDF:
  • Utiliza um conjunto modular de scripts .ld organizados em:
    • memory.ld: define as regiões de memória disponíveis.
    • sections.ld: organiza onde o código e dados são colocados.
    • esp32.ld: script de entrada que inclui os anteriores.
  • Permite criar fragmentos de linker (ld fragments) no diretório do componente para colocar variáveis em regiões específicas, como IRAM.

Exemplo de fragmento:

myvar (noinit) : ALIGN(4)
{
  _myvar_start = .;
  KEEP(*(.myvar_section))
  _myvar_end = .;
} > DRAM

• idf.py linkmap:
  • Gera o mapa de ligação (.map) detalhado, útil para depuração de problemas de alocação de memória.

Boas Práticas

• Sempre gere e revise o mapa de ligação (.map) após compilar. Ele mostra o endereço final de cada seção.
• Valide o tamanho das regiões para evitar sobreposição.
• Em projetos com OTA, certifique-se de que as partições app0/app1 não ultrapassem o tamanho máximo.
• Use ASSERT() no script .ld para verificar restrições em tempo de link:

ASSERT(SIZEOF(.data) < 0x2000, "Data section too big!")

Casos Práticos: Customizando o Linker para necessidades reais

Resumo

Customizar o script de Linker permite criar soluções otimizadas para aplicações embarcadas que demandam desempenho, economia de energia ou acesso rápido à memória. A seguir, são apresentados exemplos reais de customizações em projetos com STM32 e ESP32, incluindo alocação de variáveis em regiões específicas, execução de código diretamente na RAM, buffers persistentes e uso de seções noinit.

Executar código diretamente na RAM (STM32)

Para funções críticas em tempo real — como interrupções com baixa latência — pode ser necessário colocá-las na RAM, onde a execução é mais rápida que na Flash.

Etapas:

1. Criar uma seção .ramfunc no script:

.ramfunc :
{
  *(.ramfunc*)
} > RAM

2. Declarar a função no código com atributo:

__attribute__((section(".ramfunc"))) void critical_ISR(void) {
  // Código de alta prioridade
}

3. (Opcional) Garantir cópia da Flash para RAM durante a inicialização usando AT() e símbolos auxiliares para copiar os dados.

2Criar buffers fixos em local específico da RAM (ESP32 e STM32)

Se você precisa garantir que um buffer de DMA fique em uma região não cacheada da memória (ou alinhada), é possível forçar sua posição.

ESP32 – usando fragmento de linker:

1. Crie um arquivo linker_fragment.ld no componente:

__dma_buffer_start = .;
.dma_buffer (NOLOAD):
{
  . = ALIGN(32);
  KEEP(*(.dma_buffer))
  . = ALIGN(32);
} > DRAM
__dma_buffer_end = .;

2. No código:

__attribute__((section(".dma_buffer"))) uint8_t dma_rx[256];

3. Buffer persistente entre resets (seção .noinit)

A seção .noinit impede que variáveis sejam zeradas na inicialização. Isso é útil para armazenar dados temporários entre resets, watchdogs ou soft reboots.

Script LD:

.noinit (NOLOAD):
{
  *(.noinit*)
} > RAM

Código C:

__attribute__((section(".noinit"))) uint32_t retained_counter;

Importante: você é responsável por inicializar essa variável, pois o C startup não o fará.

4. Espaço reservado para bootloader ou firmware OTA

Em projetos com bootloaders, você pode reservar o início da Flash para ele e mover o início da aplicação:

MEMORY
{
  BOOTLOADER (rx) : ORIGIN = 0x08000000, LENGTH = 16K
  APP_FLASH  (rx) : ORIGIN = 0x08004000, LENGTH = 496K
}

E ajustar o início da seção .text para a nova região APP_FLASH.

5. Dividindo a RAM em blocos com finalidades distintas

No STM32 com RAMs separadas (SRAM1, SRAM2), você pode mover buffers grandes para a RAM auxiliar:

MEMORY
{
  RAM1 (xrw): ORIGIN = 0x20000000, LENGTH = 96K
  RAM2 (xrw): ORIGIN = 0x20018000, LENGTH = 32K
}

.bigbuffers (NOLOAD):
{
  *(.bigbuffer*)
} > RAM2

Esses exemplos ilustram o poder e a flexibilidade dos scripts de Linker quando bem utilizados. Customizá-los pode ser a chave para alcançar desempenho, estabilidade e segurança em sistemas embarcados críticos.

Considerações Finais e Dicas de Diagnóstico

A compreensão e personalização de scripts de Linker são habilidades essenciais para engenheiros de sistemas embarcados. Erros nesse estágio podem resultar em falhas silenciosas, corrupção de dados, mau uso de memória e comportamento imprevisível do firmware. Esta seção final destaca boas práticas, armadilhas comuns e ferramentas úteis para diagnóstico e validação do layout de memória.

Boas Práticas ao Trabalhar com .ld

• Comente extensivamente cada bloco do script para documentar a intenção de uso de cada região.
• Use símbolos nomeados (_start, _end, stack_top) para facilitar o acesso no código C.
• Divida responsabilidades em arquivos menores com INCLUDE (usado amplamente no ESP-IDF).
• Crie seções específicas para dados críticos, buffers, código de interrupção ou dados de boot.
• Teste variações de layout com segurança em projetos de bootloader + aplicação OTA.

Validação com o Arquivo .map

Após a compilação, o GCC gera um arquivo de mapa de ligação (.map), contendo o endereço real de cada símbolo, função e variável alocada.

Dicas para leitura do .map:

• Verifique se há sobreposição entre seções;
• Confirme se buffers grandes foram realmente colocados em RAM auxiliar;
• Localize variáveis em .bss que estão ocupando muito espaço;
• Confirme se a tabela de interrupções foi posicionada corretamente (ex: início da Flash).

Uso de ASSERTs no Linker

Para evitar erros silenciosos, você pode usar ASSERT() no script .ld para impor limites:

ASSERT(SIZEOF(.data) <= 0x2000, "Erro: a seção .data ultrapassou o limite da RAM!")

Isso impede que a compilação gere um firmware que vá ultrapassar o espaço físico disponível.

Ferramentas de Apoio

• objdump (arm-none-eabi-objdump -h): mostra as seções e onde foram colocadas.
• nm (arm-none-eabi-nm): lista símbolos com endereços — útil para variáveis específicas.
• size (arm-none-eabi-size): resume o tamanho das seções .text, .data e .bss.
• idf.py size-components (ESP32): mostra quanto cada componente ocupa na Flash/RAM.
• STM32CubeIDE: gera visualizações gráficas do uso de memória, além de adaptar o linker automaticamente.

Armadilhas Comuns

• Esquecer de alinhar buffers de DMA (pode causar falha silenciosa).
• Colocar código na IRAM sem definir corretamente as seções no ESP32.
• Deixar variáveis grandes na .data (copiadas da Flash para a RAM, consumindo tempo e espaço).
• Não usar NOLOAD em seções como .noinit, resultando em perda de dados após o reset.

Conclusão

Scripts de Linker não são apenas “detalhes técnicos”, mas componentes essenciais que controlam como o firmware funciona na prática. Dominar sua estrutura, lógica e sintaxe permite que você construa sistemas mais rápidos, estáveis e confiáveis — explorando ao máximo o hardware disponível, seja no robusto STM32 ou no versátil ESP32.

The post Introdução ao Linker em Sistemas Embarcados first appeared on MCU & FPGA.

Este artigo explora como utilizar o ESP-Modbus na plataforma ESP-IDF, explicando conceitos-chave e orientando sobre a configuração de comunicação com dispositivos Modbus em suas variantes mais comuns, como Modbus RTU, Modbus ASCII e Modbus TCP/IP.

Visão Geral do Modbus

O protocolo Modbus define regras de comunicação para troca de mensagens entre dispositivos mestre (master) e escravos (slaves) em uma rede. Ele é amplamente adotado em aplicações industriais devido à sua simplicidade e eficiência.

Tipos de Modbus:

1. Modbus RTU (Remote Terminal Unit):
   • Comunicação serial com dados representados em formato binário compacto.
   • Utiliza verificação de erros com checksum (CRC).
   • Requer intervalos de silêncio para enquadrar mensagens, sendo o RS-485 a interface mais utilizada.
2. Modbus ASCII:
   • Dados em formato legível por humanos (ASCII).
   • Inclui checagem de erros com verificação longitudinal (LRC).
   • Mensagens são delimitadas por um caractere : no início e CR/LF no final.
3. Modbus TCP/IP:
   • Adaptação para redes Ethernet utilizando o protocolo TCP/IP.
   • Transmissão via porta padrão 502, sem necessidade de checksum adicional devido à proteção fornecida pelas camadas inferiores do TCP/IP.

Os dados no Modbus são organizados em registros, que podem ser de quatro tipos principais:

• Coils (Saídas discretas): Valores binários para controle de atuadores.
• Discrete Inputs (Entradas discretas): Leituras binárias de sensores.
• Holding Registers: Valores de 16 bits para leitura e escrita.
• Input Registers: Valores de 16 bits apenas para leitura.

A biblioteca ESP-Modbus do ESP32 é baseada na FreeModbus, oferecendo suporte para as implementações RTU, ASCII e TCP/IP, tanto para dispositivos mestre quanto escravo.

Modelo de Mensagem e Mapeamento de Dados

O Modbus é um protocolo baseado em registros que define um modelo de comunicação estruturado, independente do meio físico utilizado para a transmissão de dados. Este modelo organiza as mensagens como transações entre dispositivos mestre e escravo, onde o mestre controla toda a comunicação.

Comunicação Mestre-Escravo

Em uma rede Modbus:

• O mestre envia comandos para os dispositivos escravos.
• Os escravos respondem aos comandos ou permanecem inativos se não forem endereçados.
• Não há comunicação direta entre escravos.

No caso do Modbus TCP/IP, múltiplos mestres podem coexistir na mesma rede, aproveitando a natureza da comunicação IP.

Tipos de Registros no Modbus

Os dispositivos mapeiam seus dados em quatro tipos de registros que representam características físicas, como leituras de sensores ou estados de atuadores. Abaixo, detalhamos esses tipos:

1. Coils (Saídas Discretas):
   • Bits de saída que podem ser controlados pelo mestre.
   • Geralmente usados para ligar/desligar dispositivos como relés.
2. Discrete Inputs (Entradas Discretas):
   • Bits de entrada somente leitura.
   • Utilizados para monitorar estados, como o fechamento de um contato.
3. Holding Registers:
   • Registros de 16 bits que permitem leitura e escrita.
   • Comumente usados para armazenar valores configuráveis, como setpoints de temperatura.
4. Input Registers:
   • Registros de 16 bits somente leitura.
   • Geralmente associados a sensores analógicos que enviam valores convertidos.

Mapeamento de Dados no ESP-Modbus

No ESP-Modbus, cada dispositivo na rede é identificado por um endereço escravo único, configurado em seu manual. O mestre deve conhecer o mapa de registros do dispositivo para acessar os dados corretamente. Esse mapa define:

• O tipo de registro (Coil, Holding, etc.).
• O endereço inicial.
• A quantidade de registros disponíveis.

Este mapeamento é essencial para configurar o Modbus no ESP32 e estabelecer uma comunicação eficiente entre dispositivos.

Inicialização da Porta Modbus

Para iniciar a comunicação Modbus em um ESP32 utilizando o ESP-Modbus, é necessário configurar corretamente a porta de comunicação. O ESP-Modbus suporta tanto comunicação serial (via RTU ou ASCII) quanto TCP/IP. A inicialização correta da porta é o primeiro passo para utilizar as APIs disponíveis.

Configuração de Portas no ESP-Modbus

O ESP-Modbus fornece as seguintes funções para inicializar controladores Modbus, tanto para dispositivos mestre quanto escravo, dependendo do tipo de comunicação:

• Serial (RTU/ASCII):

  • mbc_slave_init(): Inicializa um escravo Modbus em comunicação serial.
  • mbc_master_init(): Inicializa um mestre Modbus em comunicação serial.

• TCP/IP:

  • mbc_slave_init_tcp(): Inicializa um escravo Modbus em comunicação TCP/IP.
  • mbc_master_init_tcp(): Inicializa um mestre Modbus em comunicação TCP/IP.

A escolha da função depende do tipo de dispositivo (mestre ou escravo) e do meio de transmissão (serial ou TCP/IP).

Exemplo de Inicialização

Para inicializar uma porta serial no modo escravo, o seguinte código pode ser usado:

void* slave_handler = NULL;
// Estrutura de interface 
esp_err_t err = mbc_slave_init(MB_PORT_SERIAL_SLAVE, &slave_handler); 
if (slave_handler == NULL || err != ESP_OK) {
  ESP_LOGE(TAG, "Falha na inicialização do controlador Modbus."); 
}

No caso de comunicação TCP/IP, a inicialização segue um padrão similar, mas com a função mbc_slave_init_tcp:

void* slave_handler = NULL;
esp_err_t err = mbc_slave_init_tcp(&slave_handler);

if (slave_handler == NULL || err != ESP_OK) {
    ESP_LOGE(TAG, "Falha na inicialização do controlador Modbus TCP.");
}

Essas funções configuram a estrutura base para a comunicação Modbus e devem ser chamadas antes de qualquer outra operação relacionada ao protocolo.

API Modbus Mestre – Visão Geral

A API do Modbus para dispositivos mestre no ESP32 oferece uma estrutura completa para configurar, acessar e gerenciar a comunicação com dispositivos escravos. Essa API segue uma sequência lógica de passos para configurar a comunicação e realizar transações.

Etapas Principais da Comunicação Mestre

1. Inicialização da Porta Modbus:
   • Configura a interface de comunicação (serial ou TCP/IP) e o controlador mestre.
2. Configuração do Acesso a Dados:
   • Define os parâmetros que o mestre acessará nos dispositivos escravos.
   • Utiliza um mapeamento chamado “Dicionário de Dados”, que associa identificadores únicos (CID) a registros Modbus.
3. Opções de Comunicação:
   • Configura parâmetros específicos, como baud rate (para serial) ou endereços IP (para TCP/IP).
4. Início da Comunicação:
   • Ativa o controlador Modbus, permitindo o envio e recebimento de dados entre mestre e escravos.
5. Finalização:
   • Libera recursos do controlador Modbus ao finalizar a comunicação.

Dicionário de Dados e CID

O ESP-Modbus introduz um nível de abstração acima do protocolo padrão, denominado “Dicionário de Dados”. Cada parâmetro acessível pelo mestre é identificado por:

• CID (Identificador de Característica): Um número único que identifica um parâmetro no dispositivo escravo.
• Nome e Unidades: Uma descrição textual do parâmetro e sua unidade física (como °C para temperatura).
• Tipo de Registro e Endereço: Define o tipo de registro Modbus (Holding, Input, etc.) e seu endereço inicial no dispositivo escravo.

Exemplo de definição de parâmetros no Dicionário de Dados:

mb_parameter_descriptor_t device_parameters[] = {
    { CID_SER_NUM1, "Serial_number_1", "--", MB_DEVICE_ADDR1, MB_PARAM_INPUT, 0, 2, 0, PARAM_TYPE_U32, 4 },
    { CID_TEMP_DATA_1, "Temperature_1", "C", MB_DEVICE_ADDR1, MB_PARAM_HOLDING, 0, 2, 0, PARAM_TYPE_FLOAT, 4 }
};

Neste exemplo:

• O parâmetro CID_SER_NUM1 refere-se ao número de série do dispositivo.
• O parâmetro CID_TEMP_DATA_1 mapeia um registro de temperatura em graus Celsius.

Configuração do Mestre

Após definir o Dicionário de Dados, ele deve ser associado ao controlador Modbus utilizando a função mbc_master_set_descriptor():

ESP_ERROR_CHECK(mbc_master_set_descriptor(&device_parameters[0], num_device_parameters));

Isso permite que o mestre acesse os parâmetros do escravo conforme o mapeamento definido.

Configuração de Acesso a Dados no Mestre

Para que um dispositivo mestre possa acessar parâmetros de dispositivos escravos, é necessário configurar o acesso aos dados. Isso é realizado definindo os detalhes de cada parâmetro que será lido ou escrito, utilizando o Dicionário de Dados já apresentado.

Estrutura do Dicionário de Dados

Cada entrada no Dicionário de Dados representa uma característica física ou lógica disponível no dispositivo escravo, como temperatura, pressão ou um número de série. A configuração inclui:

• CID (Identificador de Característica): Um identificador único que referencia o parâmetro.
• Endereço do Registro: Define onde os dados estão localizados no mapa de registros do escravo.
• Tipo de Registro: Especifica se é um registro de entrada, holding, etc.
• Tamanho: Determina quantos registros Modbus são utilizados para armazenar o valor.

Exemplo Prático de Configuração

Abaixo está um exemplo de definição de parâmetros para dois dispositivos escravos conectados a um mestre:

mb_parameter_descriptor_t device_parameters[] = {
    { CID_TEMP_DATA_1, "Temperature_1", "C", MB_DEVICE_ADDR1, MB_PARAM_HOLDING, 0, 2, 0, PARAM_TYPE_FLOAT, 4 },
    { CID_HUMIDITY_1, "Humidity_1", "%", MB_DEVICE_ADDR1, MB_PARAM_INPUT, 2, 1, 0, PARAM_TYPE_U16, 2 },
    { CID_TEMP_DATA_2, "Temperature_2", "C", MB_DEVICE_ADDR2, MB_PARAM_HOLDING, 0, 2, 0, PARAM_TYPE_FLOAT, 4 },
    { CID_HUMIDITY_2, "Humidity_2", "%", MB_DEVICE_ADDR2, MB_PARAM_INPUT, 2, 1, 0, PARAM_TYPE_U16, 2 }
};

Neste exemplo:

• CID_TEMP_DATA_1: Mapeia a temperatura do dispositivo 1 (endereço MB_DEVICE_ADDR1) em registros de holding.
• CID_HUMIDITY_1: Mapeia a umidade do dispositivo 1 como registro de entrada.
• CID_TEMP_DATA_2 e CID_HUMIDITY_2: Seguem a mesma lógica para o segundo dispositivo.

O número de parâmetros no Dicionário de Dados pode ser calculado automaticamente:

uint16_t num_device_parameters = (sizeof(device_parameters) / sizeof(device_parameters[0]));

Configuração no Controlador Mestre

Após definir o Dicionário de Dados, ele deve ser registrado no controlador Modbus para permitir o acesso aos dispositivos escravos:

ESP_ERROR_CHECK(mbc_master_set_descriptor(&device_parameters[0], num_device_parameters));

Com essa configuração, o mestre está preparado para acessar os parâmetros definidos nos escravos, conforme as especificações do Dicionário de Dados.

Opções de Comunicação do Mestre

Depois de configurar os parâmetros de acesso no Dicionário de Dados, é necessário definir as opções de comunicação do mestre para garantir uma troca de dados eficiente e confiável com os dispositivos escravos. Essas opções incluem parâmetros de comunicação específicos para cada tipo de interface: serial ou TCP/IP.

Configuração de Comunicação Serial

Ao utilizar a comunicação serial (Modbus RTU ou ASCII), os seguintes parâmetros devem ser definidos:

• Porta Serial: Identifica qual porta UART será utilizada.
• Modo de Comunicação: Define se será RTU ou ASCII.
• Taxa de Baud: Determina a velocidade da transmissão em bits por segundo.
• Paridade: Especifica o tipo de verificação de paridade (nenhuma, ímpar ou par).

Exemplo de configuração para uma porta serial:

mb_communication_info_t comm_info = {
    .port = MB_PORT_NUM,        // Número da porta serial
    .mode = MB_MODE_RTU,        // Modo de comunicação Modbus (RTU ou ASCII)
    .baudrate = 9600,           // Taxa de transmissão em bits por segundo
    .parity = MB_PARITY_NONE    // Tipo de paridade (nenhuma neste caso)
};

// Configura o mestre Modbus com os parâmetros de comunicação
ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));

Configuração de Comunicação TCP/IP

Para comunicação via TCP/IP, além dos parâmetros gerais, é necessário configurar os endereços IP dos dispositivos escravos. Esses endereços são utilizados para identificar cada dispositivo na rede.

Exemplo de configuração para uma rede TCP/IP:

char* slave_ip_address_table[MB_SLAVE_COUNT] = {
    "192.168.1.2", // Endereço IP do escravo 1
    "192.168.1.3", // Endereço IP do escravo 2
    NULL           // Término da tabela
};

mb_communication_info_t comm_info = {
    .ip_port = MB_TCP_PORT,                    // Porta Modbus TCP (padrão 502)
    .ip_addr_type = MB_IPV4,                   // Tipo de endereço IP (IPv4)
    .ip_mode = MB_MODE_TCP,                    // Modo de comunicação TCP
    .ip_addr = (void*)slave_ip_address_table,  // Tabela de endereços IP dos escravos
    .ip_netif_ptr = esp_netif_ptr              // Ponteiro para a interface de rede
};

// Configura o mestre Modbus com os parâmetros de comunicação
ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));

Considerações Importantes

1. Para comunicação RS-485, é necessário configurar o modo UART e os pinos apropriados usando as APIs UART do ESP-IDF.
2. No caso de redes TCP/IP, a descoberta automática de dispositivos pode ser configurada utilizando o serviço mDNS.

Com as opções de comunicação configuradas, o mestre está pronto para iniciar a troca de dados com os escravos.

Comunicação do Mestre

Após configurar o mestre Modbus e suas opções de comunicação, o próximo passo é iniciar a comunicação com os dispositivos escravos. O ESP-Modbus oferece APIs para iniciar, enviar requisições e processar as respostas recebidas.

Inicialização da Comunicação

A comunicação do mestre Modbus é iniciada com a chamada da função mbc_master_start(), que ativa a pilha Modbus e permite a troca de dados.

Exemplo de inicialização:

esp_err_t err = mbc_master_start();
if (err != ESP_OK) {
    ESP_LOGE(TAG, "Falha ao iniciar o controlador Modbus, erro = %x.", err);
}

Envio de Requisições

O mestre envia requisições aos escravos utilizando a função mbc_master_send_request(). Essa função é bloqueante, ou seja, ela aguarda uma resposta do escravo antes de continuar.

Exemplo básico de envio de requisição:

mb_param_request_t request = {
    .slave_addr = 1,          // Endereço do dispositivo escravo
    .command = MB_FUNC_READ,  // Comando Modbus (ex.: leitura de registros)
    .reg_start = 0,           // Endereço inicial do registro
    .reg_size = 2             // Número de registros a serem lidos
};

uint8_t response_data[4]; // Buffer para armazenar a resposta
esp_err_t err = mbc_master_send_request(&request, response_data);
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Requisição bem-sucedida. Dados recebidos.");
} else {
    ESP_LOGE(TAG, "Erro na requisição Modbus, código de erro: %x.", err);
}

Leitura de Dados

O mestre pode acessar os valores de parâmetros definidos no Dicionário de Dados utilizando mbc_master_get_parameter(). Essa função permite recuperar os dados mapeados por um CID específico.

Exemplo de leitura de parâmetro:

const mb_parameter_descriptor_t* param_descriptor = NULL;
uint8_t data_buffer[4]; // Buffer para armazenar os dados
uint8_t data_type;

esp_err_t err = mbc_master_get_cid_info(CID_TEMP_DATA_1, ¶m_descriptor);
if (err == ESP_OK) {
    err = mbc_master_get_parameter(param_descriptor->cid, (char*)param_descriptor->param_key, data_buffer, &data_type);
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "Parâmetro: %s, Valor: 0x%08x", param_descriptor->param_key, *(uint32_t*)data_buffer);
    } else {
        ESP_LOGE(TAG, "Erro ao ler o parâmetro, código de erro: %x.", err);
    }
}

Escrita de Dados

O mestre também pode alterar valores nos registros de um escravo utilizando mbc_master_set_parameter().

Exemplo de escrita:

uint8_t new_value[4] = {0x12, 0x34, 0x56, 0x78};
esp_err_t err = mbc_master_set_parameter(CID_TEMP_DATA_1, "Temperature_1", new_value, NULL);
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Parâmetro atualizado com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao atualizar parâmetro, código de erro: %x.", err);
}

Encerramento do Mestre Modbus

Ao finalizar a utilização do mestre Modbus, é essencial encerrar corretamente a pilha de comunicação para liberar os recursos do sistema. O ESP-Modbus oferece APIs específicas para garantir que todo o contexto do controlador seja destruído de forma segura.

Parada da Pilha Modbus

A função mbc_master_stop() deve ser chamada para interromper a pilha de comunicação. Isso encerra todas as operações ativas e desativa o controlador.

Exemplo de parada da pilha:

esp_err_t err = mbc_master_stop();
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Pilha Modbus parada com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao parar a pilha Modbus, código de erro: %x.", err);
}

Destruição do Controlador

Após a parada da pilha, o controlador Modbus deve ser destruído utilizando a função mbc_master_destroy(). Isso libera a memória e outros recursos alocados durante a inicialização.

Exemplo de destruição do controlador:

esp_err_t err = mbc_master_destroy();
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Controlador Modbus destruído com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao destruir o controlador Modbus, código de erro: %x.", err);
}

Boas Práticas

• Verificação de Erros: Sempre verifique os códigos de retorno das funções para identificar possíveis falhas e tratar erros de forma adequada.
• Liberação de Recursos: Certifique-se de que a função mbc_master_destroy() seja chamada antes de finalizar a aplicação para evitar vazamentos de memória.
• Sincronização: Garanta que todas as operações Modbus tenham sido concluídas antes de encerrar a pilha.

Com esses passos, o ciclo de vida do controlador mestre Modbus é finalizado de forma segura e eficiente.

API Modbus Escravo – Visão Geral

A API Modbus para dispositivos escravos no ESP32 permite configurar e gerenciar a comunicação com mestres Modbus. Assim como a API para mestres, a API para escravos segue uma sequência lógica de configuração e operação.

Etapas Principais da Comunicação Escravo

1. Inicialização da Porta Modbus:
   • Configura a interface de comunicação (serial ou TCP/IP) e o controlador escravo.
2. Configuração de Acesso a Dados:
   • Define os registros que estarão disponíveis para acesso pelo mestre, como holding registers ou input registers.
3. Opções de Comunicação:
   • Configura parâmetros específicos, como taxa de transmissão e endereços de comunicação.
4. Início da Comunicação:
   • Ativa a pilha Modbus, permitindo a troca de dados entre o escravo e o mestre.
5. Finalização:
   • Libera os recursos do controlador ao finalizar a comunicação.

Estrutura de Dados no Escravo

Assim como no mestre, o escravo utiliza estruturas de dados para organizar os registros Modbus acessíveis pelo mestre. A configuração de cada área de registro inclui:

• Tipo de Registro: Define se é um holding register, input register, coil, ou discrete input.
• Endereço Inicial: Especifica a posição inicial do registro na memória do dispositivo.
• Tamanho: Determina o número de registros disponíveis para acesso.

Configuração de Acesso a Dados no Escravo

A configuração de acesso a dados no escravo Modbus é uma etapa essencial para disponibilizar registros aos mestres. No ESP-Modbus, isso é feito definindo áreas de memória específicas que armazenarão os dados acessíveis. Essas áreas são mapeadas para tipos de registros Modbus, como Holding Registers e Input Registers.

Definindo Áreas de Registro

Cada tipo de registro Modbus no escravo é configurado utilizando a estrutura mb_register_area_descriptor_t. Essa estrutura especifica:

• Offset Inicial: A posição relativa do registro dentro do tipo configurado.
• Tipo de Registro: Indica se a área é de Holding Registers, Input Registers, Coils ou Discrete Inputs.
• Endereço de Memória: Um ponteiro para a área de memória onde os dados serão armazenados.
• Tamanho da Área: Define o número de registros disponíveis para leitura/escrita.

Exemplo de configuração de áreas de registro:

#define MB_REG_INPUT_START_AREA0    (0)
#define MB_REG_HOLDING_START_AREA0  (0)
#define MB_REG_HOLD_CNT             (100) // Número de registros de holding
#define MB_REG_INPUT_CNT            (100) // Número de registros de input

mb_register_area_descriptor_t reg_area; // Estrutura de descrição da área de registros

// Área de registros de holding
uint16_t holding_reg_area[MB_REG_HOLD_CNT] = {0};
reg_area.type = MB_PARAM_HOLDING;
reg_area.start_offset = MB_REG_HOLDING_START_AREA0;
reg_area.address = (void*)&holding_reg_area[0];
reg_area.size = sizeof(holding_reg_area);
ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));

// Área de registros de input
uint16_t input_reg_area[MB_REG_INPUT_CNT] = {0};
reg_area.type = MB_PARAM_INPUT;
reg_area.start_offset = MB_REG_INPUT_START_AREA0;
reg_area.address = (void*)&input_reg_area[0];
reg_area.size = sizeof(input_reg_area);
ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));

Proteção e Acesso aos Registros

Para evitar inconsistências durante a escrita/leitura dos registros, é importante proteger as áreas de memória com seções críticas. Exemplo:

portENTER_CRITICAL(¶m_lock);
holding_reg_area[2] += 10; // Atualizando um registro
portEXIT_CRITICAL(¶m_lock);

Requisitos para a Configuração

• Pelo menos uma área de cada tipo de registro necessário deve ser configurada.
• Caso um mestre tente acessar uma área não configurada, será gerada uma exceção Modbus.

Opções de Comunicação do Escravo

Após configurar as áreas de registro, é necessário definir as opções de comunicação para o escravo Modbus. Esses parâmetros garantem que o dispositivo esteja corretamente configurado para se comunicar com o mestre, seja em modo serial (RTU/ASCII) ou TCP/IP.

Configuração de Comunicação Serial

Na comunicação serial, os parâmetros principais são:

• Porta UART: Define qual porta física será utilizada.
• Modo de Comunicação: Indica se será RTU ou ASCII.
• Endereço do Escravo: Identifica unicamente o dispositivo na rede.
• Taxa de Baud: Determina a velocidade de transmissão.
• Paridade: Configura o tipo de paridade (nenhuma, ímpar ou par).

Exemplo de configuração serial:

#define MB_SLAVE_DEV_SPEED 9600
#define MB_SLAVE_ADDR 1
#define MB_SLAVE_PORT_NUM 2

mb_communication_info_t comm_info = {
    .mode = MB_MODE_RTU,                    // Modo RTU
    .slave_addr = MB_SLAVE_ADDR,            // Endereço do escravo
    .port = MB_SLAVE_PORT_NUM,              // Porta UART
    .baudrate = MB_SLAVE_DEV_SPEED,         // Taxa de baud
    .parity = MB_PARITY_NONE                // Sem paridade
};

// Configura o escravo Modbus com os parâmetros definidos
ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));

Configuração de Comunicação TCP/IP

Na comunicação via TCP/IP, o escravo precisa estar associado a uma interface de rede válida e configurado para escutar em uma porta específica. A porta padrão para Modbus TCP é a 502.

Exemplo de configuração TCP/IP:

mb_communication_info_t comm_info = {
    .ip_port = MB_TCP_PORT,                    // Porta Modbus TCP (padrão 502)
    .ip_addr_type = MB_IPV4,                   // IPv4
    .ip_mode = MB_MODE_TCP,                    // Modo TCP
    .ip_addr = NULL,                           // Aceita conexões de qualquer cliente
    .ip_netif_ptr = esp_netif_ptr              // Ponteiro para a interface de rede
};

// Configura o escravo Modbus para comunicação TCP/IP
ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));

Considerações para Comunicação Estável

1. RS-485: Caso a interface serial utilize RS-485, configure os pinos UART e o modo half-duplex utilizando as APIs UART do ESP-IDF.
2. Descoberta Automática: Para TCP/IP, é possível usar o serviço mDNS para facilitar a descoberta de dispositivos na rede.
3. Respostas em Tempo Real: Certifique-se de que os registros necessários estejam configurados para evitar erros de timeout no mestre.

Com os parâmetros de comunicação configurados, o escravo está pronto para se comunicar com o mestre.

Comunicação do Escravo

Com as áreas de registro e as opções de comunicação configuradas, o escravo Modbus está pronto para iniciar a troca de dados com o mestre. O ESP-Modbus oferece APIs para gerenciar eventos e processar acessos aos registros configurados.

Início da Comunicação

A comunicação do escravo é iniciada com a função mbc_slave_start(). Isso ativa a pilha Modbus, permitindo que o dispositivo receba e responda às requisições do mestre.

Exemplo de inicialização:

esp_err_t err = mbc_slave_start();
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Escravo Modbus iniciado com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao iniciar o escravo Modbus, código: %x.", err);
}

Monitoramento de Eventos

O escravo pode monitorar eventos relacionados ao acesso aos registros utilizando a função mbc_slave_check_event(). Essa função é bloqueante e retorna o tipo de evento ocorrido, como leitura ou escrita em um registro.

Exemplo de monitoramento de eventos:

#define MB_READ_MASK (MB_EVENT_INPUT_REG_RD | MB_EVENT_HOLDING_REG_RD)
#define MB_WRITE_MASK (MB_EVENT_HOLDING_REG_WR)
#define MB_READ_WRITE_MASK (MB_READ_MASK | MB_WRITE_MASK)

mb_event_group_t event = mbc_slave_check_event(MB_READ_WRITE_MASK);

if (event & MB_EVENT_HOLDING_REG_WR) {
    ESP_LOGI(TAG, "Escrita em Holding Register detectada.");
} else if (event & MB_EVENT_INPUT_REG_RD) {
    ESP_LOGI(TAG, "Leitura em Input Register detectada.");
}

Acesso a Parâmetros

A função mbc_slave_get_param_info() permite obter detalhes sobre o registro acessado pelo mestre, como tipo de registro, endereço e tamanho.

Exemplo de acesso:

mb_param_info_t reg_info;
esp_err_t err = mbc_slave_get_param_info(®_info, MB_PAR_INFO_GET_TOUT);
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Registro acessado: Tipo=%u, Endereço=%u, Tamanho=%u",
             reg_info.type, reg_info.mb_offset, reg_info.size);
} else {
    ESP_LOGE(TAG, "Erro ao obter informações do parâmetro, código: %x.", err);
}

Respostas em Tempo Real

O escravo responde automaticamente às requisições do mestre com base nos registros configurados. Certifique-se de que as áreas de registro estejam atualizadas com os valores corretos para evitar comportamentos inesperados.

Encerramento do Escravo Modbus

Ao finalizar a operação do escravo Modbus, é fundamental encerrar corretamente a pilha de comunicação e liberar os recursos alocados. Isso garante a estabilidade do sistema e evita vazamentos de memória.

Parada da Pilha Modbus

A função mbc_slave_stop() é usada para interromper a pilha Modbus. Essa chamada encerra todas as operações ativas do escravo.

Exemplo de parada:

esp_err_t err = mbc_slave_stop();
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Pilha Modbus do escravo parada com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao parar a pilha Modbus, código: %x.", err);
}

Destruição do Controlador

Após parar a pilha, a função mbc_slave_destroy() deve ser chamada para destruir o controlador Modbus e liberar todos os recursos alocados durante a inicialização.

Exemplo de destruição:

esp_err_t err = mbc_slave_destroy();
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Controlador do escravo Modbus destruído com sucesso.");
} else {
    ESP_LOGE(TAG, "Erro ao destruir o controlador Modbus, código: %x.", err);
}

Boas Práticas

1. Verificação de Operações Ativas: Antes de encerrar a pilha, certifique-se de que todas as operações de leitura/escrita tenham sido concluídas.
2. Liberação de Recursos: Sempre chame mbc_slave_destroy() para evitar vazamentos de memória ou instabilidades.
3. Sincronização de Tarefas: Caso múltiplas tarefas acessem os registros Modbus, garanta que todas tenham finalizado antes de destruir o controlador.

Com esses passos, o ciclo de vida do escravo Modbus é encerrado de forma segura e eficiente.

Possíveis Problemas de Comunicação e Soluções

Durante a implementação do protocolo Modbus, podem ocorrer problemas de comunicação entre o mestre e os escravos. A identificação e a solução desses problemas são essenciais para garantir o funcionamento correto do sistema.

Principais Erros e Soluções

1. Requisição Inválida (ESP_ERR_NOT_SUPPORTED – Código: 0x106)
   • Causa: O mestre enviou uma requisição para um registro ou comando não suportado pelo escravo.
   • Solução: Verifique o mapa de registros do escravo e ajuste a requisição do mestre para corresponder às capacidades do dispositivo.
2. Timeout na Resposta do Escravo (ESP_ERR_TIMEOUT – Código: 0x107)
   • Causa: O escravo não respondeu dentro do tempo esperado.
   • Solução: Certifique-se de que:
     • O escravo está conectado corretamente.
     • A taxa de baud e os parâmetros de comunicação (como paridade) são compatíveis entre mestre e escravo.
     • O endereço do escravo na requisição está correto.
3. Resposta Inválida (ESP_ERR_INVALID_RESPONSE – Código: 0x108)
   • Causa: O mestre recebeu uma resposta corrompida ou com erro de validação (checksum inválido).
   • Solução: Verifique a integridade do cabo de comunicação (no caso de RTU/ASCII) ou a estabilidade da conexão de rede (no caso de TCP/IP). Além disso, confirme que os parâmetros Modbus no escravo estão configurados corretamente.
4. Estado Inválido (ESP_ERR_INVALID_STATE – Código: 0x103)
   • Causa: Erro crítico no controlador Modbus, como sequência de comandos incorreta ou controlador ocupado.
   • Solução: Reinicie o controlador Modbus no mestre ou no escravo. Verifique se múltiplas tarefas estão acessando o controlador simultaneamente e sincronize-as.

Dicas para Diagnóstico

• Logs Detalhados: Ative logs no ESP-IDF para capturar mensagens de erro detalhadas, como falhas de inicialização ou problemas durante a execução.
• Testes Isolados: Teste cada dispositivo escravo individualmente antes de integrar vários dispositivos na rede.
• Osciloscópio ou Analisador de Rede: Use ferramentas de diagnóstico para verificar os sinais na linha de comunicação serial ou monitorar pacotes TCP/IP.

Exemplos de Mensagens de Erro

Um exemplo de mensagem de erro capturada nos logs do mestre:

E (1692332) MB_CONTROLLER_MASTER: mbc_master_get_parameter(111): SERIAL master get parameter failure error=(0x107) (ESP_ERR_TIMEOUT).

Neste caso, o erro indica que o escravo não respondeu no tempo esperado. A solução seria revisar as conexões físicas e os parâmetros de comunicação.

Exemplos de Aplicação

O ESP-Modbus fornece suporte completo para implementar soluções Modbus em dispositivos ESP32, permitindo a integração com uma ampla variedade de dispositivos industriais. Abaixo estão exemplos práticos de aplicações para mestre e escravo, baseados nas APIs discutidas.

Exemplo 1: Mestre Modbus Serial para Monitoramento de Sensores

Um mestre Modbus pode ser utilizado para monitorar parâmetros de sensores conectados via RS-485. O exemplo abaixo ilustra como configurar o mestre para ler a temperatura e umidade de dois dispositivos escravos.

Configuração do Mestre:

#include "mbcontroller.h"

// Configuração do dicionário de dados
mb_parameter_descriptor_t device_parameters[] = {
    { CID_TEMP, "Temperature", "C", MB_DEVICE_ADDR1, MB_PARAM_HOLDING, 0, 2, 0, PARAM_TYPE_FLOAT, 4 },
    { CID_HUMID, "Humidity", "%", MB_DEVICE_ADDR1, MB_PARAM_INPUT, 2, 1, 0, PARAM_TYPE_U16, 2 }
};

void app_main() {
    void* master_handler = NULL;
    ESP_ERROR_CHECK(mbc_master_init(MB_PORT_SERIAL_MASTER, &master_handler));

    mb_communication_info_t comm_info = {
        .port = MB_PORT_NUM,
        .mode = MB_MODE_RTU,
        .baudrate = 9600,
        .parity = MB_PARITY_NONE
    };
    ESP_ERROR_CHECK(mbc_master_setup((void*)&comm_info));

    ESP_ERROR_CHECK(mbc_master_set_descriptor(device_parameters, sizeof(device_parameters) / sizeof(device_parameters[0])));
    ESP_ERROR_CHECK(mbc_master_start());

    uint8_t temp_data[4];
    ESP_ERROR_CHECK(mbc_master_get_parameter(CID_TEMP, "Temperature", temp_data, NULL));
    ESP_LOGI(TAG, "Temperatura lida: %f", *(float*)temp_data);

    ESP_ERROR_CHECK(mbc_master_destroy());
}

Exemplo 2: Escravo Modbus TCP para Controle de Atuadores

Um escravo Modbus pode ser utilizado para controlar dispositivos como relés ou motores conectados via Ethernet. O exemplo abaixo configura o escravo para gerenciar dois relés.

Configuração do Escravo:

#include "mbcontroller.h"

#define RELAY_1_GPIO 25
#define RELAY_2_GPIO 26

void app_main() {
    uint16_t relay_registers[2] = {0}; // Registradores para os relés

    mb_register_area_descriptor_t reg_area = {
        .type = MB_PARAM_COIL,
        .start_offset = 0,
        .address = relay_registers,
        .size = sizeof(relay_registers)
    };
    ESP_ERROR_CHECK(mbc_slave_set_descriptor(reg_area));

    mb_communication_info_t comm_info = {
        .ip_port = MB_TCP_PORT,
        .ip_addr_type = MB_IPV4,
        .ip_mode = MB_MODE_TCP,
        .ip_addr = NULL,
        .ip_netif_ptr = esp_netif_ptr
    };
    ESP_ERROR_CHECK(mbc_slave_setup((void*)&comm_info));
    ESP_ERROR_CHECK(mbc_slave_start());

    while (true) {
        if (relay_registers[0]) {
            gpio_set_level(RELAY_1_GPIO, 1);
        }
        if (relay_registers[1]) {
            gpio_set_level(RELAY_2_GPIO, 1);
        }
        vTaskDelay(pdMS_TO_TICKS(100));
    }

    ESP_ERROR_CHECK(mbc_slave_destroy());
}

Integração com Outras Tecnologias

• MQTT: Combine Modbus com MQTT para enviar dados lidos pelo mestre para um servidor em nuvem.
• Automação Industrial: Use o ESP-Modbus para integrar dispositivos como CLPs e inversores de frequência a um sistema de supervisão (SCADA).

Conclusão e Próximos Passos

O suporte ao Modbus no ESP32, através da biblioteca ESP-Modbus, oferece uma solução robusta e flexível para aplicações de automação e integração industrial. Seja na leitura de sensores via Modbus RTU ou no controle remoto de dispositivos com Modbus TCP/IP, o ESP-Modbus simplifica a implementação e gerenciamento dessas comunicações.

Resumo dos Passos

1. Configuração Inicial: Defina os parâmetros de comunicação e o mapeamento de dados.
2. Troca de Dados: Utilize as APIs para enviar, receber e processar dados entre mestres e escravos.
3. Diagnóstico e Resolução de Problemas: Monitore logs e corrija eventuais falhas de comunicação.
4. Encerramento: Libere recursos corretamente ao finalizar a aplicação.

Próximos Passos

• Integração com Outras Protocolos: Experimente combinar o Modbus com protocolos como MQTT ou WebSocket para criar sistemas híbridos e conectados.
• Escalabilidade: Explore o uso de redes maiores com múltiplos dispositivos mestre e escravo.
• Customização: Adapte os exemplos fornecidos às suas necessidades específicas, otimizando o desempenho e a confiabilidade.

Recursos Adicionais

Para mais informações sobre o ESP-Modbus e o ESP-IDF, acesse:

• Documentação oficial do ESP-IDF
• Especificações do protocolo Modbus

Com os exemplos e explicações fornecidos neste artigo, você terá uma base sólida para desenvolver aplicações Modbus em dispositivos ESP32.

The post Introdução ao ESP-Modbus com ESP-IDF first appeared on MCU & FPGA.

O que é Armazenamento Não Volátil?

O termo “armazenamento não volátil” refere-se a uma memória que preserva os dados armazenados, mesmo quando não está alimentada por energia. No caso do ESP32, a NVS utiliza uma parte da memória flash para salvar pares de chave-valor. Esse mecanismo é ideal para armazenar pequenas quantidades de dados que precisam ser acessadas com frequência e com alta confiabilidade.

Características Principais da NVS

1. Armazenamento baseado em pares de chave-valor:
   • Cada entrada na NVS consiste em uma chave (string ASCII) e um valor.
   • As chaves podem ter até 15 caracteres.
   • Os valores suportam tipos como:
     • Inteiros (uint8_t, int16_t, uint32_t, etc.).
     • Strings (terminadas em nulo).
     • Blobs (dados binários de tamanho variável).
2. Organização por espaços de nome (namespaces):
   • Os pares chave-valor podem ser organizados em namespaces para evitar conflitos.
   • Um namespace é uma string ASCII, também limitada a 15 caracteres.
   • Até 254 namespaces podem ser criados por partição NVS.
3. Suporte para múltiplos tipos de dados:
   • A NVS é eficiente para armazenar pequenos valores (como configurações ou contadores).
   • Para dados maiores, como arquivos, é recomendado usar um sistema de arquivos como FAT.
4. Robustez e integridade:
   • A NVS foi projetada para lidar com falhas de energia sem perda de dados.
   • Em situações críticas, como reinicializações inesperadas, os dados permanecem protegidos, exceto durante a escrita de novos valores.

Implicações do Uso da Memória Flash

A memória flash, embora seja uma solução confiável para armazenamento persistente, tem uma vida útil limitada, contabilizada pelo número de ciclos de programação e apagamento (P/E). Cada setor de memória flash pode suportar um número finito de ciclos, geralmente na faixa de 10.000 a 100.000 operações de escrita/apagamento, dependendo do fabricante e do tipo de memória.

Impactos no Uso da NVS:

1. Escritas frequentes podem reduzir a vida útil da memória:
   • Operações repetidas de escrita (como em contadores) devem ser otimizadas para minimizar o desgaste.
   • É importante agrupar alterações antes de escrever na NVS.
2. Fragmentação da memória:
   • A atualização frequente de valores pode gerar fragmentação, forçando a reorganização e apagamento de setores inteiros para liberar espaço.
3. Cuidados com a durabilidade:
   • Para reduzir o desgaste, é recomendado:
     • Usar a NVS apenas para dados que realmente precisam ser persistidos.
     • Configurar parâmetros que limitem a frequência de escritas, como buffer em memória RAM.

Você tem razão novamente: depender da RAM para manter o progresso entre reinicializações não é adequado, já que a RAM é volátil e será reiniciada junto com o dispositivo. Para abordar isso corretamente, ajustamos o código para salvar cada incremento diretamente na NVS, enquanto aplicamos técnicas para minimizar o desgaste na memória flash.

Nova Abordagem: Escrita Otimizada Direta na NVS

Nessa abordagem, o contador é atualizado e salvo na NVS em cada reinicialização, mas utilizamos estratégias para distribuir o desgaste, como manter o progresso direto sem múltiplos intermediários na RAM.

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    // Inicializa a NVS
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    // Abre o armazenamento NVS no namespace "storage"
    nvs_handle_t my_handle;
    err = nvs_open("storage", NVS_READWRITE, &my_handle);
    if (err != ESP_OK) {
        printf("Erro ao abrir a NVS!\n");
    } else {
        printf("NVS aberta com sucesso!\n");

        // Lê o contador de reinicializações
        int32_t restart_counter = 0;
        err = nvs_get_i32(my_handle, "restart_counter", &restart_counter);
        switch (err) {
            case ESP_OK:
                printf("Contador de reinicializações lido: %d\n", restart_counter);
                break;
            case ESP_ERR_NVS_NOT_FOUND:
                printf("Contador não inicializado. Configurando para 0.\n");
                restart_counter = 0; // Inicializa o contador
                break;
            default:
                printf("Erro ao ler contador (%s)\n", esp_err_to_name(err));
        }

        // Incrementa o contador
        restart_counter++;
        printf("Incrementando contador: %d\n", restart_counter);

        // Salva o contador na NVS
        err = nvs_set_i32(my_handle, "restart_counter", restart_counter);
        if (err == ESP_OK) {
            printf("Contador salvo na NVS: %d\n", restart_counter);
            err = nvs_commit(my_handle);
            if (err != ESP_OK) {
                printf("Erro ao confirmar gravação (%s)\n", esp_err_to_name(err));
            }
        } else {
            printf("Erro ao salvar contador na NVS (%s)\n", esp_err_to_name(err));
        }

        // Fecha a NVS
        nvs_close(my_handle);
    }

    printf("Contador atualizado. Reinicie o dispositivo para testar novamente.\n");
}

O que Esta Abordagem Faz?

1. Persistência Total:
   • A cada incremento, o valor atualizado é imediatamente salvo na NVS. Isso garante que, mesmo em falhas de energia ou reinicializações inesperadas, o contador reflita o valor real acumulado.
2. Consideração da Vida Útil da Memória Flash:
   • Apesar de salvar a cada incremento, o contador evita salvamentos desnecessários ou fragmentação de dados, garantindo eficiência máxima.
   • Este é o comportamento básico necessário para garantir persistência em sistemas críticos.
3. Simplicidade de Implementação:
   • O código lida diretamente com a leitura e escrita da NVS, sem necessidade de lógicas adicionais que dependam da RAM ou outros sistemas voláteis.

Implicações e Cuidados

• Ciclos de Escrita:
  • Cada gravação consome um ciclo do tempo de vida da memória flash. Para contadores que incrementam frequentemente (como em reinicializações ou eventos de alta frequência), isso pode levar ao esgotamento mais rápido de setores da memória.
  • Uma solução para cenários de alta frequência seria implementar buffers de eventos em sistemas complementares, como RTC ou FRAM, e sincronizar periodicamente com a NVS.
• Fragmentação:
  • Como os valores são salvos diretamente, não há riscos de fragmentação de espaço, mas é necessário garantir espaço suficiente para entradas contínuas no setor utilizado pela NVS.

Caso esta versão esteja adequada, podemos prosseguir para a próxima seção sobre a estrutura interna da NVS, onde explicarei como os dados são organizados em páginas e entradas na memória flash. Posso avançar?

Estrutura Interna da NVS

A estrutura interna da NVS no ESP32 foi projetada para ser eficiente e robusta, mesmo em casos de uso intenso ou falhas inesperadas. Abaixo, detalhamos como os dados são armazenados, organizados e gerenciados pela biblioteca.

Organização em Páginas e Entradas

A NVS utiliza um modelo baseado em páginas e entradas para gerenciar os pares de chave-valor armazenados na memória flash.

1. Páginas:
   • Cada página corresponde a um setor lógico na memória flash, geralmente com 4 KB (tamanho padrão de um setor em dispositivos ESP32).
   • As páginas têm estados específicos que refletem sua utilidade:
     • Vazia: Nenhum dado foi gravado ainda.
     • Ativa: Dados estão sendo gravados, e há espaço livre disponível.
     • Cheia: Todos os espaços disponíveis foram utilizados.
     • Corrompida: O cabeçalho ou os dados da página estão inválidos e não podem ser usados.
   • Páginas em uso possuem um número de sequência, indicando a ordem de criação.
2. Entradas:
   • Cada entrada armazena um único par de chave-valor ou parte dele.
   • Uma entrada ocupa 32 bytes, alinhada com os requisitos de criptografia e eficiência da flash.
   • Para valores grandes (strings ou blobs), as entradas podem ser divididas em várias partes.

Como os Dados São Gravados

• Gravação Incremental:
  • Novos pares de chave-valor são adicionados ao final da página ativa.
  • Atualizações não sobrescrevem valores existentes; em vez disso, uma nova entrada é adicionada, e a antiga é marcada como apagada.
• Reaproveitamento de Espaço:
  • Quando uma página está cheia, a NVS move as entradas não apagadas para outra página antes de limpar a atual. Isso evita perda de dados.

Exemplo de Estados de Página

O exemplo abaixo ilustra os estados de quatro páginas em uso:

+--------+     +--------+     +--------+     +--------+
| Página 1 |     | Página 2 |     | Página 3 |     | Página 4 |
| Cheia   |     | Cheia   |     | Ativa   |     | Vazia   |
| Seq #11 |     | Seq #12 |     | Seq #14 |     |        |
+---+----+     +----+---+     +----+---+     +---+----+

1. Página Cheia (1 e 2):
   • Não pode receber novas gravações, mas as entradas ainda podem ser lidas.
2. Página Ativa (3):
   • Dados podem ser gravados até que o espaço acabe.
3. Página Vazia (4):
   • Reservada para uso futuro.

Estrutura de uma Página

Uma página é dividida em três partes principais:

1. Cabeçalho:
   • Contém metadados, como o estado da página, número de sequência, versão e checksum (CRC32) para verificar integridade.
2. Bitmap de Estado de Entradas:
   • Um mapa que indica o estado de cada entrada:
     • Vazia: Nenhum dado foi gravado.
     • Escrita: Dados válidos estão presentes.
     • Apagada: A entrada foi descartada.
3. Entradas:
   • Dados reais armazenados, incluindo chave, valor e tipo.

Exemplo de Gravação

Abaixo está uma simulação de como os dados são armazenados:

+-----------+--------------+-------------+------------------------+--------+
| Cabeçalho | Bitmap de Estado | Entrada 1  | Entrada 2             | ...    |
+-----------+--------------+-------------+------------------------+--------+

• Entrada 1:
  • Tipo: Inteiro (4 bytes).
  • Dados: restart_counter = 10.
• Entrada 2:
  • Tipo: String (16 bytes).
  • Dados: "SSID do Wi-Fi".

Impacto nos Ciclos de Vida da Flash

A organização da NVS minimiza o desgaste da memória flash ao evitar gravações desnecessárias e reaproveitar setores apenas quando necessário. No entanto:

• A repetida atualização de valores pequenos pode encher páginas rapidamente, levando ao apagamento frequente.
• Para mitigar isso, considere agrupar alterações ou usar buffers.

Namespaces na NVS

A biblioteca NVS oferece um mecanismo chamado namespaces (espaços de nome) para organizar os dados armazenados e evitar conflitos entre diferentes módulos ou partes de uma aplicação. Essa funcionalidade é especialmente útil em projetos complexos, onde vários subsistemas podem precisar salvar dados na memória flash.

O que são Namespaces?

Namespaces são contêineres lógicos que agrupam pares de chave-valor na NVS. Cada namespace possui um nome único e segue as mesmas regras de nomenclatura das chaves:

• Limite de caracteres: 15 caracteres ASCII.
• Unicidade: Cada namespace deve ter um nome único dentro de uma partição NVS.

Com namespaces, diferentes módulos da aplicação podem usar as mesmas chaves sem sobrescrever os dados uns dos outros.

Características Principais

1. Isolamento de Dados:
   • Os dados em um namespace são isolados dos dados em outros namespaces, evitando conflitos de chave.
2. Suporte a Múltiplos Namespaces:
   • Cada partição NVS pode suportar até 254 namespaces diferentes.
3. Identificação Única:
   • O namespace é especificado durante a inicialização de uma operação de leitura ou gravação.
4. Uso em Múltiplas Partições:
   • Namespaces com o mesmo nome, mas em partições diferentes, são considerados independentes.

Como Usar Namespaces na NVS

O uso de namespaces requer a abertura de um “handle” para um namespace específico antes de acessar os dados. Abaixo está um exemplo prático:

Exemplo de Uso de Namespaces

No exemplo abaixo, dois módulos diferentes armazenam dados no mesmo dispositivo, mas em namespaces separados:

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    // Inicializa a NVS
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    // Modulo 1: Armazena configuração de Wi-Fi no namespace "wifi"
    nvs_handle_t wifi_handle;
    err = nvs_open("wifi", NVS_READWRITE, &wifi_handle);
    if (err == ESP_OK) {
        printf("Namespace 'wifi' aberto com sucesso!\n");

        // Salva o SSID
        const char *ssid = "Rede-WiFi";
        err = nvs_set_str(wifi_handle, "ssid", ssid);
        if (err == ESP_OK) {
            printf("SSID salvo: %s\n", ssid);
            nvs_commit(wifi_handle);
        }

        nvs_close(wifi_handle);
    }

    // Modulo 2: Armazena configuração de PWM no namespace "pwm"
    nvs_handle_t pwm_handle;
    err = nvs_open("pwm", NVS_READWRITE, &pwm_handle);
    if (err == ESP_OK) {
        printf("Namespace 'pwm' aberto com sucesso!\n");

        // Salva a frequência do PWM
        uint16_t pwm_freq = 1000; // 1 kHz
        err = nvs_set_u16(pwm_handle, "frequency", pwm_freq);
        if (err == ESP_OK) {
            printf("Frequência PWM salva: %d Hz\n", pwm_freq);
            nvs_commit(pwm_handle);
        }

        nvs_close(pwm_handle);
    }

    printf("Dados salvos em namespaces diferentes.\n");
}

Explicação do Código

1. Namespace wifi:
   • Utilizado para armazenar o SSID de uma rede Wi-Fi.
   • O par chave-valor "ssid" é salvo nesse namespace.
2. Namespace pwm:
   • Utilizado para armazenar a frequência de PWM de um módulo.
   • O par chave-valor "frequency" é salvo nesse namespace.
3. Isolamento:
   • Os dados salvos no namespace wifi são completamente independentes dos dados salvos no namespace pwm. Mesmo que ambos usem a chave "frequency", os valores não colidem.

Práticas Recomendadas

• Nomeação de Namespaces:
  • Use nomes descritivos e curtos, como wifi, sensor, config.
• Organização de Dados:
  • Defina namespaces para diferentes módulos ou subsistemas (ex.: um namespace para sensores, outro para configurações de rede).
• Gerenciamento de Recursos:
  • Sempre feche os handles de namespace com nvs_close() após concluir as operações.

Uso da API NVS para Leitura e Gravação

A API da NVS (Non-Volatile Storage) no ESP32-IDF fornece um conjunto robusto de funções para manipular dados armazenados na memória flash. Essas funções permitem gravar, ler e apagar pares de chave-valor, garantindo a persistência dos dados em diversas aplicações.

Funções Principais da API

Abaixo estão as funções mais utilizadas na NVS para leitura e gravação, organizadas por operação:

1. Inicialização e Fechamento:
   • nvs_flash_init(): Inicializa o sistema NVS.
   • nvs_flash_erase(): Apaga todo o conteúdo da partição NVS.
   • nvs_open(): Abre um namespace para leitura/escrita.
   • nvs_close(): Fecha o handle do namespace.
2. Gravação de Dados:
   • nvs_set_*(): Define o valor de uma chave (set_i8, set_u32, set_str, etc.).
   • nvs_commit(): Garante que as alterações sejam persistidas.
3. Leitura de Dados:
   • nvs_get_*(): Obtém o valor de uma chave (get_i8, get_u32, get_str, etc.).
4. Apagar Dados:
   • nvs_erase_key(): Remove uma chave específica.
   • nvs_erase_all(): Remove todas as chaves de um namespace.

Exemplo Básico: Gravação e Leitura

O exemplo abaixo demonstra como gravar e recuperar diferentes tipos de dados na NVS.

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    // Inicializa a NVS
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    // Abre o namespace "storage" no modo leitura/escrita
    nvs_handle_t my_handle;
    err = nvs_open("storage", NVS_READWRITE, &my_handle);
    if (err != ESP_OK) {
        printf("Erro ao abrir o namespace NVS!\n");
        return;
    }

    // Grava diferentes tipos de dados
    printf("Gravando valores na NVS...\n");
    err = nvs_set_i32(my_handle, "int_key", 42);
    if (err == ESP_OK) printf("Inteiro salvo com sucesso!\n");

    err = nvs_set_str(my_handle, "str_key", "ESP32-IDF");
    if (err == ESP_OK) printf("String salva com sucesso!\n");

    float float_value = 3.14159f;
    err = nvs_set_blob(my_handle, "blob_key", &float_value, sizeof(float));
    if (err == ESP_OK) printf("Blob salvo com sucesso!\n");

    // Confirma a gravação
    err = nvs_commit(my_handle);
    if (err == ESP_OK) {
        printf("Alterações confirmadas na NVS.\n");
    }

    // Lê os dados gravados
    printf("Lendo valores da NVS...\n");
    int32_t int_value;
    err = nvs_get_i32(my_handle, "int_key", &int_value);
    if (err == ESP_OK) printf("Inteiro lido: %d\n", int_value);

    char str_value[20];
    size_t str_len = sizeof(str_value);
    err = nvs_get_str(my_handle, "str_key", str_value, &str_len);
    if (err == ESP_OK) printf("String lida: %s\n", str_value);

    float read_blob;
    size_t blob_size = sizeof(read_blob);
    err = nvs_get_blob(my_handle, "blob_key", &read_blob, &blob_size);
    if (err == ESP_OK) printf("Blob lido: %.5f\n", read_blob);

    // Fecha o handle
    nvs_close(my_handle);
    printf("Operações concluídas.\n");
}

Explicação do Código

1. Inicialização da NVS:
   • nvs_flash_init() prepara a memória flash para operações.
   • Em caso de erro, como falta de páginas livres, a memória é apagada e reinicializada.
2. Gravação de Dados:
   • nvs_set_i32() grava um número inteiro.
   • nvs_set_str() grava uma string terminada em nulo.
   • nvs_set_blob() grava um bloco binário, como um valor float.
3. Leitura de Dados:
   • nvs_get_i32() recupera um número inteiro.
   • nvs_get_str() recupera uma string, usando um buffer para armazenamento.
   • nvs_get_blob() recupera um blob, especificando o tamanho.
4. Persistência Garantida:
   • nvs_commit() assegura que as gravações sejam salvas definitivamente.
5. Fechamento:
   • nvs_close() libera recursos associados ao handle.

Tratamento de Erros

A API retorna códigos de erro em caso de falhas, como:

• ESP_ERR_NVS_NOT_FOUND: A chave não existe.
• ESP_ERR_NVS_INVALID_HANDLE: O handle foi fechado ou é inválido.
• ESP_ERR_NVS_NOT_ENOUGH_SPACE: Espaço insuficiente para gravar o valor.

Práticas Recomendadas

• Sempre use nvs_commit() após gravações para garantir persistência.
• Verifique os códigos de erro ao ler ou gravar dados.
• Use buffers apropriados para leitura de strings e blobs.

Exemplos Avançados com Strings e Blobs na NVS

Strings e blobs (dados binários de tamanho variável) são tipos de dados amplamente utilizados na NVS. Esses tipos permitem armazenar informações como textos e estruturas complexas em formatos binários.

Nesta seção, exploraremos como trabalhar com esses tipos de dados de maneira eficiente e segura.

Armazenando e Recuperando Strings

Strings são armazenadas na NVS como valores terminados em nulo. A função nvs_set_str() grava uma string, enquanto nvs_get_str() a recupera.

Exemplo Prático: Salvando e Lendo Strings

No exemplo abaixo, salvamos e recuperamos o nome de um dispositivo:

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    // Inicializa a NVS
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    // Abre o namespace "storage"
    nvs_handle_t my_handle;
    err = nvs_open("storage", NVS_READWRITE, &my_handle);
    ESP_ERROR_CHECK(err);

    // Grava uma string
    const char *device_name = "ESP32-Device";
    err = nvs_set_str(my_handle, "device_name", device_name);
    if (err == ESP_OK) {
        printf("Nome do dispositivo salvo: %s\n", device_name);
        nvs_commit(my_handle);
    }

    // Lê a string gravada
    char buffer[50];
    size_t required_size = sizeof(buffer);
    err = nvs_get_str(my_handle, "device_name", buffer, &required_size);
    if (err == ESP_OK) {
        printf("Nome do dispositivo lido: %s\n", buffer);
    }

    // Fecha o namespace
    nvs_close(my_handle);
}

Explicação do Código

1. Gravação de String:
   • nvs_set_str() grava uma string no par chave-valor.
   • A string é armazenada de forma compacta na NVS.
2. Leitura de String:
   • nvs_get_str() recupera a string.
   • É necessário passar um buffer para armazenar a string e informar o tamanho.

Armazenando e Recuperando Blobs

Blobs (Binary Large Objects) são usados para armazenar dados binários arbitrários, como estruturas, arrays ou objetos codificados.

Exemplo Prático: Salvando e Lendo Blobs

No exemplo abaixo, salvamos e lemos uma estrutura de configuração:

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

typedef struct {
    int32_t baud_rate;
    uint8_t parity;
    uint8_t stop_bits;
} uart_config_t;

void app_main(void) {
    // Inicializa a NVS
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    // Abre o namespace "config"
    nvs_handle_t my_handle;
    err = nvs_open("config", NVS_READWRITE, &my_handle);
    ESP_ERROR_CHECK(err);

    // Grava um blob
    uart_config_t uart_config = {115200, 0, 1};
    err = nvs_set_blob(my_handle, "uart_cfg", &uart_config, sizeof(uart_config));
    if (err == ESP_OK) {
        printf("Configuração UART salva.\n");
        nvs_commit(my_handle);
    }

    // Lê o blob gravado
    uart_config_t read_config;
    size_t blob_size = sizeof(read_config);
    err = nvs_get_blob(my_handle, "uart_cfg", &read_config, &blob_size);
    if (err == ESP_OK) {
        printf("Configuração UART lida: Baud Rate = %d, Paridade = %d, Stop Bits = %d\n",
               read_config.baud_rate, read_config.parity, read_config.stop_bits);
    }

    // Fecha o namespace
    nvs_close(my_handle);
}

Explicação do Código

1. Gravação de Blob:
   • nvs_set_blob() grava o blob. É necessário informar o ponteiro para os dados e o tamanho.
2. Leitura de Blob:
   • nvs_get_blob() recupera o blob. O tamanho deve ser conhecido e informado para alocar memória adequadamente.

Práticas Recomendadas

1. Gerenciamento de Buffers:
   • Sempre use buffers de tamanho adequado ao armazenar e recuperar strings ou blobs.
2. Verificação de Erros:
   • Cheque os códigos de erro retornados pelas funções da NVS, como ESP_ERR_NVS_NOT_FOUND (chave não encontrada).
3. Reduza a Fragmentação:
   • Evite gravar blobs muito grandes para minimizar a fragmentação na NVS.

Segurança e Criptografia na NVS

A segurança dos dados armazenados em dispositivos embarcados é uma preocupação fundamental, especialmente em aplicações que lidam com informações sensíveis, como credenciais de rede, chaves de API ou configurações críticas do sistema. A NVS (Non-Volatile Storage) no ESP32 oferece suporte à criptografia para proteger os dados armazenados.

Como Funciona a Criptografia na NVS

1. Integração com a Criptografia de Flash do ESP32:
   • A NVS utiliza a criptografia de flash nativa do ESP32 para proteger os dados armazenados.
   • Com a criptografia habilitada, os dados gravados na NVS são cifrados automaticamente antes de serem armazenados na memória flash.
2. Chaves de Criptografia:
   • As chaves de criptografia usadas pela NVS são armazenadas de forma segura em uma partição dedicada (nvs_keys).
   • Se essa partição estiver vazia, novas chaves serão geradas automaticamente durante a inicialização.
3. Transparência para o Desenvolvedor:
   • A API da NVS permanece a mesma, independentemente de a criptografia estar habilitada ou não.
   • As operações de leitura e gravação são tratadas de forma transparente, sem necessidade de ajustes no código.

Habilitando a Criptografia na NVS

Para ativar a criptografia na NVS, é necessário configurar o projeto no menuconfig do ESP-IDF:

1. Acesse o menuconfig:

   idf.py menuconfig
   

2. Navegue até:

   Component config -> NVS -> Enable NVS encryption
   

3. Ative a opção Enable NVS encryption.
4. Certifique-se de que a partição nvs_keys esteja definida na tabela de partições. Um exemplo de entrada na tabela seria:

   nvs_keys,      data, nvs_keys,   0x6000,   0x1000
   

Exemplo de Código: Inicialização com Criptografia

O exemplo abaixo mostra como inicializar a NVS com criptografia habilitada:

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    // Inicializa a NVS com suporte à criptografia
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());
        err = nvs_flash_init();
    }
    ESP_ERROR_CHECK(err);

    printf("NVS inicializada com criptografia habilitada.\n");

    // Abre o namespace "secure_data"
    nvs_handle_t my_handle;
    err = nvs_open("secure_data", NVS_READWRITE, &my_handle);
    if (err == ESP_OK) {
        printf("Namespace 'secure_data' aberto com sucesso!\n");

        // Grava uma string segura
        const char *secure_key = "my_secure_key";
        err = nvs_set_str(my_handle, "api_key", secure_key);
        if (err == ESP_OK) {
            printf("Chave segura salva: %s\n", secure_key);
            nvs_commit(my_handle);
        }

        // Fecha o handle
        nvs_close(my_handle);
    } else {
        printf("Erro ao abrir o namespace 'secure_data'.\n");
    }
}

Benefícios da Criptografia na NVS

1. Proteção contra Acessos Não Autorizados:
   • Mesmo que alguém tenha acesso físico ao chip, os dados permanecem cifrados e ilegíveis sem as chaves.
2. Compatibilidade com as APIs Existentes:
   • A criptografia é habilitada sem necessidade de alterações significativas no código.
3. Robustez contra Manipulações:
   • Dados alterados ou corrompidos de forma maliciosa serão invalidados pela NVS.

Limitações

1. Ausência de Resistência a Apagamento:
   • A criptografia protege contra leitura e modificação não autorizada, mas não impede que dados sejam apagados.
2. Requisitos de Memória:
   • O uso de criptografia pode aumentar levemente o consumo de memória RAM e CPU devido ao processamento criptográfico.

Práticas Recomendadas

1. Gerenciamento de Chaves:
   • Sempre garanta que a partição nvs_keys esteja protegida e não seja compartilhada entre dispositivos.
2. Reinicialização de Chaves:
   • Em caso de suspeita de comprometimento, apague a partição e deixe o sistema regenerar novas chaves.
3. Teste Extensivo:
   • Certifique-se de testar a inicialização e leitura da NVS em dispositivos configurados com criptografia habilitada.

Diagnóstico e Depuração na NVS

A NVS no ESP32 oferece ferramentas e métodos para diagnosticar e depurar problemas relacionados ao armazenamento de dados. Esses mecanismos são importantes para identificar e corrigir erros durante o desenvolvimento ou em aplicações em produção.

Principais Problemas e Soluções

1. Chaves Não Encontradas:
   • Erro: ESP_ERR_NVS_NOT_FOUND.
   • Causa: A chave especificada não existe no namespace ou foi apagada.
   • Solução:
     • Verifique se a chave foi escrita corretamente.
     • Certifique-se de que o namespace está inicializado.
2. Armazenamento Corrompido:
   • Erro: ESP_ERR_NVS_INVALID_STATE ou comportamento inesperado.
   • Causa: Dados na flash foram corrompidos, possivelmente devido a falhas de energia durante gravações.
   • Solução:
     • Apague e reinicialize a partição NVS usando nvs_flash_erase().
3. Falta de Espaço na NVS:
   • Erro: ESP_ERR_NVS_NOT_ENOUGH_SPACE.
   • Causa: A partição está cheia ou há fragmentação excessiva.
   • Solução:
     • Otimize o uso da NVS para evitar gravações excessivas.
     • Aumente o tamanho da partição na tabela de partições.
4. Partição Não Inicializada:
   • Erro: ESP_ERR_NVS_NOT_INITIALIZED.
   • Causa: A partição NVS não foi inicializada antes de realizar operações.
   • Solução:
     • Certifique-se de chamar nvs_flash_init() antes de qualquer operação com a NVS.

Funções para Diagnóstico

A NVS oferece funções específicas para verificar o estado e o uso da memória:

1. nvs_get_stats():
   • Obtém estatísticas sobre a partição NVS, como número de entradas usadas, livres e totais.
   • Exemplo:

     #include "nvs.h"
     
     void print_nvs_stats(const char *part_name) {
         nvs_stats_t stats;
         esp_err_t err = nvs_get_stats(part_name, &stats);
         if (err == ESP_OK) {
             printf("Estatísticas da NVS:\n");
             printf("Entradas usadas: %lu\n", stats.used_entries);
             printf("Entradas livres: %lu\n", stats.free_entries);
             printf("Entradas totais: %lu\n", stats.total_entries);
             printf("Namespaces: %lu\n", stats.namespace_count);
         } else {
             printf("Erro ao obter estatísticas da NVS.\n");
         }
     }
     

2. nvs_get_used_entry_count():
   • Obtém o número de entradas usadas em um namespace específico.
   • Exemplo:

     void print_namespace_entries(nvs_handle_t handle) {
         size_t used_entries = 0;
         esp_err_t err = nvs_get_used_entry_count(handle, &used_entries);
         if (err == ESP_OK) {
             printf("Entradas usadas no namespace: %lu\n", used_entries);
         } else {
             printf("Erro ao obter contagem de entradas: %s\n", esp_err_to_name(err));
         }
     }
     

3. nvs_entry_find() e Iteradores:
   • Lista todas as chaves e valores armazenados em um namespace ou partição.
   • Exemplo:

     void list_all_entries(const char *part_name, const char *namespace) {
         nvs_iterator_t it = NULL;
         esp_err_t err = nvs_entry_find(part_name, namespace, NVS_TYPE_ANY, &it);
         while (err == ESP_OK && it != NULL) {
             nvs_entry_info_t info;
             nvs_entry_info(it, &info);
             printf("Namespace: %s, Chave: %s, Tipo: %d\n", info.namespace_name, info.key, info.type);
             err = nvs_entry_next(&it);
         }
         nvs_release_iterator(it);
     }
     

Depurando Passo a Passo

1. Inicialização:
   • Verifique se nvs_flash_init() é chamado no início do programa.
   • Certifique-se de que a tabela de partições está configurada corretamente.
2. Testes de Gravação e Leitura:
   • Teste com pequenos pares de chave-valor para garantir que a partição NVS está funcional.
   • Use nvs_commit() após gravações para garantir persistência.
3. Monitoramento de Espaço:
   • Utilize nvs_get_stats() regularmente para monitorar o uso e identificar problemas de fragmentação.
4. Logs Detalhados:
   • Habilite logs detalhados no menuconfig:

     Component config -> NVS -> Enable debug logs
     

   • Isso ajuda a identificar falhas em operações de leitura e gravação.

Práticas Recomendadas para Diagnóstico

• Sempre trate os erros retornados pelas funções da NVS.
• Antes de apagar a NVS, realize backups dos dados críticos.
• Execute testes regulares em dispositivos reais para identificar problemas de comportamento.

Internals da NVS: Logs e Mecanismos de Paginação

A arquitetura interna da NVS foi projetada para ser eficiente e confiável, utilizando um sistema baseado em logs e paginação para organizar os dados armazenados. Esta abordagem permite operações robustas mesmo em condições adversas, como falhas de energia ou acessos frequentes.

Armazenamento Baseado em Logs

A NVS usa um modelo de armazenamento sequencial, onde novos dados são adicionados ao final de um log. Isso significa que:

1. Escrita Não Sobrescreve Dados:
   • Quando um valor é atualizado, a nova versão é gravada no final do log, enquanto a entrada antiga é marcada como apagada.
   • Esse modelo minimiza o desgaste da memória flash ao evitar reescritas frequentes em setores já utilizados.
2. Organização das Entradas:
   • Cada entrada no log contém:
     • Uma chave única.
     • Um valor associado.
     • Metadados, como tipo de dado e informações de integridade.
3. Compactação:
   • Quando um log fica cheio ou fragmentado, a NVS move os dados válidos para uma nova página, liberando espaço para novas gravações.

Mecanismo de Paginação

O armazenamento da NVS é dividido em páginas, que são setores lógicos da memória flash, geralmente de 4 KB cada.

1. Estados das Páginas:
   • Vazia: Nenhuma gravação foi feita.
   • Ativa: Dados estão sendo gravados; ainda há espaço disponível.
   • Cheia: A página atingiu sua capacidade máxima.
   • Corrompida: Dados inválidos ou inconsistentes; a página não é utilizada.
2. Gerenciamento de Páginas:
   • Páginas em uso possuem números de sequência, permitindo que a NVS determine a ordem de gravação.
   • Páginas corrompidas são ignoradas durante as operações de leitura.
3. Estrutura de Página:
   • Cabeçalho:
     • Inclui informações como estado da página, número de sequência e checksum.
   • Entradas:
     • Dados reais armazenados em blocos de 32 bytes.
   • Bitmap de Estado:
     • Indica se uma entrada está vazia, ocupada ou apagada.

Exemplo de Organização Interna

Imagine um cenário com quatro páginas na NVS:

+--------+     +--------+     +--------+     +--------+
| Página 1 |     | Página 2 |     | Página 3 |     | Página 4 |
| Cheia   |     | Cheia   |     | Ativa   |     | Vazia   |
| Seq #10 |     | Seq #11 |     | Seq #12 |     |        |
+---+----+     +----+---+     +----+---+     +---+----+

• Página 1 e 2:
  • Contêm dados completos, mas não podem receber novas gravações.
• Página 3:
  • Está ativa e pode gravar novos pares de chave-valor.
• Página 4:
  • Está vazia e será usada quando a Página 3 estiver cheia.

Benefícios do Modelo

1. Minimiza o Desgaste da Flash:
   • Como os dados são gravados sequencialmente, as operações de apagamento são realizadas apenas quando necessário.
2. Resistência a Falhas:
   • Em caso de falha de energia durante a gravação, os dados existentes permanecem intactos, e a operação pode ser retomada na inicialização.
3. Gerenciamento de Fragmentação:
   • O mecanismo de compactação reorganiza os dados para liberar espaço, reduzindo a fragmentação.

Exemplo de Compactação Automática

A NVS realiza automaticamente a compactação quando uma página ativa está cheia. Os dados válidos são movidos para uma nova página, enquanto a antiga é apagada e reinicializada.

Exemplo de Log Interno

Página Ativa:
+------------+-----------------+-----------------+
| Entrada 1  | Entrada 2       | Entrada 3       |
+------------+-----------------+-----------------+

Página Nova:
+------------+-----------------+-----------------+
| Entrada 2  | Entrada 3       | Entrada 4       |
+------------+-----------------+-----------------+

• Entradas apagadas ou inválidas são descartadas durante a movimentação.

Diagnóstico com Páginas

1. Identificação de Páginas Corrompidas:
   • Utilize logs detalhados (menuconfig -> Enable debug logs) para monitorar a saúde das páginas.
2. Verificação de Espaço:
   • Use nvs_get_stats() para verificar o uso de entradas em cada página.

Melhores Práticas para Uso da NVS em Produção

O uso eficiente da NVS (Non-Volatile Storage) no ESP32 é essencial para garantir a longevidade e confiabilidade das aplicações. Abaixo estão as melhores práticas que você pode implementar para aproveitar ao máximo os recursos da NVS, minimizando os problemas de desempenho e desgaste da memória flash.

1. Otimize o Tamanho da Partição NVS

• Configure o tamanho da partição NVS com base no volume de dados que será armazenado.
• Use a tabela de partições para ajustar o espaço disponível:

  nvs,      data, nvs,     0x9000,  0x6000
  

  • Neste exemplo, a partição NVS começa no endereço 0x9000 e possui 24 KB (0x6000).

2. Use Namespaces para Organizar os Dados

• Divida os dados entre namespaces para evitar conflitos e facilitar o gerenciamento.
• Exemplo:
  • Namespace wifi para configurações de rede.
  • Namespace sensor para dados de sensores.

Benefícios:

• Permite a coexistência de diferentes módulos sem sobrescritas acidentais.
• Facilita a depuração e o backup de dados.

3. Reduza o Número de Gravações

• A memória flash tem um ciclo de vida limitado, geralmente entre 10.000 e 100.000 ciclos de gravação por setor.
• Minimize gravações frequentes:
  • Use buffers na RAM para armazenar dados temporários e grave na NVS apenas quando necessário.
  • Combine múltiplas alterações em uma única operação de gravação.

Exemplo:

Grave contadores de eventos somente após atingir um múltiplo de 10:

int event_count = 0;

// Incremento em RAM
event_count++;

// Gravação condicional na NVS
if (event_count % 10 == 0) {
    nvs_set_i32(my_handle, "event_count", event_count);
    nvs_commit(my_handle);
}

4. Monitore o Uso de Memória

• Use a função nvs_get_stats() para monitorar a utilização da NVS e identificar fragmentação ou falta de espaço.
• Exemplo:

nvs_stats_t stats;
nvs_get_stats(NULL, &stats);
printf("Usadas: %lu, Livres: %lu, Total: %lu\n",
       stats.used_entries, stats.free_entries, stats.total_entries);

5. Proteja Dados Sensíveis com Criptografia

• Habilite a criptografia da NVS para proteger dados como credenciais e chaves de API.
• Configure no menuconfig:

  Component config -> NVS -> Enable NVS encryption
  

6. Trate os Códigos de Erro Adequadamente

• Sempre verifique os códigos de retorno das funções da NVS para tratar erros como:
  • ESP_ERR_NVS_NOT_FOUND: Chave inexistente.
  • ESP_ERR_NVS_INVALID_HANDLE: Handle inválido.
  • ESP_ERR_NVS_NOT_ENOUGH_SPACE: Falta de espaço.

Exemplo:

esp_err_t err = nvs_get_i32(my_handle, "key", &value);
if (err == ESP_ERR_NVS_NOT_FOUND) {
    printf("Chave não encontrada.\n");
} else if (err != ESP_OK) {
    printf("Erro ao acessar a NVS: %s\n", esp_err_to_name(err));
}

7. Execute Backup de Dados Periódicos

• Para evitar perda de dados importantes, implemente um mecanismo de backup que exporte os dados da NVS para outro sistema (como um servidor ou cartão SD).
• Use um iterador para listar todas as chaves e seus valores:

nvs_iterator_t it = NULL;
esp_err_t res = nvs_entry_find(NULL, NULL, NVS_TYPE_ANY, &it);
while (res == ESP_OK) {
    nvs_entry_info_t info;
    nvs_entry_info(it, &info);
    printf("Namespace: %s, Chave: %s\n", info.namespace_name, info.key);
    res = nvs_entry_next(&it);
}
nvs_release_iterator(it);

8. Teste em Condições Reais

• Simule falhas de energia e reinicializações durante operações de gravação para garantir que os dados não sejam corrompidos.
• Use ferramentas como o monitor serial do ESP-IDF para depuração em tempo real.

9. Atualize Regularmente o Firmware

• A Espressif constantemente atualiza o ESP-IDF para melhorar a estabilidade da NVS.
• Mantenha o ambiente de desenvolvimento atualizado para evitar bugs e aproveitar novos recursos.

10. Planeje o Ciclo de Vida do Produto

• Se a aplicação grava frequentemente na NVS, considere estratégias para aumentar a durabilidade:
  • Divida os dados em múltiplas partições.
  • Utilize memórias externas, como FRAM ou EEPROM, para dados de alta frequência.

Resumo das Melhores Práticas

Exemplos de Aplicações Reais Usando NVS

A NVS (Non-Volatile Storage) é amplamente utilizada em projetos baseados no ESP32 para armazenamento persistente de dados críticos. Nesta seção, apresentamos exemplos práticos de casos de uso para ilustrar como a NVS pode ser aplicada em cenários reais.

1. Armazenamento de Configurações de Rede

O ESP32 é frequentemente usado em aplicações IoT que exigem conectividade Wi-Fi. A NVS pode armazenar as credenciais da rede, como SSID e senha, permitindo que o dispositivo se reconecte automaticamente após uma reinicialização.

Exemplo: Configurações de Wi-Fi

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"
#include "esp_wifi.h"

void save_wifi_config(const char *ssid, const char *password) {
    nvs_handle_t handle;
    esp_err_t err = nvs_open("wifi_config", NVS_READWRITE, &handle);
    if (err == ESP_OK) {
        nvs_set_str(handle, "ssid", ssid);
        nvs_set_str(handle, "password", password);
        nvs_commit(handle);
        nvs_close(handle);
        printf("Configurações de Wi-Fi salvas!\n");
    } else {
        printf("Erro ao abrir a NVS para Wi-Fi: %s\n", esp_err_to_name(err));
    }
}

void read_wifi_config(char *ssid, size_t ssid_len, char *password, size_t pass_len) {
    nvs_handle_t handle;
    esp_err_t err = nvs_open("wifi_config", NVS_READONLY, &handle);
    if (err == ESP_OK) {
        nvs_get_str(handle, "ssid", ssid, &ssid_len);
        nvs_get_str(handle, "password", password, &pass_len);
        nvs_close(handle);
        printf("Configurações de Wi-Fi lidas!\n");
    } else {
        printf("Erro ao ler configurações de Wi-Fi: %s\n", esp_err_to_name(err));
    }
}

void app_main(void) {
    nvs_flash_init();

    // Salva configurações de Wi-Fi
    save_wifi_config("MinhaRede", "Senha123");

    // Lê configurações de Wi-Fi
    char ssid[32], password[64];
    read_wifi_config(ssid, sizeof(ssid), password, sizeof(password));

    printf("SSID: %s, Senha: %s\n", ssid, password);
}

2. Contadores Persistentes

Em aplicações industriais ou de monitoramento, o ESP32 pode precisar rastrear eventos, como reinicializações ou leituras de sensores. A NVS pode armazenar contadores de forma persistente.

Exemplo: Contador de Reinicializações

#include <stdio.h>
#include "nvs_flash.h"
#include "nvs.h"

void app_main(void) {
    nvs_flash_init();

    nvs_handle_t handle;
    esp_err_t err = nvs_open("system_data", NVS_READWRITE, &handle);
    if (err == ESP_OK) {
        int32_t restart_counter = 0;
        nvs_get_i32(handle, "restart_counter", &restart_counter);
        restart_counter++;
        nvs_set_i32(handle, "restart_counter", restart_counter);
        nvs_commit(handle);
        nvs_close(handle);

        printf("O dispositivo reiniciou %d vezes.\n", restart_counter);
    } else {
        printf("Erro ao acessar a NVS: %s\n", esp_err_to_name(err));
    }
}

3. Configurações de Sensores

Sensores conectados ao ESP32 podem exigir calibração ou parâmetros configuráveis, como intervalos de leitura. Esses valores podem ser armazenados na NVS para persistência.

Exemplo: Configuração de Sensores

typedef struct {
    float offset;
    float scale;
} sensor_config_t;

void save_sensor_config(float offset, float scale) {
    nvs_handle_t handle;
    esp_err_t err = nvs_open("sensor_data", NVS_READWRITE, &handle);
    if (err == ESP_OK) {
        sensor_config_t config = {offset, scale};
        nvs_set_blob(handle, "calibration", &config, sizeof(config));
        nvs_commit(handle);
        nvs_close(handle);
        printf("Configuração do sensor salva!\n");
    } else {
        printf("Erro ao salvar configuração do sensor: %s\n", esp_err_to_name(err));
    }
}

void read_sensor_config(sensor_config_t *config) {
    nvs_handle_t handle;
    esp_err_t err = nvs_open("sensor_data", NVS_READONLY, &handle);
    if (err == ESP_OK) {
        size_t size = sizeof(*config);
        nvs_get_blob(handle, "calibration", config, &size);
        nvs_close(handle);
        printf("Configuração do sensor lida: Offset = %.2f, Escala = %.2f\n",
               config->offset, config->scale);
    } else {
        printf("Erro ao ler configuração do sensor: %s\n", esp_err_to_name(err));
    }
}

4. Gerenciamento de Perfis de Usuário

Em dispositivos compartilhados, como leitores de cartões ou controladores de acesso, a NVS pode armazenar perfis de usuários com permissões ou configurações específicas.

Práticas Recomendadas para Aplicações Reais

1. Isolamento Lógico:
   • Use namespaces para separar os dados de diferentes módulos.
2. Verificação de Integridade:
   • Valide os dados lidos da NVS antes de usá-los na aplicação.
3. Backup e Recuperação:
   • Implemente mecanismos de backup para evitar perda de dados críticos.

FAQ: Respostas a Problemas Comuns com NVS

Nesta seção, abordamos as dúvidas e problemas mais frequentes relacionados ao uso da NVS no ESP32, fornecendo soluções práticas para cada caso.

1. Por que recebo o erro ESP_ERR_NVS_NOT_FOUND ao tentar ler uma chave?

• Causa: A chave especificada não existe no namespace ou foi apagada.
• Solução:
  • Certifique-se de que a chave foi gravada previamente com nvs_set_*().
  • Verifique se o namespace está correto.
  • Use um valor padrão ao inicializar a variável, como mostrado no exemplo:

    int32_t value = 0; // Valor padrão
    esp_err_t err = nvs_get_i32(my_handle, "key_name", &value);
    if (err == ESP_ERR_NVS_NOT_FOUND) {
        printf("Chave não encontrada. Usando valor padrão: %d\n", value);
    }
    

2. O que fazer quando recebo ESP_ERR_NVS_NOT_ENOUGH_SPACE?

• Causa: Não há espaço suficiente na partição NVS para salvar novos dados.
• Solução:
  • Aumente o tamanho da partição NVS na tabela de partições.
  • Reduza a quantidade de dados armazenados ou apague chaves antigas:

    nvs_erase_key(my_handle, "old_key");
    nvs_commit(my_handle);
    

  • Use nvs_get_stats() para monitorar o uso de memória.

3. Como tratar ESP_ERR_NVS_INVALID_STATE ou dados corrompidos?

• Causa: A NVS está em um estado inválido, possivelmente devido a falhas de energia durante gravações.
• Solução:
  • Apague e reinicialize a partição NVS:

    esp_err_t err = nvs_flash_erase();
    if (err == ESP_OK) {
        nvs_flash_init();
    }
    

4. É possível alterar o tamanho máximo de uma string ou blob?

• Resposta: Sim, mas há limites físicos impostos pela memória flash:
  • Strings: Até 4000 bytes (incluindo terminador nulo).
  • Blobs: Até 508 KB ou 97,6% do tamanho da partição.
  • Certifique-se de que há espaço contíguo suficiente para armazenar os dados.

5. Como depurar erros inesperados durante operações da NVS?

• Solução:
  • Habilite logs detalhados no menuconfig:

    Component config -> NVS -> Enable debug logs
    

  • Use a função esp_err_to_name() para interpretar códigos de erro:

    esp_err_t err = nvs_set_i32(my_handle, "key", value);
    if (err != ESP_OK) {
        printf("Erro: %s\n", esp_err_to_name(err));
    }
    

6. Por que a leitura de dados falha após uma atualização de firmware?

• Causa: A tabela de partições foi modificada, ou a partição NVS foi sobrescrita durante a atualização.
• Solução:
  • Certifique-se de que a tabela de partições é consistente entre as versões de firmware.
  • Se necessário, implemente migrações de dados ao atualizar o firmware.

7. Como lidar com limitações de ciclo de vida da memória flash?

• Solução:
  • Minimize gravações frequentes, combinando alterações em uma única operação.
  • Para dados de alta frequência, use memórias não voláteis externas, como FRAM ou EEPROM.

8. Posso compartilhar a NVS entre diferentes dispositivos?

• Resposta: Não diretamente, pois a NVS é projetada para armazenamento local. Para compartilhar dados:
  • Sincronize com um servidor remoto.
  • Use interfaces de comunicação como Wi-Fi ou Bluetooth.

9. Existe suporte para dados criptografados na NVS?

• Resposta: Sim, a NVS suporta criptografia nativa no ESP32. Certifique-se de habilitá-la no menuconfig e configurar a partição nvs_keys.

10. O que acontece se a NVS atingir sua capacidade máxima?

• Resposta:
  • Gravações adicionais falharão com o erro ESP_ERR_NVS_NOT_ENOUGH_SPACE.
  • Use nvs_erase_key() ou nvs_erase_all() para liberar espaço.

11. A NVS é segura contra alterações não autorizadas?

• Resposta: Com a criptografia habilitada, os dados armazenados na NVS estão protegidos contra leitura ou modificação não autorizada. No entanto, ela não é resistente ao apagamento físico dos dados.

12. Como restaurar dados padrões em caso de erro crítico?

• Solução:
  • Defina uma lógica para apagar e restaurar dados padrões:

    esp_err_t err = nvs_flash_erase();
    if (err == ESP_OK) {
        nvs_flash_init();
        save_default_values(); // Salva valores padrões
    }
    

Resumo e Conclusão do Guia sobre NVS

A Biblioteca de Armazenamento Não Volátil (NVS) é uma ferramenta essencial no desenvolvimento com ESP32, oferecendo uma maneira confiável e eficiente de armazenar dados persistentes. Este guia detalhou os principais conceitos, funcionalidades, melhores práticas e exemplos de uso da NVS, capacitando desenvolvedores a utilizá-la de forma otimizada em suas aplicações.

Recapitulando os Principais Pontos

1. Introdução à NVS:
   • A NVS armazena pares de chave-valor em memória flash, com suporte para tipos de dados como inteiros, strings e blobs.
   • Ideal para armazenar configurações, estados de sensores e contadores persistentes.
2. Estrutura Interna e Funcionamento:
   • Baseada em logs e páginas para garantir integridade e minimizar desgaste da memória flash.
   • Gerencia automaticamente fragmentação e compactação.
3. Segurança:
   • Suporte para criptografia nativa protege dados sensíveis contra acesso não autorizado.
4. Melhores Práticas:
   • Use namespaces para organizar dados.
   • Minimize gravações frequentes para prolongar a vida útil da memória.
   • Monitore o uso de memória com ferramentas como nvs_get_stats().
5. Exemplos Reais:
   • Configurações de rede.
   • Contadores persistentes.
   • Dados de calibração de sensores.
6. Diagnóstico e Soluções de Problemas:
   • Métodos para identificar e corrigir erros, como ESP_ERR_NVS_NOT_FOUND ou ESP_ERR_NVS_NOT_ENOUGH_SPACE.

Destaques e Benefícios

• Persistência Confiável: Os dados armazenados permanecem intactos mesmo após falhas de energia ou reinicializações.
• Flexibilidade: Suporta diferentes tipos de dados e estruturas, com APIs intuitivas para leitura e gravação.
• Robustez: Projetada para resistir a falhas e minimizar fragmentação.

Recomendações Finais

1. Planeje a Estrutura da NVS:
   • Determine o tamanho ideal da partição e os namespaces necessários antes de implementar.
2. Teste em Condições Reais:
   • Simule cenários como falhas de energia durante gravações para validar a integridade dos dados.
3. Implemente Rotinas de Backup:
   • Para dados críticos, considere exportar periodicamente os dados da NVS para um servidor remoto ou dispositivo de armazenamento externo.
4. Atualize Regularmente o ESP-IDF:
   • Mantenha o framework atualizado para aproveitar melhorias e correções de bugs relacionados à NVS.

Próximos Passos

Se você deseja explorar mais sobre a NVS ou tecnologias relacionadas ao ESP32, considere:

• Desenvolver exemplos avançados: Como integrar a NVS com sistemas de arquivos FAT ou serviços de nuvem.
• Aprender sobre outras APIs de armazenamento do ESP-IDF: Como a SPIFFS ou LittleFS.
• Aprofundar-se em segurança embarcada: Implementar sistemas de proteção de dados completos.

Com este guia, você está pronto para utilizar a NVS de forma eficaz em seus projetos com ESP32.

The post Introdução à Biblioteca de Armazenamento Não Volátil (NVS) no ESP32-IDF first appeared on MCU & FPGA.