Warning
This is a work in progress. It has been tested to be functional, but please consult sadekbaroudi in the #vik channel of the fingerpunch discord server if you'd like to design a keyboard or module.
Note
To see the list of known supported keyboards and modules, go to this section at the bottom of the readme
Note
Please be aware that for keyboard pcbs, VIK assumes that it's running at 3.3v logic levels. This is easily achieved by using a RP2040. If you are using a 5v controller, it is the keyboard's responsibility to level shift before going to the VIK module. See the Microcontroller selection section below
The licensing for VIK works as follows:
The main LICENSE.md in the git repository root directory applies to the whole repo, except where there is a LICENSE.md in the sub-folder. In that case, that LICENSE.md is then applied recursively until there is another LICENSE.md in any of its subdirectories (if any).
VIK is a standard for a data interface between printed circuit boards. It is intended to provide modularity between a mechanical keyboard pcb and additional features. The main pcb can have a controller and a switch matrix, while the modules can provide additional features.
The standard specifies the following:
- The type of connector
- The signals mapped to each pin on the connector
- The type of cable
- (optional) The size of the module pcb and mounting hole locations
- Inclusion of the VIK logo on the PCB
Note
Adding support for VIK is as simple as adding a symbol and footprint, provided in this repository, followed by some basic wiring. If you want to jump straight to the guide to do this using Kicad, go to Implementation with Kicad
Keyboard with VIK certification using the keyboard footprint
Module with VIK certification using the module footprint
In a community full of talented people doing lots of innovation, we are seeing a plethora of new options for keyboard layout configurations, features, etc. With all this innovation, we're doing very little to share our efforts.
For example, if one person invests in adding support for a trackball with a scroll wheel, others have to identify how to do that, and add support for their keyboard design.
With VIK support, upgrading your features is as simple as getting a new VIK module, and swapping it out.
Let's say you built a keyboard with an integrated trackpad, and you love it. Months after setting it up, you realize that you'd love to have a trackball and haptic feedback. Now you need to design a new pcb (or find someone who has) with the features you'd like. Most people don't know how, or don't want to put forth this effort, so they will settle for their current configuration. With much less effort, you can create a new VIK module, assemble it, and connect to your existing keyboard.
One of the biggest challengs I find, is that a keyboard may have some really excellent features, but I really don't like the key layout. In that case, I won't be interested in the keyboard, despite wanting the features.
Provided that keyboard designers adopt the VIK standard on the main keyboard pcb, the modules are usable on any of those keyboards. So, you can design or find a keyboard that has your preferred layout, and then add the features that you like. True customizability for the exact keyboard you want to use.
There are two things that must be implemented for this to be successful. The keyboard pcb must support the VIK interface, and the module pcb must support the VIK interface
The required connector is a FPC 12 pin 0.5mm pitch connector. It should be available on both the keyboard pcb and the module pcb.
I've received feedback that the recommended part number C479750 for the fpc connector (vik-{keyboard|module}-connector-horizontal) is frequently out of stock. Fortunately, there are many equivalent parts that line up identically to this one.
To find an equivalent, I generally just search for "12p 0.5mm fpc clamshell". Then I pick one that looks identical to C479750. During PCBA part placement, go into 3D mode and adjust the view to make sure the pads line up nicely with the connectors. An example of an alternative part number is C2906115.
The cable should be a 12 pin 0.5mm pitch FPC Type A cable (leads are exposed on the same side).
The specs below state that you must invert the connector pin order between the keyboard and the module, which means Type A is required.
The interface includes the following signals:
- 3.3V
- GND
- SDA
- SCL
- RGB Data Out
- 5V
- Digital/Analog GPIO 1
- MOSI
- Digital/Analog GPIO 2
- SPI CS
- MISO
- SCLK
The order specified above is the order they should be used on the FPC connector on the keyboard side, pins 1 through 12. For the module pcbs, they should be inverted, since the cable will automatically invert the order when connected. If you use the VIK Kicad symbols and footprints, this is managed for you. See the Implementation with Kicad section below
So long as you adhere to the specs above, you can consider your keyboard pcb or module VIK enabled. The last thing you do before publishing or manufacturing your PCB is to include the VIK logo.
There are a collection of logos you can use in the kicad/vik.pretty directory of this repository, all prefixed with vik-logo. For instance, you could take the pre-made kicad footprints and include them on your pcb. If you aren't using kicad, there is a dxf and svg you can use as well.
This is optional, but highly recommended. By adhereing to a standard size and mounting, this will allow others to design keyboard pcbs and/or cases that will support mounting a variety of modules.
There are two specs, a small and large pcb.
All mounting holes should fit M2 screws
Size: less than 25mm by 42mm
Mounting: 2 mounting holes
Size: less than 65mm by 65mm
Mounting: 4 mounting holes
The mounting holes should 44.5mm apart in a square, centered around the center of the pcb. Alternatively, you can place these mounting holes evenly distributed around a 63mm circle, also centered around the center of the pcb.
There are two mounting footprints, found in the vik.pretty footprints folder:
- vik-module-mounting-small
- vik-module-mounting-large
You can use these for one of two purposes:
- When creating a module, use the footprint to ensure that your module pcb has the correct mounting locations
- When creating a keyboard, use the footprint to position where you'd like to mount a module pcb
You can use the Mounting Hole symbol in the schematic, and associate one of the footprints as shown below:
Given Kicad's popularity, I've made it (hopefully) very convenient to implement VIK on the keyboard and module side.
- Clone this repository to your local machine
- Add the VIK symbol library your project
- Add the VIK footprint library to your project
Please note that the path in the screenshots won't be the same as yours. It should be:
{PATH TO CLONE OF THIS REPO}/kicad/vik.kicad_sym
and
{PATH TO CLONE OF THIS REPO}/kicad/vik.pretty
- Add a new symbol in the schematic, and select the
vik-keyboard-connector - Connect all the signals as specified
- Associate with the type of footprint you'd like to use (all of the VIK examples use the horizontal connector footprint). Given you are making a keyboard connector, be sure to use the ones that have the word keyboard in them. See the image below for an example.
- Update your PCB from the schematic and wire it up!
- Add a new symbol in the schematic, and select the
vik-module-connector - Connect all the signals as specified
- Associate with the type of footprint you'd like to use (all of the VIK examples use the horizontal connector footprint). Given you are making a module connector, be sure to use the ones that have the word module in them. See the image below for an example.
- Update your PCB from the schematic and wire it up!
Assuming you already have the VIK symbols and footprints included in your schematic, you will need to wire them according to the specs. Let's walk through each signal, and review how to wire. I'll break this into two parts, one for the keyboard design, and one for the module design.
First and foremost, it's very important that the keyboard have everything set up correctly. Given it's the one supplying the signals to the module, you want to be fully compatible with as many modules as possible.
Here is each signal, and an overview of how to wire it.
3.3V
This one is fairly straight forward in the sense that you just need to supply 3.3v. That said, there are controllers out there that do not include it natively. Please review the Microcontroller selection section below for details.
GND
Connect ground to this pin.
SDA
Microcontrollers usually have more than one set of I2C signals. On dev boards like the Helios or Elite-Pi, it's as simple as wiring the SDA pin to the corresponding SDA pin on the VIK connector.
SCL
This is the exact same as described for SDA, but using SCL instead
RGB Data Out
If you don't have RGB leds on your keyboard, this can be any digital GPIO. Just pick any data signal, and route it to the RGB pin on the VIK connector.
If you are using RGB leds, you'll want to do two things:
- Wire the data out from the last LED to the RGB pin on the VIK connector
- Connect from the controller LED data pin to the VIK connector, but put an open jumper in the middle. The nice thing about this is that it allows the end user to still use the LED feature on a module without necessarily having the LEDs assembled on their keyboard.
5V
Connect 5V to the VIK connector. Be careful not to use VCC on an RP2040 controller, as that is 3.3V. Instead, you can take the RAW output from a controller. On all controllers that I'm aware of as of this writing, it's the top right pin (please double check this before you wire it up).
For example, on the elite-pi:
Digital/Analog GPIO 1
Similar to the RGB Data Out, you can select any pin, but it should support both digital and analog. Below is an example of the Elite-Pi, highlighting its pins that support both.
MOSI
Similar to I2C, SPI has predefined locations on most controllers. If doing an integrated controller, please refer to the datasheet to determine the correct pins.
That said, on dev controllers like the Helios or Elite-Pi, they are standard locations. See the image below. You can wire the 4 SPI pins as shown.
Digital/Analog GPIO 2
Same as Digital/Analog GPIO 1, but this should be a second independent GPIO of the same specifications.
SPI CS
No additional info beyond the MOSI section above. Same course of action, but for the SPI CS signal.
MISO
No additional info beyond the MOSI section above. Same course of action, but for the MISO signal.
SCLK
No additional info beyond the MOSI section above. Same course of action, but for the SCLK signal.
There aren't any major considerations for the schematic for the module. Everything on the connector is an input, so you can choose what to do with them.
That said, please note that using the I2C or SPI pins for anything other than I2C or SPI will break on keyboards that use those signals on the main board. So, please avoid doing so if you care about maximizing compatibility.
For the keyboard side, I created a keyboard called vulpes minora. This keyboard has been manufactured and tested to work with VIK modules.
For the module side, please see the pcb directory in this repository. Each subdirectory within it has a module that you can review to see how these are implemented.
As mentioned above, the responsibility of using pull up resistors is on the VIK modules. This may cause challenges for a few reasons. You may want (or need) to use I2C on the main keyboard PCB, which means you need to use pull up resistors. If this is the case, please provide instructions to inform the users that when using VIK modules, they will need to remove (or not place) the pull up resistor on the keyboard.
When designing a module, please ensure that you include pull up resistors, since the guidelines state that the keyboard pcb is not responsible for it.
If you are designing a keyboard pcb that uses a dev board as a controller (e.g. pro micro, elite-c, stemcell, etc), you should consider that the VIK specs calls for 3.3V and 5V. Given these controllers operate on 5V and don't provide 3.3V, you won't be able to use them for VIK compatibility without additonal circuitry to convert 5V to 3.3V.
As described at the top of the README in the note, the keyboard pcb should run at at 3.3v logic levels. The simplest option is to use a RP2040 based development board. For integrated controllers, either use a controller that already runs at 3.3v logic, or level shift the GPIO before going into the VIK connector.
Some options include:
- Support only RP2040 based controllers (e.g. splinky, elite-pi, helios), where VCC is 3.3V, and the RAW pin provides 5V
- Support other 5V controllers, and use something like an LDO to convert 5V to 3.3V for the VIK 3.3V signal and GPIO signals
- Anything you want, as long as you can provide 5V and 3.3V (both power and 3.3v gpio logic levels)
The vulpes minora is an example of point number 1 above.
In order to be VIK certified, you should be compliant with everything above, and have your keyboard or module reviewed. Upon review, the reviewer will make a card for your pcb, as explained below.
- FPC connector: has the correct FPC connector with the right pinout, and is wired to specificaton. See the connectors in the kicad/vik.pretty directory
- Breakout pins: includes breakout pins using the VIK breakout pin footprint, or has through holes for all the signals. This allows easy access to all the signals. Also, the footprint is compatible with a hand solderable FPC breakout board.
- Supplies: SPI supplies SPI signals, including MISO, MOSI, SCLK, and CS
- Supplies: I2C: supplies I2C, including SDA and SCL
- I2C on main PCB: Does the main PCB use any I2C already. Valid responses are
yesorno. If this is true, theI2C pull upsfield must have a value - I2C pull ups: I2C pull up resistor value, ❌ if no pull ups on the main pcb, or resistor value if present
- Supplies: RGB: supplies RGB data out
- Supplies: Extra GPIO 1: supplies the extra GPIO, response will be one of: (❌ | Digital Only | Analog/Digital)
- Supplies: Extra GPIO 2: supplies the extra GPIO, response will be one of: (❌ | Digital Only | Analog/Digital)
Example of a failing card:
| Category | Classification | Response |
|---|---|---|
| FPC connector | Required | ✔️ |
| Breakout pins | Recommended | ❌ |
| Supplies: SPI | Required | ✔️ |
| Supplies: I2C | Required | ✔️ |
| I2C on main PCB | Discouraged | yes |
| I2C pull ups | Informative | 2.2kΩ |
| Supplies: RGB | Required | ❌ |
| Supplies: Extra GPIO 1 | Required | ❌ |
| Supplies: Extra GPIO 2 | Required | ❌ |
A "perfect" keyboard card would look like this:
| Category | Classification | Response |
|---|---|---|
| FPC connector | Required | ✔️ |
| Breakout pins | Recommended | ✔️ |
| Supplies: SPI | Required | ✔️ |
| Supplies: I2C | Required | ✔️ |
| I2C on main PCB | Discouraged | no |
| I2C pull ups | Informative | N/A |
| Supplies: RGB | Required | ✔️ |
| Supplies: Extra GPIO 1 | Required | Analog/Digital |
| Supplies: Extra GPIO 2 | Required | Analog/Digital |
- FPC connector: has the correct FPC connector with the right pinout, and is wired to specificaton. See the connectors in the kicad/vik.pretty directory
- Breakout pins: includes breakout pins using the VIK breakout pin footprint, or has through holes for all the signals. This allows easy access to all the signals. Also, the footprint is compatible with a hand solderable FPC breakout board.
- Uses: SPI: the module is utilizing SPI
- SPI used for SPI only: if you are using any of the SPI gpio for any purpose other than SPI, this will remain unchecked. This means that keyboard pcbs that use SPI will be incompatible with this module.
- Uses: I2C:
- I2C used for I2C only: if you are using any of the I2C gpio for any purpose other than I2C, this will remain unchecked. This means that keyboard pcbs that use I2C will be incompatible with this module.
- I2C pull ups: I2C pull up resistor value, if applicable. These are only required if I2C is being used on the module.
- Uses: RGB: uses RGB data out
- Uses: Extra GPIO 1: uses the extra GPIO, response will be one of: (❌ | Digital Only | Analog/Digital)
- Uses: Extra GPIO 2: uses the extra GPIO, response will be one of: (❌ | Digital Only | Analog/Digital)
- Standard PCB Size/Mount: adheres to standard module size and mounts, responses will be one of: (❌ | Small | Large)
General example:
| Category | Classification | Response |
|---|---|---|
| FPC connector | Required | ✔️ |
| Breakout pins | Recommended | ❌ |
| Uses: SPI | Optional | ✔️ |
| SPI used for SPI only | Strongly recommended | ✔️ |
| Uses: I2C | Optional | ✔️ |
| I2C used for I2C only | Strongly Recommended | ✔️ |
| I2C pull ups | Required | 4.7kΩ |
| Uses: RGB | Optional | ❌ |
| Uses: Extra GPIO 1 | Optional | ❌ |
| Uses: Extra GPIO 2 | Optional | ❌ |
| Standard PCB Size/Mount | Strongly recommended | Large |
| Name | GPIO (excluding VIK connector) | Status | Open source or Commercial | Creator |
|---|---|---|---|---|
| svlinky | 18 | Complete | Open source | Sadek Baroudi |
| xivik | 11 | In progress | Commercial | Sadek Baroudi |
| Name | Keys | Style | Status | Open source or Commercial | Creator |
|---|---|---|---|---|---|
| vulpes minora | 36 | Split | Complete | Open source | Sadek Baroudi |
| ximi | 36/42 | Split | Complete | Commercial | Sadek Baroudi |
| stront | 38 | Split | Partial support (see stront readme) | Open source | zzeneg |
| Honeydew | 63 | Unibody | Work in progress | Open source | Ariamelon |
| Benboard / Benboard - commercial | 42 | Split | Work in progress | Commercial / Open source | Ben |
| DragonFruit | 38 | Unibody | Complete | Open source | protieusz |
| ZodiarkPi (product) (cert) | 68 | Split | Complete | Commercial | Aleblazer |
| ZodiPact (product) (cert) | 68 | Split | Complete | Commercial | Aleblazer |
| Name | Function | Status | Open source or Commercial | Creator |
|---|---|---|---|---|
| haptic | Pimoroni Haptic Feedback | Complete | Open source | Sadek Baroudi |
| haptic-drv2605l | Haptic Feedback using DRV2605L controller | Complete | Open source | zzeneg |
| per56-cirque-leds | Scroll ring, cirque trackpad, RGB LEDs | Complete | Open source | Sadek Baroudi |
| per56-pmw3360-leds | Scroll ring, trackball, RGB LEDs | Complete | Open source | Sadek Baroudi |
| per56-pmw3360-cirque-leds (Kiwano) | Scroll ring, cirque or trackball, RGB LEDs | Complete | Open source | Ariamelon |
| pmw3360 | Trackball | Complete | Open source | Sadek Baroudi |
| ssd1351 (Crenshaw) | Color display | Complete | Open source | Ariamelon |
| weact-st7735 | WeAct ST7735 1.8" color display adapter | Complete | Open source | Sadek Baroudi |
| gc9a01 | gc9a01 round display breakout adapter | Complete | Open source | Sadek Baroudi |
| waveshare-22224 | waveshare 22224 1.47" display adapter | Complete | Open source | Sadek Baroudi |
| azoteq-tps | Azoteq Proxsense TPS43 and TPS65 | Complete | Open source | Sadek Baroudi |
| trackpoint | Trackpoint 2 piece adapter | Complete | Open source | Sadek Baroudi |
| ec11-evqwgd001 | EC11 and EVQWDG001 with RGB leds | Complete | Open source | Sadek Baroudi |
| joysticks | adafruit 2765, sparkfun 9032, joycon | Untested | Open source | Sadek Baroudi |
| vik-playground | module for prototyping and testing VIK | Untested | Open source | Sadek Baroudi |
| vik-universal | for connecting any through hole board w/VIK | Complete | Open source | Sadek Baroudi |
| ili9341v | Display with capacitive touch and SD card | Complete | Open source | Sadek Baroudi |
| nice!view | nice!view display | Untested | Open source | Sadek Baroudi |
| vik-display-adapter | various display adapters in different sizes | Complete | Open source | zzeneg |
| shift-register-spi-breakout-pcb | dual shift register breakout for extended key matrix | Untested | Open source | Chris Trotter |
| pmw3610 | Trackball (for wireless boards) | Complete | Open source | Sadek Baroudi |
| pmw3610-xs | Trackball (for wireless boards) | Untested | Open source | Sadek Baroudi |
| vikropad | Macropad (18 key) with 2x 5 way switches | Untested | Open source | Sadek Baroudi |
| solenoid-1 | Solenoid module using 3.3v or 5v and 1 gpio | Complete | Open source | Sadek Baroudi |
| solenoid-2 | Solenoid module using 5v and 1 gpio | Complete | Open source | Aleblazer |
