|
Утилита 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: библиотека энергонезависимого хранилища данных. |
