Metadata-Version: 2.4
Name: pyblufi
Version: 0.1.0
Summary: Python BluFi client for ESP32 WiFi provisioning via BLE
Author-email: ESP32 Solar Manager <dev@example.com>
License: MIT
Project-URL: Homepage, https://github.com/maybetaken/pyblufi
Project-URL: Repository, https://github.com/maybetaken/pyblufi.git
Project-URL: Issues, https://github.com/maybetaken/pyblufi/issues
Keywords: blufi,esp32,ble,wifi,provisioning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: bleak>=0.20.0
Requires-Dist: cryptography>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"

# pyblufi

Python implementation of Espressif's BluFi protocol for ESP32 WiFi provisioning over Bluetooth Low Energy (BLE).

## Features

- Full BluFi protocol implementation
- WiFi provisioning via BLE using [bleak](https://github.com/hbldh/bleak)
- WiFi scanning from ESP32 device
- WiFi status reporting (connection, SSID, BSSID)
- Custom data transmission
- Async/await API
- Command-line tool for quick provisioning
- No encryption support (plaintext mode)

## Installation

```bash
pip install .
```

Or from PyPI (once published):
```bash
pip install pyblufi
```

## Requirements

- Python >= 3.8
- bleak >= 0.20.0

## Quick Start

### Command Line

```bash
# Scan for BluFi devices
blufi-provision scan

# Provision a device with WiFi credentials
blufi-provision provision --ssid "MyWiFi" --password "secret123" --device "BLUFI_DEVICE"
```

### Python API

```python
import asyncio
from pyblufi import BlufiClient

async def main():
    client = BlufiClient(debug=True)
    
    # Scan and find device
    device = await client.scan_for_device("BLUFI_DEVICE", timeout=10)
    
    # Connect
    await client.connect(device.address)
    
    # Set STA mode
    await client.set_sta_mode()
    
    # Send SSID and password
    await client.set_ssid("MyWiFi")
    await client.set_password("secret123")
    
    # Trigger connection
    await client.connect_to_ap()
    
    # Wait for WiFi status via notifications
    status = await client.wait_for_wifi_status(timeout=30)
    print(f"Connected: {status}")
    
    await client.disconnect()

asyncio.run(main())
```

## Protocol

BluFi frame format:
```
[TypeSubtype][FrameControl][Sequence][Length][Data...]
```

- **TypeSubtype**: Combined byte (type in lower 2 bits, subtype in upper 6 bits)
- **FrameControl**: Control flags (encryption, checksum, fragmentation)
- **Sequence**: Auto-incrementing sequence number (wraps at 256)
- **Length**: Payload length (max 255)
- **Data**: Variable-length payload

### Frame Types

| Type | Value | Description |
|------|-------|-------------|
| CTRL | 0x00 | Control frame |
| DATA | 0x01 | Data frame |

### Control Subtypes

| Subtype | Command |
|---------|---------|
| 0x00 | ACK |
| 0x02 | SET_WIFI_OPMODE |
| 0x03 | CONN_TO_AP |
| 0x05 | GET_WIFI_STATUS |
| 0x09 | GET_WIFI_LIST |

### Data Subtypes

| Subtype | Command |
|---------|---------|
| 0x00 | NEG (negotiation) |
| 0x02 | STA_SSID |
| 0x03 | STA_PASSWD |
| 0x0F | WIFI_REP (WiFi status report) |
| 0x11 | WIFI_LIST (WiFi scan results) |

## Testing

```bash
pytest tests/ -v
```

## License

MIT
