01 Overview

The Console is a UART-based command-line interface on the ESP32, commonly used for production testing and lab debugging. It allows executing hardware self-tests, reading parameters, and writing configuration via simple text commands.

On the production line, the Console works with a fixture to quickly verify each board's basic functions: LED operation, Wi-Fi RF performance, MAC address readability, and serial number writability. These tests catch early failures.

The Console is also handy during development, letting engineers directly access registers, view logs, and trigger specific behaviors without re-flashing firmware.

However, the Console is not a consumer-facing interface. If exposed, end users might misoperate or exploit it, causing device malfunction or security vulnerabilities. Therefore, production firmware must disable or protect the Console.

This page focuses on using the Console as a factory test tool, covering hardware design, firmware flow, and precautions.

02 Hardware

• UART interface: The test UART typically uses the default UART0 (GPIO1/GPIO3), but can share the log port. For a separate port, use other UART pins, but specify in the schematic.
• Test pads: Reserve test pads or headers on the PCB for fixture connection. Plan this on the first board to avoid later rework.
• Level shifting: If the fixture uses 5V logic, add a level shifter (e.g., TXS0108) to avoid damaging GPIOs.
• Power: During testing, the fixture supplies power; ensure the regulator (e.g., AMS1117) can handle the current draw.
• Antenna connection: For Wi-Fi tests, ensure the antenna connector (e.g., IPEX) can be disconnected to connect conducted test equipment.
• Other peripherals: Depending on the product, you may need to bring out test points for LEDs, buttons, sensors, but reuse existing interfaces where possible.
• Layout notes: Test points should be near the board edge for easy probe access; avoid being covered by the enclosure.

03 Software flow

1. Initialize NVS and default pins, then call `console_cmd_init()` to register basic commands (e.g., help, free, heap).

2. Register factory-specific commands such as `test_led`, `test_wifi`, `read_mac`, `write_serial`. Each command maps to a handler function.

3. In factory mode, receive commands over UART, parse and execute. Add a simple handshake (e.g., send a specific character) to prevent accidental triggers.

4. After executing a test command, return results (e.g., OK/FAIL) over UART; the fixture decides pass/fail.

5. For operations like writing serial numbers, ensure they are written to NVS or OTP, and verify uniqueness.

6. In production firmware, disable factory commands via compile-time macros or runtime flags, or require a password to enter.

7. If remote updates are needed, combine with OTA, but the factory port is not for user upgrades.

04 Core points

• The CLI is a factory asset, not a user feature. Exposing it to users can lead to security risks; disable or protect it in release firmware.
• Custom work: fixture protocol, serialisation, release switch. Define the command set and flow based on the product.
• UART sharing: If sharing with the log port, note that log output may interfere with command parsing; disable logs or use a different baud rate in factory mode.
• Test coverage: Factory commands should cover key hardware (e.g., Flash, PSRAM, sensors), but avoid over-testing to keep production time low.
• Security: Commands like serial write need permission control to prevent accidental misuse.
• Do not copy console implementations from other chips: ESP32's console component is based on readline; command registration differs from Linux, so follow the ESP-IDF example.