Skip to content

README.md

Latest commit

 

History

History
202 lines (158 loc) · 8.01 KB

README.md

File metadata and controls

202 lines (158 loc) · 8.01 KB
Raw

PyBLE

Python over Bluetooth Low Energy — an open-source, tablet-first MicroPython IDE.

CI License: MIT Platforms Protocol

PyBLE lets you edit, transfer, run, and stop MicroPython programs on a compatible microcontroller board over Bluetooth Low Energy. Its normal workflow needs no USB serial connection, Wi-Fi onboarding, cloud account, or telemetry.

Actual PyBLE iPad app showing GPIO 48 NeoPixel Blocks beside generated MicroPython code

Actual PyBLE app in landscape: GPIO 48 NeoPixel Blocks beside the generated MicroPython.

What works

App

The Flutter app currently provides:

  • filtered BLE discovery and PBLE/1 connection;
  • a MicroPython editor with save, run, stop, soft reboot, and live console;
  • wireless file browsing and transfer with integrity checks;
  • an offline Blockly workspace with GPIO and standard MicroPython NeoPixel blocks;
  • editable beginner examples;
  • exact Blockly sidecar reopening and a bounded Python-to-blocks importer;
  • an adaptive tablet interface for portrait and landscape use; and
  • local operation without an account, analytics, or cloud dependency.

The iPad build is available through public TestFlight. Android source and CI support are present; a public store channel has not been announced.

Firmware

The board-side agent is built with upstream MicroPython and exposes PBLE/1 as a BLE GATT peripheral. It supports:

  • capability and device-information negotiation;
  • run, stop, console, and soft-reboot control;
  • filesystem operations with CRC validation and atomic uploads;
  • resumable transfer behavior and bounded transport recovery;
  • optional main.py auto-run protection;
  • board naming and identify support; and
  • upstream MicroPython’s standard neopixel module.

The public browser installer currently offers the exact v0.4.2 hardware-tested beta for both current profiles. Production Chrome erase/install and deliberately interrupted-flash recovery passed on real hardware for both exact profiles. Complete release qualification continues across the app, PBLE/1, resource, and remaining firmware matrices:

Installer profile Exact target constraint Public status
esp32-4mb Classic ESP32, 4 MiB external SPI flash; no PSRAM assumed v0.4.2 hardware-tested beta; browser install/recovery passed
esp32-s3-n16r8 ESP32-S3, 16 MiB flash / 8 MiB Octal PSRAM; N16R8-class only v0.4.2 hardware-tested beta; browser install/recovery passed
esp32-c3-4mb ESP32-C3, 4 MiB external SPI flash; no PSRAM assumed Planned; unavailable; no public image

See the post-release production-browser attestation for the exact hashes, completed checks, and deliberately bounded claim.

These are the initial port targets, not a chip-family allowlist. A future board is compatible when it has a maintained PyBLE agent port, BLE GATT peripheral support, adequate resources, PBLE/1 conformance, recovery testing, and hardware-validation evidence. Stock MicroPython plus generic Bluetooth hardware is not sufficient by itself.

How it fits together

┌─────────────────────────┐       PBLE/1 over BLE       ┌─────────────────────────┐
│ PyBLE Flutter app       │ ◀─────────────────────────▶ │ Compatible board        │
│ iPadOS / Android        │  run · files · console      │ MicroPython + agent     │
└─────────────────────────┘                             └─────────────────────────┘

This repository is intentionally a monorepo:

  • app/ — the Flutter tablet application;
  • firmware/ — the portable agent, board overlays, and release tooling;
  • docs/specifications/protocol.md — the open PBLE/1 wire contract;
  • tests/ — host, conformance, release, and HIL test runners;
  • tools/ — repository gates and the pyble.dev website; and
  • docs/ — public specifications, decisions, roadmap, and validation evidence.

Keeping these parts together lets a protocol change update the app, firmware, shared conformance corpus, documentation, and CI atomically.

Try PyBLE

  1. Install the iPad beta from TestFlight, or build the Flutter app locally.
  2. Open pyble.dev/flash in a supported desktop Chromium browser. The exact v0.4.2 hardware-tested beta is active. Browser installation and interrupted-flash recovery passed on both exact profiles; complete release qualification continues. Confirm the active version, your exact profile, and the enabled install action.
  3. Before flashing, back up the board, confirm its exact memory profile, and accept every safety acknowledgement before using the one-time wired installer. Flashing erases the board.
  4. Open PyBLE, scan for the provisioned board, connect, and run an example over BLE.

See support and troubleshooting for browser, Bluetooth, and recovery requirements.

Build and test

Clone with both pinned upstream dependencies:

git clone --recurse-submodules https://github.com/PyBLE-dev/PyBLE.git
cd PyBLE

App:

cd app
flutter pub get --enforce-lockfile
flutter gen-l10n
dart format --output=none --set-exit-if-changed lib test integration_test
flutter analyze
flutter test

Firmware host tests:

tests/firmware_tests/run_tests.sh

Firmware build preparation and target builds:

firmware/scripts/install_esp_idf.sh
firmware/scripts/build.sh esp32
firmware/scripts/build.sh esp32-s3
firmware/scripts/build.sh esp32-c3

Website:

cd tools/web
npm ci
npm run check

The complete build requires the pinned toolchains documented in the relevant component README and specifications.

Documentation

Contributing

Contributions are welcome, especially new validated board ports, protocol and transport tests, accessibility improvements, translations, and beginner examples. Read CONTRIBUTING.md and AGENTS.md before opening a pull request.

Every commit must carry a DCO sign-off. PyBLE uses a clean-room boundary and CI gates for prohibited identifiers, SPDX headers, dependency boundaries, localization parity, submodule pins, app tests, website checks, and firmware builds.

PyBLE is an independent MIT-licensed SciLabPro open-source project.