search

WootingKb / wooting-analog-sdk

Native support for Analog Keyboards #WootDev
Mozilla Public License 2.0
131 stars 19 forks source link

readme

Build Status wooting-analog-common Crates.io wooting-analog-plugin-dev Crates.io Documentation

Wooting Analog SDK

The Wooting Analog SDK is the open driver for Analog keyboards. It's goal is to create native support for Analog keyboards in any game or application. The repository is mostly aimed at developers looking to implement the Analog SDK or for users looking to dig a little deeper. If you want to use the Analog SDK just jump to the installing section. On Windows it will automatically get installed with the Wootility.

This repo contains all the core cross-platform components of the Wooting Analog SDK. The SDK and most of the components are built on Rust and should run on Windows, Mac and Linux, following the same steps for each platform unless otherwise specified.

Installing

Windows

On Windows the SDK & Wooting Plugin will be installed & updated automatically through Wootility (>= v3.4). If you wish to install manually, download the latest .msi from the latest release

Linux

Ubuntu / Debian / Pop!_OS etc

On Linux the primarily installation method is the deb package, which includes both the SDK and the Wooting Plugin, which can be found on the latest release.

Here is some helpful information for installing a deb package manually. For all (terminal instructions) and Ubuntu (GUI instructions)

Manual

Mac

Homebrew (Recommended)

We now have a Homebrew package available to install the sdk and our plugin from our own tap.

  1. Install Homebrew from their website
  2. Open the terminal and enter the command below:
brew install wootingkb/wooting/wooting-analog-sdk

Manual

Plugins

This SDK uses Plugins to provide support for Analog hardware, these must be located in a subdirectory of WootingAnalogPlugins. Which can be found in these places on each platform:

OS Plugins Directory
Windows C:\Program Files\WootingAnalogPlugins\
Linux /usr/local/share/WootingAnalogPlugins/
Mac /usr/local/share/WootingAnalogPlugins/

So an example path on Windows would be:

C:\Program Files\WootingAnalogPlugins\wooting-analog-plugin\wooting_analog_plugin.dll

Documentation

The core documentation can be found in SDK usage for a guide on how to use the SDK and the Plugin introduction for information on creating plugins.

Virtual Keyboard

The SDK includes a 'Virtual Keyboard' app which will emulate an Analog Keyboard and allows you to test with the Analog SDK without needing a keyboard. To use this, ensure you have the wooting-analog-test-plugin installed, on windows the installer allows you to choose if you want to install the feature. On Linux it is currently installed automatically with the deb package. If you wish to install it otherwise, you can find it in the .tar.gz for your platform from the latest release under $extract/wrapper/sdk/{lib}wooting_analog_test_plugin.{dll/so/dylib}, install it as discussed above in the Plugins section

You can get the virtual keyboard by downloading the .tar.gz archive for your platfrom from the latest release and find the wrapper/sdk/wooting-analog-virtual-control executable.

Components

Headers

Building

Build Dependencies

How to Build

Everything can be built using this command. All the outputs will be under target/debug

# Build debug
cargo make build
# Build & run tests (To verify headers you'll need the nightly toolchain installed)
cargo make

Cleanup:

cargo make clean

To test:

cargo make test-flow

The current build process is setup to verify the existing generated headers in the test phase. If you decide to make changes which effect these outputs, you can update the headers by running:

cargo make gen-headers

To run the test application:

cargo make test-app

To run the virtual keyboard (The Analog SDK must be running for this to work):

cargo make virtual-kb

Build & install the Analog SDK & plugins:

cargo make install

To build the windows installer for the SDK:

cd wooting-analog-sdk
cargo make win-installer

The installer will be located in $gitroot/target/wix

To build the deb package for the SDK:

cargo make build-deb

The deb package will be located in $gitroot/target/debian

Outputs

All build outputs can be found under target/debug, with generated headers coming under the includes and includes-cpp directories.

Currently the headers have to be manually generated and kept in the repo. When intentional changes are made, the testing phase verifies that the pre-generated headers match what would be generated now to ensure that accidental changes aren't made to the output of the header generation.

Contributing Note

The headers generated for the wrapper, common and plugin-dev crates are verified in the CI to ensure that the current headers are up to date and that we can review any changes which are made to the headers (rather than purely generating them and potentially not knowing exactly what has changed). Before commiting (if you've made changes to any of the previously mentioned crates) you should run cargo make verify-headers to ensure that your headers are up to date, if this fails due to them being different, run cargo make gen-headers and review the changes to the headers before commiting.

Related Repositories