pyblufi 0.1.0__tar.gz

pyblufi-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+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

pyblufi-0.1.0/README.md

@@ -0,0 +1,126 @@
+# 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

pyblufi-0.1.0/pyblufi/__init__.py

@@ -0,0 +1,30 @@
+"""PyBluFi - Python implementation of ESP32 BluFi protocol for WiFi provisioning over BLE."""
+
+__version__ = "0.1.0"
+__author__ = "ESP32 Solar Manager"
+
+from .protocol import BlufiProtocol
+from .client import BlufiClient, WifiStatus, WifiNetwork
+from .constants import (
+    BLUFI_TYPE,
+    BLUFI_CTRL_SUBTYPE,
+    BLUFI_DATA_SUBTYPE,
+    WIFI_OP_MODE,
+    WIFI_AUTH_MODE,
+    WIFI_STATUS,
+    SECURITY_MODE,
+)
+
+__all__ = [
+    "BlufiProtocol",
+    "BlufiClient",
+    "WifiStatus",
+    "WifiNetwork",
+    "BLUFI_TYPE",
+    "BLUFI_CTRL_SUBTYPE",
+    "BLUFI_DATA_SUBTYPE",
+    "WIFI_OP_MODE",
+    "WIFI_AUTH_MODE",
+    "WIFI_STATUS",
+    "SECURITY_MODE",
+]

pyblufi-0.1.0/pyblufi/cli.py

@@ -0,0 +1,273 @@
+"""Command-line interface for PyBluFi."""
+
+import argparse
+import asyncio
+import sys
+import textwrap
+from typing import List, Optional
+
+from .client import BlufiClient, WifiStatus
+from .constants import WIFI_STATUS
+
+
+def _print_wifi_status(status: WifiStatus) -> None:
+    """Print WiFi status in a nice format."""
+    status_map = {
+        WIFI_STATUS.STA_CONN_SUCCESS: "Connected (with IP)",
+        WIFI_STATUS.STA_CONN_FAIL: "Connection failed",
+        WIFI_STATUS.STA_CONN_CONNECTING: "Connecting...",
+        WIFI_STATUS.STA_CONN_NO_IP: "Connected (no IP)",
+    }
+    conn_status = status_map.get(status.sta_conn_status, f"Unknown ({status.sta_conn_status})")
+
+    print(f"  Operation Mode:   {status.op_mode}")
+    print(f"  Connection:       {conn_status}")
+    print(f"  SSID:             {status.sta_ssid or 'N/A'}")
+    print(f"  IP:               {status.sta_ip or 'N/A'}")
+    print(f"  BSSID:            {status.sta_bssid or 'N/A'}")
+    print(f"  SoftAP Clients:   {status.softap_conn_num}")
+
+
+async def cmd_scan(args: argparse.Namespace) -> int:
+    """Scan for BluFi devices."""
+    print("Scanning for BluFi devices...")
+    client = BlufiClient(debug=args.debug)
+    devices = await client.scan(timeout=args.timeout)
+
+    if not devices:
+        print("No devices found.")
+        return 1
+
+    print(f"\nFound {len(devices)} device(s):")
+    print("-" * 60)
+    for i, dev in enumerate(devices, 1):
+        print(f"{i}. {dev.name or 'Unknown'} ({dev.address})")
+        print(f"   RSSI: {dev.rssi} dBm")
+    print("-" * 60)
+    return 0
+
+
+async def cmd_provision(args: argparse.Namespace) -> int:
+    """Provision WiFi credentials to a BluFi device."""
+    print(f"Provisioning device: {args.device}")
+    print(f"  SSID:     {args.ssid}")
+    print(f"  Password: {'*' * len(args.password)}")
+    print()
+
+    client = BlufiClient(debug=args.debug)
+
+    # Find device
+    if args.address:
+        address = args.address
+        print(f"Using address: {address}")
+    else:
+        print(f"Scanning for device matching '{args.device}'...")
+        device = await client.scan_for_device(args.device, timeout=args.timeout)
+        if not device:
+            print(f"Device '{args.device}' not found.")
+            return 1
+        address = device.address
+        print(f"Found: {device.name} ({device.address})\n")
+
+    # Connect
+    print("Connecting...")
+    if not await client.connect(address, timeout=args.timeout):
+        print("Failed to connect.")
+        return 1
+    print("Connected!\n")
+
+    try:
+        # Send WiFi credentials
+        print("Setting STA mode...")
+        await client.set_sta_mode()
+        await asyncio.sleep(0.5)
+
+        print(f"Setting SSID: {args.ssid}")
+        await client.set_ssid(args.ssid)
+        await asyncio.sleep(0.5)
+
+        print("Setting password...")
+        await client.set_password(args.password)
+        await asyncio.sleep(0.5)
+
+        print("Connecting to AP...")
+        await client.connect_to_ap()
+        await asyncio.sleep(1.0)
+
+        # Wait for connection
+        print(f"\nWaiting for WiFi connection (timeout={args.wait}s)...")
+        status = await client.wait_for_wifi_status(timeout=args.wait)
+
+        if status and status.sta_conn_status == WIFI_STATUS.STA_CONN_SUCCESS:
+            print("\nWiFi connected successfully!")
+            _print_wifi_status(status)
+            return 0
+        else:
+            print("\nWiFi connection timed out or failed.")
+            return 1
+
+    except Exception as e:
+        print(f"Error during provisioning: {e}")
+        return 1
+    finally:
+        await client.disconnect()
+        print("\nDisconnected.")
+
+
+async def cmd_status(args: argparse.Namespace) -> int:
+    """Get WiFi status from a connected device."""
+    client = BlufiClient(debug=args.debug)
+
+    print(f"Connecting to {args.address}...")
+    if not await client.connect(args.address, timeout=args.timeout):
+        print("Failed to connect.")
+        return 1
+
+    try:
+        print("Getting WiFi status...")
+        status = await client.get_wifi_status()
+        if status:
+            _print_wifi_status(status)
+        else:
+            print("No status received.")
+    finally:
+        await client.disconnect()
+
+    return 0
+
+
+async def cmd_scan_wifi(args: argparse.Namespace) -> int:
+    """Scan for nearby WiFi networks via the device."""
+    client = BlufiClient(debug=args.debug)
+
+    print(f"Connecting to {args.address}...")
+    if not await client.connect(args.address, timeout=args.timeout):
+        print("Failed to connect.")
+        return 1
+
+    try:
+        print("Scanning for WiFi networks...")
+        networks = await client.get_wifi_list()
+        if networks:
+            print(f"\nFound {len(networks)} network(s):")
+            print("-" * 40)
+            for net in networks:
+                signal = ""
+                if net.rssi > -50:
+                    signal = "Excellent"
+                elif net.rssi > -60:
+                    signal = "Good"
+                elif net.rssi > -70:
+                    signal = "Fair"
+                else:
+                    signal = "Weak"
+                print(f"  {net.ssid:<32} {net.rssi:>4} dBm ({signal})")
+            print("-" * 40)
+        else:
+            print("No networks found.")
+    finally:
+        await client.disconnect()
+
+    return 0
+
+
+async def cmd_custom(args: argparse.Namespace) -> int:
+    """Send custom data to the device."""
+    client = BlufiClient(debug=args.debug)
+
+    print(f"Connecting to {args.address}...")
+    if not await client.connect(args.address, timeout=args.timeout):
+        print("Failed to connect.")
+        return 1
+
+    try:
+        data = args.data.encode("utf-8")
+        print(f"Sending custom data: {data.hex()}")
+        await client.send_custom_data(data)
+        print("Sent.")
+    finally:
+        await client.disconnect()
+
+    return 0
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="blufi-provision",
+        description="PyBluFi - ESP32 WiFi provisioning via BLE",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""\
+            Examples:
+              blufi-provision scan
+              blufi-provision provision --ssid "MyWiFi" --password "secret123" --device "BLUFI_DEVICE"
+              blufi-provision status --address AA:BB:CC:DD:EE:FF
+              blufi-provision scan-wifi --address AA:BB:CC:DD:EE:FF
+              blufi-provision custom --address AA:BB:CC:DD:EE:FF --data "hello"
+        """),
+    )
+    parser.add_argument(
+        "--debug", "-d",
+        action="store_true",
+        help="Enable debug output",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # scan
+    scan_parser = subparsers.add_parser("scan", help="Scan for BluFi devices")
+    scan_parser.add_argument(
+        "--timeout", "-t",
+        type=float,
+        default=5.0,
+        help="Scan timeout in seconds (default: 5.0)",
+    )
+
+    # provision
+    prov_parser = subparsers.add_parser("provision", help="Provision WiFi credentials")
+    prov_parser.add_argument("--ssid", "-s", required=True, help="WiFi SSID")
+    prov_parser.add_argument("--password", "-p", default="", help="WiFi password")
+    prov_parser.add_argument("--device", "-D", default="BLUFI", help="Device name filter")
+    prov_parser.add_argument("--address", "-a", help="BLE address (skip scan)")
+    prov_parser.add_argument("--timeout", "-t", type=float, default=10.0, help="Timeout")
+    prov_parser.add_argument("--wait", "-w", type=float, default=30.0, help="Wait for WiFi connection")
+
+    # status
+    status_parser = subparsers.add_parser("status", help="Get WiFi status")
+    status_parser.add_argument("--address", "-a", required=True, help="BLE address")
+    status_parser.add_argument("--timeout", "-t", type=float, default=10.0, help="Timeout")
+
+    # scan-wifi
+    scan_wifi_parser = subparsers.add_parser("scan-wifi", help="Scan for WiFi networks via device")
+    scan_wifi_parser.add_argument("--address", "-a", required=True, help="BLE address")
+    scan_wifi_parser.add_argument("--timeout", "-t", type=float, default=10.0, help="Timeout")
+
+    # custom
+    custom_parser = subparsers.add_parser("custom", help="Send custom data")
+    custom_parser.add_argument("--address", "-a", required=True, help="BLE address")
+    custom_parser.add_argument("--data", "-d", required=True, help="Data to send")
+    custom_parser.add_argument("--timeout", "-t", type=float, default=10.0, help="Timeout")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    command_map = {
+        "scan": cmd_scan,
+        "provision": cmd_provision,
+        "status": cmd_status,
+        "scan-wifi": cmd_scan_wifi,
+        "custom": cmd_custom,
+    }
+
+    if args.command in command_map:
+        return asyncio.run(command_map[args.command](args))
+    else:
+        parser.print_help()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())