175 lines
3.6 KiB
Markdown
175 lines
3.6 KiB
Markdown
# 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.
|