| 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.
Важное замечание: в первой строке файла 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. |