first commit

CONSOLE_SIMPLE_INIT_TUTORIAL.md

@@ -0,0 +1,174 @@
+# 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.