1.. _burn-custom-mac-cmd:
2
3Burn Custom Mac
4===============
5
6The ``espefuse.py burn_custom_mac`` command burns a 48-bit Custom MAC Address.
7
8Positional arguments:
9
10* ``MAC``. Custom MAC Address (``CUSTOM_MAC``) to burn given in hexadecimal format with bytes separated by colons (e.g. AA:CD:EF:01:02:03)
11
12Optional arguments:
13
14* ``--force-write-always``. Write the eFuse key even if it looks like it is already been written, or is write protected. Note that this option can't disable write protection, or clear any bit which has already been set.
15
16If ``CUSTOM_MAC`` is placed in an eFuse block with a coding scheme and already has data then it is not possible to write new data without breaking the encoding. The correct way is to contact Espressif to order chips with ``CUSTOM_MAC`` pre-burned from the factory. Another way is, it is not recommended, to use the ``--force-write-always`` flag to ignore the encoding violation.
17
18.. only:: esp32
19
20    This command burns a few eFuse fields:
21
22    1. ``CUSTOM_MAC``
23    2. ``MAC_VERSION`` = 1
24    3. ``CUSTOM_MAC_CRC`` = crc8(``CUSTOM_MAC``)
25
26    .. code-block:: none
27
28        > espefuse.py  burn_custom_mac 48:63:92:15:72:16
29
30        === Run "burn_custom_mac" command ===
31            - 'MAC_VERSION' (Version of the MAC field) 0x00 -> 0x1
32            - 'CUSTOM_MAC' (Custom MAC) 0x000000000000 -> 0x167215926348
33            - 'CUSTOM_MAC_CRC' (CRC of custom MAC) 0x00 -> 0x75
34
35        Check all blocks for burn...
36        idx, BLOCK_NAME,          Conclusion
37        [03] BLOCK3               is empty, will burn the new value
38        .
39        This is an irreversible operation!
40        Type 'BURN' (all capitals) to continue.
41        BURN
42        BURN BLOCK3  - OK (write block == read block)
43        Reading updated efuses...
44        Custom MAC Address version 1: 48:63:92:15:72:16 (CRC 0x75 OK)
45        Successful
46
47        > espefuse.py summary
48        ...
49        MAC_VERSION (BLOCK3):                              Version of the MAC field                           = Custom MAC in BLOCK3 R/W (0x01)
50        CUSTOM_MAC (BLOCK3):                               Custom MAC
51        = 48:63:92:15:72:16 (CRC 0x75 OK) R/W
52        CUSTOM_MAC_CRC (BLOCK3):                           CRC of custom MAC                                  = 117 R/W (0x75)
53        ...
54        BLOCK3 (BLOCK3):                                   Variable Block 3
55        = 75 48 63 92 15 72 16 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 R/W
56
57.. only:: esp32c2
58
59    This command burns a few eFuse fields:
60
61    1. ``CUSTOM_MAC``
62    2. ``CUSTOM_MAC_USED`` = 1
63
64    .. code-block:: none
65
66        > espefuse.py burn_custom_mac 48:63:92:15:72:16
67
68        === Run "burn_custom_mac" command ===
69            - 'CUSTOM_MAC' (Custom MAC addr) 0x000000000000 -> 0x167215926348
70
71        Check all blocks for burn...
72        idx, BLOCK_NAME,          Conclusion
73        [00] BLOCK0               is not empty
74                (written ): 0x0000000000000080
75                (to write): 0x0400000000000000
76                (coding scheme = NONE)
77        [01] BLOCK1               is empty, will burn the new value
78        .
79        This is an irreversible operation!
80        Type 'BURN' (all capitals) to continue.
81        BURN
82        BURN BLOCK1  - OK (write block == read block)
83        BURN BLOCK0  - OK (all write block bits are set)
84        Reading updated efuses...
85        Custom MAC Address: 48:63:92:15:72:16 (OK)
86        Successful
87
88        > espefuse.py summary
89        ...
90        CUSTOM_MAC_USED (BLOCK0)                           Enable CUSTOM_MAC programming                      = True R/W (0b1)
91        CUSTOM_MAC (BLOCK1)                                Custom MAC addr
92        = 48:63:92:15:72:16 (OK) R/W
93
94.. only:: esp32c3 or esp32s2 or esp32s3
95
96    This command burns a given MAC to ``CUSTOM_MAC`` field.
97
98    .. code-block:: none
99
100        > espefuse.py burn_custom_mac 48:63:92:15:72:16
101
102        === Run "burn_custom_mac" command ===
103            - 'CUSTOM_MAC' (Custom MAC Address) 0x000000000000 -> 0x167215926348
104
105        Check all blocks for burn...
106        idx, BLOCK_NAME,          Conclusion
107        [03] BLOCK_USR_DATA       is empty, will burn the new value
108        .
109        This is an irreversible operation!
110        Type 'BURN' (all capitals) to continue.
111        BURN
112        BURN BLOCK3  - OK (write block == read block)
113        Reading updated efuses...
114        Custom MAC Address: 48:63:92:15:72:16 (OK)
115        Successful
116
117        > espefuse.py summary
118        ...
119        CUSTOM_MAC (BLOCK3)                                Custom MAC Address
120        = 48:63:92:15:72:16 (OK) R/W