### Full Audio Module Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_audio/README.md

Demonstrates the usage of various audio functions including input/output setup, tone playback, WAV recording and playback, microphone level reading, and spectrum analysis. Ensure the 'audio' and 'board_manager' modules are imported.

```lua
local audio = require("audio")
local bm = require("board_manager")
local storage = require("storage")

local output_codec, rate, channels, bits =
    bm.get_audio_codec_output_params("audio_dac")
local input_codec =
    bm.get_audio_codec_input("audio_adc")
local output = audio.new_output(output_codec, rate, channels, bits)
local input = audio.new_input(input_codec, rate, channels, bits)
local wav_path = storage.join_path(storage.get_root_dir(), "test.wav")

audio.set_volume(output, 60)

audio.play_tone(output, 880, 200, 35, true)

local rec = audio.record_wav(input, wav_path, 1000)
print("recorded:", rec.path, rec.duration_ms, rec.bytes)

audio.play_wav(output, wav_path)

local level = audio.mic_read_level(input, 100)
print("mic rms:", level.rms, "peak:", level.peak)

local spectrum = audio.read_spectrum(input, 512, 16)
print("peak freq:", spectrum.peak_freq_hz, "peak db:", spectrum.peak_db, "rms:", spectrum.rms)

for i, band in ipairs(spectrum.bands) do
    print("band", i, band)
end

audio.close(input)
audio.close(output)

```

--------------------------------

### Basic Storage Operations Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_storage/README.md

Demonstrates common storage operations like getting the root directory, joining paths, creating directories, writing, reading, checking existence, getting file stats, listing directories, and checking free space.

```lua
local storage = require("storage")

local root = storage.get_root_dir()
local dir = storage.join_path(root, "demo")
local file = storage.join_path(dir, "test.txt")
local log_file = storage.join_path(root, "logs", "today.txt")

storage.mkdir(dir)
storage.write_file(file, "hello")
local text = storage.read_file(file)

if storage.exists(file) then
    local info = storage.stat(file)
    local entries = storage.listdir(dir)
    local space = storage.get_free_space()
end
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_magnetometer/README.md

A complete example demonstrating how to import the module, initialize the sensor, read data, and close the connection.

```APIDOC
## Example Usage

### Description
This example shows a basic workflow for using the magnetometer module.

### Code
```lua
local magnetometer = require("magnetometer")

-- Initialize sensor with board defaults
local sensor = magnetometer.new()

-- Read magnetic field data and temperature
local sample = sensor:read()
print("Magnetic X:", sample.magnetic.x)
print("Magnetic Y:", sample.magnetic.y)
print("Magnetic Z:", sample.magnetic.z)
print("Temperature:", sample.temperature)

-- Close the sensor connection
sensor:close()
```
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ssd1306/README.md

A complete example demonstrating the initialization, drawing, and cleanup process.

```APIDOC
```lua
local i2c = require("i2c")
local ssd1306 = require("ssd1306")

local bus = i2c.new(0, 14, 13, 400000)
local dev = bus:device(0x3C)
local oled = ssd1306.new(dev, {
    width = 128,
    height = 64,
    addr = 0x3C,
})

oled:init()
oled:clear(false)
oled:draw_text(10, 10, "SSD1306 OK", true)
oled:show()

oled:close()
dev:close()
bus:close()
```
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_touch/README.md

A complete Lua code example demonstrating how to use the touch module.

```APIDOC
```lua
local touch = require("touch")

local keys = touch.new()                  -- uses board defaults
local sample = keys:read()
for _, key in ipairs(sample.keys) do
    print(key.index, key.pressed, key.delta)
end
keys:close()
```
```

--------------------------------

### Initialize and Capture with Lua Camera

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_camera/README.md

This example demonstrates the basic workflow of opening a camera, retrieving stream information, getting and releasing a frame, and capturing an image to storage. Ensure the camera is properly initialized before use and frames are released to avoid issues.

```lua
local camera = require("camera")
local board_manager = require("board_manager")

local camera_paths = board_manager.get_camera_paths()
camera.open(camera_paths.dev_path)
local info = camera.info()
print(info.width, info.height, info.pixel_format)

local frame = camera.get_frame(1000)
local frame_info = frame:info()
print(frame_info.width, frame_info.height, frame_info.pixel_format, frame:bytes())
frame:release()

local storage = require("storage")
local capture = camera.capture(storage.join_path(storage.get_root_dir(), "capture.jpg"), 3000)
print(capture.path, capture.bytes)
camera.close()
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_storage/README.md

A practical example demonstrating the usage of various functions within the storage module.

```APIDOC
## Example Usage

```lua
local storage = require("storage")

-- Get root directory and construct paths
local root = storage.get_root_dir()
local dir = storage.join_path(root, "demo")
local file = storage.join_path(dir, "test.txt")
local log_file = storage.join_path(root, "logs", "today.txt")

-- Create directory and write to file
storage.mkdir(dir)
storage.write_file(file, "hello")

-- Read file content
local text = storage.read_file(file)

-- Check existence, get stats, list directory, and check free space
if storage.exists(file) then
    local info = storage.stat(file)
    local entries = storage.listdir(dir)
    local space = storage.get_free_space()
    -- Process info, entries, and space as needed
end

-- Example of removing a file
-- storage.remove(file)

-- Example of renaming/moving a file
-- local new_file_path = storage.join_path(dir, "renamed_test.txt")
-- storage.rename(file, new_file_path)
```
```

--------------------------------

### Initialize Lua Modules in Application

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-cap/lua-modules.mdx

Example of initializing various Lua modules and drivers within an application's setup function. Registration must be completed before calling cap_lua_register_group().

```c
// app_claw.c or equivalent init
#include "lua_module_display.h"
#include "lua_driver_gpio.h"
#include "lua_module_delay.h"
#include "cap_lua.h"

void app_lua_modules_init(void)
{
    lua_module_display_register();
    lua_driver_gpio_register();
    lua_module_delay_register();
    // …other modules…

    cap_lua_register_group();  // lock—no more registration afterward
}
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ssd1306/lib/ssd1306.md

A complete example demonstrating how to initialize the I2C bus, create an SSD1306 display object, and draw text on the screen.

```APIDOC
## Example

```lua
local i2c = require("i2c")
local ssd1306 = require("ssd1306")

local bus = i2c.new(0, 14, 13, 400000)
local dev = bus:device(0x3C)
local oled = ssd1306.new(dev, { width = 128, height = 64 })

oled:init()
oled:clear(false)
oled:draw_text(10, 10, "SSD1306 OK", true)
oled:show()

oled:close()
dev:close()
bus:close()
```
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_imu/README.md

A complete example demonstrating how to initialize, read data from, and close the IMU sensor.

```APIDOC
## Example Usage

### Description
This example demonstrates a typical workflow for using the Lua IMU module, from initialization to reading data and closing the sensor.

### Code
```lua
local imu = require("imu")

-- Initialize the sensor using board defaults
local sensor = imu.new()

-- Read accelerometer and gyroscope data
local sample = sensor:read()

-- Print the accelerometer readings
print("Accelerometer:")
print("  X: " .. tostring(sample.accel.x))
print("  Y: " .. tostring(sample.accel.y))
print("  Z: " .. tostring(sample.accel.z))

-- Print the gyroscope readings
print("Gyroscope:")
print("  X: " .. tostring(sample.gyro.x))
print("  Y: " .. tostring(sample.gyro.y))
print("  Z: " .. tostring(sample.gyro.z))

-- Read and print the temperature
local temp = sensor:read_temperature()
print("Temperature: " .. tostring(temp))

-- Read and print the interrupt status
local status = sensor:read_int_status()
print("Interrupt Status: " .. tostring(status))

-- Close the sensor when done
sensor:close()
```
```

--------------------------------

### ESP-Claw Application Bootstrap Example

Source: https://context7.com/espressif/esp-claw/llms.txt

A complete example demonstrating the initialization and startup of ESP-Claw with all its components, including capabilities, memory, event routing, scheduling, skills, and core services.

```c
#include "claw_core.h"
#include "claw_cap.h"
#include "claw_event_router.h"
#include "claw_memory.h"
#include "claw_skill.h"
#include "cap_lua.h"
#include "cap_scheduler.h"
#include "cap_mcp_server.h"
#include "cap_im_telegram.h"

esp_err_t app_start(const app_settings_t *settings)
{
    // 1. Initialize capability system
    ESP_RETURN_ON_ERROR(claw_cap_init(), TAG, "cap init failed");

    // 2. Initialize memory system
    claw_memory_config_t mem_cfg = {
        .session_root_dir = "/data/sessions",
        .memory_root_dir = "/data/memory",
        .max_session_messages = 20,
    };
    ESP_RETURN_ON_ERROR(claw_memory_init(&mem_cfg), TAG, "memory init failed");

    // 3. Initialize event router
    claw_event_router_config_t router_cfg = {
        .rules_path = "/data/router_rules.json",
        .default_route_messages_to_agent = true,
    };
    ESP_RETURN_ON_ERROR(claw_event_router_init(&router_cfg), TAG, "router init failed");

    // 4. Initialize scheduler
    cap_scheduler_config_t sched_cfg = {
        .schedules_path = "/data/schedules.json",
        .publish_event = claw_event_router_publish,
    };
    ESP_RETURN_ON_ERROR(cap_scheduler_init(&sched_cfg), TAG, "scheduler init failed");

    // 5. Initialize skills
    claw_skill_config_t skill_cfg = {
        .skills_root_dir = "/data/skills",
    };
    ESP_RETURN_ON_ERROR(claw_skill_init(&skill_cfg), TAG, "skill init failed");

    // 6. Register capability groups
    cap_im_tg_set_token(settings->telegram_token);
    cap_im_tg_register_group();
    cap_lua_register_group("/data/scripts");
    cap_mcp_server_register_group();
    cap_scheduler_register_group();
    claw_memory_register_group();

    // 7. Set LLM-visible groups
    const char *visible[] = {"cap_lua", "cap_files", "claw_memory"};
    claw_cap_set_llm_visible_groups(visible, 3);
    claw_cap_start_all();

    // 8. Register outbound bindings
    claw_event_router_register_outbound_binding("telegram", "tg_send_message");

    // 9. Initialize core with LLM config
    claw_core_config_t core_cfg = {
        .api_key = settings->llm_api_key,
        .profile = settings->llm_profile,
        .model = settings->llm_model,
        .system_prompt = "You are ESP-Claw assistant.",
        .call_cap = claw_cap_call_from_core,
        .append_session_turn = claw_memory_append_session_turn_callback,
    };
    ESP_RETURN_ON_ERROR(claw_core_init(&core_cfg), TAG, "core init failed");

    // 10. Add context providers
    claw_core_add_context_provider(&claw_memory_profile_provider);
    claw_core_add_context_provider(&claw_memory_session_history_provider);
    claw_core_add_context_provider(&claw_skill_skills_list_provider);
    claw_core_add_context_provider(&claw_cap_tools_provider);

    // 11. Start all services
    claw_core_start();
    claw_event_router_start();
    cap_scheduler_start();

    return ESP_OK;
}

```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_knob/README.md

A practical example demonstrating how to use the Lua Knob module to create a knob, subscribe to events, and handle them.

```APIDOC
## Example

```lua
local knob = require("knob")

-- Create a new knob handle using GPIO pins 48 and 47
local handle = knob.new(48, 47)

-- Subscribe to the 'left' rotation event
knob.on(handle, "left", function(evt)
  print("Rotated left, current count: " .. tostring(evt.count))
end)

-- Subscribe to the 'right' rotation event
knob.on(handle, "right", function(evt)
  print("Rotated right, current count: " .. tostring(evt.count))
end)

-- Poll for and dispatch knob events (should be called periodically in your main loop)
knob.dispatch()

-- Close the knob handle when it's no longer needed to free up resources
knob.close(handle)
```
```

--------------------------------

### Full Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ir/README.md

A comprehensive example demonstrating the import, initialization, information retrieval, sending, and receiving of IR signals.

```APIDOC
## Full Example Usage

```lua
local ir = require("ir")

local dev = ir.new("ir_blaster")
local info = dev:info()
print(info.name, info.tx_gpio, info.rx_gpio, info.carrier_hz)

local symbols, err = dev:receive(5000)
if symbols then
    dev:send_raw(symbols)
else
    print("receive failed: " .. tostring(err))
    dev:send_nec(0x00FF, 0x10EF)
end

dev:close()
```
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_sci/README.md

A complete Lua code example demonstrating the initialization and basic usage of the sci module.

```APIDOC
## Example Usage

### Description
This example demonstrates how to initialize the `sci` module, set the refresh rate, retrieve version and SKU information, and read sensor data.

### Code
```lua
local sci = require("sci")

-- Initialize the SCI module with specific I2C port, GPIO pins, address, and frequency
local dev = sci.new(1, 47, 48, 0x21, 100000)

-- Set the data refresh rate to 1 second
dev:set_refresh_rate(sci.REFRESH_1S)

-- Get and print the SCI firmware version
local version = dev:get_version()
print("SCI firmware: " .. version.text)

-- Get and print the SKUs of all connected sensors
print("SKUs: " .. dev:get_sku(sci.ALL))

-- Get and print detailed sensor readings for all ports, including timestamp
print("Readings: " .. dev:get_information(sci.ALL, true))

-- Close the device handle when done
dev:close()
```
```

--------------------------------

### GPIO Module Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_gpio/README.md

A practical example demonstrating how to import the GPIO module and use its functions to configure a pin as output and set its level.

```APIDOC
## Example Usage

### Description
This example shows how to initialize the GPIO module and control a GPIO pin.

### Code
```lua
local gpio = require("gpio")

-- Set GPIO pin 2 to output mode
gpio.set_direction(2, "output")

-- Set GPIO pin 2 to high level (1)
gpio.set_level(2, 1)

-- To read the level of a pin (e.g., pin 3):
-- local current_level = gpio.get_level(3)
-- print("Level of pin 3 is: " .. current_level)
```
```

--------------------------------

### Example Usage

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_fuel_gauge/README.md

A complete Lua code example demonstrating how to initialize and use the fuel gauge module.

```APIDOC
```lua
local fuel_gauge = require("lib_fuel_gauge")
local i2c = require("i2c")

local bus = i2c.new(0, 14, 13, 400000)
local gauge = fuel_gauge.new({
    bus = bus,
    chip = "bq27220",   -- or "max17048"
})

print("chip:", gauge:chip())
local sample = gauge:read()
print(sample.voltage_mv, sample.current_ma, sample.soc)
gauge:close()
bus:close()
```
```

--------------------------------

### Example Skill Documentation (weather.md)

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-project/skills.mdx

An example of a Skill's Markdown body, detailing its purpose, usage rules, and example calls. This content is injected into the chat for the LLM.

```md
# Weather

Get the current weather for a location.

## Usage rules

- When calling `get_weather`, `location` must be non-empty.
- On failure, check `location` and retry once.

## Example calls

Basic invocation:
```json
{"location": "London"}
```

With optional fields:
```json
{"location": "London", "unit": "celsius"}
```

## Error handling

- `Error: location is required` — add `location`, then retry.
- `Error: invalid location` — check spelling, then retry.

```

--------------------------------

### Full IR Transmit and Receive Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ir/README.md

A comprehensive example demonstrating opening an IR device, retrieving its info, attempting to receive an IR frame, sending raw symbols if successful, or sending a NEC frame if reception fails. Finally, it closes the device.

```lua
local ir = require("ir")

local dev = ir.new("ir_blaster")
local info = dev:info()
print(info.name, info.tx_gpio, info.rx_gpio, info.carrier_hz)

local symbols, err = dev:receive(5000)
if symbols then
    dev:send_raw(symbols)
else
    print("receive failed: " .. tostring(err))
    dev:send_nec(0x00FF, 0x10EF)
end

dev:close()
```

--------------------------------

### Test Script Example

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-cap/lua-modules.mdx

A basic Lua script demonstrating the usage of the `gpio` module functions.

```APIDOC
## Test Script Example

This example shows how to use the `gpio` module in a Lua script.

```lua
-- Require the gpio module
local gpio = require("gpio")

-- Configure GPIO pin 2 as an output
gpio.set_direction(2, "output")

-- Set GPIO pin 2 to a high level
gpio.set_level(2, 1)

-- Read the current level of GPIO pin 2
local level = gpio.get_level(2)

-- Print the level to the console
print("GPIO2 level:", level)
```

**Note:** When selecting GPIO pins for testing, avoid strapping pins, Flash/PSRAM pins, or pins already in use by other peripherals.
```

--------------------------------

### Skill Directory Layout Example

Source: https://github.com/espressif/esp-claw/blob/master/components/common/skill_builder/claw-skill-spec.md

Illustrates the standard directory structure for a skill component, including required and optional subdirectories.

```text
component_xx/
└── skills/
    └── skill_id/
        ├── SKILL.md
        ├── references/
        │   └── guide.md
        ├── scripts/
        │   └── action.lua
        └── assets/
            └── image.bin
```

--------------------------------

### Parse Schema with arg_schema Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_system/lib/arg_schema.md

Demonstrates parsing arguments with integer and boolean types, specifying defaults and minimum values.

```lua
local ctx = arg_schema.parse(args, {
    duration_ms = arg_schema.int({ default = 30000, min = 1 }),
    enabled = arg_schema.bool({ default = true }),
})
```

--------------------------------

### Start New Session

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/tutorial/faq.mdx

Initiate a new session with the `/new` command to reset the Agent's context.

```bash
/new
```

--------------------------------

### Search for Current Documentation

Source: https://github.com/espressif/esp-claw/blob/master/components/claw_capabilities/cap_web_search/skills/cap_web_search/SKILL.md

Example of a focused query to find specific documentation. Keep queries concise and clear.

```json
{
  "query": "ESP-IDF mDNS example"
}
```

--------------------------------

### C-Backed Lua Module CMakeLists.txt Example

Source: https://github.com/espressif/esp-claw/blob/master/components/common/lua_module_builder/lua-module-spec.md

C-backed modules must list their source files and include directories in CMakeLists.txt.

```cmake
idf_component_register(
    SRCS "lua_module_xx.c"
    INCLUDE_DIRS "include"
)
```

--------------------------------

### Begin Frame with Custom Background

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_display/README.md

Starts a new frame, optionally clearing the screen with a specified background color. Use this for full-screen updates.

```lua
display.begin_frame({ clear = true, r = 12, g = 18, b = 28 })
```

--------------------------------

### Capability-Backed Skill Template

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-project/skills.mdx

A comprehensive template for writing Skill documentation, including scenario framing, usage rules, JSON examples, and error handling. This guides the LLM on how and when to use the associated tools.

```markdown
# My Feature

One sentence describing when this Skill should activate.

## Usage rules

- When calling `my_action`, `param` must be non-empty
- On failure, validate `param`, then retry once
- Never issue more than three calls in a row; wait ≥ 500 ms between attempts

## Example calls

Basic invocation:
```json
{"param": "hello"}
```

With optional fields:
```json
{"param": "hello", "mode": "fast"}
```

## Error handling

- `Error: param is required` — add `param`, then retry
- `Error: invalid state` — device not ready; tell the user to try later

```

--------------------------------

### Full SSD1306 OLED Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ssd1306/lib/ssd1306.md

Demonstrates initializing the display, clearing it, drawing text, and flushing the framebuffer. Remember to close the display, device, and bus when done.

```lua
local i2c = require("i2c")
local ssd1306 = require("ssd1306")

local bus = i2c.new(0, 14, 13, 400000)
local dev = bus:device(0x3C)
local oled = ssd1306.new(dev, { width = 128, height = 64 })

oled:init()
oled:clear(false)
oled:draw_text(10, 10, "SSD1306 OK", true)
oled:show()

oled:close()
dev:close()
bus:close()
```

--------------------------------

### MCPWM Initialization and Configuration

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_mcpwm/README.md

Demonstrates how to import the mcpwm module, create a new PWM handle with various configuration options, and start the PWM output.

```APIDOC
## MCPWM Initialization

### Description
Initializes a new MCPWM handle with specified GPIOs, frequency, and duty cycles.

### Method
mcpwm.new(config_table)

### Parameters
#### Config Table
- **gpio** or **gpio_a** (number) - Required - Primary output GPIO.
- **gpio_b** (number) - Optional - Secondary output GPIO on the same operator.
- **group_id** (number) - Optional - Defaults to `0`.
- **resolution_hz** (number) - Optional - Defaults to `1000000`.
- **frequency_hz** (number) - Optional - Defaults to `1000`.
- **duty_percent** (number) - Optional - Defaults to `50` for channel 1.
- **duty_percent_b** (number) - Optional - Defaults to `50` for channel 2.
- **invert** (boolean) - Optional - Defaults to `false` for channel 1.
- **invert_b** (boolean) - Optional - Defaults to `false` for channel 2.

### Request Example
```lua
local mcpwm = require("mcpwm")

local pwm = mcpwm.new({
    gpio = 2,
    gpio_b = 4,
    frequency_hz = 1000,
    duty_percent = 25,
    duty_percent_b = 75,
})
```
```

--------------------------------

### Manually Start Telegram Service

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-cap/cap-im-platform.mdx

Manually start the Telegram service. This is typically handled by `claw_cap_start_group`.

```c
// Manual start (normally via claw_cap_start_group)
cap_im_tg_start();
```

--------------------------------

### Initializing the IR Device

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ir/README.md

Demonstrates how to import the `ir` module and initialize an IR device using various methods, including default board configurations or explicit GPIO assignments.

```APIDOC
## Initializing the IR Device

Import the module and open the board IR device.

### Methods

- `ir.new()`: Use board defaults from the device named `ir_blaster`.
- `ir.new("ir_blaster")`: Choose a board device name explicitly.
- `ir.new({ tx_gpio = 39, rx_gpio = 38, ctrl_gpio = 44 })`: Provide options directly.
- `ir.new("ir_blaster", { carrier_hz = 38000 })`: Board defaults plus per-field overrides.
```

--------------------------------

### Get Current Date with cap_cli

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/assets/example-skill.md

Use this command to get the current date, which may be useful for constructing search queries.

```bash
cap_cli time --now
```

--------------------------------

### Initialize Touch Device with Board Defaults

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_touch/README.md

Import the touch module and initialize a touch device using board defaults. Ensure the touch module is required before use.

```lua
local touch = require("touch")

local keys = touch.new()                  -- uses board defaults
local sample = keys:read()
for _, key in ipairs(sample.keys) do
    print(key.index, key.pressed, key.delta)
end
keys:close()
```

--------------------------------

### Import and Initialize Sensor

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_magnetometer/README.md

Demonstrates how to import the magnetometer module and initialize the sensor with different configuration options.

```APIDOC
## Import and Initialize Sensor

### Description
Import the magnetometer module and initialize the sensor. You can use board defaults or provide custom options.

### Usage

1. **Import the module:**
   ```lua
   local magnetometer = require("magnetometer")
   ```

2. **Initialize the sensor:**
   - Use board defaults:
     ```lua
     local sensor = magnetometer.new()
     ```
   - Specify a device name:
     ```lua
     local sensor = magnetometer.new("magnetometer_sensor")
     ```
   - Provide options directly:
     ```lua
     local sensor = magnetometer.new({ peripheral = "i2c_master" })
     ```
   - Use board defaults with per-field overrides:
     ```lua
     local sensor = magnetometer.new("magnetometer_sensor", { i2c_addr = 0x15 })
     ```

### Options Table
All fields are optional. Any field omitted falls back to the board `board_devices.yaml` value for the device named by `device` (default `"magnetometer_sensor"`). On a board that does not declare the device, missing required fields will raise an error.

| Field        | Type    | Meaning                                                               |
|--------------|---------|-----------------------------------------------------------------------|
| `device`     | string  | Board device name to read defaults from (default `magnetometer_sensor`) |
| `peripheral` | string  | Board I2C master peripheral name (e.g. `"i2c_master"`)               |
| `i2c_addr`   | integer | BMM350 7-bit I2C address (`0x14` or `0x15`)                          |
| `frequency`  | integer | I2C clock in Hz (default `100000`)                                   |
| `int_gpio`   | integer | Optional GPIO number wired to the BMM350 interrupt pin               |
```

--------------------------------

### Initialize Sensor with Options Table

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_magnetometer/README.md

Demonstrates initializing the magnetometer sensor by providing configuration options directly in a table, such as specifying the peripheral to use.

```lua
local sensor = magnetometer.new({ peripheral = "i2c_master" })
```

--------------------------------

### GPIO Light Control

Source: https://github.com/espressif/esp-claw/blob/master/application/edge_agent/main/skills/light_switch/SKILL.md

Examples for controlling GPIO lights, including turning them on/off and setting their active level. These examples use the `gpio_light_switch.lua` script.

```APIDOC
## GPIO Light Control

Use the `gpio_light_switch.lua` script to control GPIO lights. The `args` parameter accepts a JSON object with properties like `io`, `enabled`, and `active_level`.

### Turn off an active-high GPIO light
```json
{"path":"{CUR_SKILL_DIR}/scripts/gpio_light_switch.lua","args":{"io":23,"enabled":false,"active_level":1}}
```

### Turn on an active-low GPIO light
```json
{"path":"{CUR_SKILL_DIR}/scripts/gpio_light_switch.lua","args":{"io":43,"enabled":true,"active_level":0}}
```
```

--------------------------------

### LED Strip Control

Source: https://github.com/espressif/esp-claw/blob/master/application/edge_agent/main/skills/light_switch/SKILL.md

Examples for controlling LED strips, including turning them on/off, setting brightness, and color. These examples use the `led_strip_switch.lua` script.

```APIDOC
## LED Strip Control

Use the `led_strip_switch.lua` script to control LED strips. The `args` parameter accepts a JSON object with properties like `enabled`, `brightness`, and `color`.

### Turn off
```json
{"path":"{CUR_SKILL_DIR}/scripts/led_strip_switch.lua","args":{"enabled":false}}
```

### Turn on white
```json
{"path":"{CUR_SKILL_DIR}/scripts/led_strip_switch.lua","args":{"enabled":true}}
```

### Set red at half brightness
```json
{"path":"{CUR_SKILL_DIR}/scripts/led_strip_switch.lua","args":{"enabled":true,"brightness":128,"color":{"r":255,"g":0,"b":0}}}
```

### Set all pixels in a 3-pixel LED strip to red at half brightness
```json
{"path":"{CUR_SKILL_DIR}/scripts/led_strip_switch.lua","args":{"io":46,"led_count":3,"enabled":true,"brightness":128,"color":{"r":255,"g":0,"b":0}}}
```
```

--------------------------------

### Initialize and Read Magnetometer Data

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_magnetometer/README.md

Demonstrates how to import the magnetometer module, initialize a sensor instance using default board settings, read magnetic field data and temperature, and then close the sensor.

```lua
local magnetometer = require("magnetometer")

local sensor = magnetometer.new()
local sample = sensor:read()
print(sample.magnetic.x, sample.magnetic.y, sample.magnetic.z)
print(sample.temperature)
sensor:close()
```

--------------------------------

### Install ESP Board Manager Assist

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-project/build-from-source.mdx

Install the ESP Board Manager package after activating the ESP-IDF environment. This tool is used for managing development board configurations.

```bash
pip install esp-bmgr-assist
```

--------------------------------

### Initializing Touch Keys

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_touch/README.md

Demonstrates different ways to initialize the touch module, either using board defaults or specifying GPIOs directly.

```APIDOC
## Initializing Touch Keys

Import the module with `local touch = require("touch")`.

Open the device with one of the following methods:

- `local keys = touch.new()`: Uses board defaults from the device named `touch_keys`.
- `local keys = touch.new("touch_keys")`: Explicitly chooses a device name.
- `local keys = touch.new({ key1_gpio = 2, key2_gpio = 3 })`: Provides GPIOs directly.
- `local keys = touch.new("touch_keys", { threshold_milli = 20 })`: Uses board defaults with overrides.
```

--------------------------------

### BQ27220 Fuel Gauge Example

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_fuel_gauge/lib/lib_fuel_gauge.md

A complete example demonstrating how to initialize the BQ27220 fuel gauge, read battery state (state of charge, voltage, current), print the values, and close the gauge and bus connections.

```lua
local bq27220 = require("lib_bq27220")
local i2c = require("i2c")

local bus = i2c.new(0, 14, 13, 400000)
local gauge = bq27220.new({
    bus = bus,
    addr = 0x55,
})

local sample = gauge:read()
print(sample.soc, sample.voltage_mv, sample.current_ma)

gauge:close()
bus:close()
```

--------------------------------

### Telegram Attachment Saved Payload Example

Source: https://github.com/espressif/esp-claw/blob/master/docs/src/content/docs/en/reference-cap/cap-im-platform.mdx

This JSON object represents an example payload for an 'attachment_saved' event in the Telegram integration. It includes details about the saved file's path, name, MIME type, caption, and platform-specific identifiers.

```json
{
  "platform": "telegram",
  "attachment_kind": "photo",
  "saved_path": "/fatfs/inbox/telegram/-123456/789/photo.jpg",
  "saved_dir": "/fatfs/inbox/telegram/-123456/789",
  "saved_name": "photo.jpg",
  "mime": "image/jpeg",
  "caption": "Look at this",
  "platform_file_id": "AgACAgIAAxkBAAI...",
  "size_bytes": 45231,
  "saved_at_ms": 1714000000000
}
```

--------------------------------

### Initialize and Control LED Strip

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_led_strip/README.md

Import the module, create a new strip instance, set a pixel's color using RGB and HSV, and refresh the strip to apply changes. Ensure the correct GPIO pin and maximum LED count are provided during initialization.

```lua
local led_strip = require("led_strip")

local strip = led_strip.new(8, 1)
strip:set_pixel(0, 255, 0, 0)
strip:set_pixel_hsv(0, 120, 255, 64)
strip:refresh()
```

--------------------------------

### Build and Flash ESP-IDF Project

Source: https://github.com/espressif/esp-claw/blob/master/application/edge_agent/boards/movecall/movecall_cuican_esp32s3/README.md

Commands to set the target chip, generate board configuration, build the project, flash it to the device, and monitor logs. Replace the serial port with your actual device path.

```bash
cd application/edge_agent

# Set target chip
idf.py set-target esp32s3

# Generate board configuration
idf.py bmgr --customer-path ./boards -b movecall_cuican_esp32s3

# Build
idf.py build

# Flash (replace with your actual serial port)
idf.py -p /dev/cu.usbmodem2101 flash

# Monitor logs
idf.py -p /dev/cu.usbmodem2101 monitor
```

--------------------------------

### Get Router Rule

Source: https://github.com/espressif/esp-claw/blob/master/components/claw_capabilities/cap_router_mgr/skills/cap_router_mgr/SKILL.md

Retrieves a specific router rule by its ID.

```APIDOC
## get_router_rule

### Description
Retrieves a single router rule object by its ID. Returns standard error JSON with `ok=false` if the rule is not found.

### Input
`{"id":"rule_id"}`

### Output
One rule object, or standard error JSON with `ok=false`.
```

--------------------------------

### Initializing an LCD Panel

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_lcd/README.md

This snippet demonstrates how to import the `lcd` module, create a new LCD panel using `lcd.new` with a configuration table, and then use the returned values with `display.init`.

```APIDOC
## lcd.new(config)

### Description
Initializes an SPI or QSPI LCD panel based on the provided configuration.

### Parameters
- **config** (table) - A table containing the configuration for the LCD panel. See the 'Config shape' section for details.

### Return Values
- **dev** (userdata) - The Lua LCD device userdata.
- **panel_handle** (lightuserdata) - Lightuserdata for the panel.
- **io_handle** (lightuserdata) - Lightuserdata for the panel IO.
- **width** (integer) - The width of the panel.
- **height** (integer) - The height of the panel.
- **panel_if** (constant) - Panel interface constant for `display.init(...)`.

### Request Example
```lua
local lcd = require("lcd")
local display = require("display")

local dev, panel_handle, io_handle, width, height, panel_if = lcd.new({
    controller = "st7789",
    bus = {
        host = 2,
        mode = "spi",
        sclk = 4,
        mosi = 5,
        max_transfer_sz = 6400,
    },
    io = {
        cs = 15,
        dc = 7,
        spi_mode = 0,
        pclk_hz = 40000000,
    },
    panel = {
        reset = 6,
        mirror_x = false,
        mirror_y = true,
        swap_xy = true,
        invert_color = true,
    },
    resolution = {
        width = 320,
        height = 240,
    }
})

-- Use the returned values with display.init
display.init(panel_handle, io_handle, width, height, panel_if)
```
```

--------------------------------

### Get Volume

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_audio/README.md

Retrieves the current volume level of an audio output handle.

```APIDOC
## audio.get_volume

### Description
Retrieves the current volume level of an audio output handle.

### Parameters
- **output_handle**: (handle) - The audio output handle.

### Returns
- (number) - The current volume level as a percentage.
```

--------------------------------

### Initialize and Display Text on SSD1306

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_ssd1306/README.md

Demonstrates how to initialize the SSD1306 display, clear the screen, draw text, and show it. Ensure the I2C bus and device are correctly set up before creating the display object. The display is closed afterwards.

```lua
local i2c = require("i2c")
local ssd1306 = require("ssd1306")

local bus = i2c.new(0, 14, 13, 400000)
local dev = bus:device(0x3C)
local oled = ssd1306.new(dev, {
    width = 128,
    height = 64,
    addr = 0x3C,
})

oled:init()
oled:clear(false)
oled:draw_text(10, 10, "SSD1306 OK", true)
oled:show()

oled:close()
dev:close()
bus:close()
```

--------------------------------

### Run Audio FFT Visualizer

Source: https://github.com/espressif/esp-claw/blob/master/application/edge_agent/main/skills/lua_demo/SKILL.md

Use this tool call to run the Audio FFT visualizer. Requires an audio input device and a compatible LED strip.

```json
{"path":"{CUR_SKILL_DIR}/scripts/audio_fft.lua","args":{}}
```

--------------------------------

### Get Device Address

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_i2c/README.md

Retrieve the 7-bit I2C address of the attached device.

```APIDOC
## dev:address()

### Description
Returns the 7-bit I2C address of the device.

### Returns
- `addr` (integer) - The 7-bit I2C address.
```

--------------------------------

### Get a specific scheduler entry

Source: https://github.com/espressif/esp-claw/blob/master/components/claw_capabilities/cap_scheduler/skills/cap_scheduler/SKILL.md

Retrieves a single scheduler entry by its unique ID.

```APIDOC
## scheduler_get

### Description
Gets one scheduler entry by its `id`.

### Method
POST

### Endpoint
/scheduler/get

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier of the schedule to retrieve.

### Request Example
```json
{
  "id": "daily_report"
}
```

### Response
#### Success Response (200)
- **schedule** (object) - The scheduler entry object.

#### Response Example
```json
{
  "schedule": {
    "id": "daily_report",
    "kind": "cron",
    "cron_expr": "0 8 * * *",
    "enabled": true,
    "event_type": "report",
    "event_key": "daily_report",
    "source_channel": "time",
    "chat_id": "chat123",
    "content_type": "trigger",
    "session_policy": "trigger",
    "text": "Generate daily report.",
    "payload_json": "{}",
    "max_runs": 0,
    "runtime_state": {
      "next_fire_time_ms": 1678886400000,
      "last_fire_time_ms": 1678800000000,
      "run_count": 100
    }
  }
}
```
```

--------------------------------

### Initializing and Reading from Environmental Sensors

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_environmental_sensor/README.md

Demonstrates how to import the module, initialize a sensor (BME690 or DHT), read all environmental values, and close the sensor.

```APIDOC
## Initialize and Read Sensor

### Description
This section covers the initialization of the environmental sensor module and reading data from it. You can initialize with default settings or specify configuration options.

### Methods

#### `environmental_sensor.new([options])`
Initializes and returns a sensor object.
- `options` (table, optional): Configuration table for the sensor. See 'Options table' for details.

#### `sensor:read()`
Reads all available environmental data from the sensor.
- Returns: A table containing sensor readings (e.g., `temperature`, `humidity`, `pressure`, `gas_resistance`).

#### `sensor:close()`
Closes the sensor connection and releases resources.

### Examples

#### BME690 Example
```lua
local environmental_sensor = require("environmental_sensor")

-- Initialize with default BME690 settings
local sensor = environmental_sensor.new()
local sample = sensor:read()

print(string.format("temperature: %.2f C", sample.temperature))
print(string.format("pressure: %.2f Pa", sample.pressure))
print(string.format("humidity: %.2f %%", sample.humidity))
print(string.format("gas resistance: %.2f ohm", sample.gas_resistance))
print(string.format("status: 0x%02X", sample.status))

sensor:close()
```

#### DHT Example
```lua
local environmental_sensor = require("environmental_sensor")

-- Initialize DHT sensor with specific configuration
local sensor = environmental_sensor.new({
    type = "dht",
    pin = 4,
    sensor_type = "dht22",
})

local sample = sensor:read()
print(string.format("temperature: %.2f C", sample.temperature))
print(string.format("humidity: %.2f %%", sample.humidity))

sensor:close()
```
```

--------------------------------

### Initializing the IMU Sensor

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_imu/README.md

Demonstrates how to import the IMU module and initialize a sensor instance using different methods.

```APIDOC
## Importing and Initializing the IMU Module

### Description
Import the `imu` module and initialize a sensor object. You can use board defaults, specify a device name, or provide configuration options directly.

### Usage

1. **Import the module:**
   ```lua
   local imu = require("imu")
   ```

2. **Initialize the sensor:**
   - Using board defaults for a device named `imu_sensor`:
     ```lua
     local sensor = imu.new()
     ```
   - Specifying a device name explicitly:
     ```lua
     local sensor = imu.new("imu_sensor")
     ```
   - Providing options directly:
     ```lua
     local sensor = imu.new({ peripheral = "i2c_master", int_gpio = 21 })
     ```
   - Using board defaults with per-field overrides:
     ```lua
     local sensor = imu.new("imu_sensor", { frequency = 100000 })
     ```

### Options Table
All fields in the options table are optional. If a field is omitted, it falls back to the value defined in `board_devices.yaml` for the specified device name (defaulting to `"imu_sensor"`).

| Field        | Type     | Meaning                                                       |
|--------------|----------|---------------------------------------------------------------|
| `device`     | string   | Board device name to read defaults from (default `"imu_sensor"`)
| `peripheral` | string   | Board I2C master peripheral name (e.g. `"i2c_master"`)
| `i2c_addr`   | integer  | Selected backend's 7-bit I2C address (default `0x68`)
| `frequency`  | integer  | I2C clock in Hz (default `400000`)
| `int_gpio`   | integer  | GPIO number wired to the sensor interrupt pin
| `sdo_gpio`   | integer  | Optional address-select pin; for MPU6050 it drives `AD0`
```

--------------------------------

### Once Schedule Example

Source: https://github.com/espressif/esp-claw/blob/master/components/claw_capabilities/cap_scheduler/skills/cap_scheduler/SKILL.md

Use this to trigger an event at a specific timestamp. Ensure `start_at_ms` is provided for this kind.

```json
{
  "schedule_json": "{\"id\":\"bootstrap_once\",\"enabled\":true,\"kind\":\"once\",\"start_at_ms\":1893456000000,\"event_type\":\"schedule\",\"event_key\":\"bootstrap_once\",\"source_channel\":\"time\",\"content_type\":\"trigger\",\"session_policy\":\"trigger\",\"text\":\"bootstrap once\",\"payload_json\":{\"task\":\"bootstrap\"},\"max_runs\":1}"
}
```

--------------------------------

### Initialize and Control MCPWM Output in Lua

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_driver_mcpwm/README.md

Demonstrates how to create an MCPWM handle, configure it for dual outputs, start PWM, adjust duty cycles for both channels, and finally stop and close the handle. Ensure the module is imported correctly.

```lua
local mcpwm = require("mcpwm")

local pwm = mcpwm.new({
    gpio = 2,
    gpio_b = 4,
    frequency_hz = 1000,
    duty_percent = 25,
    duty_percent_b = 75,
})

pwm:start()
pwm:set_duty(75)
pwm:set_duty(2, 40)
pwm:stop()
pwm:close()
```

--------------------------------

### display.begin_frame

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_display/README.md

Starts a new frame for rendering. Optionally clears the frame with a specified background color.

```APIDOC
## display.begin_frame([options])

### Description
Starts a frame. This is the preferred mode when drawing a full screen or multiple primitives together.

### Parameters
- **options** (optional table): A table that can contain the following keys:
  - **clear** (boolean): If `true`, the frame will be cleared. Defaults to `true`.
  - **r** (integer): The red component of the background color (0-255). Defaults to `0`.
  - **g** (integer): The green component of the background color (0-255). Defaults to `0`.
  - **b** (integer): The blue component of the background color (0-255). Defaults to `0`.

### Example
```lua
display.begin_frame({ clear = true, r = 12, g = 18, b = 28 })
```
```

--------------------------------

### Build and Flash ESP32-C5 Project

Source: https://github.com/espressif/esp-claw/blob/master/application/edge_agent/boards/movecall/movecall_moji2_esp32c5/README.md

Commands to set the target chip, generate board configuration, build the project, flash the firmware, and monitor logs. Replace '/dev/cu.usbmodem2101' with your actual serial port.

```bash
cd application/edge_agent

# Set target chip
idf.py set-target esp32c5

# Generate board configuration
idf.py bmgr --customer-path ./boards -b movecall_moji2_esp32c5

# Build
idf.py build

# Flash (replace with your actual serial port)
idf.py -p /dev/cu.usbmodem2101 flash

# Monitor logs
idf.py -p /dev/cu.usbmodem2101 monitor
```

--------------------------------

### Initialize SPI LCD Panel

Source: https://github.com/espressif/esp-claw/blob/master/components/lua_modules/lua_module_lcd/README.md

Example of initializing an ST7789 SPI LCD panel with specific configuration. This includes setting up the bus, I/O, panel properties, and resolution. It also demonstrates retrieving panel info and initializing the display.

```lua
local lcd = require("lcd")
local display = require("display")

local dev, panel_handle, io_handle, width, height, panel_if = lcd.new({
    controller = "st7789",
    bus = {
        host = 2,
        mode = "spi",
        sclk = 4,
        mosi = 5,
        max_transfer_sz = 6400,
    },
    io = {
        cs = 15,
        dc = 7,
        spi_mode = 0,
        pclk_hz = 40000000,
    },
    panel = {
        reset = 6,
        mirror_x = false,
        mirror_y = true,
        swap_xy = true,
        invert_color = true,
    },
    resolution = {
        width = 320,
        height = 240,
    }
})

local info = lcd.get_info(dev)
print(info.controller, info.width, info.height, info.bus_mode)

display.init(panel_handle, io_handle, width, height, panel_if)
```

--------------------------------

### Pause Schedule Example

Source: https://github.com/espressif/esp-claw/blob/master/components/claw_capabilities/cap_scheduler/skills/cap_scheduler/SKILL.md

Provide the `id` of the schedule to pause it. This action does not require the full schedule configuration.

```json
{
  "id": "sedentary_reminder"
}
```