Getting Started

What is PyKey?

PyKey or "PythonKeyboard" is a CircuitPython firmware based on the various examples contained in the Adafruit learning guides available in their GitHub repository and is targeted to be user friendly and be a starting point into the world of CircuitPython and Keyboards.

More advanced users may want to move towards KMK. If you are familiar with QMK, KMK may be more interesting for you.

A number of keyboards created by JPConstantineau (Such as the PyKey60 Keyboard) are also named with the PyKey name but these have additional characters added to indicate the configuration of the keyboard.

Why CircuitPython and not C/C++?

Many Keyboard firmwares are available in C/C++. Take for example TMK, QMK, BlueMicro_BLE, ZMK and many others. They all implement a firmware that combine the low-level hardware scanning as well as the high-level keyboard functionality that users want.

With PyKey, the aim is on keeping it simple and away from the hardware-specific details and focussed on the high level keyboard logic. This therefore makes it more DIY friendly and portable from one platform to another with minimal code chhanges.

With CircuitPython 7.0.0, the most frequently called code in a keyboard firmware (the key scanning and debouncing routines) has been embedded within the core of CircuitPython (in the keypad module) and runs as compiled C++ code. This reduces significantly the amount of Python code that continuously runs waiting for keys to be pressed; thus improving performance. The rest of the keyboard logic, which only runs once keypresses are detected, has more time to run between key scans.

CircuitPython also makes it very simple to customize the keymaps and the keyboard logic without any toolchain and without the need to recompile and flash your keyboard. If you have a text editor and can edit a file saved in a mass storage device, you can make live changes to how your keyboard works.

Getting Started

Get some supported hardware.

Lots of hardware supports CircuitPython. Currently, 242 boards support it. Not all are destined to be keyboards. Keyboards that support one of the breakout boards listed in the CircuitPython Downloads is a good start. There are even macropads in the list.

Here are a few examples in pictures:

PicoFeather840 ItsyBitsy M4
blueMicro840NiceNano Pro micro RP2040
macropadtrelliskeybow

Install CircuitPython on it

Go here and download the latest CircuitPython for your hardware. PyKey uses features included in CircuitPython 7.0.0. You can download the Absolute Newest (automated builds) or the latest 7.0.0 release. Don't download a 6.x release as some of the necessary modules have only been included since 7.0.0.

Download and Install the CircuitPython Libraries

You will need to download the libraries from here. Since there are hundreds of different libraries included in the package, they generally won't fit if you copy them all to your board. As such, you only need to copy the ones that are needed. Typically this is the following:

  • adafruit_hid (folder)
  • neopixel.mpy (file)

Read the basics of CircuitPython

Adafruit has created great documentation on how to start with CircuitPython:

Possible Hardware Components

Input Devices

A number of input devices and methods can be used with CircuitPython:

  • Buttons: Single keys connected between GPIO and GND
  • Key Matrix: Matrix of keys with diodes. Columns and rows are connected to GPIOs: 5x6 keypad
  • Rotary Encoders: A and B connected to GPIOs.
  • Potentiometers: Read an Analog value/position...
  • Nunchuck and other digital input devices
  • Battery Level: Analog read of battery voltage.
  • USB Connection: is it connected to computer through USB?

Output devices

Similarly to input devicecs, CircuitPython supports a vast array of feedback methods to the user:

  • LED: Single LED connected to GPIO
  • PWM LED: A number of LEDs connected to a Mosfet for PWM intensity control.
  • LED Matrix: matrix of LEDs, Columns and Rows are connected to GPIOs
  • RGB LEDs: addressable LEDs. Also known as Neopixels.
  • Speaker: Single speaker connected to a GPIO
  • Displays: Too many types to count...
  • Serial port: useful for debugging...

HID Profiles

Human Interface Devices define multiple interfaces for interacting with computers:

  • Keyboard - standard keycodes
  • Keyboard - consumer
  • Mouse
  • Gamepad

HID Connections

CircuitPython supports both USB and Bluetooth.

Example Code

You can find different examples of code to put in your code.py file in the pykey/examples folder.

If using the examples you may need to add two folders to your board:

  • layers (with whatever layer.py file you wish to choose)
  • pykey (with the contents of the pykey/pykey file in this GitHub