终极指南：使用esptool读取与修改ESP芯片唯一标识符（2025最新版）

2026-02-05 05:00:18作者：邵娇湘

项目地址：https://gitcode.com/gh_mirrors/esp/esptool

引言：为什么芯片唯一标识符如此重要？

你是否曾在批量生产中因无法区分每颗ESP芯片而头疼？是否在设备管理时因缺乏唯一标识而导致系统混乱？作为嵌入式开发者，掌握芯片唯一标识符（Unique Identifier, UID）的读取与修改技术，是解决这些问题的关键。本指南将带你深入了解如何使用esptool工具链，专业、高效地操作ESP芯片的唯一标识符，从根本上解决设备身份识别难题。

读完本文，你将能够：

理解ESP芯片UID的存储机制与安全特性
使用esptool读取不同型号ESP芯片的UID
掌握通过efuse修改自定义MAC地址的完整流程
规避操作efuse的风险，确保系统稳定性
应用UID实现设备的唯一身份认证与管理

ESP芯片唯一标识符的底层实现

UID存储架构与硬件基础

ESP系列芯片的唯一标识符主要通过两种方式实现：工厂预设的MAC地址和用户可配置的efuse存储区。以下是ESP32芯片的efuse存储架构示意图：

classDiagram
    class EfuseBlock0 {
        +MAC_VERSION : 2 bits
        +MAC_ADDR : 48 bits
        +MAC_CRC : 8 bits
        +CHIP_VER_REV : 3 bits
        +WAFER_VERSION : 4 bits
    }
    
    class EfuseBlock1 {
        +BLOCK1 : 256 bits
        +CODING_SCHEME : 2 bits
    }
    
    class EfuseBlock2 {
        +BLOCK2 : 256 bits
        +SECURE_BOOT_EN : 1 bit
    }
    
    class EfuseBlock3 {
        +MAC_VERSION : 1 bit
        +CUSTOM_MAC : 48 bits
        +CUSTOM_MAC_CRC : 8 bits
        +BLK3_PART_RESERVE : 1 bit
    }
    
    EfuseBlock0 --> "包含出厂MAC" EfuseBlock3
    EfuseBlock3 --> "可选自定义MAC" EfuseBlock0
    EfuseBlock1 --> "影响UID存储方式" EfuseBlock3

ESP芯片的UID存储具有以下关键特性：

出厂MAC地址存储在efuse Block0，不可修改
自定义MAC地址可存储在efuse Block3，需配合MAC_VERSION位使用
支持3/4编码方案（CODING_SCHEME），影响数据存储密度
具有CRC校验机制，确保数据完整性
采用位级写入保护，一旦烧写无法恢复

不同ESP型号的UID差异

芯片型号	UID长度	存储位置	可修改性	安全特性
ESP32	48 bits	Block0 (出厂) / Block3 (自定义)	部分可修改	CRC校验, 写保护
ESP32-C3	48 bits	Block0 (出厂) / Block3 (自定义)	部分可修改	CRC校验, 写保护
ESP32-S3	64 bits	Block0 (出厂) / Block3 (自定义)	部分可修改	ECC校验, 读保护
ESP8266	48 bits	eFuse	不可修改	无校验
ESP32-C6	64 bits	Block0 (出厂) / Block3 (自定义)	部分可修改	AES加密存储

环境准备与工具链安装

系统环境要求

操作系统：Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+, CentOS 8+)
Python版本：3.7 - 3.11（不支持Python 3.12及以上版本）
pip版本：20.0.0以上
硬件连接：USB转UART调试器（如CP2102、CH340），确保驱动正常安装

安装esptool工具链

# 通过pip安装最新稳定版
pip install esptool

# 从源码仓库安装开发版（包含最新特性）
git clone https://gitcode.com/gh_mirrors/esp/esptool.git
cd esptool
pip install -e .

# 验证安装是否成功
esptool.py version
espefuse.py version

安装成功后，你将看到类似以下输出：

esptool.py v4.7.0
espsecure.py v4.7.0
espefuse.py v4.7.0

配置udev规则（Linux系统）

为避免Linux系统下的权限问题，创建udev规则文件：

# 创建udev规则文件
sudo nano /etc/udev/rules.d/99-esp32.rules

# 添加以下内容
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", MODE="0666", GROUP="dialout"
SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE="0666", GROUP="dialout"
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666", GROUP="dialout"

# 重新加载udev规则
sudo udevadm control --reload-rules
sudo udevadm trigger

读取ESP芯片唯一标识符的完整流程

进入bootloader模式

ESP芯片必须进入bootloader模式才能与esptool通信。以下是不同进入方式的对比：

进入方式	操作步骤	适用场景	成功率
自动复位	esptool.py flash_id	已安装驱动的开发板	95%
手动按键	按住BOOT键，按一下RESET键	所有开发板	100%
硬件自动	复位电路配合DTR/RTS	批量生产环境	98%
软件触发	通过应用程序代码	远程设备管理	85%

手动进入bootloader模式的详细步骤：

确保开发板通过USB连接到电脑
按住开发板上的BOOT键（通常标记为"IO0"或"BOOT"）
短暂按下并释放RESET键
释放BOOT键
此时开发板已进入bootloader模式，TX/RX指示灯可能会闪烁

使用espefuse读取UID

espefuse.py是操作efuse的专用工具，支持多种输出格式：

# 基本读取：显示所有efuse摘要信息
espefuse.py summary

# 读取MAC地址（简洁输出）
espefuse.py summary --format value_only MAC_ADDR

# 读取详细UID信息（JSON格式）
espefuse.py summary --format json MAC_ADDR CUSTOM_MAC MAC_VERSION > uid_info.json

# 读取原始efuse数据（十六进制）
espefuse.py dump --format united uid_dump.bin

典型输出示例：

EFUSE_NAME (Block)         Description                      [Meaningful Value]              [Readable/Writeable] (Hex Value)
---------------------------------------------------------------------------------------
MAC_ADDR (BLK0)            Factory MAC Address              24:6F:28:XX:XX:XX (CRC 0x9a OK) R/- (0x246F28XXXXXXXX)
MAC_VERSION (BLK0)         MAC version                      0                               R/- (0x0)
CUSTOM_MAC (BLK3)          Custom MAC Address               00:00:00:00:00:00 (CRC 0x00 invalid - calculated 0x5a) R/W (0x000000000000)
CUSTOM_MAC_CRC (BLK3)      CRC8 for Custom MAC              0                               R/W (0x0)

解析输出结果

解析espefuse输出的关键信息：

MAC_ADDR: 工厂预设的48位MAC地址，格式为XX:XX:XX:XX:XX:XX
MAC_VERSION: 0表示使用出厂MAC，1表示使用自定义MAC
CUSTOM_MAC: 用户可配置的MAC地址，默认为全0
CUSTOM_MAC_CRC: 自定义MAC的CRC校验值，确保数据正确性

使用Python解析JSON输出：

import json

with open('uid_info.json', 'r') as f:
    uid_data = json.load(f)
    
factory_mac = uid_data['MAC_ADDR']['value']
custom_mac = uid_data['CUSTOM_MAC']['value']
mac_version = uid_data['MAC_VERSION']['value']

if mac_version == 1 and custom_mac != "00:00:00:00:00:00":
    print(f"使用自定义MAC: {custom_mac}")
else:
    print(f"使用出厂MAC: {factory_mac}")

修改ESP芯片唯一标识符的高级操作

efuse写入前的关键注意事项

不可逆操作警告：efuse一旦烧写，相关位将永久置1，无法恢复。在执行任何写操作前，请务必：

备份原始efuse数据：

espefuse.py dump --format separated efuse_backup_

验证芯片型号与兼容性：
```
esptool.py chip_id
```
检查写保护状态：
```
espefuse.py summary | grep -i "write"
```
了解编码方案影响：
```
espefuse.py summary CODING_SCHEME
```

修改自定义MAC地址的完整步骤

以下是设置自定义MAC地址的详细流程：

flowchart TD
    A[检查当前MAC配置] -->|espefuse.py summary MAC_VERSION CUSTOM_MAC| B{MAC_VERSION是否为0?}
    B -->|是| C[准备自定义MAC与CRC]
    B -->|否| D[警告:已使用自定义MAC]
    C --> E[生成有效的MAC地址]
    E --> F[计算CRC校验值]
    F --> G[确认efuse可写]
    G --> H[执行烧写命令]
    H --> I[验证烧写结果]
    I --> J[完成]

具体命令序列：

# 1. 生成符合规范的MAC地址（前3字节使用厂商OUI）
# 例如使用Espressif的OUI: 24:6F:28, 后面3字节自定义
NEW_MAC="24:6F:28:12:34:56"

# 2. 烧写自定义MAC地址
espefuse.py burn_efuse CUSTOM_MAC $NEW_MAC

# 3. 设置MAC_VERSION为1，启用自定义MAC
espefuse.py burn_efuse MAC_VERSION 1

# 4. 验证修改结果
espefuse.py summary MAC_ADDR CUSTOM_MAC MAC_VERSION

烧写过程中的确认提示：

The efuses to burn:
  from BLOCK3

Burning efuses:

    - 'CUSTOM_MAC' (Custom MAC Address) 000000000000 -> 246f28123456

This is an irreversible operation!
Type 'BURN' (all caps) to continue.
BURN

    - 'MAC_VERSION' (MAC version) 0 -> 1

This is an irreversible operation!
Type 'BURN' (all caps) to continue.
BURN

Checking efuses...
Successful

高级：修改64位唯一标识符

部分ESP32型号（如ESP32-S3、ESP32-C6）支持64位UID，可通过组合多个efuse块实现：

# 1. 准备64位UID数据（存储为二进制文件）
echo -n -e "\x11\x22\x33\x44\x55\x66\x77\x88" > uid_64bit.bin

# 2. 烧写到efuse BLOCK1（注意：此操作将永久占用BLOCK1）
espefuse.py burn_block_data BLOCK1 uid_64bit.bin

# 3. 验证写入结果
espefuse.py dump --format united | hexdump -C | grep "11 22 33 44 55 66 77 88"

实战案例：基于UID的设备认证系统

硬件准备

组件	规格	用途
ESP32开发板	ESP32-WROOM-32	主控制器
USB转UART	CP2102	调试与烧写
面包板	400孔	电路搭建
LED	5mm红色	状态指示
电阻	220Ω	LED限流

设备端实现代码

以下是读取UID并实现简单认证的Arduino代码：

#include "esp_efuse.h"
#include "esp_efuse_fields.h"

// UID存储缓冲区
uint8_t uid[8] = {0};
char uid_str[18] = {0}; // 格式化为XX:XX:XX:XX:XX:XX

// 读取UID并格式化
void read_uid() {
  // 读取MAC地址（6字节）
  esp_efuse_mac_get_default(uid);
  
  // 格式化为字符串
  sprintf(uid_str, "%02X:%02X:%02X:%02X:%02X:%02X",
          uid[0], uid[1], uid[2], uid[3], uid[4], uid[5]);
}

// 简单的UID认证
bool authenticate_device() {
  // 读取UID
  read_uid();
  
  // 在实际应用中，这里应该是更复杂的加密认证
  // 示例：检查UID是否以特定厂商OUI开头
  if (uid[0] == 0x24 && uid[1] == 0x6F && uid[2] == 0x28) {
    return true; // 认证成功
  } else {
    return false; // 认证失败
  }
}

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  Serial.begin(115200);
  
  // 等待串口连接
  while (!Serial) {}
  
  // 读取并显示UID
  read_uid();
  Serial.printf("Device UID: %s\n", uid_str);
  
  // 执行认证
  if (authenticate_device()) {
    Serial.println("Authentication successful");
    digitalWrite(LED_BUILTIN, HIGH); // 点亮LED表示认证成功
  } else {
    Serial.println("Authentication failed");
    // 认证失败时的处理逻辑
    for (int i = 0; i < 5; i++) {
      digitalWrite(LED_BUILTIN, HIGH);
      delay(300);
      digitalWrite(LED_BUILTIN, LOW);
      delay(300);
    }
  }
}

void loop() {
  // 认证后不需要持续运行
  delay(1000);
}

上位机验证工具

使用Python编写的UID验证工具：

import serial
import re
import time

def read_device_uid(port='COM3', baudrate=115200):
    """读取设备发送的UID信息"""
    try:
        ser = serial.Serial(port, baudrate, timeout=2)
        time.sleep(1)  # 等待设备初始化
        
        # 读取串口输出
        output = ""
        for _ in range(10):  # 尝试读取10行
            if ser.in_waiting:
                line = ser.readline().decode('utf-8').strip()
                output += line + "\n"
                # 查找UID行
                uid_match = re.search(r'Device UID: ([0-9A-Fa-f:]+)', line)
                if uid_match:
                    return uid_match.group(1)
            time.sleep(0.1)
        
        # 如果没有找到UID，返回所有输出供调试
        return f"Error: UID not found. Output: {output}"
        
    except serial.SerialException as e:
        return f"Serial error: {str(e)}"
    finally:
        if 'ser' in locals() and ser.is_open:
            ser.close()

def verify_uid(uid):
    """验证UID格式和有效性"""
    # 检查MAC地址格式
    mac_pattern = re.compile(r'^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$')
    if not mac_pattern.match(uid):
        return False, "Invalid MAC address format"
    
    # 检查是否是我们设置的自定义MAC范围
    oui = uid[:8].upper()
    if oui == "24:6F:28":
        return True, "Valid custom UID from our OUI range"
    elif oui in ["AC:67:B2", "BC:DD:C2"]:  # 其他已知OUI
        return True, "Valid UID from known OUI"
    else:
        return False, "Unknown OUI prefix"

# 主程序
if __name__ == "__main__":
    uid = read_device_uid()
    print(f"Read UID: {uid}")
    
    if "Error" not in uid:
        valid, message = verify_uid(uid)
        print(f"Verification: {'Success' if valid else 'Failed'} - {message}")

常见问题与解决方案

无法读取UID的故障排除

问题现象	可能原因	解决方案
"Failed to connect"	未进入bootloader模式	重新执行BOOT+RESET操作
"Permission denied"	串口权限不足	添加用户到dialout组或使用sudo
"No serial port found"	驱动未安装或USB线故障	重新安装驱动，更换USB线
"Timed out waiting for packet header"	波特率不匹配或干扰	尝试指定--baud 115200参数
"Invalid head of packet"	串口连接不稳定	缩短USB线，避免电磁干扰

高级诊断命令：

# 检查串口设备
ls -l /dev/ttyUSB* /dev/ttyACM*  # Linux
ls /dev/cu.*                     # macOS

# 详细连接调试
esptool.py --port /dev/ttyUSB0 --baud 115200 --debug chip_id

# 测试串口通信
screen /dev/ttyUSB0 115200  # 然后按复位键，观察输出

修改UID失败的解决方案

错误信息	原因分析	解决方法
"Efuse is write protected"	目标efuse已被写保护	无法恢复，更换芯片
"Invalid the efuse name"	命令中使用了错误的efuse名称	检查efuse名称拼写，使用tab补全
"Data does not fit"	写入数据长度与efuse块大小不匹配	调整数据长度或使用正确的块
"Coding scheme incompatible"	编码方案不支持当前操作	检查CODING_SCHEME值，使用兼容命令
"MAC must be a unicast MAC"	MAC地址第一位为奇数	修改为偶数（unicast地址）

修改MAC地址时的常见错误：

使用广播/组播MAC地址（第一位为奇数）
未提供冒号分隔的正确格式
尝试修改出厂MAC_ADDR（只读）
CRC校验失败（通常由格式错误导致）

安全最佳实践与注意事项

保护efuse的安全策略

最小权限原则：
- 仅在必要时才烧写efuse
- 生产环境中限制对espefuse工具的访问
- 实施操作审计日志

不可逆操作确认流程：

# 创建安全烧写脚本，强制二次确认
# save as safe_burn_efuse.sh
#!/bin/bash
EFUSE_NAME=$1
VALUE=$2

echo "WARNING: This will permanently modify $EFUSE_NAME to $VALUE"
echo "This operation CANNOT be undone!"
read -p "Type 'CONFIRM' to proceed: " CONFIRM

if [ "$CONFIRM" = "CONFIRM" ]; then
  espefuse.py burn_efuse $EFUSE_NAME $VALUE
else
  echo "Operation cancelled"
fi

批量生产的安全措施：
- 使用脚本自动化烧写流程，减少人为错误
- 建立UID数据库，记录每颗芯片的唯一标识
- 实施生产流程中的双重校验机制

避免常见操作风险

永远不要烧写的efuse：
- BLK0的出厂MAC地址和芯片信息
- 任何标记为"R/-"的只读efuse
- SECURE_BOOT_EN和FLASH_CRYPT_CNT等安全相关位
烧写前的检查清单：
- [ ] 确认目标芯片型号与命令匹配
- [ ] 验证新值的格式和范围是否正确
- [ ] 检查efuse当前值是否已被修改
- [ ] 确认编码方案是否兼容
- [ ] 备份当前efuse状态
紧急恢复方案：
- 对于支持双分区的芯片，保持一个未修改UID的固件分区
- 使用efuse的错误恢复命令：espefuse.py check_error --recovery
- 记录原始UID，在应用层实现逻辑恢复机制