---
title: cap_system — System info and device restart
description: Query runtime status (system, memory, CPU, Wi-Fi, IP) and perform operational actions like delayed restart.
---

import LinkToSource from '@/components/LinkToSource.astro';
import { Aside } from '@astrojs/starlight/components';

Source: <LinkToSource relativePath="components/claw_capabilities/cap_system/src/cap_system.c" /> · Header: <LinkToSource relativePath="components/claw_capabilities/cap_system/include/cap_system.h" />

## Positioning

`cap_system` provides a unified entry point for runtime status queries and a controlled restart operation. It is a system-level tool group directly callable by the LLM, suitable for device diagnostics, health checks, and remote recovery.

## Tools exposed to LLM

| Tool ID | Function | Input Parameters |
|---------|----------|------------------|
| `get_system_info` | Return a system summary (chip, memory, CPU, Wi-Fi, IP, uptime) | (None) |
| `get_memory_info` | Return memory details (internal memory, heap, PSRAM) | (None) |
| `get_cpu_usage` | Return CPU usage and runtime stats | (None) |
| `get_wifi_info` | Return current Wi-Fi status (SSID, RSSI, channel, etc.) | (None) |
| `get_ip_address` | Return current station IP / netmask / gateway | (None) |
| `restart_device` | Schedule a delayed device restart | `delay_ms` (optional, milliseconds) |

## Response structure notes

- `get_system_info` combines multiple sub-objects: `memory`, `cpu`, `wifi`, `ip`.
- If FreeRTOS runtime stats are not enabled, `get_cpu_usage` returns `supported: false` plus an explanatory message.
- When not connected, `get_wifi_info` / `get_ip_address` return `connected: false` with empty-value fields.

## `restart_device` behavior

- `delay_ms` is optional. If omitted or set to `0`, the default delay is used. Currently, the default is 500ms.
- Restart is scheduled asynchronously: the tool returns success first, then a background task executes `esp_restart()`.
- On failure, it returns `ok: false` with an error-code string.

Example:

```json
{"delay_ms": 1500}
```

Possible result:

```json
{"ok":true,"message":"device restart scheduled","delay_ms":1500}
```

<Aside type="caution">
  `restart_device` will reboot the device, interrupting ESP-Claw runtime execution.
  If `delay_ms` is very small, the device may reboot before the LLM sends back execution status, and no reply may be received.
</Aside>
