Keyplus aims to be an easy to use keyboard firmware with support for wireless and wired split keyboards.

Currently in beta so lots of stuff still might change.

Stable releases (recommended)

Latest builds on Keyplus CI

Just download the EXE file.

Clone the repository:

git clone https://github.com/ahtn/keyplus
git checkout v0.3.0

Next, install the packages avr-gcc, avr-libc, avr-binutils, python3, make, hidapi, and python3-pyside.

Then, install the python dependencies:

pip install -U --user keyplus

Also, you need to initialize the git submodules:

cd keyplus
git submodule update --init --recursive

Now, you can run the program:

cd host-software
sudo python3 keyplus_flasher.py

To connect USB devices on Linux without using sudo, you need to add the appropriate udev rules to set their permissions. To do this run the following commands from the keyplus directory:

sudo cp host-software/etc/udev/rules.d/50-keyplus.rules /etc/udev/rules.d/50-keyplus.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

You also will need to unplug and reconnect the USB device you want to use.

When starting with a new keyplus mini board, flash the latest firmware, configure the device and RF, and configure the layout, in that order.

Download the latest firmware from the releases page. In the drop down box at the top of the window, select "Firmware Update". Then, click the "Browse" button and select the firmware file you downloaded. Plug in your keyplus mini (or other compatible board), and you should see it appear in the bottom box.

Click the "Program" button, and it should flash the firmware onto the board. If it gives an error, try again.

In the drop down box at the top of the window, select "Device and RF". Then, click "Generate new RF settings", and save the file somewhere. Click the "Browse" button next to the "Layout settings file" box, and select your layout YAML file. Input your device ID, and click the program button that is next to the board you want to program. If it doesn't work, try again.

To make the layout file, see here.

In the drop down box at the top of the window, select "Layout". Click the "Browse" button next to the "Layout settings file" box, and select your layout YAML file. Click the program button that is next to the board you want to program. If it doesn't work, try again.

TODO

Currently building of the firmware has been tested on Linux.

To compile the code on Linux, you will need the following programs installed: avr-gcc, avr-libc, avr-binutils, python3, make, and hidapi. On Arch Linux:

sudo pacman -S avr-gcc avr-libc avr-binutils python3 make hidapi python-pyside

Make sure that you have a relatively recent version of avr-gcc. Some older versions do not have support for xmega chips (e.g. avr-gcc included in Ubuntu 14.04). If the build commands fail with an error like warning "device type not defined", then you probably need a newer version of avr-gcc and avr-libc.

The build scripts need some python libraries installed. You should get all the necessary packages if you install the keyplus python library with:

pip install --user -U keyplus

Also, you need to initialize the git submodules:

git submodule update --init --recursive

From the xmega directory, run:

make BOARD=keyplus_mini

You can provide the build system with layout files and it will preload them into the generated hex file:

make BOARD=keyplus_mini RF_FILE=rf.yaml LAYOUT_FILE=layout.yaml ID=0

You should then be able to program the board using the bootloader using:

make BOARD=keyplus_mini program-boot

If you have a board that you made yourself, then you will need to flash the bootloader before you can use the program-boot command. To do this, you will first need to build and flash the bootloader.

To build the bootloader, first enter the xmega/xusb-boot/ directory, and run:

make BOARD=keyplus_mini

To program the bootloader, you will need a PDI programmer. Based on which programmer you are using you will need to change the AVRDUDE_CMD variable in the Makefile. The default is set for AVRISP MkII, so if you are using this programmer, you don't need to change anything.

Then once the programmer is configured and connected to the board correctly, you should be able to run:

make program-fuses
make BOARD=keyplus_mini program-hard
make program-lock

There are several different versions of xmega microcontrollers, with different flash and package sizes. The build system assumes that you are using an ATxmega32a4u by default. If you are not using this chip, then you will need to tell the build system which one you are using by setting the MCU variable. For example, to build the bootloader or firmware for the ATxmega64a4u you would need to call the make like this:

make MCU=atxmega64a4u BOARD=keyplus_mini

You will also need to set the MCU variable when calling the programming commands.

For more information about layout file format see here.

For more information about the hardware see this link.

The keyplus source code is released under the MIT software.

Although the code in this project can be used with Logitech products it is in no way endorsed by or affiliated with Logitech.