# BLE Volume Knob with CircuitPython
## Overview
https://youtu.be/P3F6PPLCLSc
You can build your own devices that act like remote keyboards and HID devices for nearly any mobile device or computer with Bluetooth LE and the Adafruit HID library in CircuitPython!
Traditionally, the USB HID library has been used to send keyboard and mouse commands over a USB cable to a computer or mobile device. Now, you can cut that wire and do all the same things using BLE wirelessly!
This tutorial will show one of the many exciting projects you can build with these techniques.
You'll build a wireless volume knob that can turn your sound up and down, mute, and press the play/pause button from across the room to control your mobile device or computer sound!
Plus, we've added Bluetooth LE bonding support, so once you pair your devices, they'll automatically reconnect whenever you turn on the devices.
## Parts
### 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)
### Rotary Encoder + Extras
[Rotary Encoder + Extras](https://www.adafruit.com/product/377)
This rotary encoder is the best of the best, it's a high-quality 24-pulse encoder, with detents and a nice feel. It is panel mountable for placement in a box, or you can plug it into a breadboard (just cut/bend the two mechanical side tabs.) We also include a nice soft-touch knob with an...
In Stock
[Buy Now](https://www.adafruit.com/product/377)
[Related Guides to the Product](https://learn.adafruit.com/products/377/guides)
### Small Alligator Clip to Male Jumper Wire Bundle - 6 Pieces
[Small Alligator Clip to Male Jumper Wire Bundle - 6 Pieces](https://www.adafruit.com/product/3448)
When working with unusual non-header-friendly surfaces, these handy cables will be your best friends! No longer will you have long, cumbersome strands of alligator clips. These compact jumper cables have a premium male header on one end and a grippy mini alligator clip on the...
Out of Stock
[Buy Now](https://www.adafruit.com/product/3448)
[Related Guides to the Product](https://learn.adafruit.com/products/3448/guides)
### Half Sized Premium Breadboard - 400 Tie Points
[Half Sized Premium Breadboard - 400 Tie Points](https://www.adafruit.com/product/64)
This is a cute, half-size breadboard with 400 tie points, good for small projects. It's 3.25" x 2.2" / 8.3cm x 5.5cm with a standard double-strip in the middle and two power rails on both sides. You can pull the power rails off easily to make the breadboard as...
In Stock
[Buy Now](https://www.adafruit.com/product/64)
[Related Guides to the Product](https://learn.adafruit.com/products/64/guides)
### Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh](https://www.adafruit.com/product/4237)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/4237)
[Related Guides to the Product](https://learn.adafruit.com/products/4237/guides)
## Optional Parts
If you want to build a more permanent volume knob, you can use a Proto Gizmo and solder down the encoder.
### Circuit Playground Proto Gizmo - Bolt-on Perma-Proto
[Circuit Playground Proto Gizmo - Bolt-on Perma-Proto](https://www.adafruit.com/product/4320)
Extend and expand your Circuit Playground projects with a bolt-on Perma-Proto that lets you connect solderable circuits in a sturdy and reliable fashion. This PCB looks just like a solderless breadboard but has permanently affixed M3 standoffs that act as mechanical and electrical connections....
Out of Stock
[Buy Now](https://www.adafruit.com/product/4320)
[Related Guides to the Product](https://learn.adafruit.com/products/4320/guides)
### Hook-up Wire Spool Set - 22AWG Solid Core - 6 x 25 ft
[Hook-up Wire Spool Set - 22AWG Solid Core - 6 x 25 ft](https://www.adafruit.com/product/1311)
Perfect for bread-boarding, free wiring, etc. This box contains 6 spools of solid-core wire. The wire is easy to solder to and when bent it keeps its shape pretty well. We like to have a few spools of this stuff around which is why this set is quite nice! We suggest picking up wire strippers...
In Stock
[Buy Now](https://www.adafruit.com/product/1311)
[Related Guides to the Product](https://learn.adafruit.com/products/1311/guides)
### Fully Reversible Pink/Purple USB A to micro B Cable - 1m long
[Fully Reversible Pink/Purple USB A to micro B Cable - 1m long](https://www.adafruit.com/product/4111)
This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also fully reversible! That's right, you will save _seconds_ a day by not having to flip the cable around.
First let's talk about the cover and over-molding. We got these...
In Stock
[Buy Now](https://www.adafruit.com/product/4111)
[Related Guides to the Product](https://learn.adafruit.com/products/4111/guides)
# BLE Volume Knob with CircuitPython
## Understanding BLE
## BLE Basics
To understand how we communicate between the MagicLight Bulb and the Circuit Playground Bluefruit (CPB), it's first important to get an overview of how Bluetooth Low Energy (BLE) works in general.
The nRF52840 chip on the CPB uses Bluetooth Low Energy, or BLE. BLE is a wireless communication protocol used by many devices, including mobile devices. You can communicate between your CPB and peripherals such as the Magic Light, mobile devices, and even other CPB boards!
There are a few terms and concepts commonly used in BLE with which you may want to familiarize yourself. This will help you understand what your code is doing when you're using CircuitPython and BLE.
Two major concepts to know about are the two modes of BLE devices:
- Broadcasting mode (also called **GAP** for **G** eneric **A** ccess **P** rofile)
- Connected device mode (also called **GATT** for **G** eneric **ATT** ribute Profile).
**GAP** mode deals with broadcasting peripheral advertisements, such as "_I'm a device named LEDBlue-19592CBC_", as well as advertising information necessary to establish a dedicated device connection if desired. The peripheral may also be advertising available services.
**GATT** mode deals with communications and attribute transfer between two devices once they are connected, such as between a heart monitor and a phone, or between your CPB and the Magic Light.
## Bluetooth LE Terms
### GAP Mode
#### Device Roles:
- **Peripheral** - The low-power device that broadcasts advertisements. Examples of peripherals include: heart rate monitor, smart watch, fitness tracker, iBeacon, and the Magic Light. The CPB can also work as a peripheral.
- **Central** - The host "computer" that observes advertisements being broadcast by the Peripherals. This is often a mobile device such as a phone, tablet, desktop or laptop, but the CPB can also act as a central (which it will in this project).
#### Terms:
- **Advertising** - Information sent by the peripheral before a dedicated connection has been established. **All** nearby Centrals can observe these advertisements. When a peripheral device advertises, it may be transmitting the name of the device, describing its capabilities, and/or some other piece of data. Central can look for advertising peripherals to connect to, and use that information to determine each peripheral's capabilities (or Services offered, more on that below).
### GATT Mode
#### Device Roles:
- **Server -** In connected mode, a device may take on a new role as a **Server** , providing a Service available to clients. It can now send and receive data packets as requested by the Client device to which it now has a connection.
- **Client -** In connected mode, a device may also take on a new role as **Client** that can send requests to one or more of a Server's available Services to send and receive data packets.
Primary:
#### Terms:
- **Profile -** A pre-defined collection of **Services** that a BLE device can provide. For example, the Heart Rate Profile, or the Cycling Sensor (bike computer) Profile. These Profiles are defined by the Bluetooth Special Interest Group (SIG). For devices that don't fit into one of the pre-defined Profiles, the manufacturer creates their own Profile. For example, there is not a "Smart Bulb" profile, so the Magic Light manufacturer has created their own unique one.
- **Service** - A function the Server provides. For example, a heart rate monitor armband may have separate Services for **Device Information** , **Battery Service** , and **Heart Rate** itself. Each Service is comprised of collections of information called **Characteristics**. In the case of the Heart Rate Service, the two Characteristics are **Heart Rate Measurement** and **Body Sensor Location.** The peripheral advertises its services.
- **Characteristic -** A Characteristic is a container for the value, or attribute, of a piece of data along with any associated metadata, such as a human-readable name. A characteristic may be readable, writable, or both. For example, the Heart Rate Measurement Characteristic can be served up to the Client device and will report the heart rate measurement as a number, as well as the unit string "bpm" for beats-per-minute. The Magic Light Server has a Characteristic for the RGB value of the bulb which can be written to by the Central to change the color. Characteristics each have a Universal Unique Identifier (UUID) which is a 16-bit or 128-bit ID.
- **Packet** - Data transmitted by a device. BLE devices and host computers transmit and receive data in small bursts called packets.
[This guide](https://learn.adafruit.com/introduction-to-bluetooth-low-energy/introduction) is another good introduction to the concepts of BLE, including GAP, GATT, Profiles, Services, and Characteristics.
# BLE Volume Knob with CircuitPython
## CircuitPython on Circuit Playground Bluefruit
# Install or Update CircuitPython
Follow this quick step-by-step to install or update CircuitPython on your Circuit Playground Bluefruit.
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/circuitplayground_bluefruit/)
**Click the link above and download the latest UF2 file**
Download and save it to your Desktop (or wherever is handy)
Plug your Circuit Playground Bluefruit into your computer using a known-good data-capable USB cable.
**A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.**
Double-click the small **Reset** button in the middle of the CPB (indicated by the red arrow in the image). The ten NeoPixel LEDs will all turn red, and then will all turn green. If they turn all red and stay red, check the USB cable, try another USB port, etc. The little red LED next to the USB connector will pulse red - this is ok!
If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!
(If double-clicking doesn't do it, try a single-click!)
You will see a new disk drive appear called **CPLAYBTBOOT**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **CPLAYBTBOOT.**
The LEDs will turn red. Then, the **CPLAYBTBOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
# BLE Volume Knob with CircuitPython
## Code the BLE Volume Knob
Once your CPB is set up with CircuitPython, you'll also need to add some libraries. [Follow this page](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit/circuitpython-libraries) for info on how to download and add libraries to your CPB.
From the library bundle you downloaded in that guide page, transfer the following libraries onto the CPB board's **/lib** directory:
- **adafruit\_ble**
- **adafruit\_hid**
- **neopixel**
## Text Editor
Adafruit recommends using the Mu editor for using your CircuitPython code with the Circuit Playground Bluefruit boards. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor).
Alternatively, you can use any text editor that saves files.
## Code.py
Copy the code below and paste it into Mu. Then, save it to your CPB as **code.py**.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CPB_Volume_BLE/code.py
## Code Explainer
Here are the main things our code does:
- Loading libraries for time, digitalio, rotaryio, neopixel, hid consumer control (media buttons), and adafruit BLE
- Advertising that it is a BLE device that can be connected to
- setting up the button A on the CPB and rotary encoder for reading
- lighting up the NeoPixels yellow until there's a connection made
- lighting the NeoPixels cyan, with one brighter NeoPixel to represent relative volume position
- lighting the NeoPixels red when the push encoder is pressed to mute the volume
## Pairing and Bonding
One of the more advanced features used in this project is BLE bonding.
When the Central (your mobile device or computer) connects with the Peripheral (the CPB), you will be asked on the mobile device or computer if you want to **Pair** with the CPB. Once you agree to pair, a **bonding** process takes place.
During bonding, encrypted keys are exchanged between the two devices and saved away for use the next time the devices attempt to connect. Since they are bonded, the two will connect automatically without asking for a pairing confirmation. This is really convenient, because it means you can walk one of the devices out of range, thus dropping the connection, and when you return, the two devices will re-connect as if nothing ever happened!
Now, let's build the volume knob!
## Beyond the Code
Want to try some variations on the code? A user pointed out:
> Maybe this should use the Circuit Playground to simplify accessing the button: https://learn.adafruit.com/circuitpython-made-easy-on-circuit-playground-express/circuit-playground-express-library
>
> Maybe this could use the Debouncing library: https://learn.adafruit.com/debouncer-library-python-circuitpython-buttons-sensors/overview
# BLE Volume Knob with CircuitPython
## Build and Use the BLE Volume Knob
Here we'll build a simple-yet-powerful volume knob using a rotary encoder and Circuit Playground Bluefruit.
## Build on Breadboard
Following the schematic above, plug the rotary encoder into the breadboard, and then connect the alligator clip wires between the encoder pins and the CPB.
The encoder is essentially two components in one -- the three lower pins are for measuring the knob rotational position, while the two upper pins are for the push switch when the knob is pressed down.
This is the wiring connection list:
- Encoder **A** pin to CPB **A3**
- Encoder **GND** to CPB **GND**
- Encoder **B** pin to CPB **A2**
- Switch **ground** to CPB **GND**
- Switch **button** to CPB **A1**
## Pair (and Bond)
Now you can power up the device with a battery (or USB power) and it will begin to advertise and turn the NeoPixel ring yellow.
On your mobile device or computer with BLE, pick the device (the first time you connect it may have a nondescript name, or the name Bluefruit Volume Control as seen here on an iPad), and agree to the Pairing prompt.
The devices will be paired, and automatically bonded so they can auto reconnect later.
## Remote Control
Once connected, the NeoPixel ring will turn cyan. Rotate the knob to raise and lower the volume. Neat huh?! You'll see the bright pixel rotating around along with the knob.
Now, press the push encoder knob down to mute, and the NeoPixels turn red. You can unmute by pressing the button again, or by turning the volume knob.
You can also use the button A on the CPB to toggle Play/Pause.
https://youtu.be/f_LL6eOA4FE
## Fancy Version
If you like, you can build a more permanent version using a Perma-Proto Gizmo.
First, remove the side mounting legs from the encoder using some diagonal cutters. We don't have mounting holes for them, and they aren't part of the circuit, they are just for mechanical stability.
Insert the encoder in the board as shown.
Be sure to remove the twelve amber Kapton stickers from the standoffs, otherwise there won't be an electrical connection to the CPB when we screw them together.
Using short lengths of hookup wire, solder the connections as shown in the schematic drawing below.
You can run all of the wiring on the underside of the Gizmo if you like,for a neater appearance.
Trim all of the excess pin and wire lengths with diagonal side cutters.
## Battery
Place the battery between the two boards, and then screw them together with the provided M3 mounting screws.
Plug in the power, pair the CPB with your mobile device or computer with BLE, and you can use your volume knob in style!
https://youtu.be/P3F6PPLCLSc
## Featured Products
### 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)
### Rotary Encoder + Extras
[Rotary Encoder + Extras](https://www.adafruit.com/product/377)
This rotary encoder is the best of the best, it's a high-quality 24-pulse encoder, with detents and a nice feel. It is panel mountable for placement in a box, or you can plug it into a breadboard (just cut/bend the two mechanical side tabs.) We also include a nice soft-touch knob with an...
In Stock
[Buy Now](https://www.adafruit.com/product/377)
[Related Guides to the Product](https://learn.adafruit.com/products/377/guides)
### Small Alligator Clip to Male Jumper Wire Bundle - 6 Pieces
[Small Alligator Clip to Male Jumper Wire Bundle - 6 Pieces](https://www.adafruit.com/product/3448)
When working with unusual non-header-friendly surfaces, these handy cables will be your best friends! No longer will you have long, cumbersome strands of alligator clips. These compact jumper cables have a premium male header on one end and a grippy mini alligator clip on the...
Out of Stock
[Buy Now](https://www.adafruit.com/product/3448)
[Related Guides to the Product](https://learn.adafruit.com/products/3448/guides)
### Half Sized Premium Breadboard - 400 Tie Points
[Half Sized Premium Breadboard - 400 Tie Points](https://www.adafruit.com/product/64)
This is a cute, half-size breadboard with 400 tie points, good for small projects. It's 3.25" x 2.2" / 8.3cm x 5.5cm with a standard double-strip in the middle and two power rails on both sides. You can pull the power rails off easily to make the breadboard as...
In Stock
[Buy Now](https://www.adafruit.com/product/64)
[Related Guides to the Product](https://learn.adafruit.com/products/64/guides)
### Fully Reversible Pink/Purple USB A to micro B Cable - 1m long
[Fully Reversible Pink/Purple USB A to micro B Cable - 1m long](https://www.adafruit.com/product/4111)
This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also fully reversible! That's right, you will save _seconds_ a day by not having to flip the cable around.
First let's talk about the cover and over-molding. We got these...
In Stock
[Buy Now](https://www.adafruit.com/product/4111)
[Related Guides to the Product](https://learn.adafruit.com/products/4111/guides)
### Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh](https://www.adafruit.com/product/4237)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/4237)
[Related Guides to the Product](https://learn.adafruit.com/products/4237/guides)
### Circuit Playground Proto Gizmo - Bolt-on Perma-Proto
[Circuit Playground Proto Gizmo - Bolt-on Perma-Proto](https://www.adafruit.com/product/4320)
Extend and expand your Circuit Playground projects with a bolt-on Perma-Proto that lets you connect solderable circuits in a sturdy and reliable fashion. This PCB looks just like a solderless breadboard but has permanently affixed M3 standoffs that act as mechanical and electrical connections....
Out of Stock
[Buy Now](https://www.adafruit.com/product/4320)
[Related Guides to the Product](https://learn.adafruit.com/products/4320/guides)
### Hook-up Wire Spool Set - 22AWG Solid Core - 6 x 25 ft
[Hook-up Wire Spool Set - 22AWG Solid Core - 6 x 25 ft](https://www.adafruit.com/product/1311)
Perfect for bread-boarding, free wiring, etc. This box contains 6 spools of solid-core wire. The wire is easy to solder to and when bent it keeps its shape pretty well. We like to have a few spools of this stuff around which is why this set is quite nice! We suggest picking up wire strippers...
In Stock
[Buy Now](https://www.adafruit.com/product/1311)
[Related Guides to the Product](https://learn.adafruit.com/products/1311/guides)
## Related Guides
- [Adafruit Circuit Playground Bluefruit](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit.md)
- [Sound Reactive Sunflower Baby Crib Mobile with Bluetooth Control](https://learn.adafruit.com/sound-reactive-sunflower-baby-crib-mobile-with-bluetooth-control.md)
- [Circuit Playground Express Serial Communications](https://learn.adafruit.com/circuit-playground-express-serial-communications.md)
- [Bluefruit Luminary Lanterns with Capacitive Touch](https://learn.adafruit.com/bluefruit-luminary-lanterns-with-capacitive-touch.md)
- [CLUE Metal Detector in CircuitPython](https://learn.adafruit.com/clue-metal-detector-circuitpython.md)
- [CircuitPython Made Easy on Circuit Playground Express and Bluefruit](https://learn.adafruit.com/circuitpython-made-easy-on-circuit-playground-express.md)
- [Circuit Playground TFT Gizmo Dreidel](https://learn.adafruit.com/circuit-playground-tft-gizmo-dreidel.md)
- [Anatomical 3D Printed Beating Heart with MakeCode](https://learn.adafruit.com/anatomical-3d-printed-beating-heart-with-makecode.md)
- [Bluetooth TV Zapper](https://learn.adafruit.com/bluetooth-tv-zapper.md)
- [Comparison and Experimentation with Flammable Gas Sensors](https://learn.adafruit.com/gas-sensor-comparison.md)
- [Remote Control Candy Dispenser Ghost](https://learn.adafruit.com/ble-claw.md)
- [Grand Central Soundboard in Ten Minutes](https://learn.adafruit.com/grand-central-soundboard-in-ten-minutes.md)
- [Circuit Playground-O-Phonor](https://learn.adafruit.com/circuit-playground-o-phonor.md)
- [Wirelessly Code your Bluetooth Device with CircuitPython](https://learn.adafruit.com/wirelessly-code-your-bluetooth-device-with-circuitpython.md)
- [Wirelessly Program a Circuit Playground Bluefruit Using the File Glider App ](https://learn.adafruit.com/how-to-transfer-files-to-a-circuit-playground-bluefruit-using-the-fileglider-app.md)
- [Sailor Moon Star Locket](https://learn.adafruit.com/sailor-moon-star-locket.md)