> ## 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.

# Bluetooth BLE

> Scan, connect, and communicate with Bluetooth Low Energy devices.

# BLE Toolkit

Bluetooth Low Energy scanning and communication — discover devices, connect, read/write characteristics, and subscribe to notifications.

Requires `@stoprocent/noble` as an optional peer dependency.

***

## Quick Start

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

const ble = new BleToolkit({
  scanTimeout: 5000,
  serviceUuidFilter: ["180f"], // Battery Service
});

const agent = new Agent({
  name: "ble-agent",
  model: ollama("llama3.2:1b"),
  instructions: "Discover nearby BLE devices and read their data.",
  tools: [...ble.getTools()],
});

const result = await agent.run("Scan for nearby Bluetooth devices");
```

***

## Config

<ParamField body="scanTimeout" type="number" default="5000">
  Default scan duration in milliseconds.
</ParamField>

<ParamField body="serviceUuidFilter" type="string[]" default="[]">
  Only discover devices advertising these service UUIDs.
</ParamField>

***

## Tools

| Tool          | Description                               |
| ------------- | ----------------------------------------- |
| `ble_scan`    | Discover nearby BLE peripherals           |
| `ble_connect` | Connect to a device by ID                 |
| `ble_read`    | Read a characteristic value               |
| `ble_write`   | Write data to a characteristic            |
| `ble_notify`  | Subscribe to characteristic notifications |

***

## Workflow

A typical BLE interaction follows this pattern:

```
1. Scan → 2. Connect → 3. Read/Write/Subscribe
```

### Example: Reading a Temperature Sensor

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

const ble = new BleToolkit({
  scanTimeout: 5000,
  serviceUuidFilter: ["1809"], // Health Thermometer Service
});

const agent = new Agent({
  name: "sensor-reader",
  model: ollama("llama3.1"),
  instructions: `You control BLE devices. Follow this workflow:
1. Scan for nearby devices
2. Connect to the temperature sensor
3. Read the temperature characteristic (UUID: 2a1c)
Report the temperature in both Celsius and Fahrenheit.`,
  tools: [...ble.getTools()],
});

const result = await agent.run("What's the current temperature from the sensor?");

// The agent will:
// 1. Call ble_scan → finds "TempSensor-01" (id: "aa:bb:cc:dd:ee:ff")
// 2. Call ble_connect → { deviceId: "aa:bb:cc:dd:ee:ff" }
// 3. Call ble_read → { deviceId: "...", serviceUuid: "1809", characteristicUuid: "2a1c" }
// 4. Interpret the raw bytes and respond: "The sensor reads 23.5°C (74.3°F)"
```

### Subscribing to Notifications

For real-time data (e.g., heart rate monitor), use `ble_notify`:

```typescript theme={null}
const result = await agent.run("Monitor the heart rate sensor for 10 seconds");

// The agent calls ble_notify with:
// { deviceId: "...", serviceUuid: "180d", characteristicUuid: "2a37" }
// Returns notification data as it arrives
```