# Getting Started with CircuitPython and Bluetooth Low Energy

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/070/334/medium800/micropython___circuitpython_Blinka_Bluefruit_Ouroboros_Dark.png?1548968545)

The Adafruit nRF52840 has joined the growing list of CircuitPython compatible boards. It features a Cortex M4 chip with Bluetooth Low Energy. We've added BLE support to CircuitPython which makes it super simple to get started!

CircuitPython is Python that runs on microcontrollers. It's designed to lower the barrier for entry to learning programming and electronics. If you're new to CircuitPython, please check out [the Welcome to CircuitPython guide](https://learn.adafruit.com/welcome-to-circuitpython) to find out how to get started with CircuitPython.

## CircuitPython, BLE and Bluefruit LE Connect

This guide is designed to help you get started with CircuitPython, the Adafruit nRF52840 and the Bluefruit LE Connect app.

First you'll learn some Bluetooth Low Energy Basics to help you understand what your CircuitPython code is doing.

There is a quick intro to the Adafruit Bluefruit LE Connect app with links to install it, and how to get to the controller interface.

Then you'll be provided a series of quick demos using CircuitPython, the Adafruit nRF52840, and the Bluefruit LE Connect app for mobile devices. You'll learn things like how to read a button press from the app's control pad interface, how to change the color of a NeoPixel, or how to read acceleration data from your mobile device.

Let's get started!

## Parts
### Adafruit Feather nRF52840 Express

[Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)
The **Adafruit Feather nRF52840 Express** is the new Feather family member with Bluetooth® Low Energy and _native USB support_ featuring the nRF52840!  It's our take on an 'all-in-one' Arduino-compatible + Bluetooth® Low Energy with built-in USB...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4062)
[Related Guides to the Product](https://learn.adafruit.com/products/4062/guides)
![Angled shot of a Adafruit Feather nRF52840 Express. ](https://cdn-shop.adafruit.com/640x480/4062-02.jpg)

### USB cable - USB A to Micro-B

[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller

Approximately 3 feet / 1 meter long

Out of Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
![USB cable - USB A to Micro-B - 3 foot long](https://cdn-shop.adafruit.com/640x480/592-01.jpg)

# Getting Started with CircuitPython and Bluetooth Low Energy

## Bluetooth Low Energy Basics

![](https://cdn-learn.adafruit.com/assets/assets/000/070/422/medium800/micropython___circuitpython_Bluetooth_Logo.png?1549045741)

The nRF52840 uses Bluetooth Low Energy, or BLE. BLE is a wireless communication protocol used by many devices, including mobile devices. You'll be able to communicate with your nRF52840 board using your mobile phone!

There's a few terms and concepts commonly used in BLE with which you may want to familiarise yourself. This will help you understand what your code is doing when you're using CircuitPython and BLE.

The major concepts can be broken down into two categories: connection set up and communication. The first deals with setting up connections between devices, such as between your mobile phone and the nRF52840 board. The second deals with communication between the devices once they are connected.

## Bluetooth Terms

- **Central** - The host computer. This is often a mobile device such as a phone or tablet, or it could be a desktop or laptop.
- **Peripheral** - The connected device. Examples of peripherals are: heart rate monitor, smart watch, or fitness tracker. The CircuitPython code we have so far is designed to make the Adafruit nRF52840 devices work as peripherals.
- **Advertising** - Information sent by the peripheral during connection set up. When a device advertises, it is transmitting the name of the device and describing its capabilities. The central looks for an advertising peripheral to connect to, and uses that information to determine what the peripheral is capable of.
- **Service** - A function the peripheral provides. The peripheral advertises its services. A really common service that we use is the UART service, which acts like a hardware UART and is a way of bidirectionally sending information to and from devices. 
- **Packet** - Data transmitted by a device. BLE devices and host computers transmit and receive data in small bursts called packets.

## Making a Bluetooth Connection

To use these terms in the context of connecting to your Adafruit nRF52840:

- You run CircuitPython code that makes your board act as a peripheral by advertising its name and the services it's capable of.
- You start up Adafruit's **Bluefruit LE Connect app** on an Android or iOS device in central mode, that device becomes the central, and begins listening for the peripheral.
- You set up the connection between the nRF52840 peripheral and the Bluefruit LE Connect app, and the app discovers the details about the services that the peripheral is capable of.
- Once this connection is made, you can use CircuitPython code to read packets sent from the Bluefruit LE Connect app to your nRF52840 board. For example, you can receive data describing screen button presses or RGB color values.

Now that you have a general idea of basic BLE terms and concepts, it's time to install the Bluefruit LE Connect application, and run some CircuitPython demos!

# Getting Started with CircuitPython and Bluetooth Low Energy

## Bluefruit LE Connect Basics

## Getting the free Adafruit Bluefruit LE Connect App

To interact with your board from your phone or tablet, you'll use the Adafruit [Bluefruit LE Connect App](https://learn.adafruit.com/bluefruit-le-connect-for-ios). Install it from the [Apple App Store](https://itunes.apple.com/us/app/adafruit-bluefruit-le-connect/id830125974) or [Google Play App Store](https://play.google.com/store/apps/details?id=com.adafruit.bluefruit.le.connect).

## Find Your nRF52840 Board

If you're in a situation where there are multiple nRF52840 boards available, and you need to figure out which one is yours, there is a simple solution.

Plug your board into your computer, connect to the serial console, and connect to the REPL. You should see the `>>>` prompt. From the REPL, run the following commands:

```python
from adafruit_ble import BLERadio
ble = BLERadio()
ble.name
```

This will return something like **CIRCUITPYxxxx** where " **xxxx**" is four alphanumeric digits. For example, **CIRCUITPY34e7** is a possible option. This is the name of your board as it will show up in the Adafruit Bluefruit LE Connect app!

## Connect to nRF52840
Info: 

Start your Adafruit nRF52840 board with code running from **code.py**. You must have Bluetooth connectivity code running for this to work! The examples on the following pages have ready to go CircuitPython **code.py** scripts to try out.

For your board to appear in the app, in your  **code.py** , you must have the following code _at a minimum_:

```python
from adafruit_ble import BLERadio
from adafruit_ble.advertising.standard import ProvideServicesAdvertisement
from adafruit_ble.services.nordic import UARTService

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

ble.start_advertising(advertisement)
while True:
    # Normally other work would be done here after connecting.
	pass
```

Next, start up the Bluefruit LE Connect app, and make sure it's in Central Mode (left button on the bottom).  When you start the app, you should see a device named **CIRCU** or **CIRCUITPY**. If there's a long list of devices, you can shorten it by turning on the " **Must have UART Service**" switch.

To connect to the Adafruit nRF52840, touch the **Connect** button. You should see " **Connecting**" and then " **Discovering Services**".

If you don't see **CIRCU** or **CIRCUITPY** right away, try pulling down to refresh. If that doesn't work, try turning Bluetooth off and back on on your phone or tablet and restarting the app.

![](https://cdn-learn.adafruit.com/assets/assets/000/129/840/medium800/circuitpython_select-device.png?1714930717)

## Device Menu

After you connect, you'll see a menu of how you can interact with the device. Choose **Controller**.

![](https://cdn-learn.adafruit.com/assets/assets/000/129/841/medium800/circuitpython_modules.png?1714930904)

## Controller Menu

After you choose Controller, you'll see another screen with more choices.

![](https://cdn-learn.adafruit.com/assets/assets/000/070/496/medium800/micropython___circuitpython_bluefruitle_3.png?1549054681)

## Control Pad

Here's the **Control Pad** screen. You can use the buttons as inputs in CircuitPython. For example, you could have code that moved a servo arm up and down when the up or down button is pressed.

![](https://cdn-learn.adafruit.com/assets/assets/000/070/497/medium800/micropython___circuitpython_bluefruitle_4.png?1549054692)

## Color Picker

To change the color of the NeoPixels, use the **Color Picker** screen. Choose a color and press **Send Selected Color**.

![](https://cdn-learn.adafruit.com/assets/assets/000/070/498/medium800/micropython___circuitpython_bluefruitle_5.png?1549054723)

## Stream Sensor Data

There are multiple options under Stream Sensor Data including **Accelerometer**. You enable these options to stream the associated data from your mobile device to your Adafruit nRF52840 board, and use CircuitPython to read that data.

For example, if you have code that reads the acceleration data from your mobile device, you'd want to enable **Accelerometer** once you connected to the app.

![](https://cdn-learn.adafruit.com/assets/assets/000/070/505/medium800/micropython___circuitpython_bluefruit-connect-accelerometer-stream.png?1549056932)

Check out [this detailed guide](https://learn.adafruit.com/bluefruit-le-connect) for more information about the Adafruit Bluefruit LE Connect application.

# Getting Started with CircuitPython and Bluetooth Low Energy

## Button Press

The Bluefruit LE Connect app has a control pad with 8 buttons: UP, DOWN, LEFT, RIGHT, 1, 2, 3 and 4. This demo will show you how to access those buttons, and use them to print a message to the serial console.

Save the following as **code.py** on your `CIRCUITPY` drive and then connect to the board using the Bluefruit LE Connect app. Then, connect to the serial console on your computer.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Getting_Started_With_BLE_and_CP/button_presses/code.py

Connect to your board using the Bluefruit LE Connect application and navigate to the Control Pad page.

![](https://cdn-learn.adafruit.com/assets/assets/000/071/869/medium800/micropython___circuitpython_Control_Pad_Screenshot.png?1551036465)

Let's take a look at the code.

First we import the necessary libraries and instantiate the UART server.

Inside the loop, we first begin advertising.

Once connected, the board begins listening for packets. In the event that a button packet is received, it checks to see if the button was pressed. Then it checks to see whether it was button 1 or the UP button, and prints a message to the serial console.

The buttons are available as:

- 1 = `ButtonPacket.BUTTON_1`
- 2 = `ButtonPacket.BUTTON_2`
- 3 = `ButtonPacket.BUTTON_3`
- 4 = `ButtonPacket.BUTTON_4`
- UP = `ButtonPacket.DOWN`
- DOWN = `ButtonPacket.UP`
- LEFT = `ButtonPacket.LEFT`
- RIGHT = `ButtonPacket.RIGHT`

If the board loses connection, the loop will begin again and the board will resume advertising until a new connection is made.

Now you can press the up button or the 1 button, and see the resulting print statement in the serial console!

That's all there is to reading button presses from the Bluefruit LE Connect app with CircuitPython! Now you can use those buttons do all sorts of things like control a servo, light up an LED, or control your robotic creation. Give it a try!

# Getting Started with CircuitPython and Bluetooth Low Energy

## NeoPixel Color

The Bluefruit LE Connect app has a Color Picker that allows you to easily set the color of NeoPixels connected to your Adafruit nRF52840. For this demo, we'll change the color of the on-board NeoPIxel using CircuitPython and the Bluefruit LE Connect app.

Save the following as **code.py** on your `CIRCUITPY` drive and then connect to the board using the Bluefruit LE Connect app.

Danger: 

[Click here to download the latest CircuitPython for your board.](https://circuitpython.org/downloads)
[Click here to download the latest CircuitPython library bundle.](https://circuitpython.org/libraries)
Drag the library files from the library bundle to the **lib** folder on your **CIRUCUITPY** drive.

https://github.com/adafruit/Adafruit_CircuitPython_BLE/blob/main/examples/ble_bluefruit_color_picker.py

Connect to your board using the Bluefruit LE Connect application and navigate to the Color Picker page.

![](https://cdn-learn.adafruit.com/assets/assets/000/071/871/medium800/micropython___circuitpython_Color_Picker_Screenshot.png?1551037658)

Let's take a look at the code.

First we import the necessary libraries and instantiate the UART server.

Inside the loop, we first begin advertising.

Once connected, the board begins listening for packets. In the event that a color packet is received, it changes the color of the NeoPixel to the chosen color.

Now you can use the color picker to change the color and send that color to the NeoPixel.

That's all there is to changing the color of NeoPixels with the Bluefruit LE Connect app and CircuitPython! You can easily attach external NeoPixels and change the color with the app as well. Check it out!

# Getting Started with CircuitPython and Bluetooth Low Energy

## Mobile Movement Data

The Bluefruit Connect app allows you to access the accelerometer, magnetometer, gyroscopic and quaternion movement information from your mobile device. This demo will show you how to access that data and print it to the serial console.

Save the following as **code.py** on your `CIRCUITPY` drive and then connect to the board using the Bluefruit LE Connect app. Then, connect to the serial console.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Getting_Started_With_BLE_and_CP/mobile_movement_data_streams/code.py

Connect to your board using the Bluefruit LE Connect application and navigate to the controller page. Enable the following streams: Quaternion, Accelerometer, Gyro, Magnetometer.

![](https://cdn-learn.adafruit.com/assets/assets/000/071/867/medium800/micropython___circuitpython_Mobile_Movement_Data_Streams_Screenshot.png?1551035869)

Let's take a look at the code.

First we import the necessary libraries and instantiate the UART server.

Inside the loop, we first begin advertising.

Once connected, the board begins listening for packets. In the event that an accelerometer, magnetometer, gyro or quaternion packet is received, it prints a message to the serial console.

That's all there is to accessing acceleration, magnetometer, gyro and [quaternion](https://en.wikipedia.org/wiki/Quaternion) data from your mobile using the Bluefruit LE Connect app and CircuitPython!

# Getting Started with CircuitPython and Bluetooth Low Energy

## Location

The Bluefruit LE Connect application allows you to access the location data from your phone. This demo will show you how to access that data and print it to the serial console.

Save the following as **code.py** on your `CIRCUITPY` drive and then connect to the board using the Bluefruit LE Connect app. Then, connect to the serial console.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Getting_Started_With_BLE_and_CP/location/code.py

Connect to your board using the Bluefruit LE Connect application and navigate to the Controller page. Enable the Location data stream.

![](https://cdn-learn.adafruit.com/assets/assets/000/071/870/medium800/micropython___circuitpython_Location_Screenshot.png?1551037041)

Let's take a look at the code.

First we import the necessary libraries and instantiate the UART server.

Inside the loop, we first begin advertising.

Once connected, the board begins listening for packets. In the event that a location packet is received, it prints a message to the serial console.

That's all there is to accessing location data from your mobile using the Bluefruit LE Connect app and CircuitPython!

# Getting Started with CircuitPython and Bluetooth Low Energy

## BLE Technical Details


## Featured Products

### Adafruit Feather nRF52840 Express

[Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)
The **Adafruit Feather nRF52840 Express** is the new Feather family member with Bluetooth® Low Energy and _native USB support_ featuring the nRF52840!  It's our take on an 'all-in-one' Arduino-compatible + Bluetooth® Low Energy with built-in USB...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4062)
[Related Guides to the Product](https://learn.adafruit.com/products/4062/guides)
### Circuit Playground Bluefruit - Bluetooth® Low Energy

[Circuit Playground Bluefruit - Bluetooth® Low Energy](https://www.adafruit.com/product/4333)
 **Circuit Playground Bluefruit** is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've taken the popular Circuit Playground Express and made it even better! Now the main chip is an nRF52840...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
### Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE

[Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE](https://www.adafruit.com/product/4481)
What's smaller than a Feather but larger than a Trinket? It's an **Adafruit ItsyBitsy nRF52840 Express** featuring the **Nordic nRF52840 Bluetooth® LE** processor! Teensy & powerful, with an fast nRF52840 Cortex M4 processor running at 64 MHz and 1 MB...

In Stock
[Buy Now](https://www.adafruit.com/product/4481)
[Related Guides to the Product](https://learn.adafruit.com/products/4481/guides)
### USB cable - USB A to Micro-B

[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller

Approximately 3 feet / 1 meter long

Out of Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
### Adafruit Circuit Playground Bluefruit Express Starter Kit

[Adafruit Circuit Playground Bluefruit Express Starter Kit](https://www.adafruit.com/product/4504)
If you missed out on ADABOX 014, its not too late for you to pick up the parts necessary to build many of the projects! This kit pack doesn't come with tissue paper or the nifty extras, but it does have all the electronic goodies you need  
  
This project pack features...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4504)
[Related Guides to the Product](https://learn.adafruit.com/products/4504/guides)

## Related Guides

- [Introducing the Adafruit nRF52840 Feather](https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather.md)
- [Adafruit Circuit Playground Bluefruit](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit.md)
- [Adafruit ItsyBitsy nRF52840 Express](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express.md)
- [Wireless BLE MIDI Robot Xylophone](https://learn.adafruit.com/wireless-ble-midi-robot-xylophone.md)
- [BLE Synth with the Feather nRF52840 and Circuit Playground Bluefruit](https://learn.adafruit.com/ble-synth-with-the-feather-nrf52840-and-circuit-playground-bluefruit.md)
- [Bluefruit Playground Hide and Seek](https://learn.adafruit.com/hide-n-seek-bluefruit-ornament.md)
- [Circuit Playground TFT Gizmo Snow Globe](https://learn.adafruit.com/circuit-playground-tft-gizmo-snow-globe.md)
- [CircuitPython BLE Advertising Beacons](https://learn.adafruit.com/circuitpython-ble-advertising-beacons.md)
- [Circuit Playground Bluetooth Cauldron](https://learn.adafruit.com/cpx-cauldron.md)
- [Circuit Playground Gizmo Ornaments](https://learn.adafruit.com/display-ornaments-with-circuit-playground.md)
- [Adafruit Circuit Playground TFT Gizmo](https://learn.adafruit.com/adafruit-tft-gizmo.md)
- [PyLeap MP3 Playback for Circuit Playground Bluefruit](https://learn.adafruit.com/pyleap-mp3-playback-for-cpb.md)
- [PyLeap Tone Piano for Circuit Playground Bluefruit](https://learn.adafruit.com/pyleap-tone-piano-for-cpb.md)
- [CircusPython: Jump through Hoops with CircuitPython Bluetooth LE](https://learn.adafruit.com/circuspython-jump-through-hoops-with-bluetooth-le.md)
- [Bluefruit TFT Gizmo ANCS Notifier for iOS](https://learn.adafruit.com/ancs-gizmo.md)
- [PyLeap Button Controlled NeoPixels for Circuit Playground Bluefruit](https://learn.adafruit.com/pyleap-buttons-neopixels.md)
- [TensorFlow Lite for Circuit Playground Bluefruit Quickstart](https://learn.adafruit.com/tensorflow-lite-for-circuit-playground-bluefruit-quickstart.md)
- [Adafruit Feather RP2040 ThinkInk](https://learn.adafruit.com/adafruit-rp2040-feather-thinkink.md)