pyblufi 0.1.0

Python BluFi client for ESP32 WiFi provisioning via BLE

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
• 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

pip install .

Or from PyPI (once published):

pip install pyblufi

Requirements

• Python >= 3.8
• bleak >= 0.20.0

Quick Start

Command Line

# 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

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

pytest tests/ -v

License

MIT