> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# GPIO

> Control Raspberry Pi GPIO pins — read, write, watch edges, and software PWM.

# GPIO Toolkit

Control Raspberry Pi GPIO pins with read, write, edge watching, and software PWM. Compatible with Pi 5 (chip 4) and Pi 4 (chip 0).

Requires `node-libgpiod` as an optional peer dependency.

***

## Quick Start

```typescript theme={null}
import { Agent, ollama } from "@agentium/core";
import { GpioToolkit } from "@agentium/edge";

const gpio = new GpioToolkit({
  chipNumber: 4,         // Pi 5
  allowedPins: [17, 27, 22],
  maxPwmFrequency: 1000,
});

const agent = new Agent({
  name: "gpio-agent",
  model: ollama("llama3.2:1b"),
  instructions: "Control GPIO pins on the Raspberry Pi. Only use pins 17, 27, and 22.",
  tools: [...gpio.getTools()],
});
```

***

## Config

<ParamField body="chipNumber" type="number" default="0">
  GPIO chip number. Use `4` for Pi 5, `0` for Pi 4 and earlier.
</ParamField>

<ParamField body="allowedPins" type="number[]" default="[]">
  Allowlist of pin numbers. Empty array = all pins allowed.
</ParamField>

<ParamField body="maxPwmFrequency" type="number" default="1000">
  Maximum software PWM frequency in Hz.
</ParamField>

***

## Tools

| Tool         | Description                               |
| ------------ | ----------------------------------------- |
| `gpio_read`  | Read the current state (0 or 1) of a pin  |
| `gpio_write` | Set a pin to HIGH (1) or LOW (0)          |
| `gpio_watch` | Watch for rising/falling edge changes     |
| `gpio_pwm`   | Software PWM for LEDs, buzzers, or servos |

***

## Safety

### Pin Allowlisting

The `allowedPins` config restricts which GPIO pins the agent can access. This prevents accidental writes to system-critical pins (e.g., I2C, SPI, UART lines):

```typescript theme={null}
const gpio = new GpioToolkit({
  chipNumber: 4,
  allowedPins: [17, 27, 22], // Only these pins can be read/written
  maxPwmFrequency: 1000,
});
```

If the agent tries to access a pin not in `allowedPins`, the tool returns an error:

```
Error: Pin 14 is not in the allowed pin list [17, 27, 22]
```

### Best Practices

* **Always set `allowedPins`** in production to prevent unintended hardware interaction
* **Use descriptive instructions** that tell the agent which pins correspond to which hardware:
  ```typescript theme={null}
  instructions: `You control GPIO on a Raspberry Pi.
  Pin 17 = LED (output), Pin 27 = Button (input), Pin 22 = Buzzer (PWM).
  Never write to pin 27 (it's an input).`
  ```
* **Limit PWM frequency** with `maxPwmFrequency` to protect sensitive components
* **Test in simulation first** — use a breadboard with LEDs before connecting to production hardware

### Example: LED and Button

```typescript theme={null}
import { Agent, ollama } from "@agentium/core";
import { GpioToolkit } from "@agentium/edge";

const gpio = new GpioToolkit({
  chipNumber: 4,
  allowedPins: [17, 27],
  maxPwmFrequency: 500,
});

const agent = new Agent({
  name: "hardware-agent",
  model: ollama("llama3.1"),
  instructions: `You control a Raspberry Pi. Pin 17 is an LED (output). Pin 27 is a button (input).
When asked about the button, read pin 27. When asked to control the LED, write to pin 17.`,
  tools: [...gpio.getTools()],
});

// Read button state
await agent.run("Is the button pressed?");
// Agent calls gpio_read({ pin: 27 }) → "Pin 27 is LOW (button not pressed)"

// Control LED
await agent.run("Turn on the LED");
// Agent calls gpio_write({ pin: 17, value: 1 }) → "Pin 17 set to HIGH"

// PWM for dimming
await agent.run("Dim the LED to 50%");
// Agent calls gpio_pwm({ pin: 17, frequency: 500, dutyCycle: 0.5 })
```