octokeyz

README

octokeyz

Package octokeyz provides support for interacting with an octokeyz USB macropad.

For more information, please visit: https://rafaelmartins.com/p/octokeyz

Documentation

Overview

Package octokeyz provides support for interacting with an octokeyz USB macropad.

Index

• Constants
• Variables
• type Button
  • func (b *Button) String() string
  • func (b *Button) WaitForRelease() time.Duration
• type ButtonHandler
• type ButtonHandlerError
  • func (b ButtonHandlerError) Error() string
  • func (b ButtonHandlerError) Unwrap() error
• type ButtonID
  • func (b ButtonID) String() string
• type Device
  • func Enumerate() ([]*Device, error)
  • func GetDevice(serialNumber string) (*Device, error)
  • func (d *Device) AddHandler(button ButtonID, fn ButtonHandler) error
  • func (d *Device) Close() error
  • func (d *Device) DisplayClear() error
  • func (d *Device) DisplayClearLine(line DisplayLine) error
  • func (d *Device) DisplayClearWithDelay(delay time.Duration) error
  • func (d *Device) DisplayLine(line DisplayLine, str string, align DisplayLineAlign) error
  • func (d *Device) GetDisplayCharsPerLine() byte
  • func (d *Device) Led(state LedState) error
  • func (d *Device) Listen(errCh chan error) error
  • func (d *Device) Open() error
  • func (d *Device) SerialNumber() string
• type DisplayLine
• type DisplayLineAlign
• type LedState
• type Modifier
  • func (m *Modifier) Handler(b *Button) error
  • func (m *Modifier) Pressed() bool

Examples

• Device

Constants

const (
	// USB vendor identifier reported by octokeyz
	USBVendorId uint16 = 0x1d50

	// USB product identifier reported by octokeyz
	USBProductId uint16 = 0x6184

	// Major USB version number reported by octokeyz firmware that is supported by this package
	// (this is the interface version, not a USB protocol or product/firmware version)
	USBVersion byte = 0x01

	// USB manufacturer name reported by octokeyz
	USBManufacturer = "rgm.io"

	// USB product name reported by octokeyz
	USBProduct = "octokeyz"
)

Variables

var (
	ErrButtonInvalid                           = errors.New("button is not valid")
	ErrButtonHandlerInvalid                    = errors.New("button handler is not valid")
	ErrDeviceDisplayClearWithDelayNotSupported = errors.New("device firmware does not supports display clear with delay")
	ErrDeviceDisplayNumberOfLinesInvalid       = errors.New("device firmware reported an incompatible number of display lines")
	ErrDeviceDisplayNotSupported               = errors.New("device hardware does not includes a display")
	ErrDeviceEnumerationFailed                 = usbhid.ErrDeviceEnumerationFailed
	ErrDeviceFailedToClose                     = usbhid.ErrDeviceFailedToClose
	ErrDeviceFailedToOpen                      = usbhid.ErrDeviceFailedToOpen
	ErrDeviceFirmwareVersionIncompatible       = errors.New("device firmware version is not compatible")
	ErrDeviceIsClosed                          = usbhid.ErrDeviceIsClosed
	ErrDeviceIsOpen                            = usbhid.ErrDeviceIsOpen
	ErrDeviceLocked                            = usbhid.ErrDeviceLocked
	ErrDeviceMoreThanOne                       = errors.New("more than one device found")
	ErrDeviceNotFound                          = errors.New("device not found")
	ErrGetFeatureReportFailed                  = usbhid.ErrGetFeatureReportFailed
	ErrGetInputReportFailed                    = usbhid.ErrGetInputReportFailed
	ErrReportBufferOverflow                    = usbhid.ErrReportBufferOverflow
	ErrSetFeatureReportFailed                  = usbhid.ErrSetFeatureReportFailed
	ErrSetOutputReportFailed                   = usbhid.ErrSetOutputReportFailed
)

Errors returned from octokeyz package may be tested against these errors with errors.Is.

Types

type Button

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

Button is an opaque structure that represents an octokeyz USB macropad button.

func (*Button) String

func (b *Button) String() string

String returns a string representation of a button

func (*Button) WaitForRelease

func (b *Button) WaitForRelease() time.Duration

WaitForRelease blocks a button handler until the button that was pressed to activated the handler is released. It returns the duration of the button press.

This function should not be called outside a ButtonHandler. It may cause undefined behavior.

type ButtonHandler

type ButtonHandler func(b *Button) error

ButtonHandler is a function prototype that helps defining a callback function to handle button events.

type ButtonHandlerError

type ButtonHandlerError struct {
	ButtonID ButtonID
	Err      error
}

ButtonHandlerError represents the error returned by a button handler including the button identifier.

func (ButtonHandlerError) Error

func (b ButtonHandlerError) Error() string

Error returns a string representation of a button handler error.

func (ButtonHandlerError) Unwrap

func (b ButtonHandlerError) Unwrap() error

Unwrap returns the underlying button handler error.

type ButtonID

type ButtonID uint8

ButtonID represents the identifier of a button.

const (
	BUTTON_1 ButtonID = iota + 1
	BUTTON_2
	BUTTON_3
	BUTTON_4
	BUTTON_5
	BUTTON_6
	BUTTON_7
	BUTTON_8
)

An octokeyz USB macropad contains 8 buttons

func (ButtonID) String

func (b ButtonID) String() string

String returns a string representation of a button identifier

type Device

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

Device is an opaque structure that represents an octokeyz USB macropad device connected to the computer.

Example

package main

import (
	"fmt"
	"log"
	"time"

	"rafaelmartins.com/p/octokeyz"
)

func main() {
	dev, err := octokeyz.GetDevice("")
	if err != nil {
		log.Fatal(err)
	}

	if err := dev.Open(); err != nil {
		log.Fatal(err)
	}
	defer dev.Close()

	for i := 0; i < 3; i++ {
		dev.Led(octokeyz.LedFlash)
		time.Sleep(100 * time.Millisecond)
	}

	dev.AddHandler(octokeyz.BUTTON_1, func(b *octokeyz.Button) error {
		fmt.Println("pressed")
		duration := b.WaitForRelease()
		fmt.Printf("released. pressed for %s\n", duration)
		return nil
	})

	if err := dev.Listen(nil); err != nil {
		log.Fatal(err)
	}
}

func Enumerate

func Enumerate() ([]*Device, error)

Enumerate lists the octokeyz USB macropads connected to the computer.

func GetDevice

func GetDevice(serialNumber string) (*Device, error)

GetDevice returns an octokeyz USB macropad found connected to the machine that matches the provided serial number. If serial number is empty and only one device is connected, this device is returned, otherwise an error is returned.

func (*Device) AddHandler

func (d *Device) AddHandler(button ButtonID, fn ButtonHandler) error

AddHandler registers a ButtonHandler callback to be called whenever the given button is pressed.

func (*Device) Close

func (d *Device) Close() error

Close closes the octokeyz USB macropad.

func (*Device) DisplayClear

func (d *Device) DisplayClear() error

DisplayClear erases the whole display. An error may be returned.

func (*Device) DisplayClearLine

func (d *Device) DisplayClearLine(line DisplayLine) error

DisplayClearLine erases the provided display line. An error may be returned.

func (*Device) DisplayClearWithDelay

func (d *Device) DisplayClearWithDelay(delay time.Duration) error

DisplayClearWithDelay erases the whole display after the provided delay (milliseconds resolution). An error may be returned if the display does not support this feature. If a new line is drawn while the delay is ongoing the display is cleared immediately.

func (*Device) DisplayLine

func (d *Device) DisplayLine(line DisplayLine, str string, align DisplayLineAlign) error

DisplayLine draws the provided string to the provided display line with the provided horizontal alignment. An error may be returned.

func (*Device) GetDisplayCharsPerLine

func (d *Device) GetDisplayCharsPerLine() byte

GetDisplayCharsPerLine returns how many characters can fit in a display line without overflowing.

func (*Device) Led

func (d *Device) Led(state LedState) error

Led sets the state of the octokeyz USB macropad led.

func (*Device) Listen

func (d *Device) Listen(errCh chan error) error

Listen listens to button press events from the macropad and calls ButtonHandler callbacks as required.

errCh is an error channel to receive errors from the button handlers. If set to a nil channel, errors are sent to standard logger. Errors are sent non-blocking.

func (*Device) Open

func (d *Device) Open() error

Open opens the octokeyz USB macropad for usage.

func (*Device) SerialNumber

func (d *Device) SerialNumber() string

SerialNumber returns the serial number of the octokeyz USB macropad.

type DisplayLine

type DisplayLine byte

DisplayLine represents the identifier of a display line number.

const (
	DisplayLine1 DisplayLine = iota + 1
	DisplayLine2
	DisplayLine3
	DisplayLine4
	DisplayLine5
	DisplayLine6
	DisplayLine7
	DisplayLine8
)

An octokeyz USB macropad may contain up to 8 lines

type DisplayLineAlign

type DisplayLineAlign byte

DisplayLine represents the identifier of a display line horizontal alignment.

const (
	DisplayLineAlignLeft DisplayLineAlign = iota + 1
	DisplayLineAlignRight
	DisplayLineAlignCenter
)

A display line may have its content horizontally aligned left, right or center.

type LedState

type LedState byte

LedState represents a state to set the octokeyz USB macropad led to.

const (
	// LedOn sets the led on.
	LedOn LedState = iota + 1

	// LedFlash sets the led to flash on for a short time and go off.
	LedFlash

	// LedSlowBlink sets the led to blink slowly.
	LedSlowBlink

	// LedFastBlink sets the led to blink fastly.
	LedFastBlink

	// LedOff sets the led off.
	LedOff
)

type Modifier

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

Modifier is an opaque structure that represent a modifier button.

Modifier buttons allow the implementation of secondary functions for buttons, by checking if the modifier button is pressed or not in a button handler callback.

func (*Modifier) Handler

func (m *Modifier) Handler(b *Button) error

Handler is a ButtonHandler implementation for a modifier button. It should be added to the button that will be used as modifier.

func (*Modifier) Pressed

func (m *Modifier) Pressed() bool

Pressed returns true if the modifier button is pressed.