mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 19:13:21 +00:00
Doc/review api ref storage
This commit is contained in:
Kirill Chalov
committed by
Krzysztof Budzynski
Krzysztof Budzynski
parent
e20b37aff9
commit
4faf2de035
+111
-89
@@ -1,50 +1,56 @@
|
||||
Manufacturing Utility
|
||||
=====================
|
||||
|
||||
|
||||
Introduction
|
||||
----------------
|
||||
------------
|
||||
|
||||
This utility is designed to create instances of factory NVS partition images on a per-device basis for mass manufacturing purposes. The NVS partition images are created from CSV files containing user-provided configurations and values.
|
||||
|
||||
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using:
|
||||
|
||||
- esptool.py
|
||||
- Flash Download tool (available on Windows only)
|
||||
- Direct flash programming
|
||||
|
||||
This utility is designed to create per device instances factory nvs partition images for mass manufacturing purposes.
|
||||
These images are created from user provided configuration and values csv files.
|
||||
This utility only creates the manufacturing binary images and you can choose to use esptool.py or Windows based flash programming utility or direct flash programming to program these images at the time of manufacturing.
|
||||
|
||||
Prerequisites
|
||||
------------------
|
||||
-------------
|
||||
|
||||
**This utility is dependent on the esp-idf nvs partition utility.**
|
||||
**This utility is dependent on esp-idf's NVS partition utility.**
|
||||
|
||||
* Operating System requirements:
|
||||
- Linux / MacOS / Windows (standard distributions)
|
||||
* Operating System requirements:
|
||||
- Linux / MacOS / Windows (standard distributions)
|
||||
|
||||
* The following packages are needed for using this utility:
|
||||
- Python version: 2.7 (minimum) is required.
|
||||
- Link to install python: <https://www.python.org/downloads/>
|
||||
* The following packages are needed to use this utility:
|
||||
- Python version: 2.7 (minimum) is required. You can find it here: <https://www.python.org/downloads/>
|
||||
|
||||
.. note:: Make sure the python path is set in the PATH environment variable before using this utility.
|
||||
.. note::
|
||||
|
||||
Before using this utility, please make sure that:
|
||||
- The path to Python is added to the PATH environment variable.
|
||||
- You have installed the packages from `requirement.txt`, the file in the root of the esp-idf directory.
|
||||
|
||||
Make sure to include packages from `requirement.txt` in top level IDF directory.
|
||||
|
||||
Workflow
|
||||
-----------
|
||||
--------
|
||||
|
||||
.. blockdiag::
|
||||
|
||||
blockdiag {
|
||||
A [label = "CSV Configuration file"];
|
||||
B [label = "Master CSV Values file"];
|
||||
B [label = "Master Value CSV file"];
|
||||
C [label = "Binary files", stacked];
|
||||
|
||||
A -- B -> C
|
||||
}
|
||||
|
||||
|
||||
CSV Configuration File:
|
||||
------------------------
|
||||
CSV Configuration File
|
||||
----------------------
|
||||
|
||||
This file contains the configuration of the device to be manufactured.
|
||||
This file contains the configuration of the device to be flashed.
|
||||
|
||||
The data in configuration file **must** have the following format (`REPEAT` tag is optional)::
|
||||
The data in the configuration file has the following format (the `REPEAT` tag is optional)::
|
||||
|
||||
name1,namespace, <-- First entry should be of type "namespace"
|
||||
key1,type1,encoding1
|
||||
@@ -53,12 +59,12 @@ The data in configuration file **must** have the following format (`REPEAT` tag
|
||||
key3,type3,encoding3
|
||||
key4,type4,encoding4
|
||||
|
||||
.. note:: First entry in this file should always be ``namespace`` entry.
|
||||
.. note:: The first line in this file should always be the ``namespace`` entry.
|
||||
|
||||
Each row should have these 3 parameters: ``key,type,encoding`` separated by comma.
|
||||
If ``REPEAT`` tag is present, the value corresponding to this key in the Master CSV Values File will be the same for all devices.
|
||||
Each line should have three parameters: ``key,type,encoding``, separated by a comma.
|
||||
If the ``REPEAT`` tag is present, the value corresponding to this key in the master value CSV file will be the same for all devices.
|
||||
|
||||
*Please refer to README of nvs_partition utility for detailed description of each parameter.*
|
||||
*Please refer to README of the NVS Partition Generator utility for detailed description of each parameter.*
|
||||
|
||||
Below is a sample example of such a configuration file::
|
||||
|
||||
@@ -69,115 +75,131 @@ Below is a sample example of such a configuration file::
|
||||
device_no,data,i32
|
||||
|
||||
|
||||
.. note:: Make sure there are no spaces before and after ',' in the configuration file.
|
||||
.. note::
|
||||
|
||||
Master CSV Values File:
|
||||
------------------------
|
||||
Make sure there are **no spaces**:
|
||||
- before and after ','
|
||||
- at the end of each line in a CSV file
|
||||
|
||||
This file contains details of the device to be manufactured. Each row in this file corresponds to a device instance.
|
||||
|
||||
Master Value CSV File
|
||||
---------------------
|
||||
|
||||
This file contains details of the devices to be flashed. Each line in this file corresponds to a device instance.
|
||||
|
||||
The data in values file **must** have the following format::
|
||||
The data in the master value CSV file has the following format::
|
||||
|
||||
key1,key2,key3,.....
|
||||
value1,value2,value3,....
|
||||
|
||||
.. note:: First line in this file should always be the ``key`` names. All the keys from the configuration file should be present here in the **same order**. This file can have additional columns(keys) and they will act like metadata and would not be part of final binary files.
|
||||
.. note:: The first line in the file should always contain the ``key`` names. All the keys from the configuration file should be present here in the **same order**. This file can have additional columns (keys). The additional keys will be treated as metadata and would not be part of the final binary files.
|
||||
|
||||
Each row should have the ``value`` of the corresponding keys, separated by comma. If key has ``REPEAT`` tag, then its corresponding value **must** be entered in the second line only. Keep the entry empty for this value in the next lines. Below is the description of this parameter:
|
||||
Each line should contain the ``value`` of the corresponding keys, separated by a comma. If the key has the ``REPEAT`` tag, its corresponding value **must** be entered in the second line only. Keep the entry empty for this value in the following lines.
|
||||
|
||||
The description of this parameter is as follows:
|
||||
|
||||
``value``
|
||||
Data value.
|
||||
Data value
|
||||
|
||||
Below is a sample example of such a values file::
|
||||
Data value is the value of data corresponding to the key.
|
||||
|
||||
Below is a sample example of a master value CSV file::
|
||||
|
||||
id,firmware_key,serial_no,device_no
|
||||
1,1a2b3c4d5e6faabb,A1,101
|
||||
2,1a2b3c4d5e6fccdd,,102
|
||||
3,1a2b3c4d5e6feeff,,103
|
||||
|
||||
.. note:: *If 'REPEAT' tag is present, a new Master CSV Values File is created in the same folder as the input Master CSV File with the values inserted at each line for the key with 'REPEAT' tag.*
|
||||
.. note:: *If the 'REPEAT' tag is present, a new master value CSV file will be created in the same folder as the input Master CSV File with the values inserted at each line for the key with the 'REPEAT' tag*.
|
||||
|
||||
.. note:: *Intermediate CSV files are created by this utility which are input to the nvs partition utility to generate the binary files.*
|
||||
This utility creates intermediate CSV files which are used as input for the NVS partition utility to generate the binary files.
|
||||
|
||||
The format of this intermediate csv file will be::
|
||||
The format of this intermediate CSV file is as follows::
|
||||
|
||||
key,type,encoding,value
|
||||
key,namespace, ,
|
||||
key1,type1,encoding1,value1
|
||||
key2,type2,encoding2,value2
|
||||
|
||||
.. note:: An intermediate csv file will be created for each device instance.
|
||||
An instance of an intermediate CSV file will be created for each device on an individual basis.
|
||||
|
||||
|
||||
Running the utility
|
||||
----------------------
|
||||
-------------------
|
||||
|
||||
The mfg\_gen.py utility is using the generated CSV Configuration file and Master CSV Values file and is generating per device instance factory images.
|
||||
The mfg\_gen.py utility uses the generated CSV Configuration file and the master value CSV file to generate factory images for each device.
|
||||
|
||||
*Sample CSV Configuration file and Master CSV Values file is provided with this utility.*
|
||||
*A sample CSV Configuration file and a master value CSV file are both provided with this utility.*
|
||||
|
||||
**Usage**::
|
||||
|
||||
$ ./mfg_gen.py [-h] [--conf CONFIG_FILE] [--values VALUES_FILE]
|
||||
./mfg_gen.py [-h] [--conf CONFIG_FILE] [--values VALUES_FILE]
|
||||
[--prefix PREFIX] [--fileid FILEID] [--outdir OUTDIR]
|
||||
[--size PART_SIZE] [--version {v1,v2}]
|
||||
[--keygen {true,false}] [--encrypt {true,false}]
|
||||
[--keyfile KEYFILE]
|
||||
|
||||
The description of the arguments is given in the table below.
|
||||
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| Arguments | Description |
|
||||
+========================+==============================================================================================+
|
||||
| --conf CONFIG_FILE | the input configuration csv file |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --values VALUES_FILE | the input values csv file |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --prefix PREFIX | the unique name as each filename prefix |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --fileid FILEID | the unique file identifier(any key in values file) |
|
||||
| | as each filename suffix (Default: numeric value(1,2,3...)) |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --outdir OUTDIR | the output directory to store the files created (Default: current directory) |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --size PART_SIZE | Size of NVS Partition in bytes (must be multiple of 4096) |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --version {v1,v2} | Set version. Default: v2 |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --keygen {true,false} | Generate keys for encryption. |
|
||||
| | Default: false |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --encrypt {true,false} | Set encryption mode. Default: false |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
| --keyfile KEYFILE | File having key for encryption (Applicable only if encryption mode is true) |
|
||||
+------------------------+----------------------------------------------------------------------------------------------+
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| Arguments | Description | Default Value |
|
||||
+========================+============================================================+===================+
|
||||
| --conf CONFIG_FILE | Path to existing CSV configuration file | |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --values VALUES_FILE | Path to existing master value CSV file | |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --prefix PREFIX | Unique filename prefix | |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --fileid FILEID | Unique file identifier (any key in the file with values) | numeric value |
|
||||
| | as a filename suffix | (1,2,3...) |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --outdir OUTDIR | Output directory to store created files | current directory |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --size PART_SIZE | Size of NVS Partition in bytes (must be multiple of 4096) | |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --version {v1,v2} | Set version | v2 |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --keygen {true,false} | Generate keys for encryption | false |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --encrypt {true,false} | Set encryption mode | false |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
| --keyfile KEYFILE | File storing key for encryption (Applicable only if | |
|
||||
| | Encryption mode is true). | |
|
||||
+------------------------+------------------------------------------------------------+-------------------+
|
||||
|
||||
*You can use the below commands to run this utility with the sample files provided*::
|
||||
|
||||
$ ./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000
|
||||
*To run this utility with the provided sample files, use the commands below*::
|
||||
|
||||
$ ./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_multipage_blob.csv --prefix Fan --size 0x4000
|
||||
|
||||
.. note:: When you use this utility to generate per device instance factory images --conf, --values, --prefix and --size arguments are mandatory.
|
||||
|
||||
$ ./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000 --outdir tmp
|
||||
./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000
|
||||
|
||||
.. note:: The --outdir directory is created if not present.
|
||||
./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_multipage_blob.csv --prefix Fan --size 0x4000
|
||||
|
||||
.. note:: The file path given in the ``file`` type in the values file is expected to be relative to the current directory from which you are running the utility.
|
||||
|
||||
$ ./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000 --encrypt true --keygen true
|
||||
When you use this utility to generate factory images on a per device basis, keep in mind that the arguments --conf, --values, --prefix, and --size are mandatory.
|
||||
|
||||
.. note:: ``keys/`` directory is generated with the encryption keys filename of the form ``prefix-fileid-keys.bin``.
|
||||
|
||||
*You can also run the below command to use the utility to* **only** *generate encryption keys binary file ( following example 'keys/' directory is created in current path), which can further be used to encrypt per device instance factory images*::
|
||||
|
||||
$ ./mfg_gen.py --keygen true
|
||||
|
||||
$ ./mfg_gen.py --keygen true --keyfile encr_keys.bin
|
||||
./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000 --outdir tmp
|
||||
|
||||
.. note:: When running utility to generate only ``keys``, if --keyfile is given it will generate encryption keys with filename given in --keyfile argument.
|
||||
.. note:: If the --outdir directory does not exist, it will be created.
|
||||
|
||||
.. note:: When you use this utility to generate only encryption keys --keygen argument is mandatory.
|
||||
The master value CSV file should have the path in the ``file`` type relative to the directory from which you are running the utility.
|
||||
|
||||
.. note:: The default numeric value: 1,2,3... of ``fileid`` argument, corresponds to each row having device instance values in master csv values file.
|
||||
./mfg_gen.py --conf samples/sample_config.csv --values samples/sample_values_singlepage_blob.csv --prefix Fan --size 0x3000 --encrypt true --keygen true
|
||||
|
||||
.. note:: ``bin/`` **and** ``csv/`` **sub-directories are created in the** ``outdir`` **directory specified while running this utility. The binary files generated will be stored in** ``bin/`` **and the intermediate csv files generated will be stored in** ``csv/``.
|
||||
.. note:: The generated ``keys/`` directory is named as the file with encryption keys of the form ``prefix-fileid-keys.bin``.
|
||||
|
||||
*If you* **only** *want to generate a binary file with encryption keys, you can run the command below.*::
|
||||
|
||||
./mfg_gen.py --keygen true
|
||||
|
||||
.. note:: When you use this utility to generate encryption keys only, the --keygen argument is mandatory.
|
||||
|
||||
In the following example, the 'keys/' directory will be created at the current path. This binary file can further be used to encrypt factory images created on the per device basis*.::
|
||||
|
||||
./mfg_gen.py --keygen true --keyfile encr_keys.bin
|
||||
|
||||
.. note:: When running the utility to generate encryption keys only, if --keyfile is given, it will generate encryption keys with the filename given in the --keyfile argument.
|
||||
|
||||
The default numeric value: 1,2,3... of the ``fileid`` argument corresponds to each line bearing device instance values in the master value CSV file.
|
||||
|
||||
While running the manufacturing utility, the following folders will be created in the specified ``outdir`` directory:
|
||||
|
||||
- ``bin/`` for storing the generated binary files
|
||||
- ``csv/`` for storing the generated intermediate CSV files
|
||||
|
||||
Reference in New Issue
Block a user