# 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:

```c
#include "console_simple_init.h"
```

## 2. Add Dependency

Run:

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

Or edit your component manifest (`idf_component.yml`):

```yaml
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`):

```cmake
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

```c
#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:

```text
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:

```bash
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:

```c
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.