# BLE HID Keyboard Buttons with CircuitPython ## Overview https://youtu.be/OWXnM8ACC9s 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 shows just one of the many exciting projects you can build with these techniques. You'll create a remote five-key keyboard for sending keystrokes or even full words and sentences to your device, just as if you were using a highly specialized wireless keyboard. Plus, we've added Bluetooth LE bonding support, so once you pair your devices, they'll automatically reconnect whenever you turn on the devices. ![](https://cdn-learn.adafruit.com/assets/assets/000/087/272/medium800/feather_IMG_0392.jpg?1579631886) Primary: ## Parts Featured ### 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) Featured ### STEMMA Wired Tactile Push-Button Pack - 5 Color Pack [STEMMA Wired Tactile Push-Button Pack - 5 Color Pack](https://www.adafruit.com/product/4431) Little clicky switches are standard input "buttons" on electronic projects. These are just like our [Colorful Round Tactile Button Switch Assortment](https://www.adafruit.com/product/1009), but already assembled onto a PCB - they even have a pull-up resistor... In Stock [Buy Now](https://www.adafruit.com/product/4431) [Related Guides to the Product](https://learn.adafruit.com/products/4431/guides) ![STEMMA Wired Tactile Push-Buttons connected to a half sized white breadboard](https://cdn-shop.adafruit.com/640x480/4431-03.jpg) Featured ### Assembled Terminal Block Breakout FeatherWing for all Feathers [Assembled Terminal Block Breakout FeatherWing for all Feathers](https://www.adafruit.com/product/2926) The Terminal Block Breakout FeatherWing kit is like the Golden Eagle of prototyping FeatherWings (eg. majestic, powerful, good-looking). To start, you get a nice prototyping area underneath your Feather, with extra pads for ground, 3.3V and SDA/SCL. Not one to stop there, we expanded the... In Stock [Buy Now](https://www.adafruit.com/product/2926) [Related Guides to the Product](https://learn.adafruit.com/products/2926/guides) ![Angled shot of rectangular terminal block breakout board with green terminal blocks.](https://cdn-shop.adafruit.com/640x480/2926-09.jpg) Featured ### 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) ![Fully Reversible Pink/Purple USB A to micro B Cable](https://cdn-shop.adafruit.com/640x480/4111-02.jpg) Featured ### Snap-action 5-Wire Block Connector (12-24 AWG) - Pack of 3 [Snap-action 5-Wire Block Connector (12-24 AWG) - Pack of 3](https://www.adafruit.com/product/874) These are like the fancy electronics equivalent of the wire nuts electricians use to bind wires together. They are a lot easier to use as well! Each block connector has a metal block inside and five levers that snap open and close to bind stranded/solid-core wire. No screwdrivers required!... In Stock [Buy Now](https://www.adafruit.com/product/874) [Related Guides to the Product](https://learn.adafruit.com/products/874/guides) ![Snap-action 4-Wire Block Connector with four wires installed](https://cdn-shop.adafruit.com/640x480/874-03.jpg) Featured ### Hook-up Wire Spool Set - 22AWG Stranded-Core - 6 x 25ft [Hook-up Wire Spool Set - 22AWG Stranded-Core - 6 x 25ft](https://www.adafruit.com/product/3111) This is a box of **six**  25ft ** ** spools of **stranded-core** wire. These spools of stranded-core wires are easily soldered to and are rated 80C and 300V (UL AWM style 1007). Best used for wiring jigs where there's... In Stock [Buy Now](https://www.adafruit.com/product/3111) [Related Guides to the Product](https://learn.adafruit.com/products/3111/guides) ![Hook-up Wire Spool Set in box with 6 colorful wires coming out](https://cdn-shop.adafruit.com/640x480/3111-02.jpg) # BLE HID Keyboard Buttons with CircuitPython ## Understanding BLE ![](https://cdn-learn.adafruit.com/assets/assets/000/086/706/medium800/leds_512px-BluetoothLogo.svg.png?1578443885) ## 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. ![](https://cdn-learn.adafruit.com/assets/assets/000/086/833/medium800/leds_ble_modes.jpg?1578680670) ## 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 HID Keyboard Buttons with CircuitPython ## CircuitPython for Feather nRF52840 [CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate. The following instructions will show you how to install CircuitPython. If you've already installed CircuitPython but are looking to update it or reinstall it, the same steps work for that as well! ## Set up CircuitPython Quick Start! Follow this quick step-by-step for super-fast Python power :) [Download the latest version of CircuitPython for this board via CircuitPython.org](https://circuitpython.org/board/feather_nrf52840_express/) **Click the link above to download the latest UF2 file.**   Download and save it to your desktop (or wherever is handy). ![circuitpython_nRF52840_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/070/318/medium640/circuitpython_nRF52840_UF2.png?1548963877) Plug your Feather nRF52840 into your computer using a known-good 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 **Reset** button next to the USB connector on your board, and you will see the NeoPixel RGB LED turn green (identified by the arrow in the image). If it turns red, check the USB cable, try another USB port, etc. **Note:** The little red LED next to the USB connector will pulse red. That's ok! If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right! ![circuitpython_FeathernRF52840_Top_Product_Image.jpg](https://cdn-learn.adafruit.com/assets/assets/000/070/319/medium640/circuitpython_FeathernRF52840_Top_Product_Image.jpg?1548963972) You will see a new disk drive appear called **FTHR840BOOT**.       Drag the **adafruit\_circuitpython\_etc.uf2** file to **FTHR840BOOT****.** ![circuitpython_FTHR840BOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/070/320/medium640/circuitpython_FTHR840BOOT.png?1548964488) ![circuitpython_Drag_nRF52840_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/070/321/medium640/circuitpython_Drag_nRF52840_UF2.png?1548964497) The LED will flash. Then, the  **FTHR840BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.   That's it, you're done! :) ![circuitpython_nRF52840_CIRCUITPY.png](https://cdn-learn.adafruit.com/assets/assets/000/070/322/medium640/circuitpython_nRF52840_CIRCUITPY.png?1548964511) # BLE HID Keyboard Buttons with CircuitPython ## BLE Keyboard Buttons https://youtu.be/OWXnM8ACC9s The Adafruit BLE HID library for CircuitPython makes it easy to send keyboard commands and keystrokes wirelessly over Bluetooth LE to mobile devices and BLE equipped computers! This means you can use buttons or switches to remotely send any keystroke, including key modifiers such as 'shift' and 'control', and even words or sentences. ![](https://cdn-learn.adafruit.com/assets/assets/000/087/214/medium800/bluefruit___ble_IMG_0391.jpg?1579581879) To build the BLE keyswitch, we'll use the Feather nRF52840, five wired push-button breakouts, and a screw terminal block breakout FeatherWing. The [push-button breakouts](https://www.adafruit.com/product/4431) used in this project have built-in pull-up resistors. If you do not use these breakouts, you'll need to uncomment statements in the code to turn on internal pull-ups for the buttons. ![](https://cdn-learn.adafruit.com/assets/assets/000/087/008/medium800/bluefruit___ble_f52840_ble_hid02.png?1579221501) These button break-out boards are very convenient -- of course you can use any momentary switch you like. Also, these are designed to be snapped off into separate buttons, and even have mounting holes for attachment, but I decided to keep them connected for this project. Plug the STEMMA wire connectors into each board, and then screw the white wires into these pins **5, 6, 9, 10 & 11** on the Feather terminal breakout board (or on a breadboard or directly to the Feather, if that's how you roll). The button breakout boards each have a ground wire that needs to be tied to the Feather ground. I chose to do so with Wago connectors as shown here, with a sixth length of wire running back to the Feather. I did the same with the red V+ wires, although this is totally optional. This allows you to use the built in pull-up resistors on the board. Lastly, plug the Feather onto the terminal breakout FeatherWing. ![bluefruit___ble_IMG_0395.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/210/medium640/bluefruit___ble_IMG_0395.jpg?1579580967) ![bluefruit___ble_IMG_0396.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/211/medium640/bluefruit___ble_IMG_0396.jpg?1579580976) ![bluefruit___ble_IMG_0394.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/212/medium640/bluefruit___ble_IMG_0394.jpg?1579581832) ![bluefruit___ble_IMG_0393.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/213/medium640/bluefruit___ble_IMG_0393.jpg?1579581847) ![](https://cdn-learn.adafruit.com/assets/assets/000/087/218/medium800/bluefruit___ble_IMG_0392.jpg?1579581893) One possible use for such a keypad is to replicate this "keyset" idea [as explored in this article](https://99percentinvisible.org/episode/of-mice-and-men/). ![](https://cdn-learn.adafruit.com/assets/assets/000/087/209/medium800/bluefruit___ble_10616196_10154835436925223_1491661547919992466_n.jpg?1579579094 A “keyset.” Courtesy of SRI International and the Doug Engelbart Institute from https://99percentinvisible.org/episode/of-mice-and-men/) Next, we'll put CircuitPython on the Feather nRF52840, as well as libraries and code. # BLE HID Keyboard Buttons with CircuitPython ## BLE Keyboard Buttons Libraries and Code Once your Feather nRF52840 is set up with CircuitPython you'll also need to add some libraries. [Follow this page](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries) for info on how to download and add libraries to your Feather. From the library bundle you downloaded in that guide page, transfer the following libraries onto the Feather's **/lib** directory: - **adafruit\_ble** - **adafruit\_bus\_device** - **adafruit\_hid** - **neopixel.mpy** - **simpleio.mpy** ![bluefruit___ble_keyslibs.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/220/medium640/bluefruit___ble_keyslibs.jpg?1579582391) ## Text Editor Adafruit recommends using the Mu editor for using your CircuitPython code with the Feather 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 Feather as **code.py**. For a full list of HID keycodes, [check out these docs](https://docs.circuitpython.org/projects/hid/en/latest/api.html#adafruit-hid-keycode-keycode). Info: https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CPB_Keybutton_BLE/code.py ## Pairing and Bonding One of the more advance 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 Feather. 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! # BLE HID Keyboard Buttons with CircuitPython ## BLE Key Button Usage ## Pair (and Bond) Now you can power up the keyboard button device with a battery (or USB power) and it will begin to advertise. On your mobile device or computer with BLE, pick the device (the first time you connect it may have a generic name such as **CIRCUITPYd133** , later it may have the name Bluefruit Keybutton Control when it reconnects), and agree to the Pairing prompt. (Note, these photos are with a different device, but the process is identical.) The devices will be paired, and automatically bonded so they can auto reconnect later. ![feather_blepad_0374c.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/319/medium640/feather_blepad_0374c.jpg?1579672203) ![feather_blepad_0375c.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/320/medium640/feather_blepad_0375c.jpg?1579672228) ![feather_blepad_0376c.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/321/medium640/feather_blepad_0376c.jpg?1579672237) ![feather_blepad_0377c.jpg](https://cdn-learn.adafruit.com/assets/assets/000/087/322/medium640/feather_blepad_0377c.jpg?1579672255) https://youtu.be/OWXnM8ACC9s Once connected, the keys will act just like any wireless keyboard to send input to your mobile device or computer. Try opening up a text editor and then press the five buttons. In the sample code here's what each button will send: - **button\_1 = BACKSPACE** - **button\_2 = the word "Bluefruit"** - **button\_3 = the letter "L"** - **button\_4 = the letter "e"** - **button\_5 = ENTER** ## Customization You can customize the code so your buttons send other keycodes. [Here's a list of HID keycodes and modifiers](https://circuitpython.readthedocs.io/projects/hid/en/latest/_modules/adafruit_hid/keycode.html) to check out. To customize the keycodes, look at this section of the code: ```python if not button_1.value: # pull up logic means button low when pressed #print("back") # for debug in REPL k.send(Keycode.BACKSPACE) time.sleep(0.1) if not button_2.value: kl.write("Bluefruit") # use keyboard_layout for words time.sleep(0.4) if not button_3.value: k.send(Keycode.SHIFT, Keycode.L) # add shift modifier time.sleep(0.4) if not button_4.value: kl.write("e") time.sleep(0.4) if not button_5.value: k.send(Keycode.ENTER) time.sleep(0.4) ``` ## Guide 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) ### STEMMA Wired Tactile Push-Button Pack - 5 Color Pack [STEMMA Wired Tactile Push-Button Pack - 5 Color Pack](https://www.adafruit.com/product/4431) Little clicky switches are standard input "buttons" on electronic projects. These are just like our [Colorful Round Tactile Button Switch Assortment](https://www.adafruit.com/product/1009), but already assembled onto a PCB - they even have a pull-up resistor... In Stock [Buy Now](https://www.adafruit.com/product/4431) [Related Guides to the Product](https://learn.adafruit.com/products/4431/guides) ### Assembled Terminal Block Breakout FeatherWing for all Feathers [Assembled Terminal Block Breakout FeatherWing for all Feathers](https://www.adafruit.com/product/2926) The Terminal Block Breakout FeatherWing kit is like the Golden Eagle of prototyping FeatherWings (eg. majestic, powerful, good-looking). To start, you get a nice prototyping area underneath your Feather, with extra pads for ground, 3.3V and SDA/SCL. Not one to stop there, we expanded the... In Stock [Buy Now](https://www.adafruit.com/product/2926) [Related Guides to the Product](https://learn.adafruit.com/products/2926/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) ### Snap-action 5-Wire Block Connector (12-24 AWG) - Pack of 3 [Snap-action 5-Wire Block Connector (12-24 AWG) - Pack of 3](https://www.adafruit.com/product/874) These are like the fancy electronics equivalent of the wire nuts electricians use to bind wires together. They are a lot easier to use as well! Each block connector has a metal block inside and five levers that snap open and close to bind stranded/solid-core wire. No screwdrivers required!... In Stock [Buy Now](https://www.adafruit.com/product/874) [Related Guides to the Product](https://learn.adafruit.com/products/874/guides) ### Hook-up Wire Spool Set - 22AWG Stranded-Core - 6 x 25ft [Hook-up Wire Spool Set - 22AWG Stranded-Core - 6 x 25ft](https://www.adafruit.com/product/3111) This is a box of **six**  25ft ** ** spools of **stranded-core** wire. These spools of stranded-core wires are easily soldered to and are rated 80C and 300V (UL AWM style 1007). Best used for wiring jigs where there's... In Stock [Buy Now](https://www.adafruit.com/product/3111) [Related Guides to the Product](https://learn.adafruit.com/products/3111/guides) ## Related Guides - [Introducing the Adafruit nRF52840 Feather](https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather.md) - [MIDI Solenoid Drum Kit](https://learn.adafruit.com/midi-solenoid-drum-kit.md) - [CircuitPython Text Editor On The Go](https://learn.adafruit.com/circuitpython-text-editor-on-the-go.md) - [NeoPixel Infinity Cube](https://learn.adafruit.com/neopixel-infinity-cube.md) - [Square NeoPixel Display with Black LED Acrylic](https://learn.adafruit.com/sqaure-neopixel-display-with-black-led-acrylic.md) - [Darth Faders](https://learn.adafruit.com/darth-faders.md) - [Minecraft GPS Compass](https://learn.adafruit.com/minecraft-gps-compass.md) - [BLE Light Switch with Feather nRF52840 and Crickit](https://learn.adafruit.com/bluetooth-light-switch-with-crickit-and-nrf52840.md) - [Leverless Controller](https://learn.adafruit.com/leverless-controller.md) - [ItsyBitsy ESP32 wFL case](https://learn.adafruit.com/itsybitsy-esp32-wfl-case.md) - [DIY Desktop Calculator with CircuitPython ](https://learn.adafruit.com/diy-rpn-desktop-calculator-with-circuitpython.md) - [A CircuitPython BLE Remote Control On/Off Switch](https://learn.adafruit.com/circuitpython-ble-remote-control-on-off.md) - [Forecast the Weather at Home with a No-Code Barometer ](https://learn.adafruit.com/dps310-analog-barometer.md) - [Servo Boss](https://learn.adafruit.com/servo-boss.md) - [Bluetooth Restroom Key Proximity Tracker](https://learn.adafruit.com/bluetooth-restroom-key-proximity-tracker.md) - [LED Reactive Light-Up Hockey Puck in MakeCode](https://learn.adafruit.com/led-hockey-puck.md)