Adafruit NeoKey BFF

by Liz Clark

published February 15, 2023, last updated February 15, 2023

posted in

Updated

Beginner

Product guide

Overview

Our QT Py boards are a great way to make very small microcontroller projects that pack a ton of power - and now we have a way for you to quickly add a nice mechanical key that also can glow any color of the rainbow.

We call this the Adafruit NeoKey BFF - a "Best Friend Forever". When you were a kid you may have learned about the "buddy" system, well this product is kinda like that! A board that will watch your QT Py's back and give it more capabilities.

This PCB is designed to fit onto the back of any QT Py or Xiao board; it can be soldered into place or use pin and socket headers to make it removable. Onboard is a Kailh socket, which means you can plug in any MX-compatible switch instead of soldering it in. You may need a little glue to keep the switch in place: hot glue or a dot of epoxy worked fine for us. The board also comes with a single reverse-mount NeoPixel pointing up through the spot where many switches would have an LED to shine through.

We include some header that you can solder to your QT Py. You can also pick up an ItsyBitsy short female header kit to make it removable but compact; you'll just need to trim down the headers to 7 pins long.

The key-switch is default connected to A2 and the NeoPixel to A3 but there are onboard jumpers you can cut to re-configure if you desire.

QT Py is not included.

Please note, each order comes with one assembled PCB and break-off header. A mechanical switch and key cap are not included! Use any MX-compatible switch: Kailh, Gateron, etc all work!

Text editor powered by tinymce.

Pinouts

The default switch pin is A2
The default NeoPixel pin is A3

NeoPixel Jumper

A3 - This jumper is located on the back of the board, below the NeoPixel LED, and is labeled A3. If you cut this jumper, it disconnects the NeoPixel data input pin from pin A3 and you can then connect the NeoPixel to another available pin by soldering a wire.

NeoPixel Pad

Neo - This solder pad is located at the bottom of the board, to the right of the BFF NeoKey silk text and the NeoPixel Jumper. It is labeled Neo. This pad is attached to the NeoPixel data input pin and can be used to wire the NeoPixel to a different pin if the NeoPixel jumper is cut to disconnect it from pin A3.

MX Key Jumper

A2 - This jumper is located on the back of the board, next to the key socket and is labeled A2. If you cut this jumper, it disconnects the switch output from pin A2 and you can then connect the NeoPixel to another available pin by soldering a wire.

MX Key Pad

Sw - This solder pad is located at the bottom of the board between the Sw silk text and BFF NeoKey silk text. It is labeled Sw. This pad is attached to the key output pin and can be used to wire the key to a different pin if the MX key jumper is cut to disconnect it from pin A2.

Text editor powered by tinymce.

CircuitPython

It's easy to use the NeoKey BFF with CircuitPython and the Adafruit_CircuitPython_NeoPixel module. This module allows you to easily write Python code that lets you control NeoPixels. A second example will use the Adafruit_CircuitPython_HID module to let you write Python code to build HID devices, like keyboards.

CircuitPython Microcontroller Wiring

Plug a NeoKey BFF into your QT Py or Xiao form factor board exactly as shown below. Here's an example of connecting a QT Py RP2040 to the BFF.

Connect the QT Py RP2040 with pin headers into the NeoKey BFF with socket headers. They should be plugged in with the backs of the boards facing each other.

For more information on soldering socket headers, check out this Learn Guide.

Then, plug an MX compatible key into the Kailh socket. You can add a keycap for extra flair.

CircuitPython Usage

Connect your QT Py to your computer via a known good USB data+power cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a thumb drive named CIRCUITPY.

To use with CircuitPython, you need to first install the NeoPixel library, and its dependencies, into the lib folder on your CIRCUITPY drive. Then you need to update code.py with the example script.

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 code.py file in a zip file. Extract the contents of the zip file, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.

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

/adafruit_hid
neopixel.mpy

Simple Example

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""Basic IoT Button with NeoPixel BFF Example"""
import time
import board
from digitalio import DigitalInOut, Direction, Pull
from rainbowio import colorwheel
import neopixel

# setup onboard NeoPixel
pixel_pin = board.A3
num_pixels = 1

pixels = neopixel.NeoPixel(pixel_pin, num_pixels, brightness=0.3, auto_write=False)

# setup onboard button
switch = DigitalInOut(board.A2)
switch.direction = Direction.INPUT
switch.pull = Pull.UP

# rainbow cycle function
def rainbow_cycle(wait):
    for j in range(255):
        for i in range(num_pixels):
            rc_index = (i * 256 // num_pixels) + j
            pixels[i] = colorwheel(rc_index & 255)
        pixels.show()
        time.sleep(wait)

while True:
    # run rainbow cycle animation
    rainbow_cycle(0)

    # if the button is not pressed..
    if switch.value:
        # neopixel brightness is zero and appears to be "off"
        pixels.brightness = 0
    # if the button is pressed..
    else:
        # neopixel brightness is 0.3 and rainbow animation is visible
        pixels.brightness = 0.3

# SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""Basic IoT Button with NeoPixel BFF Example"""
import time
import board
from digitalio import DigitalInOut, Direction, Pull
from rainbowio import colorwheel
import neopixel

# setup onboard NeoPixel
pixel_pin = board.A3
num_pixels = 1

pixels = neopixel.NeoPixel(pixel_pin, num_pixels, brightness=0.3, auto_write=False)

# setup onboard button
switch = DigitalInOut(board.A2)
switch.direction = Direction.INPUT
switch.pull = Pull.UP

# rainbow cycle function
def rainbow_cycle(wait):
    for j in range(255):
        for i in range(num_pixels):
            rc_index = (i * 256 // num_pixels) + j
            pixels[i] = colorwheel(rc_index & 255)
        pixels.show()
        time.sleep(wait)

while True:
    # run rainbow cycle animation
    rainbow_cycle(0)

    # if the button is not pressed..
    if switch.value:
        # neopixel brightness is zero and appears to be "off"
        pixels.brightness = 0
    # if the button is pressed..
    else:
        # neopixel brightness is 0.3 and rainbow animation is visible
        pixels.brightness = 0.3

Once everything is saved to the CIRCUITPY drive, you can press and hold the MX key on the BFF to make the rainbow animation show on the NeoPixel. If you release the key, the NeoPixel will stop showing the animation.

One Key Keyboard Example

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""Basic HID Macro with NeoKey BFF Example"""
import time
import board
from digitalio import DigitalInOut, Direction, Pull
import neopixel
import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode

# setup onboard NeoPixel
pixel_pin = board.A3
num_pixels = 1
pixel_color = (0, 255, 0)
off = (0, 0, 0)

pixels = neopixel.NeoPixel(pixel_pin, num_pixels, brightness=0.3, auto_write=False)

# The Keycode sent for each button, will be paired with a control key
key = Keycode.F
modifier_key = Keycode.CONTROL

# The keyboard object!
time.sleep(1)  # Sleep for a bit to avoid a race condition on some systems
keyboard = Keyboard(usb_hid.devices)

# setup onboard button
switch = DigitalInOut(board.A2)
switch.direction = Direction.INPUT
switch.pull = Pull.UP
switch_state = False

while True:

    # if the button is not pressed..
    if switch.value and switch_state:
        pixels.fill(off)
        pixels.show()
        keyboard.release_all()
        switch_state = False

    # if the button is pressed..
    elif not switch.value and not switch_state:
        pixels.fill(pixel_color)
        pixels.show()
        keyboard.press(modifier_key, key)
        switch_state = True

    time.sleep(0.05)

# SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT

"""Basic HID Macro with NeoKey BFF Example"""
import time
import board
from digitalio import DigitalInOut, Direction, Pull
import neopixel
import usb_hid
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode

# setup onboard NeoPixel
pixel_pin = board.A3
num_pixels = 1
pixel_color = (0, 255, 0)
off = (0, 0, 0)

pixels = neopixel.NeoPixel(pixel_pin, num_pixels, brightness=0.3, auto_write=False)

# The Keycode sent for each button, will be paired with a control key
key = Keycode.F
modifier_key = Keycode.CONTROL

# The keyboard object!
time.sleep(1)  # Sleep for a bit to avoid a race condition on some systems
keyboard = Keyboard(usb_hid.devices)

# setup onboard button
switch = DigitalInOut(board.A2)
switch.direction = Direction.INPUT
switch.pull = Pull.UP
switch_state = False

while True:

    # if the button is not pressed..
    if switch.value and switch_state:
        pixels.fill(off)
        pixels.show()
        keyboard.release_all()
        switch_state = False

    # if the button is pressed..
    elif not switch.value and not switch_state:
        pixels.fill(pixel_color)
        pixels.show()
        keyboard.press(modifier_key, key)
        switch_state = True

    time.sleep(0.05)

In this example, the MX key sends the computer shortcut for Find in a browser (Ctrl + F) every time its pressed. You can change the shortcut by editing the key and modifier_key variables. The NeoPixel lights up green every time you press the key. When you release the key, the NeoPixel turns off. You can change the NeoPixel color by updating the pixel_color RGB value.

Text editor powered by tinymce.

Arduino

Using the NeoKey BFF with Arduino involves plugging the breakout into your Arduino-compatible QT Py or Xiao form factor board, installing the Adafruit_NeoPixel library, and running the provided example code.

This code is confirmed to work with a QT Py RP2040. It may not compile as-is with other QT Py or Xiao form factor boards.

Wiring

Plug a NeoKey BFF into your QT Py or Xiao form factor board exactly as shown below. Here's an example of connecting a QT Py RP2040 to the BFF.

Connect the QT Py RP2040 with pin headers into the NeoKey BFF with socket headers. They should be plugged in with the backs of the boards facing each other.

For more information on soldering socket headers, check out this Learn Guide.

Then, plug an MX compatible key into the Kailh socket.

Library Installation

You can install the Adafruit NeoPixel library for Arduino using the Library Manager in the Arduino IDE.

Click the Manage Libraries ... menu item, search for Adafruit NeoPixel and select the Adafruit NeoPixel library:

There are no additional library dependencies for the NeoPixel library.

Example Keyboard Code

Download File

Copy Code

// SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
//
// SPDX-License-Identifier: MIT

// Basic Keyboard Example for NeoKey BFF

#include <Keyboard.h>
#include <Adafruit_NeoPixel.h>

#define LED_PIN A3
#define MX_PIN A2
#define LED_COUNT 1

int mxState = 0;

Adafruit_NeoPixel pixel(LED_COUNT, LED_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  Serial.begin(115200);
  Keyboard.begin();
  delay(5000);
  pinMode(MX_PIN, INPUT);
  pixel.begin();
  pixel.show();            
  pixel.setBrightness(50); 
}

void loop() {
  mxState = digitalRead(MX_PIN);

  if(mxState == HIGH) {      
    pixel.setPixelColor(0, pixel.Color(150, 0, 0));
    pixel.show();
    Keyboard.print("Hello World!");
  }

  if(mxState == LOW) {
    pixel.setPixelColor(0, pixel.Color(0, 0, 0));
    pixel.show();
  }

}

// SPDX-FileCopyrightText: 2023 Liz Clark for Adafruit Industries
//
// SPDX-License-Identifier: MIT

// Basic Keyboard Example for NeoKey BFF

#include <Keyboard.h>
#include <Adafruit_NeoPixel.h>

#define LED_PIN A3
#define MX_PIN A2
#define LED_COUNT 1

int mxState = 0;

Adafruit_NeoPixel pixel(LED_COUNT, LED_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  Serial.begin(115200);
  Keyboard.begin();
  delay(5000);
  pinMode(MX_PIN, INPUT);
  pixel.begin();
  pixel.show();            
  pixel.setBrightness(50); 
}

void loop() {
  mxState = digitalRead(MX_PIN);

  if(mxState == HIGH) {      
    pixel.setPixelColor(0, pixel.Color(150, 0, 0));
    pixel.show();
    Keyboard.print("Hello World!");
  }

  if(mxState == LOW) {
    pixel.setPixelColor(0, pixel.Color(0, 0, 0));
    pixel.show();
  }

}

Upload the sketch to your board. When you press the MX key, the text "Hello World!" will be typed. Additionally, the NeoPixel will light-up red. When the key is released, the NeoPixel will turn off.

Text editor powered by tinymce.