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

# 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

# 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.

This guide was first published on Feb 15, 2023. It was last updated on Apr 23, 2024.

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

Text editor powered by tinymce.