1.. _summary-cmd:
2
3Summary
4=======
5
6The ``espefuse.py summary`` command reads the eFuses from the chip and outputs them in text or json format. It is also possible to save it to a file. The command also supports eFuse filtering by name.
7
8Optional arguments:
9
10- ``--format`` - Select the summary format:
11    - ``summary`` - text format (default option).
12    - ``json`` - json format. Usage ``--format json``.
13    - ``value_only`` - only the value of the eFuse specified as an argument will be displayed. For more information, refer to the :ref:`Filtering eFuses <filtering-eFuses>` section.
14- ``--file`` - File to save the efuse summary. Usage ``--file efuses.json``.
15- List of eFuses to filter. For more information, refer to the :ref:`Filtering eFuses <filtering-eFuses>` section.
16
17Text Format Summary
18-------------------
19
20The text format of summary consists of 3 main columns:
21
221. This column consists of the eFuse name and additional information: the block name associated with this eFuse field and encoding errors (if any).
232. Description of eFuse field.
243. This column has human readable value, read/write protection status, raw value (hexadecimal or binary).
25
26Read and Write Protection Status
27^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
28
29The ``R/W`` output indicates a protection status of a specific eFuse field/block:
30
31- ``-/W`` indicates that read protection is set. Value of such eFuse field will always show all-zeroes, even though hardware may use the correct value. In espefuse v2.6 and newer, read-protected eFuse values are displayed as question marks (``??``). On earlier versions, they are displayed as zeroes.
32
33    .. code-block:: none
34
35        BLOCK1 (BLOCK1):
36        = ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/W
37
38- ``R/-`` indicates that write protection is set. No further bits can be set.
39- ``-/-`` means both read and write protection are set.
40
41Some eFuses have no protection at all, and some eFuses have only one read or write protection. There is no mark in the summary to expose it.
42
43Display Efuse Summary
44^^^^^^^^^^^^^^^^^^^^^
45
46The eFuse summary may vary from version to version of this tool and differ for different chips. Below is the summary for the {IDF_TARGET_NAME} chip.
47
48For details on the meaning of each eFuse value, refer to the `Technical Reference Manual <http://espressif.com/en/support/download/documents>`__.
49
50.. include:: inc/summary_{IDF_TARGET_NAME}.rst
51
52Json Format Summary
53-------------------
54
55The json representation of eFuses for the ESP32 chip is shown below.
56
57.. code-block:: none
58
59    > espefuse.py summary --format json
60
61    {
62        "ABS_DONE_0": {
63            "bit_len": 1,
64            "block": 0,
65            "category": "security",
66            "description": "Secure boot V1 is enabled for bootloader image",
67            "efuse_type": "bool",
68            "name": "ABS_DONE_0",
69            "pos": 4,
70            "readable": true,
71            "value": false,
72            "word": 6,
73            "writeable": true
74        },
75        "BLOCK1": {
76            "bit_len": 256,
77            "block": 1,
78            "category": "security",
79            "description": "Flash encryption key",
80            "efuse_type": "bytes:32",
81            "name": "BLOCK1",
82            "pos": 0,
83            "readable": true,
84            "value": "00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00",
85            "word": 0,
86            "writeable": true
87        },
88    ...
89        "CODING_SCHEME": {
90            "bit_len": 2,
91            "block": 0,
92            "category": "efuse",
93            "description": "Efuse variable block length scheme",
94            "efuse_type": "uint:2",
95            "name": "CODING_SCHEME",
96            "pos": 0,
97            "readable": true,
98            "value": "NONE (BLK1-3 len=256 bits)",
99            "word": 6,
100            "writeable": true
101        },
102    ....
103    }
104
105Save Json Format Summary To File
106--------------------------------
107
108.. code-block:: none
109
110    > espefuse.py summary --format json --file efuses.json
111
112    Connecting..........
113    Detecting chip type... Unsupported detection protocol, switching and trying again...
114    Connecting....
115    Detecting chip type... ESP32
116
117    === Run "summary" command ===
118    Saving efuse values to efuses.json
119
120.. _filtering-eFuses:
121
122Filtering Efuses and Displaying Only the Value
123----------------------------------------------
124
125The ``espefuse.py summary`` command supports filtering eFuses by name. The eFuses to filter needs to be specified as positional arguments. If no eFuses are specified, complete summary will be displayed. Example:
126
127.. code-block:: none
128
129    > espefuse.py summary ABS_DONE_0 BLOCK1
130
131    === Run "summary" command ===
132    EFUSE_NAME (Block) Description  = [Meaningful Value] [Readable/Writeable] (Hex Value)
133    ----------------------------------------------------------------------------------------
134    Security fuses:
135    ABS_DONE_0 (BLOCK0)                                Secure boot V1 is enabled for bootloader image     = False R/W (0b0)
136    BLOCK1 (BLOCK1)                                    Flash encryption key
137    = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
138
139If ``--format value_only`` is specified, only the value of the eFuse specified as an argument will be displayed. Only one eFuse can be specified as an argument for this format. Example:
140
141.. code-block:: none
142
143    > espefuse.py summary --format value_only MAC
144
145    === Run "summary" command ===
146    00:00:00:00:00:00 (CRC 0x00 OK)
147