qmk

README

qmk-go

Go client for VIA-enabled QMK keyboards.

---

Compiling

qmk-go depends on karalabe/hid and is therfore subject to the same compilation restrictions:

Cross compiling to a different platform or architecture entails disabling CGO by default in Go, causing device enumeration hid.Enumerate() to yield no results.

To cross compile a functional version of this library, you'll need to enable CGO during cross compilation via CGO_ENABLED=1 and you'll need to install and set a cross compilation enabled C toolkit via CC=your-cross-gcc.

Example

package main

import (
    "fmt"

    "github.com/ianmclinden/qmk-go"
)

const (
    vendorId  = 0x4b54 // USB VendorID
    productId = 0x2323 // USB ProductID
    serial    = ""     // Optional
)

func main() {
    // Create a new keyboard connection
    client, err := qmk.NewClient(vendorId, productId, serial)
    if err != nil {
        fmt.Errorf(err)
    }

    version, err := client.GetProtocolVersion()
    if (err != nil) {
        fmt.Errorf(err)
    }

    fmt.Printf("Connected to keyboard with VIA version 0x%04x\n", version)
}

License

Because of the license requirements from karalabe/hid this library is licensed under GNU LGPL 2.1 or later on Linux and 3-clause BSD on other platforms.

Documentation

Index

• Constants
• Variables
• type Client
  • func NewClient(vid uint16, pid uint16, serial string) (Client, error)
• type Keyboard
  • func ListKeyboards() ([]Keyboard, error)

Constants

const (
	HidMessageSize = 32
	HidUsagePage   = 0xFF60
	HidUsage       = 0x61
)

HID Usage Page

const (
	GetProtocolVersionId              = 0x01
	GetKeyboardValueId                = 0x02
	SetKeyboardValueId                = 0x03
	DynamicKeymapGetKeycodeId         = 0x04
	DynamicKeymapSetKeycodeId         = 0x05
	DynamicKeymapResetId              = 0x06
	LightingSetValueId                = 0x07
	LightingGetValueId                = 0x08
	LightingSaveId                    = 0x09
	EepromResetId                     = 0x0A
	BootloaderJumpId                  = 0x0B
	DynamicKeymapMacroGetCountId      = 0x0C
	DynamicKeymapMacroGetBufferSizeId = 0x0D
	DynamicKeymapMacroGetBufferId     = 0x0E
	DynamicKeymapMacroSetBufferId     = 0x0F
	DynamicKeymapMacroResetId         = 0x10
	DynamicKeymapGetLayerCountId      = 0x11
	DynamicKeymapGetBufferId          = 0x12
	DynamicKeymapSetBufferId          = 0x13
	UnhandledId                       = 0xFF
)

VIA Command IDs

const (
	UptimeId            = 0x01
	LayoutOptionsId     = 0x02
	SwitchMatrixStateId = 0x03
)

VIA Keyboard Value IDs

const (
	BacklightBrightnessId = 0x09
	BacklightEffectId     = 0x0A

	RgblightBrightnessId  = 0x80
	RgblightEffectId      = 0x81
	RgblightEffectSpeedId = 0x82
	RgblightColorId       = 0x83
)

VIA Lighting Value IDs

const (
	MaxDynamicKeymapBufferSize = 28
)

Dynamic Keymap

const (
	ViaProtocolVersion = 0x0009
)

VIA Protocol This is changed only when the command IDs change, so VIA Configurator can detect compatible firmware.

Variables

var (
	ErrorNoMatchingDevice = errors.New("no matching devices found")
	ErrorVersionMismatch  = errors.New("keyboard does not match this VIA version")
	ErrorBadMessageSize   = errors.New("incorrect QMK Message size")
	ErrorReadWrite        = errors.New("could not read/write to QMK device")
	ErrorUnknownCommand   = errors.New("unknown VIA command")
	ErrorBadBufferSize    = fmt.Errorf("incorrect buffer size (<=%d)", MaxDynamicKeymapBufferSize)
	ErrorMacroNotInBytes  = errors.New("macro was not found in bytes")
	ErrorMacroCopy        = errors.New("could not copy macro into buffer")
)

var (
	ErrorHIDUnsupported   = errors.New("HID API is not supported")
	ErrorNoKeyboardsFound = errors.New("no via-enabled keyboards found")
)

Types

type Client

type Client interface {
	Keyboard() Keyboard

	// id_get_protocol_version
	GetProtocolVersion() (uint16, error)
	// id_get_keyboard_value -> id_uptime (ms)
	GetUptime() (uint32, error)

	// id_get_keyboard_value -> id_layout_options
	GetLayoutOptions() (uint32, error)
	// id_set_keyboard_value -> id_layout_options
	SetLayoutOptions(uint32) error

	// id_get_keyboard_value -> id_switch_matrix_state
	GetSwitchMatrixState() ([]byte, error)

	// id_get_keyboard_value -> default (raw_hid_receive_kb)
	GetRawKeyboardValue(uint8) ([]byte, error)
	// id_set_keyboard_value -> default (raw_hid_receive_kb)
	SetRawKeyboardValue(uint8, []byte) error

	// id_dynamic_keymap_get_keycode
	GetDynamicKeymapKeycode(uint8, uint8, uint8) (keycode.Keycode, error)
	// id_dynamic_keymap_set_keycode
	SetDynamicKeymapKeycode(uint8, uint8, uint8, keycode.Keycode) error
	// id_dynamic_keymap_reset
	ResetDynamicKeymap() error

	// id_lighting_get_value -> id_qmk_backlight_brightness
	GetBacklightBrightness() (backlight.Brightness, error)
	// id_lighting_set_value -> id_qmk_backlight_brightness
	SetBacklightBrightness(backlight.Brightness) error
	// id_lighting_get_value -> id_qmk_backlight_effect
	GetBacklightEffect() (backlight.Effect, error)
	// id_lighting_set_value -> id_qmk_backlight_effect
	SetBacklightEffect(backlight.Effect) error

	// Get RGB light brightness
	GetRgblightBrightness() (rgblight.Brightness, error)
	// Set RGB light brightness
	SetRgblightBrightness(rgblight.Brightness) error
	// Get RGB light color
	GetRgblightColor() (rgblight.Color, error)
	// SetRGB Light color (optionally set brightness from color)
	SetRgblightColor(rgblight.Color, bool) error
	// Get RGB light effect
	GetRgblightEffect() (rgblight.Effect, error)
	// Set RGB light effect
	SetRgblightEffect(rgblight.Effect) error
	// Get RGB light effect speed
	GetRgblightEffectSpeed() (rgblight.Speed, error)
	// Set RGB light effect speed
	SetRgblightEffectSpeed(rgblight.Speed) error

	// Save rgblight and backlight to EEPROM
	SaveLighting() error

	// Get the number of supported macros
	GetDynamicKeymapMacroCount() (uint8, error)
	// Get macro by VIA index (preferred)
	GetDynamicKeymapMacro(uint8) ([]byte, error)
	// Set macro by VIA index (preferred)
	SetDynamicKeymapMacro(uint8, []byte) error
	// Reset the dynamic keymap
	ResetDynamicKeymapMacro() error

	// Get the number of supported keymap layers
	GetDynamicKeymapLayerCount() (uint8, error)
	// Get the number of bytes allocated for dynamic macros
	GetDynamicKeymapMacroBufferSize() (uint16, error)
	// Get dynamic macros by buffer (id_dynamic_keymap_macro_get_buffer)
	GetDynamicKeymapMacroBuffer(uint16, uint8) ([]byte, error)
	// Set dynamic macros by buffer (id_dynamic_keymap_macro_set_buffer)
	SetDynamicKeymapMacroBuffer(uint16, uint8, []byte) error

	// Get multiple keycodes by buffer (id_dynamic_keymap_get_buffer)
	GetDynamicKeymapBuffer(uint16, uint8) ([]byte, error)
	// Set multiple keycodes by buffer (id_dynamic_keymap_set_buffer)
	SetDynamicKeymapBuffer(uint16, uint8, []byte) error

	// Reset EEPROM
	ResetEeprom() error
}

Client to bind and configure QMK Keyboard

func NewClient

func NewClient(vid uint16, pid uint16, serial string) (Client, error)

type Keyboard

type Keyboard = hid.DeviceInfo

func ListKeyboards

func ListKeyboards() ([]Keyboard, error)