basic

# EdgeCommand: Basic Example

The smallest possible EdgeCommand application: initialize the engine,
register one handler, submit one command, and observe the result.

## Purpose

Demonstrates the minimum steps every EdgeCommand application needs:

1. Initialize NVS (required by EdgeCommand's built-in storage backend).
2. Build a config with `EDGECOMMAND_DEFAULT_CONFIG()`.
3. Call `edgecommand_init()` then `edgecommand_start()`.
4. Register a handler with `edgecommand_register_handler()`.
5. Wire a reporter with `edgecommand_set_reporter()` to observe status
   changes.
6. Submit a command with `edgecommand_submit()`.
7. Poll `edgecommand_get_status()` until the command reaches a
   terminal state.

## Requirements

- ESP-IDF v5.0 or newer.
- Any ESP-IDF-supported target (esp32, esp32s3, esp32c3, ...).
- No external hardware required.

## Build and flash

```sh
cd examples/basic
idf.py set-target esp32
idf.py build flash monitor
```

## Expected output

```
I (321) basic_example: status: id=example-0001 state=RECEIVED progress=0% result_status=1 message=""
I (325) basic_example: status: id=example-0001 state=PERSISTED progress=0% result_status=1 message=""
I (330) basic_example: status: id=example-0001 state=PENDING progress=0% result_status=1 message=""
I (335) basic_example: edgecommand_submit() -> ESP_OK
I (340) basic_example: status: id=example-0001 state=EXECUTING progress=0% result_status=1 message=""
I (345) basic_example: handling 'ping' (id=example-0001, payload_len=0)
I (350) basic_example: status: id=example-0001 state=COMPLETED progress=0% result_status=0 message="pong"
I (450) basic_example: command example-0001 finished in state COMPLETED
```

Exact timing and ordering between the `edgecommand_submit() -> ESP_OK`
log line and the worker task's status logs may interleave differently
run to run — `edgecommand_submit()` returns as soon as the command is
queued, and the worker task races ahead on its own task, independent
of the calling task's next `printf`/log call.

## What's happening

- `ping_handler()` is invoked synchronously from EdgeCommand's internal
  worker task. It runs to completion immediately, so this example
  doesn't demonstrate progress reporting or cancellation — see
  `examples/long_running_command` for that.
- `log_reporter()` receives a status snapshot for every state the
  command passes through: `RECEIVED` → `PERSISTED` → `PENDING` →
  `EXECUTING` → `COMPLETED`. A real application would forward these
  over MQTT/HTTP/BLE instead of logging them.
- The command is persisted to NVS as it's processed, which is why
  `nvs_flash_init()` is required. See
  `examples/persistent_commands` for what that persistence gives you
  across a restart, and `examples/recovery` for what happens if the
  device restarts *during* execution.