Smart-granary-code/CONSOLE_SIMPLE_INIT_TUTORIAL.md

ESP-IDF console_simple_init Tutorial (Project-Independent)

This guide is a standalone tutorial for adding and using espressif/console_simple_init in any ESP-IDF project.

1. What This Component Does

console_simple_init is a convenience wrapper around ESP-IDF console/REPL setup.

It provides these APIs:

• console_cmd_init()
• console_cmd_user_register()
• console_cmd_all_register()
• console_cmd_start()

Header:

#include "console_simple_init.h"

2. Add Dependency

Run:

idf.py add-dependency "espressif/console_simple_init^1.1.0"

Or edit your component manifest (idf_component.yml):

dependencies:
  idf: ">=5.0"
  espressif/console_simple_init: ^1.1.0

3. Declare CMake Dependency

In your component CMakeLists.txt (for example main/CMakeLists.txt):

idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES console_simple_init console
)

Why include console explicitly?

• console_simple_init.h uses esp_console.h.
• Explicit REQUIRES console avoids include path and IntelliSense issues.

4. Minimal Working Example

#include <stdio.h>
#include "esp_check.h"
#include "console_simple_init.h"

static int cmd_hello(int argc, char **argv)
{
    (void)argc;
    (void)argv;
    printf("hello from console\n");
    return 0;
}

void app_main(void)
{
    // Ensure required system init is done in your app:
    // - NVS initialized
    // - default event loop created

    ESP_ERROR_CHECK(console_cmd_init());
    ESP_ERROR_CHECK(console_cmd_user_register("hello", cmd_hello));
    ESP_ERROR_CHECK(console_cmd_all_register()); // optional
    ESP_ERROR_CHECK(console_cmd_start());
}

5. Preconditions

Before starting console, make sure your app has initialized:

• NVS (nvs_flash_init)
• default event loop (esp_event_loop_create_default)

If your project already has a network/bootstrap module, these may already be done.

6. How to Use at Runtime

1. Flash firmware.
2. Open monitor (idf.py monitor).
3. At prompt esp>, type:

help
hello

7. Console Channel Selection (Important)

Pick the console channel to match your physical connection:

• UART
• USB CDC
• USB Serial/JTAG

If channel and monitor port do not match, you may see warnings like write timeout when typing commands.

Configure via menuconfig:

• Component config -> ESP System Settings -> Channel for console output

Then rebuild and flash.

8. Common Issues

Issue A: #include errors for console_simple_init.h or esp_console.h

Checklist:

• Added dependency in idf_component.yml
• Added REQUIRES console_simple_init console in CMakeLists.txt
• Re-run:

idf.py reconfigure
idf.py build

• Refresh editor index/IntelliSense

Issue B: Serial port busy while flashing

Another monitor/process holds the port.

• Close monitor first
• Retry idf.py flash

Issue C: Console starts but input behaves poorly

Your terminal may not support escape sequences/history editing.

Use a terminal that supports VT sequences.

9. Next Step Ideas

• Add commands for system status (status)
• Add commands for peripheral control (pump on, light off)
• Add argument parsing and help text
• Group commands by module for maintainability

10. Quick Command Template

Use this template to add a command quickly:

static int cmd_name(int argc, char **argv)
{
    // parse args
    // run logic
    // print result
    return 0;
}

ESP_ERROR_CHECK(console_cmd_user_register("name", cmd_name));

---

This tutorial is intentionally generic so it can be reused in any ESP-IDF codebase.