CircuitPython BLE UART Example

It's easy to use Adafruit AirLift ESP32 co-processor boards for Bluetooth Low Energy (BLE) with CircuitPython. When you reset the ESP32, you can put it in WiFi mode (the default), or in BLE mode; you cannot use both modes simultaneously.

Here's a simple example of using BLE to connect CircuitPython with the Bluefruit Connect app. Use CircuitPython 6.0.0 or later.

Note: Don't confuse the ESP32 with the ESP32-S2, which is a different module with a similar name. The ESP32-S2 does not support BLE.

Currently, AirLift BLE support is not currently available on boards with Espressif chips. If the Espressif board provides _bleio, it is for native BLE support (e.g. ESP32-S3), not AirLift.
Currently the AirLift support for CircuitPython only provides BLE peripheral support. BLE central is under development. So you cannot connect to BLE devices like Heart Rate monitors, etc., but you can act as a BLE peripheral yourself.

On-Board Airlift Co-Processor - No Wiring Needed

If you have an Adafruit Metro M4 AirLift Lite, an Adafruit PyPortal (regular, Pynt, or Titano), an Adafruit MatrixPortal, or other Adafruit board with an onboard ESP32 co-processor, then everything is prewired for you, and the pins you need to use are predefined in CircuitPython.

Update the AirLift Firmware

You will need to update the AirLift's firmware to at least version 1.7.1. Previous versions of the AirLift firmware do not support BLE. 

Follow the instructions in the guide below, and come back to this page when you've upgraded the AirLift's firmware:

Ensure the AirLift firmware is version 1.7.1 or higher for BLE to work.

Install CircuitPython Libraries

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware. Thankfully, we can do this in one go. In the example below, click the Download Project Bundle button below to download the necessary libraries and the file in a zip file. Extract the contents of the zip file, and copy the entire lib folder and the file to your CIRCUITPY drive.

Your CIRCUITPY/lib folder should contain the following folders and files:

  • /adafruit_airlift
  • /adafruit_ble
  • /adafruit_bus_device
  • /adafruit_esp32spi
  • adafruit_requests.mpy

Install the Adafruit Bluefruit LE Connect App

The Adafruit Bluefruit LE Connect iOS and Android apps allow you to connect to BLE peripherals that provide a over-the-air "UART" service. Follow the instructions in the Bluefruit LE Connect Guide to download and install the app on your phone or tablet.

BLE Example

TAKE NOTE: Adjust the program as needed to suit the AirLift board you have. Comment and uncomment lines 19-55 below as necessary.
# SPDX-FileCopyrightText: 2020 Dan Halbert, written for Adafruit Industries
# SPDX-License-Identifier: Unlicense

# pylint: disable=unused-import
import board
import busio
from digitalio import DigitalInOut
from adafruit_ble import BLERadio
from adafruit_ble.advertising.standard import ProvideServicesAdvertisement
from import UARTService
from adafruit_esp32spi import adafruit_esp32spi
from adafruit_airlift.esp32 import ESP32

# If you are using a Metro M4 Airlift Lite, PyPortal,
# or MatrixPortal, you can use the default pin settings.
# Leave this DEFAULT line uncommented.
# If you are using a board with pre-defined ESP32 Pins:
esp32 = ESP32()

# If you are using a Metro M7 **OR**
# if you are using CircuitPython 6.0.0 or earlier,
# on PyPortal and PyPortal Titano only, use the pin settings
# below. Comment out the DEFAULT line above and uncomment
# the line below. For CircuitPython 6.1.0, the pin names
# have changed for these boards, and the DEFAULT line
# above is correct.
# esp32 = ESP32(tx=board.TX, rx=board.RX)

# If you are using an AirLift FeatherWing or AirLift Bitsy Add-On,
# use the pin settings below. Comment out the DEFAULT line above
# and uncomment the lines below.
# If you are using an AirLift Breakout, check that these
# choices match the wiring to your microcontroller board,
# or change them as appropriate.
# esp32 = ESP32(
#     reset=board.D12,
#     gpio0=board.D10,
#     busy=board.D11,
#     chip_select=board.D13,
#     tx=board.TX,
#     rx=board.RX,
# )

# If you are using an AirLift Shield,
# use the pin settings below. Comment out the DEFAULT line above
# and uncomment the lines below.
# esp32 = ESP32(
#     reset=board.D5,
#     gpio0=board.D6,
#     busy=board.D7,
#     chip_select=board.D10,
#     tx=board.TX,
#     rx=board.RX,
# )

adapter = esp32.start_bluetooth()

ble = BLERadio(adapter)
uart = UARTService()
advertisement = ProvideServicesAdvertisement(uart)

while True:
    print("waiting to connect")
    while not ble.connected:
    print("connected: trying to read input")
    while ble.connected:
        # Returns b'' if nothing was read.
        one_byte =
        if one_byte:

Talk to the AirLift via the Bluefruit LE Connect App

Start the Bluefruit LE Connect App on your phone or tablet. You should see a CIRCUITPY device available to connect to. Tap the Connect button (1):

You'll then see a list of Bluefruit Connect functions ("modules"). Choose the UART module (2):

On the UART module page, you can type a string and press Send (3). You'll see that string entered, and then see it echoed back (echoing is in gray).

This guide was first published on May 12, 2019. It was last updated on Jul 23, 2024.

This page (CircuitPython BLE) was last updated on Apr 09, 2024.

Text editor powered by tinymce.