keyboard_pcb/keyplus_mini

keyplus mini beta

Errata rev2

The SS and MO pins are mislabeled. The SS pin should be MO, and the MO pin should be SS.

Wiring

Wiring key matrix

The key matrix should be wired to the ROW and COL pins on the PCB. Wiring of the ROW and COL pins should start from the lowest number pin (i.e. ROW0 and COL0) and work up in consecutive order. The diodes in the key matrix should point from the COL to ROW pins (other scan modes not implemented yet).

The COL15, COL14, COL13, COL12 pins (underlined on the PCB) may also be used as ROW pins. They map to the following row pins:

• ROW6: COL15
• ROW7: COL14
• ROW8: COL13
• ROW9: COL12

Thus it is possible to have up to 120 keys connected using a 10x12 matrix.

Wired split with I2C

To connect to boards with I2C for wired split, connect the 5V, SDA, SCL, and GND pins between devices. You can connect several devices in this manner. They just need to share 5V, SDA, SCL and GND pins.

I would recommend NOT using TRRS connectors for wired split. While connecting and disconnecting the cabel, the contacts inside the TRRS cable can short to one another. Instead, I would recommend using micro USB ports, or another connector that doesn't short it's contacts when it is plugged/unplugged. Then you will be able to take advantage of the wireless/wired hot plugging functionality without worrying about damaging the hardware. You can find male-to-male micro USB cables online with a bit of searching.

Wireless with nRF24L01+

To use wireless mode, you will need a battery and a nRF24L01+ module. The battery should be 3V. Some options for the battery are 1xCR2032, 2xAA/AAA, or 1xAA/AAA with a boost converter. Note the keyplus mini controller does not support any sort of charging of the batteries. When there is no USB connecting the device will run off battery power. When the USB is plugged in, it will automatically switch to run off USB power. To connect the battery connect:

• BAT -> positive battery terminal
• GND -> negative battery terminal

To connect an nRF24L01+ module you will need to connect these pins:

• xmega -> nRF24L01+
• R0 -> CE
• R1 -> IRQ
• MO -> MO / MOSI (Note: rev2 PCB use SS instead)
• MI -> MI / MISO
• SS -> SS / CSN (Note: rev2 PCB use MO instead)
• SCK -> SCK
• GND -> GND
• 3V -> 3.3V

Note: currently the IRQ pin is not used in the code, but I'll add code to take advantage of it soon.

PCB schematic for rev 2

Schematic for keyplus mini

Mechanical information for rev 2

Layout file format and programming

TODO

For prebuilt versions of the loader and firmware.

For the mean time, refer to the example layouts, and the list of available keycodes.

Current firmware limitations

Firmware is still in beta and several features are not completely finished yet. Some prominent ones:

• Macro and hold keycodes can't be used in the layout config file yet.
• No LED support yet (including indicators)
• Pairing Unifying mouse is not exposed to devices yet

Testing key matrix

The firmware supports a mode where it will pass the raw keyboard matrix data to the PC. This can be used to check the row and column pairs in your key matrix. Currently, this can only be used on the command line using a python script keyplus/host-software/keyplus_cli.py.

To use the keyboard matrix passthrough mode, run ./keyplus_cli.py passthrough and you should see output like this:

$$ ./keyplus_cli.py passthrough
r3c5

r3c0

r1c0

r0c1
r0c1 r1c1
r1c1
r1c1 r3c3
r3c3

Where each line shows which keys in the matrix are currently being pressed. Note only devices directly connected by USB will report key presses using passthrough mode.

Unifying flasher

First working version of the Unifying flashing script can be found here. Currently this script has only been tested on Linux.

There are two types of Unifying receivers that use different microcontrollers: nRF24LU1+ and CC2544. Only Unifying receivers that use the nRF24LU1+ are supported.

You can check which kind you have by looking at the firmware version number of the receiver in Logitech's Unifying Software (or Solaar on Linux). If your receiver has a firmware number that starts with 12 (e.g. 012.005.00028), then it uses the nRF24LU1+. If it starts with 24, then it uses the CC2544.

You can find Unifying receivers on aliexpress. I've tried a few different types and they have all used the nRF24LU1+.

How to add dongle to layout file

To be able to use the dongle, you need to add it to your layout file:

devices:
  nrf_dongle:
    id: 7       # unique id that is not used by any of your other devices
    scan_mode: # rf dongle, so don't need a matrix
      mode: no_matrix # options: col_row, pins, no_matrix

Then you need to load the layout file and RF configuration file to the device.

xusb bootloader

The bootloader installed on the ATxmega is the xusb bootloader. To enter bootloader mode press the reset button (or short the RST and GND contacts) once when the USB cable is plugged in. The device will remain in bootloader mode until it is programmed, or until the reset button is pressed a second time. For a more detailed explanation of the bootloader, see here.

The lock bits on the ATxmega have been set to disable reading from flash by an external programmer. This is done to protect the encryption keys that are stored in flash. Also, for security reasons the bootloader will wipe SRAM on power up.

Trouble shooting and known issues

• Make sure that the battery contacts have a firm connection. I've had issues sometimes with my homemade CR2032 holders where vibrations from typing would cause the contacts to be unreliable.
• When using the xmega+nRF24L01+ as the wireless receiver, it will sometimes drop packets due to this issue. Should be fixed soon. The nRF24LU1+ implementation doesn't have this problem.
• If you load broken firmware onto the xmega, it won't be visible to the GUI loader or flashing scripts. In this case you will need to enter it's bootloader manually by shorting the RST pin to GND while it is connected via USB. The bootloader is stored in a protected region of flash, so the bootloader should be unbrickable.
• Currently if you have multiple devices acting as wireless receivers at the same time, they will interfere with each other. This will be fixed later.