zsa

README

ZSA Keymapp API client for Go

https://github.com/zsa/kontroll

Thin Go wrapper client around the Keymapp API for ZSA keyboards. The raw protobuf spec felt a little too less "Go" idomatic for me.

Just threw this together for now so there might be some problems. I.e. untested on MacOS/LINUX!

Dev Requirements

• go
• protoc
• google.golang.org/protobuf/cmd/protoc-gen-go
• google.golang.org/grpc/cmd/protoc-gen-go-grpc

Updating the API

wget https://raw.githubusercontent.com/zsa/kontroll/main/proto/keymapp.proto -o api/keymapp.proto
protoc --go_out=. --go-grpc_out=. --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative api/keymapp.proto

Plans

• maybe create the same wrapper API but for Python?
• configure the client to be non-blocking (i.e. just fire the requests and discard any responses)
• better error messages with more context, maybe actual error objects (and maybe stacktraces)
• ability to configure the client with a logger?
• mappings for actual keyboard keys
  • i.e. const VOYAGER_LEFT_1x1 = 0 to provide the index for the left Voyager half, first row, first key (from the right) - and so on...
  • can only obtain the LED indices for my own Voyager, not Moonlander or ErgoDox, so getting those from other people would be cool

Documentation

Index

• type Client
  • func Connect(path string) (*Client, error)
  • func ConnectDefault() (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) ConnectAnyKeyboard(ctx context.Context) error
  • func (c *Client) ConnectKeyboard(ctx context.Context, keyboard *api.Keyboard) error
  • func (c *Client) ConnectKeyboardIndex(ctx context.Context, id int32) error
  • func (c *Client) DecreaseBrightness(ctx context.Context) error
  • func (c *Client) DisconnectKeyboard(ctx context.Context) error
  • func (c *Client) GetKeyboards(ctx context.Context) (keyboards []*api.Keyboard, err error)
  • func (c *Client) GetStatus(ctx context.Context) (version string, keyboard *api.ConnectedKeyboard, err error)
  • func (c *Client) IncreaseBrightness(ctx context.Context) error
  • func (c *Client) SetLayer(ctx context.Context, layer int32) error
  • func (c *Client) SetRGBAll(ctx context.Context, color color.Color) error
  • func (c *Client) SetRGBLed(ctx context.Context, color color.Color, leds ...int32) error
  • func (c *Client) SetStatusLED(ctx context.Context, led int32, on bool) error
  • func (c *Client) UnsetLayer(ctx context.Context, layer int32) error

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a connection to the ZSA keyboard service.

func Connect

func Connect(path string) (*Client, error)

Connect establishes a connection to the ZSA keyboard service at the specified path or address.

func ConnectDefault

func ConnectDefault() (*Client, error)

ConnectDefault establishes a connection to the ZSA keyboard service using default settings. On Windows, it connects to "localhost:50051", on other platforms, it uses the socket file at "$CONFIG_DIR/.keymapp/keymapp.sock" (as specified by https://github.com/zsa/kontroll?tab=readme-ov-file#prerequisites).

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the ZSA keyboard service.

func (*Client) ConnectAnyKeyboard

func (c *Client) ConnectAnyKeyboard(ctx context.Context) error

ConnectAnyKeyboard attempts to connect to an arbitrary available keyboard.

func (*Client) ConnectKeyboard

func (c *Client) ConnectKeyboard(ctx context.Context, keyboard *api.Keyboard) error

ConnectKeyboard connects to a specific keyboard.

func (*Client) ConnectKeyboardIndex

func (c *Client) ConnectKeyboardIndex(ctx context.Context, id int32) error

ConnectKeyboardIndex connects to a specific keyboard by its index.

func (*Client) DecreaseBrightness

func (c *Client) DecreaseBrightness(ctx context.Context) error

DecreaseBrightness decreases the brightness of the keyboard.

func (*Client) DisconnectKeyboard

func (c *Client) DisconnectKeyboard(ctx context.Context) error

DisconnectKeyboard disconnects from the currently connected keyboard.

func (*Client) GetKeyboards

func (c *Client) GetKeyboards(ctx context.Context) (keyboards []*api.Keyboard, err error)

GetKeyboards retrieves a list of all detected keyboards.

func (*Client) GetStatus

func (c *Client) GetStatus(ctx context.Context) (version string, keyboard *api.ConnectedKeyboard, err error)

GetStatus retrieves the current status of the keyboard service. The returned keyboard might be "nil" in case none is currently connected.

func (*Client) IncreaseBrightness

func (c *Client) IncreaseBrightness(ctx context.Context) error

IncreaseBrightness increases the brightness of the keyboard.

func (*Client) SetLayer

func (c *Client) SetLayer(ctx context.Context, layer int32) error

SetLayer sets the active layer of the connected keyboard.

func (*Client) SetRGBAll

func (c *Client) SetRGBAll(ctx context.Context, color color.Color) error

SetRGBAll sets the color of all LEDs on the keyboard.

func (*Client) SetRGBLed

func (c *Client) SetRGBLed(ctx context.Context, color color.Color, leds ...int32) error

SetRGBLed sets the color of a specific LED on the keyboard. Each additional specified LED tirggers a separate API request. To change all LEDs at once, use "SetRGBAll".

func (*Client) SetStatusLED

func (c *Client) SetStatusLED(ctx context.Context, led int32, on bool) error

SetStatusLED sets the status LED on the keyboard.

func (*Client) UnsetLayer

func (c *Client) UnsetLayer(ctx context.Context, layer int32) error

UnsetLayer unsets a previously set layer.