lucasrguerra/ESPDocs
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

feat(i18n): zh-CN content (data, glossary, diagnostics, components, messages, examples)

Browse Source 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Lucas RayanandClaude Sonnet 5.5 committed 2026-11-01 22:06:21 -03:00
1 parent ea51aa62b8
commit 1d79051250
31 files changed
+13005
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

lib/data/zh-CN/componentes.js
+858
View File
@@ -0,0 +1,858 @@
/**
* 官方精选数据库：ESP Component Registry 与 IDF Component Manager
*
* ESP Component Registry（https://components.espressif.com）是面向
* ESP-IDF v4.4+ / v5.x+ 的模块化库的核心分发生态。
*/
export const CATEGORIAS_COMPONENTES = [
{
id: "todos",
nome: "全部组件",
icone: "Layers",
descricao: "浏览完整的精选库与驱动目录"
},
{
id: "ui_display",
nome: "UI、显示屏与图形",
icone: "Monitor",
descricao: "图形库（LVGL）、LCD/OLED 显示驱动、触摸与解码器"
},
{
id: "cloud_conectividade",
nome: "云与网络连接",
icone: "Cloud",
descricao: "ESP RainMaker、AWS IoT、MQTT、WebSocket、Mesh-Lite 与 ESP-Hosted 协处理"
},
{
id: "audio_voz_ia",
nome: "音频、语音与 AI",
icone: "Brain",
descricao: "ESP-SR 语音识别、DSP 处理、编解码器、DVP 摄像头与 TinyML"
},
{
id: "smart_home_mesh",
nome: "智能家居与 Mesh",
icone: "Home",
descricao: "Matter SDK、Zigbee 3.0（ZBOSS）协议栈、Thread 与 ESP-NOW 网络"
},
{
id: "drivers_perifericos",
nome: "驱动与传感器",
icone: "Cpu",
descricao: "按键、编码器、RGB LED、以太网（W5500/CH390）、原生 USB 以及环境/IMU 传感器"
},
{
id: "bsp_placas",
nome: "BSP（板级支持包）",
icone: "CircuitBoard",
descricao: "对 ESP-BOX-3、Korvo、EYE 和 M5Stack 等官方开发板的直接支持包"
},
{
id: "sistema_utilitarios",
nome: "系统与工具",
icone: "Wrench",
descricao: "LittleFS 文件系统、现代 C++ 封装、CBOR 与网络工具"
}
];
export const COMPONENTES_REGISTRY = [
// ==========================================
// 1. UI, Displays & Gráficos
// ==========================================
{
id: "espressif-esp_lvgl_port",
namespace: "espressif",
name: "esp_lvgl_port",
versao: "^2.4.0",
categoria: "ui_display",
oficial: true,
popular: true,
titulo: "ESP LVGL Port",
descricao: "官方的线程安全 LVGL（Light and Versatile Graphics Library）移植，面向 ESP-IDF，支持硬件加速和多显示屏。",
tags: ["LVGL", "GUI", "显示屏", "触摸", "人机界面"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-P4", "ESP32-C3", "ESP32-C6"],
dependenciasSugeridas: ["lvgl/lvgl^9.1.0"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_lvgl_port",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/components/esp_lvgl_port",
exemploYaml: `dependencies:
espressif/esp_lvgl_port: "^2.4.0"
lvgl/lvgl: "^9.1.0"`
},
{
id: "lvgl-lvgl",
namespace: "lvgl",
name: "lvgl",
versao: "^9.1.0",
categoria: "ui_display",
oficial: false,
popular: true,
titulo: "LVGL Graphics Library Core",
descricao: "嵌入式系统中最流行的 C 语言开源图形库。提供丰富的控件、流畅的动画和现代化的布局支持。",
tags: ["LVGL 9", "Graphics", "Widgets", "GUI", "Embedded UI"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-P4", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/lvgl/lvgl",
urlRepo: "https://github.com/lvgl/lvgl",
exemploYaml: `dependencies:
lvgl/lvgl: "^9.1.0"`
},
{
id: "espressif-esp32_display_panel",
namespace: "espressif",
name: "esp32_display_panel",
versao: "^0.2.0",
categoria: "ui_display",
oficial: true,
popular: true,
titulo: "ESP32 Display Panel Driver",
descricao: "统一的 LCD 控制器（RGB、SPI、QSPI、MIPI-DSI）与电容触摸驱动，专为 ESP32-S3 和 ESP32-P4 设计。",
tags: ["LCD", "MIPI-DSI", "QSPI", "Touch", "ST7789", "ILI9341"],
chips: ["ESP32-S3", "ESP32-P4", "ESP32-S2", "ESP32"],
urlRegistry: "https://components.espressif.com/components/espressif/esp32_display_panel",
urlRepo: "https://github.com/esp-arduino-libs/ESP32_Display_Panel",
exemploYaml: `dependencies:
espressif/esp32_display_panel: "^0.2.0"`
},
{
id: "espressif-esp_lcd_touch",
namespace: "espressif",
name: "esp_lcd_touch",
versao: "^1.1.2",
categoria: "ui_display",
oficial: true,
popular: true,
titulo: "ESP LCD Touch Framework",
descricao: "触摸屏 LCD 触摸面板的核心抽象组件。支持坐标校准、多点触控读取，并可直接与 LVGL 集成。",
tags: ["触摸屏", "电容式", "电阻式", "I2C 触摸", "坐标"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-P4", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_lcd_touch",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/display/touch_panel/esp_lcd_touch",
exemploYaml: `dependencies:
espressif/esp_lcd_touch: "^1.1.2"`
},
{
id: "espressif-esp_lcd_touch_gt911",
namespace: "espressif",
name: "esp_lcd_touch_gt911",
versao: "^1.1.2",
categoria: "ui_display",
oficial: true,
popular: true,
titulo: "GT911 电容触摸驱动",
descricao: "专用于 Goodix GT911 电容触摸控制器的 I2C 驱动，广泛用于 ESP32-S3 和 P4 的 4.3\"、5\" 和 7\" 显示屏。",
tags: ["GT911", "Goodix", "电容触摸", "多点触控", "I2C"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-S2"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_lcd_touch_gt911",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/display/touch_panel/esp_lcd_touch_gt911",
exemploYaml: `dependencies:
espressif/esp_lcd_touch_gt911: "^1.1.2"`
},
{
id: "espressif-esp_lcd_touch_ft5x06",
namespace: "espressif",
name: "esp_lcd_touch_ft5x06",
versao: "^1.1.0",
categoria: "ui_display",
oficial: true,
popular: false,
titulo: "FocalTech FT5x06 / FT6x36 触摸驱动",
descricao: "面向 FocalTech 控制器（FT5206、FT5316、FT5436、FT6236、FT6336）的电容触摸面板驱动，支持手势和中断。",
tags: ["FT6236", "FT5x06", "FocalTech", "触摸", "I2C"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-S2", "ESP32-C3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_lcd_touch_ft5x06",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/display/touch_panel/esp_lcd_touch_ft5x06",
exemploYaml: `dependencies:
espressif/esp_lcd_touch_ft5x06: "^1.1.0"`
},
{
id: "espressif-esp_jpeg",
namespace: "espressif",
name: "esp_jpeg",
versao: "^1.3.0",
categoria: "ui_display",
oficial: true,
popular: false,
titulo: "ESP JPEG Decoder (TJpgDec)",
descricao: "高速 JPEG 编解码器，带有汇编 SIMD 优化，可在显示屏上无延迟地显示图像和摄像头视频流。",
tags: ["JPEG", "TJpgDec", "摄像头", "图像", "SIMD"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-C3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_jpeg",
urlRepo: "https://github.com/espressif/esp-jpeg",
exemploYaml: `dependencies:
espressif/esp_jpeg: "^1.3.0"`
},
// ==========================================
// 2. Cloud & Conectividade
// ==========================================
{
id: "espressif-esp_rainmaker",
namespace: "espressif",
name: "esp_rainmaker",
versao: "^1.4.0",
categoria: "cloud_conectividade",
oficial: true,
popular: true,
titulo: "ESP RainMaker Agent",
descricao: "乐鑫 ESP RainMaker AIoT 云平台的官方固件代理。支持手机 App、Alexa、Google Home 控制以及 OTA。",
tags: ["RainMaker", "AWS Cloud", "iOS/Android App", "Alexa", "Google Home", "OTA"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_rainmaker",
urlRepo: "https://github.com/espressif/esp-rainmaker",
exemploYaml: `dependencies:
espressif/esp_rainmaker: "^1.4.0"`
},
{
id: "espressif-mesh_lite",
namespace: "espressif",
name: "mesh_lite",
versao: "^1.2.0",
categoria: "cloud_conectividade",
oficial: true,
popular: true,
titulo: "ESP Mesh-Lite Network Stack",
descricao: "轻量级 Wi-Fi Mesh 网络，每个节点都有独立的 IP 连接，可在局域网内直接通信，并通过多跳访问云端。",
tags: ["Mesh", "Wi-Fi Mesh", "Mesh 网络", "分布式 IoT", "IP Layer"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/mesh_lite",
urlRepo: "https://github.com/espressif/esp-mesh-lite",
exemploYaml: `dependencies:
espressif/mesh_lite: "^1.2.0"`
},
{
id: "espressif-esp_modbus",
namespace: "espressif",
name: "esp_modbus",
versao: "^1.0.15",
categoria: "cloud_conectividade",
oficial: true,
popular: true,
titulo: "ESP-Modbus Industrial Stack",
descricao: "完整的工业 Modbus 协议栈（主站/从站），支持 RS-485（RTU/ASCII）以及以太网/Wi-Fi（Modbus TCP）接口。",
tags: ["Modbus", "RS-485", "Modbus TCP", "工业自动化", "PLC"],
chips: ["ESP32", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_modbus",
urlRepo: "https://github.com/espressif/esp-modbus",
exemploYaml: `dependencies:
espressif/esp_modbus: "^1.0.15"`
},
{
id: "espressif-net_connect",
namespace: "espressif",
name: "net_connect",
versao: "^1.0.0",
categoria: "cloud_conectividade",
oficial: true,
popular: false,
titulo: "Unified Network Connect",
descricao: "统一的网络连接管理组件，可透明地切换并初始化 Wi-Fi、以太网、Thread 或移动 PPP。",
tags: ["Network", "Wi-Fi", "Ethernet", "故障切换", "自动连接"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/net_connect",
urlRepo: "https://github.com/espressif/esp-idf/tree/master/components",
exemploYaml: `dependencies:
espressif/net_connect: "^1.0.0"`
},
{
id: "espressif-esp_hosted",
namespace: "espressif",
name: "esp_hosted",
versao: "^0.0.10",
categoria: "cloud_conectividade",
oficial: true,
popular: false,
titulo: "ESP-Hosted Coprocessor",
descricao: "把 ESP32 变成无线通信协处理器（Wi-Fi + BLE），供 Linux 主机（Raspberry Pi、i.MX）或通过 SPI/SDIO/UART 连接的微控制器使用。",
tags: ["协处理器", "SDIO", "SPI", "Linux Wi-Fi", "Raspberry Pi"],
chips: ["ESP32", "ESP32-S3", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_hosted",
urlRepo: "https://github.com/espressif/esp-hosted",
exemploYaml: `dependencies:
espressif/esp_hosted: "^0.0.10"`
},
{
id: "espressif-esp-now",
namespace: "espressif",
name: "esp-now",
versao: "^2.5.0",
categoria: "cloud_conectividade",
oficial: true,
popular: true,
titulo: "ESP-NOW Enhanced & Provisioning",
descricao: "ESP-NOW 协议的扩展，提供遥控配对、AES-128 安全以及多设备控制等高级功能。",
tags: ["ESP-NOW", "无线", "低延迟", "广播", "遥控"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-now",
urlRepo: "https://github.com/espressif/esp-now",
exemploYaml: `dependencies:
espressif/esp-now: "^2.5.0"`
},
// ==========================================
// 3. Áudio, Voz & IA
// ==========================================
{
id: "espressif-esp-sr",
namespace: "espressif",
name: "esp-sr",
versao: "^1.5.0",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ESP-SR Speech Recognition",
descricao: "100% 离线的语音识别框架，包含 WakeNet（唤醒词）、MultiNet（本地命令）和 AFE 声学算法。",
tags: ["语音", "WakeNet", "MultiNet", "语音识别", "离线", "AEC"],
chips: ["ESP32-S3", "ESP32-P4", "ESP32"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-sr",
urlRepo: "https://github.com/espressif/esp-sr",
exemploYaml: `dependencies:
espressif/esp-sr: "^1.5.0"`
},
{
id: "espressif-esp_codec_dev",
namespace: "espressif",
name: "esp_codec_dev",
versao: "^1.3.0",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ESP Audio Codec Device HAL",
descricao: "统一的 I2S/I2C 音频编解码器抽象层（ES8311、ES8388、ES7210、ES7243、TAS5805M），用于立体声输入输出。",
tags: ["Audio Codec", "I2S", "ES8311", "ES8388", "麦克风 DAC"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_codec_dev",
urlRepo: "https://github.com/espressif/esp-codec-dev",
exemploYaml: `dependencies:
espressif/esp_codec_dev: "^1.3.0"`
},
{
id: "espressif-es8311",
namespace: "espressif",
name: "es8311",
versao: "^1.0.0",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ES8311 音频编解码器驱动",
descricao: "面向 Everest ES8311 编解码器（单声道 DAC + 麦克风 ADC）的专用低功耗驱动，见于 ESP32-S3-BOX 和 IoT 开发板。",
tags: ["ES8311", "音频", "DAC", "麦克风", "I2S"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-C3"],
urlRegistry: "https://components.espressif.com/components/espressif/es8311",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/components/es8311",
exemploYaml: `dependencies:
espressif/es8311: "^1.0.0"`
},
{
id: "espressif-esp32-camera",
namespace: "espressif",
name: "esp32-camera",
versao: "^2.0.12",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ESP32 Camera Driver",
descricao: "官方 CMOS 摄像头驱动（OV2640、OV3660、OV5640、OV7670、GC0308），支持 DMA、DMA-2D、JPEG 捕获，以及通过 HTTP/RTSP 的 MJPEG 流。",
tags: ["摄像头", "OV2640", "OV5640", "DVP", "MIPI-CSI", "视频"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-S2"],
urlRegistry: "https://components.espressif.com/components/espressif/esp32-camera",
urlRepo: "https://github.com/espressif/esp32-camera",
exemploYaml: `dependencies:
espressif/esp32-camera: "^2.0.12"`
},
{
id: "espressif-esp-dsp",
namespace: "espressif",
name: "esp-dsp",
versao: "^1.5.1",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ESP-DSP Signal Processing",
descricao: "面向 ESP32 SoC 的官方数字信号处理库（FFT、FIR/IIR 数字滤波器、矩阵与加速的线性代数）。",
tags: ["DSP", "FFT", "滤波器", "数学", "SIMD", "汇编"],
chips: ["ESP32", "ESP32-S3", "ESP32-P4", "ESP32-C3", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-dsp",
urlRepo: "https://github.com/espressif/esp-dsp",
exemploYaml: `dependencies:
espressif/esp-dsp: "^1.5.1"`
},
{
id: "espressif-esp-nn",
namespace: "espressif",
name: "esp-nn",
versao: "^1.2.0",
categoria: "audio_voz_ia",
oficial: true,
popular: true,
titulo: "ESP-NN Neural Network Kernels",
descricao: "用向量汇编优化的内核，在 ESP32 芯片上加速神经网络和 TensorFlow Lite Micro 模型。",
tags: ["TinyML", "TensorFlow Lite", "神经网络", "推理", "Edge AI"],
chips: ["ESP32-S3", "ESP32-P4", "ESP32"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-nn",
urlRepo: "https://github.com/espressif/esp-nn",
exemploYaml: `dependencies:
espressif/esp-nn: "^1.2.0"`
},
// ==========================================
// 4. Smart Home & Mesh
// ==========================================
{
id: "espressif-esp-matter",
namespace: "espressif",
name: "esp-matter",
versao: "^1.3.0",
categoria: "smart_home_mesh",
oficial: true,
popular: true,
titulo: "ESP Matter SDK",
descricao: "官方 SDK，用于创建可在 Wi-Fi 和 Thread 上与 Apple Home、Google Home、Amazon Alexa 和 Home Assistant 互操作的设备。",
tags: ["Matter", "智能家居", "Apple HomeKit", "Google Home", "Thread", "CHIP"],
chips: ["ESP32", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-matter",
urlRepo: "https://github.com/espressif/esp-matter",
exemploYaml: `dependencies:
espressif/esp-matter: "^1.3.0"`
},
{
id: "espressif-esp-zigbee-lib",
namespace: "espressif",
name: "esp-zigbee-lib",
versao: "^1.6.0",
categoria: "smart_home_mesh",
oficial: true,
popular: true,
titulo: "ESP Zigbee 3.0 Library",
descricao: "经过认证的 Zigbee 3.0 协议栈（ZBOSS），用于在 802.15.4 芯片上创建低功耗的协调器、路由器和终端设备节点。",
tags: ["Zigbee 3.0", "ZBOSS", "802.15.4", "Home Automation", "电池供电"],
chips: ["ESP32-H2", "ESP32-C6"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-zigbee-lib",
urlRepo: "https://github.com/espressif/esp-zigbee-sdk",
exemploYaml: `dependencies:
espressif/esp-zigbee-lib: "^1.6.0"`
},
{
id: "espressif-esp_rcp_update",
namespace: "espressif",
name: "esp_rcp_update",
versao: "^1.0.0",
categoria: "smart_home_mesh",
oficial: true,
popular: false,
titulo: "ESP RCP Thread/Zigbee Gateway",
descricao: "用于更新 802.15.4 射频协处理器（RCP）的组件，用来构建 Thread 边界路由器和多协议 Zigbee 网关。",
tags: ["Thread Border Router", "OpenThread", "RCP", "Zigbee Gateway"],
chips: ["ESP32-H2", "ESP32-C6", "ESP32-S3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_rcp_update",
urlRepo: "https://github.com/espressif/esp-thread-br",
exemploYaml: `dependencies:
espressif/esp_rcp_update: "^1.0.0"`
},
// ==========================================
// 5. Drivers & Sensores
// ==========================================
{
id: "espressif-led_indicator",
namespace: "espressif",
name: "led_indicator",
versao: "^1.2.0",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "LED Indicator Driver",
descricao: "智能的 LED 灯效控制驱动（快闪、呼吸/渐变、错误码和 RGB），不会阻塞主循环。",
tags: ["LED", "PWM", "RGB", "闪烁", "视觉反馈"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C2", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/led_indicator",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/led/led_indicator",
exemploYaml: `dependencies:
espressif/led_indicator: "^1.2.0"`
},
{
id: "espressif-button",
namespace: "espressif",
name: "button",
versao: "^3.4.0",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "IoT Button Handler (iot_button)",
descricao: "完整的按键管理器，支持消抖、单击、双击、多击、长按事件以及矩阵键盘。",
tags: ["按键", "消抖", "Long Press", "Double Click", "GPIO"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/button",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/button",
exemploYaml: `dependencies:
espressif/button: "^3.4.0"`
},
{
id: "espressif-led_strip",
namespace: "espressif",
name: "led_strip",
versao: "^2.5.4",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "Addressable LED Strip (WS2812/SK6812)",
descricao: "高性能驱动，使用 RMT 或 SPI 外设控制 WS2812、WS2813 和 SK6812 可寻址 LED 灯带与灯阵。",
tags: ["WS2812B", "Neopixel", "SK6812", "RMT", "LED 灯带", "RGB"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/led_strip",
urlRepo: "https://github.com/espressif/idf-extra-components/tree/master/led_strip",
exemploYaml: `dependencies:
espressif/led_strip: "^2.5.4"`
},
{
id: "espressif-esp_tinyusb",
namespace: "espressif",
name: "esp_tinyusb",
versao: "^1.5.0",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "ESP Native USB Device (TinyUSB)",
descricao: "乐鑫为 ESP32-S2、ESP32-S3 和 ESP32-P4 提供的官方 TinyUSB 扩展，可模拟 USB CDC 串口、HID 键盘/鼠标、MSC 优盘、DFU 和 WebUSB。",
tags: ["原生 USB", "TinyUSB", "USB CDC", "USB HID", "WebUSB", "MSC"],
chips: ["ESP32-S2", "ESP32-S3", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_tinyusb",
urlRepo: "https://github.com/espressif/esp-tinyusb",
exemploYaml: `dependencies:
espressif/esp_tinyusb: "^1.5.0"`
},
{
id: "espressif-w5500",
namespace: "espressif",
name: "w5500",
versao: "^1.2.0",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "WIZnet W5500 SPI Ethernet Driver",
descricao: "通过 SPI 总线驱动 WIZnet W5500 以太网芯片的官方驱动，把物理接口无缝接入 ESP-IDF 原生 TCP/IP 协议栈（lwIP）。",
tags: ["W5500", "Ethernet", "SPI Ethernet", "RJ45", "lwIP", "有线网络"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/w5500",
urlRepo: "https://github.com/espressif/esp-eth-drivers/tree/master/w5500",
exemploYaml: `dependencies:
espressif/w5500: "^1.2.0"`
},
{
id: "espressif-ch390",
namespace: "espressif",
name: "ch390",
versao: "^1.0.0",
categoria: "drivers_perifericos",
oficial: true,
popular: false,
titulo: "CH390 SPI Ethernet Driver",
descricao: "面向 WCH CH390 控制器的 SPI 10/100M 以太网驱动，适合在 ESP32-C3、S3 或 P4 开发板上低成本添加 RJ45 网口。",
tags: ["CH390", "Ethernet", "WCH", "SPI Ethernet", "RJ45"],
chips: ["ESP32", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/ch390",
urlRepo: "https://github.com/espressif/esp-eth-drivers/tree/master/ch390",
exemploYaml: `dependencies:
espressif/ch390: "^1.0.0"`
},
{
id: "espressif-usb_host_uvc",
namespace: "espressif",
name: "usb_host_uvc",
versao: "^1.0.4",
categoria: "drivers_perifericos",
oficial: true,
popular: false,
titulo: "USB Host UVC (Webcam Driver)",
descricao: "USB Host 驱动，可把标准 USB UVC 网络摄像头直接接到 ESP32-S2、ESP32-S3 或 ESP32-P4 的原生 USB 口。",
tags: ["USB Host", "UVC", "Webcam", "USB 摄像头", "视频"],
chips: ["ESP32-S2", "ESP32-S3", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/usb_host_uvc",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/usb/usb_host_uvc",
exemploYaml: `dependencies:
espressif/usb_host_uvc: "^1.0.4"`
},
{
id: "espressif-sensor_hub",
namespace: "espressif",
name: "sensor_hub",
versao: "^1.0.0",
categoria: "drivers_perifericos",
oficial: true,
popular: false,
titulo: "ESP Sensor Hub Manager",
descricao: "统一的框架，用于管理异构传感器（I2C/SPI），支持周期采样、数据融合以及由事件/中断触发。",
tags: ["传感器", "Sensor Hub", "I2C", "事件", "周期采集"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/sensor_hub",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/sensors/sensor_hub",
exemploYaml: `dependencies:
espressif/sensor_hub: "^1.0.0"`
},
{
id: "espressif-bmi270_sensor",
namespace: "espressif",
name: "bmi270_sensor",
versao: "^1.0.1",
categoria: "drivers_perifericos",
oficial: true,
popular: false,
titulo: "Bosch BMI270 IMU 传感器驱动",
descricao: "面向 Bosch BMI270 六轴惯性 IMU 传感器（加速度计 + 陀螺仪）的官方驱动，支持运动手势和计步检测。",
tags: ["BMI270", "IMU", "加速度计", "陀螺仪", "Bosch", "手势"],
chips: ["ESP32", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/bmi270_sensor",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/sensors/imu/bmi270",
exemploYaml: `dependencies:
espressif/bmi270_sensor: "^1.0.1"`
},
{
id: "espressif-ds18b20",
namespace: "espressif",
name: "ds18b20",
versao: "^1.0.0",
categoria: "drivers_perifericos",
oficial: true,
popular: true,
titulo: "DS18B20 温度传感器驱动",
descricao: "面向 Dallas/Maxim DS18B20 单总线（1-Wire）温度传感器的数字驱动，通过 RMT 总线支持在同一个 GPIO 引脚上挂接多个传感器。",
tags: ["DS18B20", "1-Wire", "温度", "传感器", "Dallas"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/ds18b20",
urlRepo: "https://github.com/espressif/esp-iot-solution/tree/master/components/sensors/temperature/ds18b20",
exemploYaml: `dependencies:
espressif/ds18b20: "^1.0.0"`
},
{
id: "esp-idf-lib-scd4x",
namespace: "esp-idf-lib",
name: "scd4x",
versao: "^1.0.0",
categoria: "drivers_perifericos",
oficial: false,
popular: true,
titulo: "Sensirion SCD40/SCD41 CO2 传感器驱动",
descricao: "面向 Sensirion SCD40 和 SCD41 光声式 CO2、温度和相对湿度传感器的高精度 I2C 驱动，带自动校准。",
tags: ["SCD40", "SCD41", "Sensirion", "CO2", "空气质量", "I2C"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/esp-idf-lib/scd4x",
urlRepo: "https://github.com/UncleRus/esp-idf-lib/tree/master/components/scd4x",
exemploYaml: `dependencies:
esp-idf-lib/scd4x: "^1.0.0"`
},
// ==========================================
// 6. BSPs (Board Support Packages)
// ==========================================
{
id: "espressif-esp-box-3",
namespace: "espressif",
name: "esp-box-3",
versao: "^1.2.0",
categoria: "bsp_placas",
oficial: true,
popular: true,
titulo: "BSP ESP32-S3-BOX-3",
descricao: "面向 ESP32-S3-BOX-3 AI 开发板的完整支持包，只需一个函数即可初始化触摸屏、音频编解码器、双麦克风、运动传感器和 LED。",
tags: ["BSP", "ESP-BOX-3", "触摸显示屏", "麦克风", "音频 ES8311", "I2C/SPI"],
chips: ["ESP32-S3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-box-3",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/bsp/esp-box-3",
exemploYaml: `dependencies:
espressif/esp-box-3: "^1.2.0"`
},
{
id: "espressif-esp32_s3_korvo_2",
namespace: "espressif",
name: "esp32_s3_korvo_2",
versao: "^1.1.0",
categoria: "bsp_placas",
oficial: true,
popular: false,
titulo: "BSP ESP32-S3-Korvo-2",
descricao: "面向 ESP32-S3-Korvo-2 音频与语音识别开发套件的板级支持包（Board Support Package），支持 I2S 麦克风和触摸按键。",
tags: ["BSP", "Korvo", "音频", "麦克风阵列", "ESP-SR"],
chips: ["ESP32-S3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp32_s3_korvo_2",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/bsp/esp32_s3_korvo_2",
exemploYaml: `dependencies:
espressif/esp32_s3_korvo_2: "^1.1.0"`
},
{
id: "espressif-esp32_s3_eye",
namespace: "espressif",
name: "esp32_s3_eye",
versao: "^1.1.0",
categoria: "bsp_placas",
oficial: true,
popular: true,
titulo: "BSP ESP32-S3-EYE",
descricao: "面向官方计算机视觉开发板 ESP32-S3-EYE 的板级支持包，配置 OV2640 摄像头、圆形 SPI LCD 显示屏和数字麦克风。",
tags: ["BSP", "ESP32-S3-EYE", "摄像头", "计算机视觉", "显示屏"],
chips: ["ESP32-S3"],
urlRegistry: "https://components.espressif.com/components/espressif/esp32_s3_eye",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/bsp/esp32_s3_eye",
exemploYaml: `dependencies:
espressif/esp32_s3_eye: "^1.1.0"`
},
{
id: "espressif-m5stack_core_s3",
namespace: "espressif",
name: "m5stack_core_s3",
versao: "^1.0.0",
categoria: "bsp_placas",
oficial: true,
popular: true,
titulo: "BSP M5Stack CoreS3",
descricao: "面向 M5Stack CoreS3 设备的官方板级支持包，初始化触摸屏、AXP2101 电源管理芯片、GC0308 摄像头和 I2S 扬声器。",
tags: ["BSP", "M5Stack", "CoreS3", "Display ILI9342C", "AXP2101", "摄像头"],
chips: ["ESP32-S3"],
urlRegistry: "https://components.espressif.com/components/espressif/m5stack_core_s3",
urlRepo: "https://github.com/espressif/esp-bsp/tree/master/bsp/m5stack_core_s3",
exemploYaml: `dependencies:
espressif/m5stack_core_s3: "^1.0.0"`
},
{
id: "waveshare-esp32_p4_wifi6_touch_lcd_7b",
namespace: "waveshare",
name: "esp32_p4_wifi6_touch_lcd_7b",
versao: "^1.0.0",
categoria: "bsp_placas",
oficial: false,
popular: true,
titulo: "BSP Waveshare ESP32-P4 Touch LCD 7\"",
descricao: "面向高性能 Waveshare ESP32-P4 开发板的支持包，配备 7 英寸电容触摸屏（MIPI-DSI 1024x600）和 Wi-Fi 6 协处理器。",
tags: ["BSP", "ESP32-P4", "MIPI-DSI", "Waveshare", "7 英寸屏", "触摸"],
chips: ["ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/waveshare/esp32_p4_wifi6_touch_lcd_7b",
urlRepo: "https://github.com/waveshare/ESP32-P4-WiFi6-Touch-LCD-7B",
exemploYaml: `dependencies:
waveshare/esp32_p4_wifi6_touch_lcd_7b: "^1.0.0"`
},
// ==========================================
// 7. Sistema & Utilitários
// ==========================================
{
id: "joltwallet-littlefs",
namespace: "joltwallet",
name: "littlefs",
versao: "^1.14.8",
categoria: "sistema_utilitarios",
oficial: false,
popular: true,
titulo: "LittleFS Filesystem for ESP-IDF",
descricao: "面向 SPI 闪存的 LittleFS 文件系统的稳健移植，带动态磨损均衡和防断电损坏保护。",
tags: ["LittleFS", "Flash", "Filesystem", "Wear Leveling", "NVS"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/joltwallet/littlefs",
urlRepo: "https://github.com/joltwallet/esp_littlefs",
exemploYaml: `dependencies:
joltwallet/littlefs: "^1.14.8"`
},
{
id: "espressif-esp-idf-cxx",
namespace: "espressif",
name: "esp-idf-cxx",
versao: "^1.2.0",
categoria: "sistema_utilitarios",
oficial: true,
popular: true,
titulo: "ESP-IDF C++ Idiomatic Wrappers",
descricao: "现代 C++（C++17/C++20/C++23）类与封装集合，采用 RAII 语义，覆盖 GPIO、Wi-Fi、定时器、FreeRTOS 队列和信号量。",
tags: ["C++", "C++20", "RAII", "Modern C++", "面向对象", "FreeRTOS"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/esp-idf-cxx",
urlRepo: "https://github.com/espressif/esp-idf-cxx",
exemploYaml: `dependencies:
espressif/esp-idf-cxx: "^1.2.0"`
},
{
id: "espressif-cbor",
namespace: "espressif",
name: "cbor",
versao: "^0.6.0",
categoria: "sistema_utilitarios",
oficial: true,
popular: false,
titulo: "TinyCBOR Serialization",
descricao: "超轻量级库，用于 CBOR（Concise Binary Object Representation）二进制格式的数据序列化与反序列化。",
tags: ["CBOR", "序列化", "二进制", "IoT Protocol", "紧凑 JSON"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-H2", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/cbor",
urlRepo: "https://github.com/espressif/tinycbor",
exemploYaml: `dependencies:
espressif/cbor: "^0.6.0"`
},
{
id: "espressif-esp_websocket_client",
namespace: "espressif",
name: "esp_websocket_client",
versao: "^1.2.4",
categoria: "sistema_utilitarios",
oficial: true,
popular: true,
titulo: "ESP WebSocket Client",
descricao: "支持 TLS/SSL（WSS）、自动重连、子协议和 ping/pong 心跳的实时双向 WebSocket 客户端。",
tags: ["WebSocket", "WSS", "TLS", "实时", "Sockets", "JSON"],
chips: ["ESP32", "ESP32-S2", "ESP32-S3", "ESP32-C3", "ESP32-C6", "ESP32-P4"],
urlRegistry: "https://components.espressif.com/components/espressif/esp_websocket_client",
urlRepo: "https://github.com/espressif/esp-protocols/tree/master/components/esp_websocket_client",
exemploYaml: `dependencies:
espressif/esp_websocket_client: "^1.2.4"`
}
];
export const GUIA_COMPONENT_MANAGER = {
titulo: "如何在 ESP-IDF 中使用 ESP Component Registry",
resumo: "从 ESP-IDF v4.4 开始，并在 v5.x 及以后版本中趋于成熟，乐鑫采用了由 IDF Component Manager 管理的模块化包架构。不用再处理复杂的 git 子模块：现在只需在项目的 idf_component.yml 清单文件中声明所需的库。",
vantagens: [
{
titulo: "自动安装，彼此解耦",
descricao: "在执行 'idf.py build' 或 'idf.py reconfigure' 时，编译系统会自动下载、编译并管理库的版本。"
},
{
titulo: "严格的语义化版本",
descricao: "通过版本运算符精确控制何时更新（^ 表示兼容次版本，~ 表示补丁版本，也可以固定为精确版本）。"
},
{
titulo: "项目更轻量、更整洁",
descricao: "项目仓库保持干净，Git 历史中不会混入第三方代码。"
},
{
titulo: "面向企业或社区的共享",
descricao: "可以把你自己的组件发布到乐鑫的公共云，也可以发布到公司内部的私有注册中心。"
}
],
comandosCli: [
{
comando: 'idf.py add-dependency "namespace/componente^versao"',
exemplo: 'idf.py add-dependency "espressif/esp_lvgl_port^2.4.0"',
explicacao: "自动创建或更新 'main/idf_component.yml' 文件，并加入指定的依赖。"
},
{
comando: "idf.py reconfigure",
exemplo: "idf.py reconfigure",
explicacao: "强制 CMake 和 Component Manager 重新解析依赖树，并下载尚未获取的包。"
},
{
comando: "compote component upload --name <component_name> --namespace <sua_org>",
exemplo: "compote component upload --name meu_driver_sensor --namespace minhadiv",
explicacao: "使用官方的 Compote CLI 工具，把你的开源或专有组件发布到 ESP Component Registry。"
}
],
sintaxeManifesto: `# 典型的文件结构：main/idf_component.yml
dependencies:
# 从乐鑫官方注册中心下载
espressif/esp_lvgl_port: "^2.4.0"
espressif/button: "~3.4.0"
# 精确版本
espressif/led_indicator: "1.2.0"
# 社区依赖
joltwallet/littlefs: "^1.14.8"
# 本地磁盘上的依赖（可选）
# meu_driver_local:
# path: "../../components/meu_driver"`
};
lib/data/zh-CN/diagnostico.js
+744
View File
@@ -0,0 +1,744 @@
/**
* ESP32 故障诊断、常见错误与问题排查指南的结构化数据。
* 涵盖 6 个技术类别，包含根因分析、最佳实践与临时凑合方案的对比，
* 以及 Arduino C++、ESP-IDF（C）和 MicroPython 的代码示例。
* 代码示例中的注释为中文，串口日志字符串保持英文，以免终端显示乱码。
*/
export const categoriasDiagnostico = [
{
id: "alimentacao",
nome: "供电与硬件",
icone: "Zap",
cor: "amber",
descricao: "Wi-Fi/BLE 射频峰值引起的电压跌落、冲突的 Strapping 引脚、电磁噪声以及 LDO 问题。",
},
{
id: "cpu-panics",
nome: "CPU 异常与 Guru Meditation",
icone: "Cpu",
cor: "red",
descricao: "空指针、内存访问违规（Load/StoreProhibited）、非法指令以及 ISR 中的缓存异常。",
},
{
id: "freertos",
nome: "FreeRTOS 与多任务",
icone: "Layers",
cor: "purple",
descricao: "任务看门狗（TWDT）、中断看门狗（IWDT）、栈溢出（Stack Overflow）以及调度器阻塞。",
},
{
id: "memoria",
nome: "内存、堆与 PSRAM",
icone: "Activity",
cor: "blue",
descricao: "堆碎片化、内存泄漏（Memory Leaks）、DMA 内存分配以及 PSRAM 的限制。",
},
{
id: "boot-flash",
nome: "引导加载程序与烧录",
icone: "Terminal",
cor: "emerald",
descricao: "串口通信失败（DTR/RTS）、SPI 闪存读取错误、时钟不匹配与分区问题。",
},
{
id: "conectividade",
nome: "网络连接与协议",
icone: "Wifi",
cor: "cyan",
descricao: "Wi-Fi Beacon 超时、缺少 SNTP 时钟导致的 TLS/HTTPS 握手失败，以及信号不稳定。",
},
];
export const sintomasRapidos = [
{ id: "bootloop", rotulo: "🔄 反复重启（Bootloop）", categoria: "todos" },
{ id: "wifi-crash", rotulo: "📶 开启 Wi-Fi/BLE 时死机", categoria: "alimentacao" },
{ id: "upload-fail", rotulo: "🔌 烧录代码失败（Upload）", categoria: "boot-flash" },
{ id: "random-freeze", rotulo: "⏱️ 运行数分钟/数小时后死机", categoria: "memoria" },
{ id: "null-pointer", rotulo: "💥 Guru Meditation（崩溃）", categoria: "cpu-panics" },
{ id: "wdt-reset", rotulo: "🐕 Watchdog Triggered", categoria: "freertos" },
{ id: "tls-fail", rotulo: "🔒 HTTPS / SSL 失败", categoria: "conectividade" },
];
export const errosCatalogo = [
{
id: "brownout-reset",
titulo: "Brownout Detector 复位（电压跌落）",
categoria: "alimentacao",
sintomas: ["bootloop", "wifi-crash"],
gravidade: "高",
logSerial: "Brownout detector was triggered\n\nrst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)",
resumo: "ESP32 的供电电压跌到了安全工作阈值以下（约 2.8V ~ 2.43V）。",
causaRaiz:
"开启 Wi-Fi 或 BLE 射频时，功率放大级（PA）会在不到 1 毫秒内产生超过 500mA 的快速电流脉冲。如果电源、又长又细的 USB 线、面包板电源轨或 LDO 稳压器无法以低阻抗提供瞬时电流，芯片 3V3 引脚上的电压就会瞬间塌陷，触发内部的 Brownout 比较电路，以避免闪存数据损坏和不确定状态。",
gambiarra: {
titulo: "通过软件关闭 Brownout",
descricao: "调用 WRITE_PERI_REG(RTC_CNTL_BROWN_OUT_REG, 0)，在代码里让错误不再出现。",
consequencia: "极其危险：ESP32 会在欠压下继续执行指令，损坏 SPI 闪存、锁死寄存器，并在现场出现无预警的不可预测行为。",
},
solucaoEngenharia: {
titulo: "合理设计硬件与去耦",
passos: [
"在尽可能靠近 ESP32 的 3V3 和 GND 引脚处，并联一个 10µF 到 100µF 的低 ESR（Low-ESR）钽电容或陶瓷电容，以及一个 100nF 陶瓷电容。",
"使用峰值电流不低于 600mA 至 1A、瞬态响应优秀的 LDO 稳压器（例如 AP2112K、ME6211、TPS73733 或可靠的 XC6206）。避免使用老款 AMS1117 的劣质仿品。",
"当 Wi-Fi 以最大功率发射时，避免用很长的面包板电源轨加细杜邦线给 ESP32 供电。",
],
},
codigoArduino: `// 不要关闭 Brownout！如果测试时需要降低峰值：
#include <WiFi.h>
void setup() {
Serial.begin(115200);
// 可选：把 Wi-Fi 最大发射功率从 20dBm 略降到 17dBm，
// 可使电流峰值降低约 20%
WiFi.setTxPower(WIFI_POWER_17dBm);
WiFi.begin("SSID", "PASSWORD");
}`,
codigoEspIdf: `// ESP-IDF 中的配置：
#include "esp_wifi.h"
#include "esp_log.h"
void app_main(void) {
// 在 menuconfig 中：Component config -> ESP32-specific -> Hardware Brownout Reset（始终保持开启）
// 在有功率限制的环境中降低峰值：
esp_wifi_set_max_tx_power(68); // 68 = 17dBm（单位为 0.25dBm）
}`,
codigoMicroPython: `# MicroPython 中带稳定等待的安全 Wi-Fi 连接：
import network
import time
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
# 等待供电稳定后再开始发射
time.sleep_ms(200)
wlan.connect("SSID", "PASSWORD")
tentativas = 0
while not wlan.isconnected() and tentativas < 30:
time.sleep_ms(200)
tentativas += 1
if wlan.isconnected():
print("Wi-Fi connected! IP:", wlan.ifconfig()[0])
else:
print("[ERROR] Failed to connect to Wi-Fi")`,
dicaPro: "如果你在设计自己的 PCB，请在模组下方铺设完整的地平面，并让电源走线宽度至少为 0.5mm 到 1mm，以承受电流浪涌而不产生阻性压降（IR drop）。",
},
{
id: "strapping-pins",
titulo: "启动时 Strapping 引脚冲突",
categoria: "alimentacao",
sintomas: ["bootloop", "upload-fail"],
gravidade: "严重",
logSerial: "rst:0x1 (POWERON_RESET),boot:0x12 (SPI_FAST_FLASH_BOOT)\nflash read err, 1000\nwaiting for download",
resumo: "ESP32 无法从闪存启动固件，或意外进入下载模式，原因是某个 Strapping 引脚在复位时被强制到了错误的逻辑电平。",
causaRaiz:
"在 EN/CHIP_PU 引脚拉高（上电复位）的瞬间，CPU 会对特定引脚（Strapping 引脚）的状态采样，以配置闪存电压（1.8V 或 3.3V）、启动模式（UART 下载或 SPI 闪存）和时钟输出。如果你在这些引脚上接了带上拉/下拉的传感器、继电器或 LED，微控制器读到的就是无效逻辑电平，启动随之卡住。",
gambiarra: {
titulo: "在代码里加延时，或每次上电都手动拔线",
descricao: "试图在 setup() 里用软件解决问题，或依赖每次重启前手动断开连线。",
consequencia: "没用：Strapping 引脚由硬件读取，此时 CPU 还没有加载你的代码或引导加载程序中的任何一行。",
},
solucaoEngenharia: {
titulo: "安全的 GPIO 分配与复位期间隔离",
passos: [
"经典 ESP32：避免使用 GPIO 0（Boot）、GPIO 2（闪存启动时必须为 LOW 或悬空）、GPIO 12（决定闪存电压：复位时若被拉高，会损坏或卡死 3.3V 闪存）以及 GPIO 15（为 LOW 时屏蔽启动日志）。",
"ESP32-C3：避免在复位时把 GPIO 8 或 GPIO 9 拉低。",
"ESP32-S3：注意 GPIO 0、GPIO 45（VDD_SPI 电压）和 GPIO 46。",
"如果必须把这些引脚用于外设，请用三极管或缓冲器隔离，直到 EN 信号完全稳定。",
],
},
codigoArduino: `// 安全引脚分配建议（经典 ESP32）：
// 适合 I2C / SPI / 一般传感器的引脚：
// SDA: GPIO 21 | SCL: GPIO 22
// SPI: MOSI 23 | MISO 19 | SCK 18 | CS 5
// 注意：GPIO 34、35、36 (VP)、39 (VN) 只能作输入（没有内部上拉）。
// 不要对它们使用 pinMode(..., OUTPUT)，也不要用于 I2C/SPI。`,
codigoEspIdf: `// 在 ESP-IDF 中，通过 eFuse 固定闪存电压设置（注意：不可逆）：
// 如果你使用经典 ESP32 且需要释放 GPIO12，可以烧写 3.3V 的 eFuse：
// espefuse.py --port /dev/ttyUSB0 set_flash_voltage 3.3V
// 这会永久关闭 GPIO12 上的硬件采样。`,
codigoMicroPython: `# MicroPython 中正确的引脚配置：
from machine import Pin
# ✅ 可安全用于输出和带内部上拉按键的引脚：
led = Pin(2, Pin.OUT) # GPIO 2
botao = Pin(4, Pin.IN, Pin.PULL_UP) # GPIO 4（安全）
# ⚠️ 引脚 34、35、36、39 只能作输入，且没有内部上拉：
sensor_analogico = Pin(36, Pin.IN) # 正确（若用作按键，需要外接电阻）`,
dicaPro: "请始终记住：“仅输入”引脚（经典 ESP32 的 GPI 34 到 39）在芯片内没有上拉/下拉电路，也没有输出三极管。在这些引脚上接模拟传感器或按键，需要外接上拉电阻。",
},
{
id: "guru-load-prohibited",
titulo: "Guru Meditation：LoadProhibited / StoreProhibited",
categoria: "cpu-panics",
sintomas: ["bootloop", "null-pointer"],
gravidade: "严重",
logSerial: "Guru Meditation Error: Core 0 panic'ed (LoadProhibited). Exception was unhandled.\nCore 0 register dump:\nPC : 0x400d14bc PS : 0x00060830 A0 : 0x800d1512 A1 : 0x3ffb1f20 \nEXCVADDR: 0x00000000",
resumo: "CPU 试图读取（Load）或写入（Store）一个不可访问或无效的内存地址，通常是空地址 0x00000000。",
causaRaiz:
"这是典型的空指针解引用（Null Pointer Dereference）或野指针（Dangling Pointer）。EXCVADDR 寄存器给出了引发故障的地址：如果 EXCVADDR 为 0x00000000 或非常接近零（例如 0x00000008，即结构体成员的偏移），就说明你访问了一个未初始化、或 malloc/创建失败的对象/指针的成员。",
gambiarra: {
titulo: "随便加延时，或在循环里不处理就重启",
descricao: "以为是时序问题，在代码里堆满 delay()，或者不查原因就屏蔽自动重启。",
consequencia: "空指针条件再次出现时，系统在量产环境中仍会随机崩溃。",
},
solucaoEngenharia: {
titulo: "防御式校验与 Backtrace 解码",
passos: [
"在访问返回值的成员之前，始终检查分配或查找类函数（malloc、WiFi.client()、JSON 解析、xQueueReceive）是否返回了 NULL。",
"在你的 IDE（Arduino IDE / PlatformIO）中安装“Espressif Exception Decoder”，或使用命令 'xtensa-esp32-elf-addr2line -pfia -e firmware.elf 0x400d14bc'，精确找到崩溃发生在 .c/.cpp 的哪一行。",
"在 ESP-IDF 中运行 'idf.py monitor'，它会实时自动解码栈回溯。",
],
},
codigoArduino: `// 防御式编程：
struct SensorData {
float temperatura;
float umidade;
};
void processarSensor(SensorData* sensor) {
// 防止 LoadProhibited 的必要检查：
if (sensor == nullptr) {
Serial.println("[ERROR] Null sensor pointer!");
return;
}
Serial.printf("Temp: %.1f C\\n", sensor->temperatura);
}`,
codigoEspIdf: `// 在 ESP-IDF 中使用 ESP_ERROR_CHECK 或显式断言：
#include "esp_log.h"
#include "esp_check.h"
static const char* TAG = "SENSOR";
esp_err_t ler_dado(char* buffer, size_t max_len) {
ESP_RETURN_ON_FALSE(buffer != NULL, ESP_ERR_INVALID_ARG, TAG, "Null buffer provided!");
// 安全的操作...
return ESP_OK;
}`,
codigoMicroPython: `# 在 MicroPython 中防止 NoneType 和对象异常：
import json
def processar_sensor(dados_raw):
# 防御式处理空 payload：
if dados_raw is None:
print("[ERROR] Null data received!")
return None
try:
obj = json.loads(dados_raw)
# 安全使用带默认值的 .get()，避免 KeyError
temperatura = obj.get("temp", 0.0)
return temperatura
except (ValueError, AttributeError) as e:
print("Error processing object:", e)
return None`,
dicaPro: "如果 EXCVADDR 类似 0x3fxxxxxx 或 0x40xxxxxx 但你的代码仍然出错，可能是数组越界访问（buffer overflow）覆盖了内存中的指针。",
},
{
id: "guru-iram-cache",
titulo: "ISR 中的 Cache Error / InstructionFetchError",
categoria: "cpu-panics",
sintomas: ["bootloop", "null-pointer"],
gravidade: "高",
logSerial: "Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region accessed)\nGuru Meditation Error: Core 0 panic'ed (InstructionFetchError)",
resumo: "中断服务例程（ISR）试图在 SPI 闪存因读写操作而被禁用时，执行闪存中的代码或读取其中的数据。",
causaRaiz:
"默认情况下，ESP32 的代码存放在外部闪存中，并通过内部缓存（Cache）按需加载给 CPU。当 ESP32 向闪存写入数据（如写入 NVS、LittleFS、SPIFFS 或 OTA 升级）时，控制器会暂时关闭指令缓存。如果此刻触发了硬件中断（定时器、GPIO 等），而 ISR 函数位于闪存中，CPU 就取不到下一条指令，立即陷入异常。",
gambiarra: {
titulo: "写闪存前关闭中断",
descricao: "不加区分地用 noInterrupts() 包住所有文件写入操作。",
consequencia: "会丢失高速传感器的脉冲，导致系统定时器不稳定，并可能引发看门狗溢出。",
},
solucaoEngenharia: {
titulo: "把 ISR 与常量放进 IRAM / DRAM",
passos: [
"给每一个中断回调函数都加上 IRAM_ATTR 属性（或 IRAM_ATTR static void...）。",
"确保 ISR 中访问的变量或字符串也位于 DRAM 中（在 ESP-IDF 中，避免在 ISR 里直接使用没有 DRAM_ATTR 标记的字符串字面量）。",
"不要在 ISR 里调用外部库的重型函数（如 Serial.print 或大量浮点计算）。",
],
},
codigoArduino: `// 正确放入 IRAM 的 ISR：
volatile uint32_t contadorPulsos = 0;
void IRAM_ATTR tratarInterrupcaoGPIO() {
contadorPulsos++;
}
void setup() {
pinMode(4, INPUT_PULLUP);
attachInterrupt(digitalPinToInterrupt(4), tratarInterrupcaoGPIO, FALLING);
}`,
codigoEspIdf: `// 在 ESP-IDF 中：
#include "esp_attr.h"
#include "driver/gpio.h"
static volatile uint32_t pulsos = 0;
// 显式放入内部 IRAM 的函数：
static void IRAM_ATTR gpio_isr_handler(void* arg) {
pulsos++;
}
void app_main(void) {
gpio_install_isr_service(ESP_INTR_FLAG_IRAM);
gpio_isr_handler_add(GPIO_NUM_4, gpio_isr_handler, NULL);
}`,
codigoMicroPython: `# MicroPython 中安全的中断（ISR）处理：
import micropython
from machine import Pin
# 分配应急缓冲区，用于调试 ISR 内部的异常：
micropython.alloc_emergency_exception_buf(100)
contador_pulsos = 0
# 中断回调：不要分配内存（不要创建字符串，不要产生新的浮点数）
def tratar_pulso(pin):
global contador_pulsos
contador_pulsos += 1
sensor = Pin(4, Pin.IN, Pin.PULL_UP)
sensor.irq(trigger=Pin.IRQ_FALLING, handler=tratar_pulso)`,
dicaPro: "如果在 ESP-IDF 中注册中断时传入了 ESP_INTR_FLAG_IRAM，那么该中断调用的任何函数（包括 FreeRTOS 函数）都必须支持 IRAM（例如 xQueueSendFromISR）。",
},
{
id: "freertos-twdt",
titulo: "任务看门狗定时器（TWDT）超时",
categoria: "freertos",
sintomas: ["bootloop", "wdt-reset"],
gravidade: "严重",
logSerial: "E (10532) task_wdt: Task watchdog got triggered. The following tasks/users did not reset the watchdog in time:\nE (10532) task_wdt: - IDLE0 (CPU 0)\nTask watchdog got triggered. System will be reset.",
resumo: "一个高优先级任务陷入阻塞式循环，没有让出 CPU 时间，使 IDLE 任务无法喂狗。",
causaRaiz:
"ESP32 上的 FreeRTOS 在每个 CPU 内核上都运行一个优先级为 0 的关键任务，名为 IDLE。任务看门狗会监测 IDLE 任务能否周期性运行（默认每 5 秒）。如果你创建了一个优先级 >= 1 的任务，其中有 while(1) 循环却没有任何阻塞调用（vTaskDelay、读队列、信号量），CPU 就会 100% 被占满，看门狗随即触发紧急复位。",
gambiarra: {
titulo: "在 menuconfig 里关闭任务看门狗，或把它调到 60 秒",
descricao: "关掉 TWDT，让代码不再重启。",
consequencia: "如果代码陷入死循环或死锁，微控制器会永远冻结，只能有人跑到现场拔电源。",
},
solucaoEngenharia: {
titulo: "事件驱动架构与让出 CPU（Yield）",
passos: [
"在 FreeRTOS 任务中，不要使用空的忙等待循环 while(!condicao);。",
"始终加入 vTaskDelay(pdMS_TO_TICKS(10))，或通过带超时的 xQueueReceive()、ulTaskNotifyTake() 或 xSemaphoreTake() 等待事件。",
"如果必须持续进行繁重的数学运算，请用 esp_task_wdt_reset() 显式喂狗。",
],
},
codigoArduino: `// Arduino 搭配 FreeRTOS 的正确写法：
void minhaTarefa(void *pvParameters) {
for (;;) {
// 读取传感器
float valor = analogRead(36);
// 把 CPU 让给 FreeRTOS 和 IDLE 任务：
vTaskDelay(pdMS_TO_TICKS(100)); // 以非阻塞方式等待 100ms
}
}`,
codigoEspIdf: `// ESP-IDF 中使用任务看门狗：
#include "esp_task_wdt.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
void tarefa_processamento(void *pvParameters) {
// 可选：把当前任务注册到 TWDT
esp_task_wdt_add(NULL);
while (1) {
// 处理...
// 如果这段处理很长，就喂狗：
esp_task_wdt_reset();
vTaskDelay(pdMS_TO_TICKS(50));
}
}`,
codigoMicroPython: `# MicroPython 中使用 uasyncio 的看门狗与非阻塞循环：
from machine import WDT
import uasyncio as asyncio
# 初始化硬件看门狗，超时 5 秒
wdt = WDT(timeout=5000)
async def tarefa_sensor():
while True:
# 每个正常周期都喂狗：
wdt.feed()
# 把控制权交还给协作式调度器：
await asyncio.sleep_ms(100)
async def main():
asyncio.create_task(tarefa_sensor())
while True:
await asyncio.sleep(1)
asyncio.run(main())`,
dicaPro: "在 Arduino 中，delay(ms) 函数内部其实调用的是 FreeRTOS 的 vTaskDelay。但使用 delayMicroseconds() 的循环或纯 CPU 运算不会让出时间，持续数秒以上就可能触发 TWDT。",
},
{
id: "freertos-stack-overflow",
titulo: "栈溢出（Stack Overflow）",
categoria: "freertos",
sintomas: ["bootloop", "null-pointer"],
gravidade: "严重",
logSerial: "Guru Meditation Error: Core 1 panic'ed (Unhandled debug exception).\nDebug exception reason: Stack canary watchpoint triggered (minha_tarefa)",
resumo: "任务消耗的栈（Stack）内存超过了创建时分配的大小，破坏了 RTOS 的保护金丝雀（canary）。",
causaRaiz:
"FreeRTOS 中的每个任务都会得到一块固定的连续内存，用来存放局部变量、函数参数和调用的返回地址。如果你声明了大数组（如 char buffer[2048];）、实例化了较大的 JSON 缓冲区（如 DynamicJsonDocument doc(4096);），或在默认栈为 2048 字节的任务里做很深的递归调用，栈就会越界并覆盖系统的关键区域。",
gambiarra: {
titulo: "不加考虑地给所有任务都设 64KB 栈",
descricao: "分配巨大的栈，免得操心溢出。",
consequencia: "ESP32 的内部 SRAM（实际可用约 320KB）很快会耗尽，导致 Wi-Fi 初始化和堆分配失败。",
},
solucaoEngenharia: {
titulo: "有意识地确定大小，并用 HighWaterMark 监控",
passos: [
"使用 uxTaskGetStackHighWaterMark() 函数测量栈的实际消耗。它返回自启动以来栈剩余空闲字节/字数的最小值。",
"把体积大的缓冲区从栈移到动态堆（临时使用 malloc/free），如果会被重复使用，则在函数作用域外声明为 static。",
"使用 TLS/HTTPS 安全连接或 SSL 的 MQTT 的任务，由于 MbedTLS 加密例程很复杂，至少需要 6KB 到 8KB 的栈。",
],
},
codigoArduino: `// 在 Arduino 中监控栈：
void tarefaSensor(void *pvParameters) {
for (;;) {
// 任务代码...
// 检查栈的最小剩余空间（经典 FreeRTOS 以 Word 为单位，ESP32 以字节为单位）
UBaseType_t espacoLivre = uxTaskGetStackHighWaterMark(NULL);
Serial.printf("[STACK] Minimum free space: %d bytes\\n", (int)espacoLivre);
vTaskDelay(pdMS_TO_TICKS(5000));
}
}
void setup() {
Serial.begin(115200);
// 合理地分配 4096 字节（4KB）：
xTaskCreatePinnedToCore(tarefaSensor, "tarefaSensor", 4096, NULL, 1, NULL, 1);
}`,
codigoEspIdf: `// 在 menuconfig 中启用栈的双重检查：
// Component config -> FreeRTOS -> Set a end of stack check -> Option 2 (Check by Stack Canary)
// 这样能在运行时数据被破坏之前就检测到溢出。`,
codigoMicroPython: `# MicroPython 中监控内存与栈：
import gc
import micropython
# 输出 Python 虚拟机的 RAM 与栈统计：
micropython.mem_info()
# 运行垃圾回收，释放孤立的内存块：
gc.collect()
print("Free heap:", gc.mem_free(), "bytes")
print("Allocated heap:", gc.mem_alloc(), "bytes")`,
dicaPro: "如果函数只是偶尔处理一次 JSON 或 HTTP 数据包，请只在处理期间把缓冲区分配在堆上，用完立刻释放，而不是撑大任务的常驻栈。",
},
{
id: "memoria-fragmentacao-heap",
titulo: "堆碎片化与内存泄漏",
categoria: "memoria",
sintomas: ["random-freeze", "tls-fail"],
gravidade: "高",
logSerial: "E (45892) mbedtls: mbedtls_ssl_setup returned -0x7f00\nE (45892) esp-tls: create_ssl_handle failed\nE (45893) HTTP_CLIENT: Connection failed, out of memory",
resumo: "微控制器分配内存失败，尽管报告的空闲内存总量看起来还很多。",
causaRaiz:
"当长时间发生成千上万次大小不一的分配与释放时（在 Arduino 中对 String 对象在循环里不断拼接文本时非常常见），堆就会碎片化。堆被分割成许多被占用块隔开的小空闲块。当 Wi-Fi 驱动或 TLS 库需要一块连续的 40KB 作为 SSL 加密缓冲区时，即便分散的空闲内存总共有 100KB，malloc 也会失败。",
gambiarra: {
titulo: "每隔 X 小时用 ESP.restart() 定期重启 ESP32",
descricao: "安排每天重启一次，以清理碎片化的内存。",
consequencia: "只是掩盖缺陷：在请求高峰时，设备会远早于计划的重启就崩溃。",
},
solucaoEngenharia: {
titulo: "避免动态字符串，使用预先分配的静态缓冲区",
passos: [
"在 Arduino 中避免使用 String 类。使用 C 风格的字符缓冲区（char buffer[128];）和 snprintf() 这类安全函数。",
"通过对照空闲内存总量（heap_caps_get_free_size）与最大连续空闲块（heap_caps_get_largest_free_block）来监控碎片化。",
"在复杂的 ESP-IDF 固件中，启用堆内存追踪（Heap Memory Tracing，CONFIG_HEAP_TRACING），精确列出是哪些文件和行忘了调用 free()。",
],
},
codigoArduino: `// 对比：
// ❌ 避免（会造成严重的堆碎片化）：
// String json = "{\\"temp\\":";
// json += String(temperatura) + "}";
// ✅ 正确（不在堆上动态分配）：
char payload[64];
snprintf(payload, sizeof(payload), "{\\"temp\\":%.2f,\\"umid\\":%.2f}", temperatura, umidade);
// 监控：
Serial.printf("Free heap: %u | Largest block: %u\\n",
ESP.getFreeHeap(),
ESP.getMaxAllocHeap());`,
codigoEspIdf: `// ESP-IDF 中的堆监控：
#include "esp_heap_caps.h"
#include "esp_log.h"
void inspecionar_memoria(void) {
size_t livre_total = heap_caps_get_free_size(MALLOC_CAP_8BIT);
size_t maior_bloco = heap_caps_get_largest_free_block(MALLOC_CAP_8BIT);
ESP_LOGI("HEAP", "Total free: %d bytes | Largest contiguous block: %d bytes", livre_total, maior_bloco);
}`,
codigoMicroPython: `# MicroPython 中预防堆碎片化：
import gc
# 1. 启用自动回收
gc.enable()
# 2. 预先分配 bytearray 并复用，而不是创建新字符串：
buffer_leitura = bytearray(256)
def ler_sensor_sem_alocacao(stream):
# 复用同一块内存读取（零分配，Zero-Allocation）：
bytes_lidos = stream.readinto(buffer_leitura)
return buffer_leitura[:bytes_lidos]
# 3. 在建立重量级连接（如 HTTPS / TLS）之前触发 GC：
gc.collect()
print(f"Free heap: {gc.mem_free()} B | Allocated: {gc.mem_alloc()} B")`,
dicaPro: "如果最大连续空闲块小于 35KB ~ 40KB，现代 HTTPS/TLS 连接会在证书握手期间失败。",
},
{
id: "memoria-dma-psram",
titulo: "在外部内存（PSRAM）中分配 DMA 失败",
categoria: "memoria",
sintomas: ["bootloop", "random-freeze"],
gravidade: "高",
logSerial: "E (1204) spi_master: spi_bus_initialize: DMA channel not compatible with external RAM buffer\nESP_ERROR_CHECK failed: esp_err_t 0x102 (ESP_ERR_INVALID_ARG)",
resumo: "固件试图把分配在外部 PSRAM 中的缓冲区交给带 DMA 的外设（SPI、I2S、LCD、SDMMC），而这些外设只能访问内部 SRAM。",
causaRaiz:
"在 ESP32 系列芯片中（尤其是采用标准总线的经典 ESP32、ESP32-S2 和 ESP32-S3），外设的 DMA 控制器没有直接访问通过 SPI/QSPI 连接的外部 PSRAM 的物理总线。DMA 要求收发缓冲区必须位于芯片的内部 SRAM 中。",
gambiarra: {
titulo: "关闭外设的 DMA",
descricao: "把 SPI/I2S 总线配置为不用 DMA 的轮询模式。",
consequencia: "传输速率大幅下降，向显示屏发送帧或进行音频流传输时 CPU 被 100% 占满。",
},
solucaoEngenharia: {
titulo: "用 MALLOC_CAP_DMA 和 MALLOC_CAP_INTERNAL 显式分配",
passos: [
"始终使用 heap_caps_malloc(大小, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL) 函数分配专用于 DMA 的缓冲区。",
"把体积大的非 DMA 数据（如解码后的图像、机器学习模型和待播放的音频）保留在 PSRAM 中，并按需把较小的块复制到内部的 DMA 缓冲区（乒乓缓冲，ping-pong buffering）。",
],
},
codigoArduino: `// 在 Arduino ESP32 中分配 DMA 缓冲区：
#include <esp_heap_caps.h>
uint8_t* dmaBuffer = nullptr;
void setup() {
size_t tamanho = 4096;
// 确保缓冲区位于支持 DMA 的内部 SRAM 中：
dmaBuffer = (uint8_t*) heap_caps_malloc(tamanho, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
if (dmaBuffer == nullptr) {
Serial.println("[ERROR] Failed to allocate DMA buffer in internal memory!");
}
}`,
codigoEspIdf: `// ESP-IDF：
#include "esp_heap_caps.h"
uint8_t* alocar_buffer_spi(size_t len) {
return (uint8_t*) heap_caps_aligned_alloc(4, len, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
}`,
codigoMicroPython: `# 在 MicroPython 中，检查可用的 PSRAM 内存：
import gc
import esp32
# 如果固件编译时带有 SPIRAM 支持（例如名称含 'SPIRAM' 的固件）：
print("Total memory accessible in MicroPython:", gc.mem_free() + gc.mem_alloc(), "bytes")
# 对外设做快速操作时，使用连续的 bytearray：
buffer_spi = bytearray(1024)`,
dicaPro: "在 ESP32-P4 上，先进的 AXI 总线架构允许在某些外部区域使用 DMA，但对整个 ESP32/S2/S3/C3 系列，必须使用内部 SRAM 的规则是严格的。",
},
{
id: "boot-failed-connect",
titulo: "Failed to connect to ESP32: Timed out waiting for packet header",
categoria: "boot-flash",
sintomas: ["upload-fail"],
gravidade: "中",
logSerial: "A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header\nesptool.py v4.6\nConnecting...................",
resumo: "烧录工具（esptool / Arduino IDE / PlatformIO）无法让微控制器进入 UART 引导加载模式。",
causaRaiz:
"开始烧录固件时，USB 转串口芯片（CH340、CP2102、FTDI）会通过 DTR 和 RTS 线把 GPIO 0 引脚拉低，同时让 EN/RST 引脚先拉低再拉高。在许多常见开发板上，EN 引脚的 RC（电阻电容）延时电路电容量不足，无法在 DTR 信号变化期间保持复位。",
gambiarra: {
titulo: "每次烧录都用手指按住 BOOT 按钮",
descricao: "每次编译器生成完二进制文件后，都要按一下物理 BOOT/GPIO0 按钮。",
consequencia: "不利于敏捷开发，对于封装好的或装在外壳内的板子则根本做不到。",
},
solucaoEngenharia: {
titulo: "在 EN 引脚加 10µF 电容，或检查数据线",
passos: [
"在板子的 EN（RST）引脚和 GND 之间接一个 10µF（或 1µF 到 10µF）的电解电容或陶瓷电容，以稳定自动复位的上升斜坡。",
"检查 USB 线的数据线（D+ 和 D-）是否正常。许多便宜的手机充电线只有 VBUS 和 GND 两根电源线。",
"在 Linux 上，确认你的用户属于 'dialout' 组（sudo usermod -a -G dialout $USER），并且 'brltty' 服务没有占用串口。",
],
},
codigoArduino: `// 用 esptool 测试串口通信的命令行提示：
// python -m esptool --port /dev/ttyUSB0 chip_id
// 如果返回了 MAC 地址和芯片型号，说明物理通信完全正常。`,
codigoEspIdf: `// 在 ESP-IDF 中：
// idf.py -p /dev/ttyUSB0 -b 460800 flash
// 如果高速烧录失败，请把波特率降到 115200：
// idf.py -p /dev/ttyUSB0 -b 115200 flash`,
codigoMicroPython: `# 通过终端把官方 MicroPython 固件烧录到 ESP32：
# 1. 擦除闪存：
# esptool.py --port /dev/ttyUSB0 erase_flash
# 2. 以稳妥的波特率写入二进制文件：
# esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x1000 ESP32_GENERIC-*.bin`,
dicaPro: "如果你使用的是带原生 USB（Direct USB-JTAG）的 ESP32-S3 或 C3 模组，请确认选择的是 CDC/JTAG 端口，而不是传统的 UART 端口。",
},
{
id: "tls-sntp-clock-fail",
titulo: "时钟不同步导致 TLS/HTTPS 握手失败",
categoria: "conectividade",
sintomas: ["tls-fail", "random-freeze"],
gravidade: "高",
logSerial: "E (15420) esp-tls-mbedtls: mbedtls_ssl_handshake returned -0x2700\nE (15420) esp-tls: Failed to verify peer certificate!\nE (15421) esp-tls: Verification info: The certificate is not yet valid (or has expired)",
resumo: "HTTPS 安全连接、AWS IoT、带 TLS 的 MQTT 或 Web API 失败，原因是 ESP32 的内部时钟停在默认日期 1970 年 1 月 1 日。",
causaRaiz:
"数字安全证书（X.509 SSL/TLS）有严格的有效期（Not Before 和 Not After）。由于 ESP32 默认没有外部 RTC 电池，上电时内部时钟总是从 Unix 纪元零点（1970 年）开始。MbedTLS 客户端校验服务器证书的日期时，会认为证书“尚未生效”（因为相对 1970 年，2026 年是未来），并立刻以错误 -0x2700（MBEDTLS_ERR_X509_CERT_VERIFY_FAILED）中止加密连接。",
gambiarra: {
titulo: "关闭 SSL 证书校验（Insecure / No-Verify）",
descricao: "在 Arduino 中使用 client.setInsecure()，或在 ESP-IDF 中关闭 CA 检查。",
consequencia: "开了一个非常严重的安全缺口：设备易受中间人攻击（MitM），攻击者可以截获密码和固件。",
},
solucaoEngenharia: {
titulo: "在 TLS 连接之前，必须通过 SNTP 同步日期和时间",
passos: [
"在 Wi-Fi 获得 IP 之后，立即启动 SNTP 客户端，指向可靠的服务器（如 pool.ntp.org、time.google.com）。",
"等待时钟状态变为已同步，再发起第一次 HTTPS/MQTT 连接。",
"配置正确的时区（Timezone），让日志显示准确的时间。",
],
},
codigoArduino: `// Arduino 中 HTTPS 之前先做 SNTP 同步：
#include <WiFi.h>
#include <time.h>
void sincronizarRelogio() {
// 配置 NTP 服务器（pool.ntp.org 和 Google）
configTime(8 * 3600, 0, "pool.ntp.org", "time.google.com");
Serial.print("Waiting for time sync");
time_t now = time(nullptr);
// 2020 年的 Unix 时间是 1577836800。如果更小，说明仍停在 1970 年：
while (now < 1577836800) {
delay(500);
Serial.print(".");
now = time(nullptr);
}
Serial.println("\\n[OK] Time synchronized! TLS connections enabled.");
}`,
codigoEspIdf: `// ESP-IDF 中的 SNTP：
#include "esp_sntp.h"
#include "esp_log.h"
void inicializar_sntp(void) {
ESP_LOGI("SNTP", "Starting SNTP client...");
esp_sntp_setoperatingmode(SNTP_OPMODE_POLL);
esp_sntp_setservername(0, "pool.ntp.org");
esp_sntp_init();
// 等待时钟同步...
}`,
codigoMicroPython: `# MicroPython 中的 SNTP 同步与 HTTPS 请求：
import ntptime
import time
import urequests
def sincronizar_e_requisitar():
try:
print("Syncing clock via NTP...")
ntptime.host = "pool.ntp.org"
ntptime.settime() # 通过 NTP 更新 ESP32 的内部 RTC
print("Synchronized UTC time:", time.localtime())
# 现在 TLS 握手可以正常校验证书，不会再出现 -0x2700 错误：
resposta = urequests.get("https://api.github.com")
print("HTTPS response:", resposta.status_code)
resposta.close()
except Exception as e:
print("[TLS/NTP ERROR]:", e)`,
dicaPro: "如果你的项目运行在无法访问外部互联网的环境（隔离的局域网），请在路由器上配置本地 NTP 服务器，或通过 I2C 添加 DS3231 之类的实体 RTC 模块。",
},
];
export const regrasDecodificadorLog = [
{
padrao: /Brownout detector was triggered/i,
titulo: "Brownout Detector（严重欠压）",
tipo: "供电 / 硬件",
explicacao:
"ESP32 的 3V3 引脚电压跌到了安全水平以下（通常是 Wi-Fi/BLE 射频的电流峰值，或电源容量不足所致）。",
acaoRecomendada:
"在 VCC 处加一个 10µF 到 100µF 的低 ESR 电容，使用稳定的电源，并检查 LDO 稳压器。",
},
{
padrao: /LoadProhibited|StoreProhibited/i,
titulo: "Guru Meditation：Load/StoreProhibited（空指针或无效指针）",
tipo: "CPU 异常 / 异常",
explicacao:
"试图读取或写入内存中的无效地址（几乎总是 NULL 指针解引用或数组越界）。",
acaoRecomendada:
"用 Exception Decoder 或 'addr2line' 解码 Backtrace，找到确切的行。加入防御式检查 `if (ptr != NULL)`。",
},
{
padrao: /Cache disabled but cached memory region accessed|InstructionFetchError/i,
titulo: "中断中的 Cache Error（ISR 不在 IRAM 中）",
tipo: "CPU 异常 / 闪存",
explicacao:
"中断服务例程（ISR）试图从闪存运行，而此时闪存正忙于写入数据（NVS、LittleFS 或 OTA）。",
acaoRecomendada:
"给中断函数加上 `IRAM_ATTR` 属性，并确保它不会访问闪存中没有 DRAM_ATTR 的变量。",
},
{
padrao: /Task watchdog got triggered/i,
titulo: "任务看门狗定时器（TWDT）超时",
tipo: "FreeRTOS / 多任务",
explicacao:
"一个高优先级任务独占 CPU 而不让出时间（没有 vTaskDelay 或阻塞），使 IDLE 任务的看门狗无法喂狗。",
acaoRecomendada:
"在长循环中加入 `vTaskDelay(pdMS_TO_TICKS(10))`，或使用队列/信号量来代替持续的 `while(1)` 循环。",
},
{
padrao: /Stack canary watchpoint triggered/i,
titulo: "栈溢出（任务栈溢出）",
tipo: "FreeRTOS / 内存",
explicacao:
"任务超出了创建时分配的栈（Stack）内存量，破坏了保护金丝雀。",
acaoRecomendada:
"在 `xTaskCreate` 中增大栈的大小（例如从 2048 增加到 4096 字节），并把大数组移到堆或静态变量中。",
},
{
padrao: /Timed out waiting for packet header|Failed to connect to ESP32/i,
titulo: "UART / 烧录连接失败",
tipo: "引导加载程序 / 连接",
explicacao:
"电脑无法通过 DTR/RTS 让 ESP32 进入烧录模式，或 USB 线没有数据线。",
acaoRecomendada:
"在 EN 引脚和 GND 之间接一个 10µF 电容，换一根带数据线的 USB 线，并在连接时尝试按住 BOOT 按钮。",
},
{
padrao: /The certificate is not yet valid|-0x2700/i,
titulo: "SSL/TLS 证书失败（时钟停在 1970 年）",
tipo: "网络连接 / TLS",
explicacao:
"ESP32 试图在日期仍为 Unix 纪元零点（1970 年 1 月 1 日）的情况下验证 HTTPS/TLS 证书。",
acaoRecomendada:
"在发起安全的 HTTPS 请求之前，通过 SNTP 同步时间（Arduino 中用 `configTime`，MicroPython 中用 `ntptime.settime()`）。",
},
{
padrao: /rst:0x1 \(POWERON_RESET\),boot:0x[0-9a-fA-F]+/i,
titulo: "上电复位 / Strapping 引脚",
tipo: "硬件 / 启动",
explicacao:
"微控制器重启并报告了 Strapping 引脚寄存器。如果之后卡住，可能是某个启动引脚处于错误的逻辑电平。",
acaoRecomendada:
"检查 GPIO 0、2、12、15（ESP32）或 8、9（C3）是否连着在启动时会强制出错误电平的电阻或外设。",
},
];
lib/data/zh-CN/glossario.js
+408
View File
@@ -0,0 +1,408 @@
/**
* ESP32 技术术语表的结构化数据。
* 涵盖乐鑫全部芯片系列（ESP32、S2、S3、S31、C2、C3、C5、C6、C61、H2、H4、P4）
* 及其硬件、外设、无线、安全与软件特性。
*/
export const categoriasGlossario = [
{
id: "processamento",
nome: "处理器、CPU 与芯片",
icone: "Cpu",
emoji: "🧠",
cor: "blue",
descricao: "Xtensa 与 RISC-V 架构、内核、ULP 协处理器、AI 向量加速器和浮点运算单元。",
termos: [
{
termo: "Xtensa 与 RISC-V 架构",
definicao: "处理器的基础指令集。经典 ESP32、S2 和 S3 使用 Tensilica 的专有 Xtensa 内核（LX6/LX7）；较新的 C 系列（C2、C3、C5、C6、C61）、H 系列（H2、H4）和 P 系列（P4）则采用开放、模块化且高能效的 32 位 RISC-V 架构。",
exemplo: "ESP32-S3 使用双核 Xtensa LX7，ESP32-C6 使用单核 RISC-V，ESP32-P4 使用 400 MHz 的双核 RISC-V。",
},
{
termo: "CPU 内核（双核与单核）",
definicao: "彼此独立的中央处理单元。双核芯片可以让一个内核（Core 0）专门负责 Wi-Fi/蓝牙射频和 FreeRTOS 调度，把第二个内核（Core 1）完全留给用户应用和计算。",
exemplo: "ESP32、ESP32-S3 和 ESP32-P4 是双核；ESP32-S2、C2、C3、C6 和 H2 是单核。",
},
{
termo: "时钟频率（MHz）",
definicao: "以兆赫兹（MHz）衡量的处理速度。ESP-IDF 会动态调整频率（动态频率调节，DFS），在空闲时节省电能。",
exemplo: "ESP32-C2 最高运行在 120 MHz；ESP32、S2、S3 和 C6 可达 160/240 MHz；ESP32-P4 可达 400 MHz。",
},
{
termo: "ULP（超低功耗协处理器）",
definicao: "独立的超低功耗辅助处理器。在主内核处于深度睡眠（Deep Sleep）时，它仍可继续执行指令，读取模拟传感器（ADC）、I2C 和 GPIO 引脚。",
exemplo: "初代 ESP32 带有 ULP FSM；ESP32-S2、S3 和 C6 带有可用 C 语言编程的 ULP RISC-V；ESP32-P4 带有专用的低功耗 ULP。",
},
{
termo: "AI 向量扩展（Vector Extension / ESP-NN）",
definicao: "芯片中的专用指令，可并行执行整数（int8/int16）向量与矩阵运算，加速卷积神经网络（CNN）和信号处理。",
exemplo: "ESP32-S3 和 ESP32-P4 可加速人脸识别、语音检测以及 TensorFlow Lite for Microcontrollers 模型的推理。",
},
{
termo: "FPU（浮点运算单元）",
definicao: "硬件浮点运算单元，可在一个时钟周期内完成小数（`float`）的加、乘、除运算，没有软件开销。",
exemplo: "ESP32 和 ESP32-S3 的 Xtensa 内核带有 FPU，ESP32-P4 的高性能 RISC-V 内核同样带有。",
},
{
termo: "PPA（像素处理加速器）",
definicao: "ESP32-P4 独有的 2D 图形硬件加速器，用于加速图像处理：帧旋转、缩放、Alpha 通道混合和颜色转换（RGB565、ARGB8888、YUV420）。",
exemplo: "以 60 FPS 渲染复杂图形界面（LVGL），且不占用主 CPU 内核的时间。",
},
],
},
{
id: "seguranca",
nome: "安全、加密与 eFuse",
icone: "ShieldCheck",
emoji: "🔒",
cor: "red",
descricao: "防篡改 eFuse、安全启动 V2（Secure Boot V2）、XTS-AES 闪存加密、密钥管理器（Key Manager）、ECC 以及 DPA 防护。",
termos: [
{
termo: "eFuse（电子熔丝）",
definicao: "由微型硅熔丝构成、只能一次性且不可逆写入的存储（OTP，一次性可编程）。用于保存加密密钥、出厂 MAC 地址，并在商用产品中锁定调试接口。",
exemplo: "配合 `espefuse.py` 工具烧写安全启动密钥，并在产品出货前禁用 JTAG 端口。",
},
{
termo: "安全启动（Secure Boot，V1 与 V2）",
definicao: "一种安全启动协议：ROM 代码先对引导加载程序和固件的 RSA-3072 或 ECDSA 签名做密码学校验，通过后才允许执行，从而阻止被篡改的代码注入。",
exemplo: "经典 ESP32 使用安全启动 V1；从 ESP32-S2 起全部采用支持多组签名密钥的安全启动 V2。",
},
{
termo: "闪存加密（Flash Encryption）",
definicao: "硬件机制，使用 XTS-AES 算法对外部 SPI 闪存的内容进行实时加密和解密。即使开发板被盗或闪存被拆焊，也无法直接读取固件。",
exemplo: "大多数芯片使用 XTS-AES-128；ESP32-S3、C5、P4 和 H4 还支持 XTS-AES-256。",
},
{
termo: "密钥管理器（Key Manager）",
definicao: "高级安全模块，在芯片内部生成、存储并使用密钥，密钥不会暴露给 SRAM 或固件，因此即使软件存在漏洞也无法提取密钥。",
exemplo: "见于 ESP32-S31、ESP32-C5 和 ESP32-P4 等高安全性系列。",
},
{
termo: "硬件 ECC 与 ECDSA",
definicao: "在芯片中实现的椭圆曲线加速器（如 P-256 和 P-384）和 ECDSA 数字签名算法，对于快速安全地连接云端以及满足 Matter 标准的认证要求至关重要。",
exemplo: "ESP32-S31、C5、C61、P4、H2 和 H4 带有 ECDSA 硬件加速器。",
},
{
termo: "HMAC 与数字签名（DS）",
definicao: "密码学认证外设，使用烧写在 eFuse 中、对固件不可见的密钥来计算 HMAC 并对消息签名。",
exemplo: "无需以明文保存证书，即可与 AWS IoT Core 和 Microsoft Azure IoT 进行安全、快速的认证。",
},
{
termo: "TRNG（真随机数发生器）",
definicao: "基于射频与硅电路的模拟热噪声的真随机数发生器，对于在 TLS/HTTPS 握手中生成会话密钥至关重要。",
exemplo: "ESP32 全系列均提供，为 HTTPS/MbedTLS 连接提供可靠的熵源。",
},
{
termo: "DPA 防护（差分功耗分析）",
definicao: "硬件层面的物理机制，通过在芯片电流消耗中加入噪声并做平衡，防止攻击者用示波器测量功耗来推断密钥。",
exemplo: "见于 ESP32-C5、C6、C61 和 H2 系列。",
},
],
},
{
id: "memoria",
nome: "内存、总线与存储",
icone: "Database",
emoji: "💾",
cor: "purple",
descricao: "内部 SRAM、启动 ROM、SPI 闪存、QSPI/Octal PSRAM、RTC 内存与 DMA 分配。",
termos: [
{
termo: "内部 SRAM",
definicao: "直接集成在 CPU 芯片内的超高速易失性存储器，用于程序变量、FreeRTOS 数据结构、驱动缓冲区和运行栈。断电后数据丢失。",
exemplo: "经典 ESP32 有 520 KB SRAM；ESP32-S3 为 512 KB；ESP32-C3 为 400 KB；ESP32-C6 为 512 KB；ESP32-P4 为 768 KB。",
},
{
termo: "启动 ROM",
definicao: "乐鑫在出厂时永久写入的只读存储器，包含一级引导加载程序（First-Stage Bootloader）、数学表和基础初始化例程，永远无法修改。",
exemplo: "上电后 ROM 最先运行，检查 Strapping 引脚，然后从闪存加载用户的引导加载程序。",
},
{
termo: "SPI 闪存（Quad-SPI 与 Octal-SPI）",
definicao: "存放应用固件的外部非易失性存储器。通过 4 线（Quad SPI / QSPI）或 8 位数据线（Octal SPI / OPI / OSPI）连接，后者的带宽和传输速率是前者的两倍。",
exemplo: "ESP32-S3 和 ESP32-P4 支持最高 120 MHz 的 Octal SPI 闪存与 PSRAM，可获得最快的纹理和代码加载速度。",
},
{
termo: "PSRAM（外部伪静态 RAM）",
definicao: "通过 SPI/QSPI/OPI 连接的高密度外部 RAM，可把微控制器的内存扩展到数十 MB，适用于需要超大缓冲区的应用。",
exemplo: "ESP32-WROVER 和 ESP32-S3-WROOM-1 配备 8 MB 外部 PSRAM，用于摄像头的 JPEG 解码和 TFT 显示屏的图形缓冲。",
},
{
termo: "RTC 快速与慢速 SRAM",
definicao: "专属于实时时钟（RTC）供电域的 SRAM 块。在深度睡眠（Deep Sleep）期间保持供电，用于存放 ULP 代码和标记为 `RTC_DATA_ATTR` 的变量。",
exemplo: "在 ESP32 以 10 µA 的功耗进入深度睡眠期间，保持读数计数器或校准数据不丢失。",
},
{
termo: "DMA 内存分配（MALLOC_CAP_DMA）",
definicao: "兼容直接内存访问（DMA）的内存，使外设（SPI、I2S、LCD、SDMMC）可以直接向 RAM 传输数据，而不占用 CPU 时间。",
exemplo: "在大多数 ESP32 芯片上，DMA 必须通过 `MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL` 标志在内部 SRAM 中分配。",
},
{
termo: "堆碎片化（Heap Fragmentation）",
definicao: "经过多次分配与释放后，动态内存被拆成零散的小块（使用 Arduino 的 `String` 对象时很常见），导致无法为 TLS/Wi-Fi 分配大块连续内存。",
exemplo: "在 ESP-IDF 中通过 `heap_caps_get_largest_free_block()` 监测，以避免 HTTPS 连接失败。",
},
],
},
{
id: "conectividade",
nome: "无线连接与协议",
icone: "Wifi",
emoji: "📡",
cor: "emerald",
descricao: "Wi-Fi 4/6、5 GHz 双频、OFDMA、TWT、经典蓝牙、BLE 5.x、LE Audio、Zigbee 3.0、Thread 与 Matter。",
termos: [
{
termo: "Wi-Fi 6（802.11ax）",
definicao: "新一代无线网络标准，支持 OFDMA（并行通信，延迟更低）、1024-QAM 调制，以及 TWT（目标唤醒时间）功能，可大幅延长 IoT 传感器的电池寿命。",
exemplo: "见于 ESP32-C6、ESP32-C61 和 ESP32-C5。",
},
{
termo: "Wi-Fi 双频（2.4 GHz 与 5 GHz）",
definicao: "既能工作在传统的 2.4 GHz 频段，也能工作在电磁拥塞更少的 5 GHz 频段，支持 20 MHz / 40 MHz 信道，连接更稳定。",
exemplo: "ESP32-C5 是乐鑫首款集成 Wi-Fi 6 双频射频的芯片。",
},
{
termo: "OFDMA（正交频分多址）",
definicao: "Wi-Fi 6 的技术，把单个射频信道划分为几十个更小的子载波（资源单元，Resource Unit），让路由器同时服务多个 ESP32 设备而不产生冲突。",
exemplo: "在有数十个节点相连的密集家庭或工业环境中，降低响应延迟。",
},
{
termo: "TWT（目标唤醒时间）",
definicao: "Wi-Fi 6 的协议：ESP32 与路由器约定好交换数据包的确切时间，使微控制器可以长时间完全关闭射频，同时不断开网络连接。",
exemplo: "由电池供电的 ESP32-C6 传感器可连接 Wi-Fi 6 运行数年，且不丢失同步。",
},
{
termo: "经典蓝牙（Bluetooth Classic，BR/EDR）",
definicao: "传统蓝牙协议，用于连续传输立体声音频（A2DP）、虚拟串口（SPP），以及需要持续高传输速率的设备。",
exemplo: "在经典 ESP32 上实现蓝牙音箱、音频接收器和 HID 键盘。",
},
{
termo: "低功耗蓝牙（BLE 5.0 至 5.4）",
definicao: "蓝牙的低功耗版本，支持 2 Mbps 速率（2M PHY）、可达数百米的远距离（Coded PHY / Long Range）、广播扩展以及蓝牙 Mesh 网络。",
exemplo: "ESP32-S3 支持 BLE 5.0；ESP32-C6 和 ESP32-H2 支持蓝牙 5.4 LE。",
},
{
termo: "蓝牙 LE Audio 与 Auracast",
definicao: "新一代高保真、超低功耗的蓝牙音频，采用 LC3 编解码器，并支持向多个听众同时广播音频（Broadcast Audio / Auracast）。",
exemplo: "ESP32-H4 系列支持，面向新的音频生态和智能耳机。",
},
{
termo: "IEEE 802.15.4（Zigbee 3.0 与 Thread）",
definicao: "2.4 GHz 的低功耗、低数据速率射频标准，是 Zigbee 3.0 和 Thread 1.3 这类工业与家用 Mesh 网络的物理层基础。",
exemplo: "ESP32-C6、ESP32-H2 和 ESP32-H4 在芯片内集成了 IEEE 802.15.4 收发器。",
},
{
termo: "Matter 协议",
definicao: "由 CSA 维护的通用开放式智能家居连接标准，可运行在 Wi-Fi、以太网和 Thread 网络上，原生兼容 Apple Home、Google Home、Alexa 和 Home Assistant。",
exemplo: "使用 ESP-Matter 在 ESP32-C6 或 ESP32-H2 上开发智能灯泡和插座，无需依赖专有云。",
},
],
},
{
id: "perifericos",
nome: "输入输出与外设",
icone: "Sliders",
emoji: "🔌",
cor: "amber",
descricao: "GPIO 引脚、Strapping 引脚、ADC/DAC 转换器、PWM/LEDC、MCPWM、RMT、PCNT、TWAI®/CAN、I2C、SPI 与 I2S。",
termos: [
{
termo: "GPIO（通用输入输出）",
definicao: "多功能引脚，可配置为数字输入或输出，带有可选的内部上拉/下拉电阻，任意引脚都支持外部中断。",
exemplo: "用 `gpio_set_level()` 或 `digitalWrite()` 读取按键、控制继电器和 LED。",
},
{
termo: "Strapping 引脚",
definicao: "特定的 GPIO 引脚，芯片在复位释放的那一毫秒由硬件采样，以决定启动模式（UART 下载与 SPI 闪存启动）和电压电平。",
exemplo: "经典 ESP32/S3 的 GPIO 0 或 ESP32-C3 的 GPIO 9：复位期间若被拉低，芯片会进入固件烧录模式。",
},
{
termo: "ADC（模数转换器）",
definicao: "把连续的模拟电压（0 至 3.3V）转换为 12 位数字值的转换器（ESP32-S2 输出 13 位，其中 12 位有效），可通过衰减器配置（0dB、2.5dB、6dB、11dB/12dB）。",
exemplo: "读取 LDR 光敏电阻、电位器、热敏电阻，以及测量锂电池电量。",
},
{
termo: "DAC（数模转换器）",
definicao: "根据软件生成的数字值产生连续比例模拟电压的转换器，无需外部电路。",
exemplo: "经典 ESP32 和 ESP32-S2 提供，可合成模拟音频或直接输出控制信号。",
},
{
termo: "LEDC（LED PWM 控制器）",
definicao: "专用于产生多路脉宽调制（PWM）信号的外设，可控制频率，分辨率最高 14-20 位，并支持硬件渐变（fade），不占用 CPU。",
exemplo: "平滑调节 RGBW LED 灯带的亮度，以及舵机定位。",
},
{
termo: "MCPWM（电机控制 PWM）",
definicao: "为驱动电机设计的高级 PWM 控制器，适用于三相变频器、可配置死区时间（dead-time）的 H 桥，并可采集正交编码器信号。",
exemplo: "在经典 ESP32、S3 和 P4 上精确控制无刷电机（BLDC）和移动机器人。",
},
{
termo: "RMT（远程控制外设）",
definicao: "可精确到微秒级时序的脉冲收发与生成器，最初为红外遥控（NEC、RC5、Sony）设计，被广泛用于驱动 WS2812B / NeoPixel 数字 LED 灯带。",
exemplo: "刷新数百颗 NeoPixel LED，而无需关闭系统中断。",
},
{
termo: "PCNT（脉冲计数器）",
definicao: "硬件脉冲计数器，可对外部高频信号的上升/下降沿计数，而无需软件为 CPU 产生中断。",
exemplo: "读取工业旋转编码器、转速计和水流量计。",
},
{
termo: "TWAI®（双线汽车接口 / CAN 总线）",
definicao: "芯片内集成的、符合 ISO 11898-1 标准的 CAN 2.0B 车载与工业总线控制器，只需外接一个物理收发器（如 SN65HVD230）。",
exemplo: "OBD-II 汽车诊断、电动车遥测以及稳健的工业自动化。",
},
{
termo: "电容触摸（Touch）",
definicao: "专用引脚，用于测量手指靠近时静电电容的变化，可隔着玻璃或亚克力制作触摸按键和滑条。",
exemplo: "ESP32-S2 和 S3 最多提供 14 个通道，可做现代触摸控制面板。",
},
{
termo: "PARLIO（并行 IO 控制器）",
definicao: "较新系列（C6、H2、P4）提供的可配置高速并行总线，使用自定义时钟向 LCD 显示屏、摄像头和外部传感器同步传输数据。",
exemplo: "与外围芯片进行高效并行通信，无需让 CPU 用位操作（bit-banging）模拟。",
},
],
},
{
id: "multimidia",
nome: "多媒体、USB 与高级接口",
icone: "Sparkles",
emoji: "✨",
cor: "pink",
descricao: "原生 USB OTG、USB Serial/JTAG、USB 高速 480Mbps、MIPI CSI/DSI、H.264 编码器与以太网 MAC。",
termos: [
{
termo: "原生 USB OTG（On-The-Go）",
definicao: "芯片内置的全速（12 Mbps）USB 控制器，使 ESP32 既可作为外设（HID 键盘、鼠标、Mass Storage 优盘），也可作为 USB 主机（读取优盘或外设）。",
exemplo: "ESP32-S2 和 ESP32-S3 原生提供，可用于制作自定义键盘和模拟器。",
},
{
termo: "原生 USB Serial/JTAG",
definicao: "芯片内集成的 USB 接口，同时提供用于控制台的串口和完整的 JTAG 调试探针，无需外接转换芯片（CH340/CP2102）。",
exemplo: "在 ESP32-C3、S3、C6 和 H2 上，只需把 USB 线接到 D+/D- 引脚，就能烧录固件并在 VS Code 中用断点调试。",
},
{
termo: "USB 2.0 高速（480 Mbps）",
definicao: "高速 USB 2.0 控制器，集成 PHY，传输速率最高 480 Mbps，带宽是全速 USB 的 40 倍。",
exemplo: "ESP32-P4 独有，用于高清视频流和大批量数据传输。",
},
{
termo: "MIPI CSI 与 MIPI DSI",
definicao: "智能手机行业的标准高速差分串行接口：MIPI-CSI（摄像头串行接口）用于高分辨率摄像头传感器，MIPI-DSI（显示串行接口）用于触摸屏。",
exemplo: "在 ESP32-P4 SoC 上连接 1080p 屏幕和高帧率摄像头。",
},
{
termo: "硬件 H.264 视频编码器",
definicao: "专用加速模块，可实时把摄像头的原始视频流压缩为标准 H.264（AVC）格式，分辨率最高 1080p、30 FPS，不增加 CPU 负担。",
exemplo: "在 ESP32-P4 上用高效压缩实现智能安防摄像头和电子门铃。",
},
{
termo: "以太网 MAC 10/100 Mbps",
definicao: "芯片内集成的有线网络数据链路层（Media Access Control）控制器，只需通过 RMII 接口外接一颗物理层收发芯片（PHY，如 LAN8720 或 IP101）。",
exemplo: "在经典 ESP32 和 ESP32-P4 上，提供不受射频噪声影响、稳定的 RJ45 以太网连接，用于楼宇自动化。",
},
{
termo: "DVP 摄像头接口（8 位 / 16 位）",
definicao: "并行总线，包含 VSYNC、HREF、PCLK 信号和数据总线，支持 DMA，可直接从常见摄像头模组（OV2640、OV5640）采集帧。",
exemplo: "用于 ESP32-CAM 和 ESP32-S3-CAM 开发板，拍照并传输 MJPEG 视频流。",
},
],
},
{
id: "energia",
nome: "电源管理与睡眠模式",
icone: "BatteryCharging",
emoji: "🔋",
cor: "teal",
descricao: "Active 模式、Modem Sleep、Light Sleep、Deep Sleep、Hibernation、欠压检测器（Brownout Detector）与唤醒源。",
termos: [
{
termo: "Active 模式",
definicao: "正常运行模式：CPU 以最高频率执行指令，所有外设和射频随时可用，电流消耗在 30 mA 到约 240 mA 之间（Wi-Fi 发射期间）。",
exemplo: "ESP32 处理音频、刷新显示屏或实时传输传感器数据。",
},
{
termo: "Modem Sleep",
definicao: "在两次发射的间隔里暂时关闭 Wi-Fi 和蓝牙射频电路，而 CPU 继续正常运行代码，把电流降到约 20 至 40 mA。",
exemplo: "连接 Wi-Fi 的应用在等待网络事件时的默认模式，不会丢失与路由器的关联。",
},
{
termo: "Light Sleep",
definicao: "中间级别的节能模式：CPU 时钟暂停、射频关闭，但内部 SRAM、外设和任务状态完整保留。芯片可在 1 ms 内唤醒。",
exemplo: "需要被按键中断或定时器快速唤醒的设备，电流约 0.8 mA。",
},
{
termo: "Deep Sleep",
definicao: "深度睡眠模式：所有数字电源域和 CPU 都被关闭，仅保留 RTC 域供电（可选保留 RTC 内存和 ULP）。电流降到 5 至 15 µA，芯片唤醒后从头开始执行。",
exemplo: "由电池和太阳能板供电的远程气象站，每小时测量一次。",
},
{
termo: "Hibernation 模式",
definicao: "芯片中功耗最低的状态：连 RTC 的晶振和慢速域都被关闭，只保留一个模拟恢复电路，可由外部按键或复位唤醒。",
exemplo: "使用 CR2032 纽扣电池、可运行数年的设备，残余电流约 5 µA。",
},
{
termo: "唤醒源（Wakeup Sources）",
definicao: "用于把 ESP32 从深度睡眠或浅睡眠中唤醒的硬件事件：RTC 定时器、外部 GPIO 引脚（EXT0 / EXT1）、电容触摸，或 ULP 协处理器的信号。",
exemplo: "`esp_sleep_enable_timer_wakeup(60 * 1000000)` 可让芯片每 60 秒准时唤醒。",
},
{
termo: "欠压检测器（Brownout Detector）",
definicao: "内部的模拟比较器硬件电路，监测 3V3 引脚的供电电压，当电压降到约 2.8V 以下时强制安全复位，防止闪存数据损坏。",
exemplo: "避免电源不足的供电在射频发射峰值期间引起部分复位，保护微控制器。",
},
],
},
{
id: "desenvolvimento",
nome: "固件、启动与操作系统",
icone: "Code2",
emoji: "🚀",
cor: "rose",
descricao: "引导加载程序、FreeRTOS、IRAM_ATTR 宏、闪存分区、带回滚的 OTA 升级与 NVS 存储。",
termos: [
{
termo: "引导加载程序（Bootloader，一级与二级）",
definicao: "电气复位后立即执行的代码。一级位于芯片 ROM 中；二级位于闪存中，负责校验分区表、检查安全签名，并加载用户固件。",
exemplo: "控制 OTA 分区之间的切换，并在 `app_main` 之前初始化 PSRAM 内存。",
},
{
termo: "FreeRTOS（实时操作系统）",
definicao: "ESP-IDF 默认的抢占式多任务内核，在多个任务（Task）、消息队列（Queue）、信号量、互斥量和软件定时器之间划分 CPU，并支持优先级控制。",
exemplo: "用 `xTaskCreatePinnedToCore()` 把繁重的任务分配到指定的 CPU 内核上。",
},
{
termo: "IRAM_ATTR 与 DRAM_ATTR",
definicao: "ESP32 的 GCC 编译器专用属性，强制函数和变量驻留在内部超高速 IRAM/DRAM 中，而不是外部闪存，对中断服务例程（ISR）是必需的。",
exemplo: "避免在闪存忙于写入数据时，中断引发崩溃（*Cache Error*）。",
},
{
termo: "分区表（partitions.csv）",
definicao: "配置文件，把闪存的存储空间映射为多个逻辑块，分别用于引导加载程序、NVS 数据、LittleFS 文件和多个固件镜像（Factory、OTA_0、OTA_1）。",
exemplo: "可自定义，以容纳带有蓝牙、Wi-Fi 和加密库的大型固件。",
},
{
termo: "带回滚的 OTA（空中升级）",
definicao: "无线固件升级：新版本被写入另一个分区。若新固件启动失败，系统会自动回滚（*Rollback*）到之前可用的版本。",
exemplo: "`esp_ota_mark_app_valid_cancel_rollback()` 用于确认现场的新升级运行正常。",
},
{
termo: "NVS（非易失性存储）与 NVS 加密",
definicao: "闪存中的结构化键值机制，用于持久保存网络凭据、校准参数和计数器，并支持通过 eFuse 中的 AES 密钥进行硬件加密。",
exemplo: "保存 Wi-Fi 名称和加密后的密码，以便断电后自动重连。",
},
{
termo: "LittleFS 与 SPIFFS",
definicao: "为闪存设计的文件系统，带磨损均衡（*wear leveling*），使应用可以读写 HTML 页面、SSL 证书和日志等文件。",
exemplo: "保存 ESP32 内置网页服务器的 HTML/CSS 页面，用于通过浏览器配置网络。",
},
{
termo: "JTAG 与 OpenOCD",
definicao: "硬件级调试标准，可通过 USB-JTAG 探针在 VS Code 或 Eclipse 中暂停 CPU、设置断点，并实时查看寄存器和变量。",
exemplo: "调试复杂崩溃和空指针问题，而不必只依赖 `Serial.println()`。",
},
],
},
];