Программирование ARM ESP32: утилита генерации раздела NVS Mon, April 22 2024  

Поделиться

Нашли опечатку?

Пожалуйста, сообщите об этом - просто выделите ошибочное слово или фразу и нажмите Shift Enter.

ESP32: утилита генерации раздела NVS Печать
Добавил(а) microsin   

Утилита nvs_partition_gen.py (находится в папке компонентов components\ nvs_flash\ nvs_partition_generator\ каталога установки ESP-IDF [2]) создает двоичный файл раздела на основе пары ключей, предоставленных в файле CSV. Двоичный файл совместим с архитектурой NVS, определенной в библиотеке энергонезависимого хранилища (Non-Volatile Storage [3]). Эта утилита идеально подходит для генерации двоичных данных типа BLOB, содержащих специфичную информацию ODM/OEM. Эти данные могут быть прошиты внешним оборудованием во время производства, что позволяет производителям генерировать множество экземпляров firmware приложения с индивидуально настроенными параметрами для каждого устройства (такими как серийный номер, данные калибровки, приватные данные и т. п.).

Чтобы можно было использовать эту утилиту в режиме шифрования (encryption mode), установите пакет криптографии (cryptography package). Все необходимые пакеты включены в файл requirements.txt, который находится в корневом каталоге среды установки ESP-IDF (каталог наподобие Espressif\frameworks\esp-idf-v4.4).

[Формат CSV]

Каждая строка в файле *.csv должна содержать 4 параметра, отделенных друг от друга запятой. Таблица ниже предоставляет описание для каждого из этих параметров.

Таблица 1. Параметры входного файла CSV для утилиты NVS Partition Generator.

Параметр Описание Примечания
1 Key Ключ данных. С помощью этого ключа впоследствии приложение может получить доступ к данным.  
2 Type Тип, поддерживаются значения file, data и namespace.  
3 Encoding Поддерживаемые значения: u8, i8, u16, i16, u32, i32, u64, i64, string, hex2bin, base64 и binary. Здесь указывается способ кодирования фактических значений данных в результирующем двоичном файле. Разница между строковой и двоичной кодировкой заключается в том, что строковые данные заканчиваются символом NULL, в то время как двоичные данные - нет. На данный момент для типа файла поддерживается только  кодировка hex2bin, base64, string и binary.
4 Value Значение данных. Encoding и Value для поля типа namespace должны быть пустыми. Encoding и Value для namespace фиксированы и не конфигурируются (любые значения игнорируются).

Важное замечание: в первой строке файла CSV должна содержать заголовок таблицы, и эта строка не должна конфигурироваться. Строка заголовка представлена в виде комментария (начинается на символ #). Другие строки комментариев не допускаются, все остальные строки, кроме первой, должны содержать параметры. Первая запись должна быть типа namespace. Убедитесь, что до и после символа разделителя ',' нет пробелов.

Ниже приведен пример дампа такого файла CSV:

# key,type,encoding,value
namespace_name,namespace,,
key1,data,u8,1
key2,file,string,/path/to/file

[NVS Entry и ассоциация с Namespace]

Когда в файле CSV встретилась запись namespace, каждая последующая запись будет обрабатываться как часть пространства имен, пока не будет найдена следующая запись namespace. В этой точке все последующие записи будут обрабатываться как часть нового пространства имен.

Важное замечание: в файле CSV первой всегда должна быть запись namespace.

Поддержка Multipage Blob. По умолчанию двоичные BLOB распространяются не несколько страницы flash, и записываются в формате, упомянутом секции "Структура записи" документации [3]. Если предполагается использовать более старый формат, утилита NVS Partition Generator предоставляет опцию для запрета этой функции.

Поддержка шифрования/дешифровки. Утилита NVS Partition Generator также позволяет создавать зашифрованный двоичный файл. Также утилита может расшифровывать двоичный файл. Используется шифрование AES-XTS, подробности см. в разделе "Шифрование NVS" документации [3].

[Запуск утилиты]

Подсказка по использованию:

python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...

Необязательные аргументы:

+------------+----------------------------------------------------------------------+
| Параметр   |                           Описание                                   |
+============+======================================================================+
| -h, --help |        Отобразит подсказку по использованию                          |
+------------+----------------------------------------------------------------------+

Команды (для дополнительной подсказки запустите nvs_partition_gen.py {command} -h):

+--------------+--------------------------------------------------------------------+
| Параметр     |                           Описание                                 |
+==============+====================================================================+
| generate     |      Генерация раздела NVS                                         |
+--------------+--------------------------------------------------------------------+
| generate-key |      Генерация ключей шифрования                                   |
+--------------+--------------------------------------------------------------------+
|  encrypt     |      Генерация шифрованного раздела NVS                            |
+--------------+--------------------------------------------------------------------+
|  decrypt     |      Расшифровка раздела NVS                                       |
+--------------+--------------------------------------------------------------------+

Для генерации раздела NVS (по умолчанию):

python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
                                     input output size

Позиционные аргументы:

+--------------+--------------------------------------------------------------------+
| Параметр     |                         Описание                                   |
+==============+====================================================================+
| input        |      Путь до обрабатываемого файла CSV                             |
+--------------+--------------------------------------------------------------------+
| output       |      Путь до выходного двоичного файла NVS                         |
+--------------+--------------------------------------------------------------------+
| size         |      Размер раздела NVS в байтах (должен нацело делиться на 4096)  |
+--------------+--------------------------------------------------------------------+

Необязательные аргументы:

+-----------------+-----------------------------------------------------------------+
| Параметр        |                          Описание                               |
+=================+=================================================================+
| -h, --help      |    Отобразит подсказку по использованию                         |
+-----------------+-----------------------------------------------------------------+
| --version {1,2} |    Установит версию multipage blob.                             |
|                 |    Версия 1 - запрещена поддержка Multipage blob.               |
|                 |    Версия 2 - разрешена поддержка Multipage blob.               |
|                 |    По умолчанию: Version 2                                      |
+-----------------+-----------------------------------------------------------------+
| --outdir OUTDIR |    Выходной каталог для сохранения созданных файлов             |
|                 |    (по умолчанию используется текущий каталог)                  |
+-----------------+-----------------------------------------------------------------+

Например, можно запустить утилиту для генерации раздела NVS следующей командой (пример файла CSV предоставляется вместе с утилитой):

python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000

Для генерации только ключей шифрования:

python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
                                         [--outdir OUTDIR]

Необязательные аргументы:

+--------------------+--------------------------------------------------------------+
| Параметр           |                          Описание                            |
+====================+==============================================================+
| -h, --help         |    Отобразит подсказку по использованию                      |
+--------------------+--------------------------------------------------------------+
| --keyfile KEYFILE  |    Путь до выходного файла ключей шифрования                 |
+--------------------+--------------------------------------------------------------+
| --outdir OUTDIR    |    Выходной каталог для сохранения созданных файлов          |
|                    |    (по умолчанию используется текущий каталог)               |
+--------------------+--------------------------------------------------------------+

Например, можно запустить утилиту для генерации ключей шифрования следующей командой:

python nvs_partition_gen.py generate-key

Для генерации шифрованного раздела NVS:

python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
                                    [--keyfile KEYFILE] [--inputkey INPUTKEY]
                                    [--outdir OUTDIR]
                                    input output size

Позиционные аргументы:

+--------------+--------------------------------------------------------------------+
| Параметр     |                         Описание                                   |
+==============+====================================================================+
| input        |      Путь до обрабатываемого файла CSV                             |
+--------------+--------------------------------------------------------------------+
| output       |      Путь до выходного двоичного файла NVS                         |
+--------------+--------------------------------------------------------------------+
| size         |      Размер раздела NVS в байтах (должен нацело делиться на 4096)  |
+--------------+--------------------------------------------------------------------+

Необязательные аргументы:

+---------------------+-------------------------------------------------------------+
| Параметр            |                          Описание                           |
+=====================+=============================================================+
| -h, --help          |    Отобразит подсказку по использованию                     |
+---------------------+-------------------------------------------------------------+
| --version {1,2}     |    Установит версию multipage blob.                         |
|                     |    Версия 1 - запрещена поддержка Multipage blob.           |
|                     |    Версия 2 - разрешена поддержка Multipage blob.           |
|                     |    По умолчанию: Version 2                                  |
+---------------------+-------------------------------------------------------------+
| --keygen            |    Генерация ключа для шифрования раздела NVS               |
+---------------------+-------------------------------------------------------------+
| --keyfile KEYFILE   |    Путь до выходного файла ключей шифрования                |
+---------------------+-------------------------------------------------------------+
| --inputkey INPUTKEY |    Файл, где находится ключ для шифрования раздела NVS      |
+---------------------+-------------------------------------------------------------+
| --outdir OUTDIR     |    Выходной каталог для сохранения созданных файлов         |
|                     |    (по умолчанию используется текущий каталог)              |
+---------------------+-------------------------------------------------------------+

Ниже показаны примеры команд для шифрования раздела (пример файла CSV предоставляется вместе с утилитой). Шифрование, при котором утилите разрешено генерировать ключи шифрования (будет создан ключ шифрования в файле /keys/keys-.bin):

python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin
 0x3000 --keygen

Шифрование, при котором утилите разрешено генерировать ключи шифрования и сохранить их в файл с указанным именем (будет создан ключ шифрования в файле /keys/sample_keys.bin):

python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin
 0x3000 --keygen --keyfile sample_keys.bin

Важное замечание: этот новый созданный файл будет содержать ключи шифрование в каталоге keys/, совместимый со структурой NVS key-partition (подробнее см. секцию "Раздел ключа NVS" в документации [3]).

Для расшифровки раздела NVS:

python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output

Позиционные аргументы:

+--------------+--------------------------------------------------------------------+
| Параметр     |                         Описание                                   |
+==============+====================================================================+
| input        |      Путь до шифрованного раздела NVS                              |
+--------------+--------------------------------------------------------------------+
| key          |      Путь до файла с ключами                                       |
+--------------+--------------------------------------------------------------------+
| output       |      Путь до выходного двоичного расшифрованного файла NVS         |
+--------------+--------------------------------------------------------------------+

Необязательные аргументы:

+---------------------+-------------------------------------------------------------+
| Параметр            |                          Описание                           |
+=====================+=============================================================+
| -h, --help          |    Отобразит подсказку по использованию                     |
+---------------------+-------------------------------------------------------------+
| --outdir OUTDIR     |    Выходной каталог для сохранения созданных файлов         |
|                     |    (по умолчанию используется текущий каталог)              |
+---------------------+-------------------------------------------------------------+

Можно запустить утилиту для расшифровки раздела NVS следующей командой:

python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin

Также можно предоставить номер версии формата: 1 для запрета поддержки Multipage Blob (Version 1), 2 для разрешения поддержки Multipage Blob (Version 2, используется по умолчанию).

Multipage Blob Support Disabled (Version 1). Ниже показана команда, которая использует версию 1 формата (пример CSV-файла предоставляется вместе с утилитой):

python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin
 0x3000 --version 1

Multipage Blob Support Enabled (Version 2). Ниже показана команда, которая использует версию 3 формата (пример CSV-файла предоставляется вместе с утилитой):

python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin
 0x4000 --version 2

Важное замечание: минимальный необходимый размер раздела NVS 0x3000 байт. Когда двоичный файл прошивается в память устройства, убедитесь, что он соответствует конфигурации приложения (sdkconfig).

[Дополнительные пояснения]

1. Утилита не проверяет наличие дубликатов ключей, и запишет данные, относящиеся к обоим ключам. Необходимо убедиться. что ключи отличаются друг от друга.

2. После создания новой страницы данные не будут записываться в область, оставшуюся свободной на предыдущей странице. Поля в файле CSV должны быть упорядочены таким образом, чтобы оптимизировать использование flash-памяти.

3. Утилита поддерживает использование CSV-файла с типом данных в виде многострочного текста и одиночные строки.

4. 64-разрядный тип данных в настоящее время не поддерживается.

[Словарик]

BLOB binary large object, двоичные данные переменной длины.

NVS Non-Volatile Storage, энергонезависимое хранилище данных.

[Ссылки]

1. ESP32 NVS Partition Generator Utility site:docs.espressif.com.
2. Установка среды разработки ESP-IDF для ESP32.
3. ESP32: библиотека энергонезависимого хранилища данных.

 

Добавить комментарий


Защитный код
Обновить

Top of Page