Metadata-Version: 2.4
Name: airctl
Version: 0.1.3
Summary: AI-friendly CLI tool for device control via Bluetooth and more
Author: AirCtl Team
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: bleak>=0.21.0
Requires-Dist: orjson>=3.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pywin32>=306; platform_system == 'Windows'
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: typing-extensions>=4.7.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# AirCtl

**AI-friendly CLI tool for device control via Bluetooth and more.**

AirCtl is designed to enable AI agents to control various devices through a command-line interface. The first implementation focuses on Bluetooth Low Energy (BLE) device control, built on top of the [Bleak](https://github.com/hbldh/bleak) library.

## Features

- **AI-First Design**: JSON output by default for easy parsing by AI agents
- **Daemon Architecture**: Background daemon maintains connections for fast operations
- **Multi-Device Support**: Connect and manage multiple BLE devices simultaneously
- **Event Streaming**: Subscribe to real-time notifications via event streams
- **Background Tasks**: Periodic read, write, and scan operations with event callbacks
- **Cross-Platform**: Works on Windows, Linux, and macOS
- **Configuration Persistence**: Save device aliases and GATT presets

## Installation

```bash
pip install airctl
```

All dependencies (bleak, typer, rich, pydantic, etc.) will be installed automatically.

Or install from source:

```bash
git clone https://github.com/skinapi2025/AirCtl.git
cd AirCtl
pip install -e ".[dev]"
```

## Quick Start

### 1. Scan for Devices

```bash
airctl ble scan -t 10
```

Output (JSON):
```json
{
  "devices": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "name": "My Sensor",
      "rssi": -45,
      "service_uuids": ["180D"]
    }
  ],
  "count": 1
}
```

### 2. Connect to a Device

```bash
airctl ble connect AA:BB:CC:DD:EE:FF -a my_sensor
```

> **Note**: Avoid using hyphens (`-`) in aliases as they may be misinterpreted as command options. Use underscores (`_`) instead.

### 3. Explore Services

```bash
airctl ble services my_sensor
airctl ble characteristics my_sensor
```

### 4. Read/Write Characteristics

```bash
# Read a characteristic by UUID
airctl ble read my_sensor -u 2A19 -f hex

# Read a characteristic by handle (useful when multiple chars have same UUID)
airctl ble read my_sensor -H 74 -f hex

# Write to a characteristic
airctl ble write my_sensor -u 2A19 -d "hex:010203"
```

> **Note**: Some devices may have multiple characteristics with the same UUID (e.g., Alert Level in both Immediate Alert and Link Loss services). Use `-H` to specify the exact characteristic handle. You can find the handle value from `airctl ble characteristics` output.

### 5. Subscribe to Notifications

```bash
# Subscribe
airctl ble notify subscribe my_sensor -u 2A37

# Stream events
airctl ble events -t notification
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        CLI Layer                                 │
│              (airctl ble/daemon/config commands)                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ JSON-RPC over IPC
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                     BLE Daemon (Background)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Connection │  │   Event     │  │    Device Manager       │  │
│  │   Manager   │  │   Stream    │  │  (multi-device support) │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Task Manager                              │ │
│  │       (periodic read/write/scan operations)                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                     Bleak Library                                │
└─────────────────────────────────────────────────────────────────┘
```

## Commands Reference

### Daemon Management

```bash
airctl daemon status          # Check daemon status (JSON output)
airctl daemon start           # Start daemon manually
airctl daemon start --log-level DEBUG  # Start with debug logging
airctl daemon stop            # Stop daemon
airctl daemon restart         # Restart daemon
```

> **Note**: Daemon logs are written to the system temp directory (`%TEMP%\airctl-daemon.log` on Windows, `/tmp/airctl-daemon.log` on Linux/macOS). Use `--log-level DEBUG` for verbose logging during troubleshooting.

### Diagnostics

```bash
airctl doctor check           # Run diagnostic checks (JSON output)
```

### BLE Operations

```bash
# Scanning
airctl ble scan [-t 10] [--service-uuids UUID1,UUID2]
airctl ble scan -n "Heart Rate"   # Filter by exact device name

# Connection
airctl ble connect <address> [-t 30] [-a alias]
airctl ble disconnect <address>
airctl ble list               # List connected devices

# GATT Operations
airctl ble services <address>
airctl ble characteristics <address> [-s UUID]
airctl ble read <address> -u UUID [-f hex|base64|text]
airctl ble read <address> -H HANDLE [-f hex|base64|text]
airctl ble write <address> -u UUID -d "hex:..."
airctl ble write <address> -H HANDLE -d "hex:..."

# Notifications
airctl ble notify subscribe <address> -u UUID
airctl ble notify unsubscribe <address> -u UUID
airctl ble events [-a ADDR] [-t TYPE]

# Background Tasks (Periodic Operations)
airctl ble task start-read <address> -u UUID -i 5       # Periodic read (every 5s)
airctl ble task start-read <address> -H HANDLE -i 2     # Using handle instead of UUID
airctl ble task start-write <address> -u UUID -d "hex:01" -i 10  # Periodic write (every 10s)
airctl ble task start-scan -i 30 --scan-timeout 5       # Periodic scan (every 30s)
airctl ble task list                                     # List all background tasks
airctl ble task stop <task_id>                           # Stop a background task
airctl ble events -t periodic_read                       # Stream periodic read events
airctl ble events -t periodic_write                      # Stream periodic write events
airctl ble events -t periodic_scan                       # Stream periodic scan events
```

### Background Task Types

| Task Type | Command | Use Case |
|-----------|---------|----------|
| **Periodic Read** | `task start-read` | Keep connection alive, monitor sensor data |
| **Periodic Write** | `task start-write` | Send heartbeat, periodic control commands |
| **Periodic Scan** | `task start-scan` | Continuously monitor nearby devices |

### Configuration

```bash
# View configuration
airctl config list
airctl config get daemon.auto_start

# Device aliases
airctl config alias list
airctl config alias set <address> <name>
airctl config alias remove <name>

# GATT presets
airctl config preset list
airctl config preset get uart
airctl config preset set <name> --service UUID --char UUID
airctl config preset remove <name>
```

## Data Input Formats

The `-d` / `--data` parameter supports multiple formats:

| Format | Example | Description |
|--------|---------|-------------|
| `hex:` | `hex:010203` | Hexadecimal bytes |
| `text:` | `text:hello` | UTF-8 text |
| `base64:` | `base64:AQID` | Base64 encoded |
| (default) | `010203` | Hexadecimal (default) |

## Built-in Presets

| Preset | Service | Description |
|--------|---------|-------------|
| `uart` | Nordic UART | UART service for serial communication |
| `heart_rate` | 180D | Heart Rate service |
| `battery` | 180F | Battery service |
| `device_info` | 180A | Device Information service |

## Configuration File

Configuration is stored in `~/.airctl/config.yaml`:

```yaml
version: 1

aliases:
  "my_sensor": "AA:BB:CC:DD:EE:FF"

presets:
  custom:
    service: "custom-service-uuid"
    char: "custom-char-uuid"

daemon:
  auto_start: true
  log_level: "INFO"
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/skinapi2025/AirCtl.git
cd AirCtl

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
.\venv\Scripts\activate  # Windows

# Install development dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black airctl tests
isort airctl tests
```

### Type Checking

```bash
mypy airctl
```

## Requirements

- Python 3.10+
- Bluetooth adapter with BLE support
- Platform-specific requirements:
  - **Windows**: Windows 10 version 16299 or later
  - **Linux**: BlueZ 5.55 or later
  - **macOS**: macOS 10.15 or later

## Dependencies

All dependencies are automatically installed with `pip install airctl`:

| Package | Purpose |
|---------|---------|
| [bleak](https://github.com/hbldh/bleak) | Cross-platform BLE library |
| [typer](https://typer.tiangolo.com/) | CLI framework |
| [rich](https://github.com/Textualize/rich) | Rich text/pretty print |
| [pydantic](https://pydantic-docs.helpmanual.io/) | Data validation |
| [orjson](https://github.com/ijl/orjson) | Fast JSON serialization |
| [pyyaml](https://pyyaml.org/) | YAML configuration |
| pywin32 | Windows named pipes (Windows only) |

## Known Issues

### Alias Naming

Avoid using hyphens (`-`) in device aliases. For example, use `my_sensor` instead of `my-sensor`. This is because command-line parsers may interpret the hyphen as an option prefix.

### Windows Daemon Stop

On Windows, the daemon uses named pipes for IPC. The `daemon stop` command works by connecting to the daemon to unblock the pipe and signal shutdown. This is handled automatically.

### BLE Authentication Errors

Some BLE characteristics require authentication (pairing) to read or write. If you encounter `Insufficient Authentication` errors, the device needs to be paired with your system first. This is a BLE security feature, not a bug.

### Multiple Characteristics with Same UUID

Some devices have multiple characteristics with the same UUID in different services (e.g., Alert Level appears in both Immediate Alert and Link Loss services). When reading by UUID, airctl automatically selects the first readable characteristic. Use `-H` for precise control.

## License

MIT License

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

## Acknowledgments

- [Bleak](https://github.com/hbldh/bleak) - Cross-platform BLE library
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation
