input

Documentation

Overview

Package input contains a gRPC based input controller client.

Package input provides human input, such as buttons, switches, knobs, gamepads, joysticks, keyboards, mice, etc. For more information, see the input controller component docs.

Package input contains a gRPC based input controller service server.

Index

• Constants
• Variables
• func Named(name string) resource.Name
• func NamesFromRobot(r robot.Robot) []string
• func NewRPCServiceServer(coll resource.APIResourceCollection[Controller]) interface{}
• type Control
• type ControlFunction
• type Controller
  • func FromDependencies(deps resource.Dependencies, name string) (Controller, error)
  • func FromRobot(r robot.Robot, name string) (Controller, error)
  • func NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, ...) (Controller, error)
• type Event
• type EventType
• type Triggerable

Constants

const SubtypeName = "input_controller"

SubtypeName is a constant that identifies the component resource API string input.

Variables

var API = resource.APINamespaceRDK.WithComponentType(SubtypeName)

API is a variable that identifies the component resource API.

Functions

func Named

func Named(name string) resource.Name

Named is a helper for getting the named input's typed resource name.

func NamesFromRobot

func NamesFromRobot(r robot.Robot) []string

NamesFromRobot is a helper for getting all input controller names from the given Robot.

func NewRPCServiceServer

func NewRPCServiceServer(coll resource.APIResourceCollection[Controller]) interface{}

NewRPCServiceServer constructs an input controller gRPC service server. It is intentionally untyped to prevent use outside of tests.

Types

type Control

type Control string

Control identifies the input (specific Axis or Button) of a controller.

const (
	// Axes.
	AbsoluteX     Control = "AbsoluteX"
	AbsoluteY     Control = "AbsoluteY"
	AbsoluteZ     Control = "AbsoluteZ"
	AbsoluteRX    Control = "AbsoluteRX"
	AbsoluteRY    Control = "AbsoluteRY"
	AbsoluteRZ    Control = "AbsoluteRZ"
	AbsoluteHat0X Control = "AbsoluteHat0X"
	AbsoluteHat0Y Control = "AbsoluteHat0Y"

	// Buttons.
	ButtonSouth  Control = "ButtonSouth"
	ButtonEast   Control = "ButtonEast"
	ButtonWest   Control = "ButtonWest"
	ButtonNorth  Control = "ButtonNorth"
	ButtonLT     Control = "ButtonLT"
	ButtonRT     Control = "ButtonRT"
	ButtonLT2    Control = "ButtonLT2"
	ButtonRT2    Control = "ButtonRT2"
	ButtonLThumb Control = "ButtonLThumb"
	ButtonRThumb Control = "ButtonRThumb"
	ButtonSelect Control = "ButtonSelect"
	ButtonStart  Control = "ButtonStart"
	ButtonMenu   Control = "ButtonMenu"
	ButtonRecord Control = "ButtonRecord"
	ButtonEStop  Control = "ButtonEStop"

	// Pedals.
	AbsolutePedalAccelerator Control = "AbsolutePedalAccelerator"
	AbsolutePedalBrake       Control = "AbsolutePedalBrake"
	AbsolutePedalClutch      Control = "AbsolutePedalClutch"
)

Controls, to be expanded as new input devices are developed.

type ControlFunction

type ControlFunction func(ctx context.Context, ev Event)

ControlFunction is a callback passed to RegisterControlCallback.

type Controller

type Controller interface {
	resource.Resource

	// Controls returns a list of Controls provided by the Controller
	Controls(ctx context.Context, extra map[string]interface{}) ([]Control, error)

	// Events returns most recent Event for each input (which should be the current state)
	Events(ctx context.Context, extra map[string]interface{}) (map[Control]Event, error)

	// RegisterCallback registers a callback that will fire on given EventTypes for a given Control.
	// The callback is called on the same goroutine as the firer and if any long operation is to occur,
	// the callback should start a goroutine.
	RegisterControlCallback(
		ctx context.Context,
		control Control,
		triggers []EventType,
		ctrlFunc ControlFunction,
		extra map[string]interface{},
	) error
}

Controller is a logical "container" more than an actual device. It could be a single gamepad, or a collection of digitalInterrupts and analogReaders, a keyboard, etc. For more information, see the input controller component docs.

Controls example:

myController, err := input.FromRobot(machine, "my_input_controller")

// Get the list of Controls provided by the controller.
controls, err := myController.Controls(context.Background(), nil)

Events example:

myController, err := input.FromRobot(machine, "my_input_controller")

// Get the most recent Event for each Control.
recent_events, err := myController.Events(context.Background(), nil)

RegisterControlCallback example:

// Define a function to handle pressing the Start Menu button, "ButtonStart", on your controller and logging the start time
printStartTime := func(ctx context.Context, event input.Event) {
    logger.Info("Start Menu Button was pressed at this time: %v", event.Time)
}

myController, err := input.FromRobot(machine, "my_input_controller")

// Define the EventType "ButtonPress" to serve as the trigger for printStartTime.
triggers := []input.EventType{input.ButtonPress}

// Get the controller's Controls.
controls, err := myController.Controls(context.Background(), nil)

// If the "ButtonStart" Control is found, trigger printStartTime when on "ButtonStart" the event "ButtonPress" occurs.
if !slices.Contains(controls, input.ButtonStart) {
    logger.Error("button 'ButtonStart' not found; controller may be disconnected")
    return
}

myController.RegisterControlCallback(context.Background(), input.ButtonStart, triggers, printStartTime, nil)

func FromDependencies

func FromDependencies(deps resource.Dependencies, name string) (Controller, error)

FromDependencies is a helper for getting the named input controller from a collection of dependencies.

func FromRobot

func FromRobot(r robot.Robot, name string) (Controller, error)

FromRobot is a helper for getting the named input controller from the given Robot.

func NewClientFromConn

func NewClientFromConn(
	ctx context.Context,
	conn rpc.ClientConn,
	remoteName string,
	name resource.Name,
	logger logging.Logger,
) (Controller, error)

NewClientFromConn constructs a new Client from connection passed in.

type Event

type Event struct {
	Time    time.Time
	Event   EventType
	Control Control // Key or Axis
	Value   float64 // 0 or 1 for buttons, -1.0 to +1.0 for axes
}

Event is passed to the registered ControlFunction or returned by State().

type EventType

type EventType string

EventType represents the type of input event, and is returned by LastEvent() or passed to ControlFunction callbacks.

const (
	// Callbacks registered for this event will be called in ADDITION to other registered event callbacks.
	AllEvents EventType = "AllEvents"
	// Sent at controller initialization, and on reconnects.
	Connect EventType = "Connect"
	// If unplugged, or wireless/network times out.
	Disconnect EventType = "Disconnect"
	// Typical key press.
	ButtonPress EventType = "ButtonPress"
	// Key release.
	ButtonRelease EventType = "ButtonRelease"
	// Key is held down. This will likely be a repeated event.
	ButtonHold EventType = "ButtonHold"
	// Both up and down for convenience during registration, not typically emitted.
	ButtonChange EventType = "ButtonChange"
	// Absolute position is reported via Value, a la joysticks.
	PositionChangeAbs EventType = "PositionChangeAbs"
	// Relative position is reported via Value, a la mice, or simulating axes with up/down buttons.
	PositionChangeRel EventType = "PositionChangeRel"
)

EventType list, to be expanded as new input devices are developed.

type Triggerable

type Triggerable interface {
	// TriggerEvent allows directly sending an Event (such as a button press) from external code
	TriggerEvent(ctx context.Context, event Event, extra map[string]interface{}) error
}

Triggerable is used by the WebGamepad interface to inject events.