Bring-up

Hello World UART heartbeat

Tells you in one page whether the toolchain, flash path and serial monitor work.

Bring-up Serial log ESP32 family

Official path: examples/get-started/hello_world

01 Overview

The official Hello World prints a counter. It validates IDF, UART and the chip clock — not a product feature.

It solves the question 'can a new environment run?': new PC, new module lot, new factory flash station. If it passes, the toolchain and hardware path are OK.

Typical scenarios: a dev machine just installed ESP-IDF, a batch of new modules, or first bring-up of a production flash station.

It does not validate Wi-Fi, Bluetooth, peripheral drivers, or business logic — it only proves that app_main runs and UART logs appear.

The official example does not cover log-level policy, disabling ROM prints, or sealing the debug port for production; those are left to the product.

02 Hardware

  • Chip: any ESP32 family target that supports ESP-IDF, such as ESP32, ESP32-S3, ESP32-C3.
  • Minimum parts: USB-UART (on-board or external). Do not rely only on USB-Serial-JTAG if you will debug sleep, as it may not wake or log properly.
  • Pins: UART0 by default, often GPIO1 (TX) and GPIO3 (RX). If the custom board moves the port, the dongle must follow.
  • Power: flashing draws more than idle; weak USB cables fail here, causing flash errors or resets.
  • Connectors: dev boards usually have an on-board USB-UART and a Micro-USB or USB-C port; custom boards need to bring out UART0 or a programming header.
  • Layout watch: if using an external USB-UART, ensure TX/RX are crossed and grounds are common.

03 Software flow

1. Install ESP-IDF and set up the environment, then run idf.py set-target to select the target chip (e.g., esp32, esp32s3).

2. Build the firmware: idf.py build.

3. Connect the board and flash with idf.py -p PORT flash.

4. Open the serial monitor with idf.py -p PORT monitor and observe the log output.

5. In app_main, the official example uses printf in a loop with a delay, printing an incrementing counter.

6. Exit the monitor with Ctrl+].

7. In product code, replace printf with ESP_LOGx macros and configure log levels for release, dropping verbose output.

04 Core points

  • This is a fixture, not a feature. Do not stop at this page when a customer asks what the product does.
  • Baud, port and chip target must match. Otherwise 'no logs' might actually be the wrong chip or miswired lines.
  • Plan how the board is programmed after the enclosure is closed — that leads to OTA.
  • Custom work: programming header, UART map, factory log format.
  • Do not copy across chips: different ESP32 variants have different UART pins; check the datasheet.

中文

点亮与上电

Hello World 串口心跳

工具链、烧录、串口监控是否通，这一页就能判断。

点亮与上电 串口日志 ESP32 family

官方路径: examples/get-started/hello_world

01 项目概述

官方 Hello World 周期性打印计数。用来确认 IDF、串口和芯片时钟，不是产品功能。

它解决的是「新环境能不能跑」的问题：新电脑、新模组、新产线工位，先跑这一页，能过就说明工具链和硬件通路没问题。

典型场景：开发机刚装好 ESP-IDF、拿到一批新模组、产线烧录工位首次调试。

它不验证 Wi-Fi、蓝牙、外设驱动或业务逻辑，只证明 app_main 在跑、UART 日志能出来。

官方例程没有做日志等级策略、关闭 ROM 打印、量产关掉调试口，这些要产品自己补。

02 项目硬件描述

  • 芯片： 任意支持 ESP-IDF 的 ESP32 系列目标，如 ESP32、ESP32-S3、ESP32-C3 等。
  • 最小物料： USB-UART（板载芯片或外部）。深睡调试不要用芯片自带 USB-Serial-JTAG 当唯一日志口，否则深睡时可能无法唤醒或日志丢失。
  • 引脚： 默认 UART0，常见 GPIO1（TX）和 GPIO3（RX）。定制板若改口，下载器要跟着改。
  • 供电： 下载时电流比空转高，USB 线要能供足，否则可能烧录失败或复位。
  • 连接器： 开发板通常有板载 USB-UART 和 Micro-USB 或 USB-C 口；定制板需引出 UART0 或预留下载座。
  • 布局注意： 如果使用外部 USB-UART，注意 TX/RX 交叉连接，且共地。

03 项目软件流程描述

1. 安装 ESP-IDF 并设置环境变量，然后运行 idf.py set-target 选择目标芯片（如 esp32、esp32s3）。

2. 编译固件：idf.py build。

3. 连接开发板，运行 idf.py -p PORT flash 烧录固件。

4. 运行 idf.py -p PORT monitor 打开串口监视器，观察日志输出。

5. 在 app_main 中，官方例程使用 printf 循环打印计数，并延时 1 秒。

6. 退出监视器按 Ctrl+] 。

7. 产品代码中应使用 ESP_LOGx 宏替代 printf，并按量产配置日志等级，关闭 verbose 输出。

04 项目核心点

  • 这是工装，不是功能。 客户问「产品做什么」时不要停在这一页。
  • 波特率、口线、芯片目标三者必须一致。 否则「没日志」其实是下错芯片或口线接错。
  • 量产要规划下载口是否引出。 外壳封死后如何升级，要和下一个 OTA 案例一起想。
  • 可定制： 下载座、UART 分配、产测打印格式。
  • 不要复制到其他芯片： 不同 ESP32 系列的 UART 引脚可能不同，需查数据手册。