If you are new to CircuitPython, we recommend you start with the Welcome to CircuitPython Guide then come back here.
Adafruit recommends installing and using the Mu editor, available for Windows, macOS, and Linux. You can learn about Mu in this guide.
The adafruit_hid Library
Adafruit has developed libraries to easily use CircuitPython devices which have HID capabilities as keyboard devices. There are several functions you may wish to use in your programs, this guide will show them with examples.
On the Circuit Playground Express, this library is built-in! On other CircuitPython boards you may have to install the library by hand, see this guide on how to do that, it's easy and just requires dragging a file onto your board.
The adafruit_circuitplayground Library
Adafruit has developed a library to access much of the functionality on the Circuit Playground Express called adafruit_circuitplayground.
You can use the library by defining from adafruit_circuitplayground.express import cpx at the start of your code. The library has functions for all the sensors, buttons, etc. The examples will use cpx.button_a and cpx.button_b to read the pushbuttons.
Sending Individual Keys
A keyboard typically has well over a hundred keys with various combinations of shift, ctrl, alt, and caps. CircuitPython can send all of these but you need to know what you want to send. The following sends a capital A on Button A and a ctrl X on Button B:
# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode
kbd = Keyboard(usb_hid.devices)
while True:
if cpx.button_a:
kbd.send(Keycode.SHIFT, Keycode.A) # Type capital 'A'
while cpx.button_a: # Wait for button to be released
pass
if cpx.button_b:
kbd.send(Keycode.CONTROL, Keycode.X) # control-X key
while cpx.button_b: # Wait for button to be released
pass
If a button is pushed, kbd.send sends a defined key. Then the while loop waits while the button is still down before checking for a new key to prevent rollover, getting a lot of sent characters for one button press.
For a list of all the keys and codes you can send, see this code.
Send Multimedia Keys
You can also send multimedia keycodes. The adafruit_hid.consumer_control library provides the functionality and the adafruit_hid.consumer_control_code library provides predefined values for multimedia keys.
The keys you can select are defined in this Read The Docs page.
The following program will increment and decrement the volume on a USB controllable multimedia device (such as my Windows 10 PC) using the Circuit Playground Express Buttons A and B. The program will only send one code per press, if the button is held down it only sends one code due to the while statement. The while statement blocks can be removed to simulate press and hold to change volume.
# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.consumer_control import ConsumerControl
from adafruit_hid.consumer_control_code import ConsumerControlCode
cc = ConsumerControl(usb_hid.devices)
while True:
if cpx.button_a:
cc.send(ConsumerControlCode.VOLUME_INCREMENT)
while cpx.button_a:
pass
if cpx.button_b:
cc.send(ConsumerControlCode.VOLUME_DECREMENT)
while cpx.button_b:
pass
Sending Multiple Characters at Once
Here is an example of sending out a string of characters at once:
# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
kbd = Keyboard(usb_hid.devices)
layout = KeyboardLayoutUS(kbd)
while True:
if cpx.button_a:
# Type 'Jane Doe' followed by Enter (a newline).
layout.write('Jane Doe\n')
while cpx.button_a:
pass
Keyboard Layouts
The adafruit_hid library currently only supports the US keyboard layout with layout.write(). However, layouts for keyboards for other languages and regions are available at https://github.com/Neradoc/Circuitpython_Keyboard_Layouts.
Documentation
The online documentation for the Adafruit HID library is available at on readthedocs.
Adafruit has another guide that goes over the functionality of the adafruit_circuitplayground (CPX) library functions.
Going Further
Besides defining your own keyboard, there are some other applications of this technology. Adafruit has another guide which demonstrates using Circuit Playground Express as a keyboard for Android devices. Then, using the Android Google keyboard GBoard, it can convert Morse Code to text. If this interests you, see the guide Android GBoard Morse Code Control with Circuit Playground Express.
