Input controller API

The input controller API allows you to give commands to your input controller components for configuring callbacks for events, allowing you to configure input devices to control your machines.

The input controller component supports the following methods:

API

GetControls

Get a list of the Controls that your controller provides.

• Python
• Go

Parameters:

• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• ( List[viam.components.input.input.Control]): : List of controls provided by the Controller.

Example:

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• ([]Control): List of Controls provided by the controller.
• (error): An error, if one occurred.

Example:

For more information, see the Go SDK Docs.

GetEvents

This method returns the current state of the controller as a map of Event Objects, representing the most recent event that has occurred on each available Control.

• Python
• Go
• TypeScript

Parameters:

Returns:

• ( Dict[viam.components.input.input.Control, viam.components.input.input.Event]): : The most recent event for each input.

Example:

For more information, see the Python SDK Docs.

Parameters:

Returns:

• (map[Control]Event): A map mapping the most recent Event for each Control.
• (error): An error, if one occurred.

Example:

For more information, see the Go SDK Docs.

Parameters:

• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise< Event[]>)

Example:

For more information, see the TypeScript SDK Docs.

TriggerEvent

Directly send an Event Object from external code.

Support Notice

This method is currently only supported for input controllers of model webgamepad.

• Python
• Go
• TypeScript

Parameters:

• event ( viam.components.input.input.Event) (required): The event to trigger.
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• event (Event): The Event to trigger on the controller.
• extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

• event ( PlainMessage) (required)
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise)

Example:

For more information, see the TypeScript SDK Docs.

GetGeometries

Get all the geometries associated with the input controller in its current configuration, in the frame of the input controller. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

• Python

Parameters:

Returns:

• ( List[viam.proto.common.Geometry]): : The geometries associated with the Component.

Example:

For more information, see the Python SDK Docs.

RegisterControlCallback

Defines a callback function to execute whenever one of the EventTypes selected occurs on the given Control.

You can only register one callback function per Event for each Control. A second call to register a callback function for a EventType on a Control replaces any function that was already registered.

You can pass a nil function here to “deregister” a callback.

Tip

Registering a callback for the ButtonChange EventType is merely a convenience for filtering. Doing so registers the same callback to both ButtonPress and ButtonRelease, but ButtonChange is not reported in an actual Event Object.

• Python
• Go

Parameters:

• control ( viam.components.input.input.Control) (required): The control to register the function for.
• triggers ( List[viam.components.input.input.EventType]) (required): The events that will trigger the function.
• function ( viam.components.input.input.ControlFunction) (optional): The function to run on specific triggers.
• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• control (Control): The Control to register the function for.
• triggers ([]EventType): The EventTypes that trigger the function.
• ctrlFunc (ControlFunction): The function to run when the specified triggers are invoked.
• extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• (error): An error, if one occurred.

Example:

For more information, see the Go SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

• Go

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• deps (Dependencies): The resource dependencies.
• conf (Config): The resource configuration.

Returns:

• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own input controller and want to add features that have no corresponding built-in API method, you can implement them with DoCommand.

• Python
• Go

Parameters:

• command (Mapping[ str, ValueTypes]) (required): The command to execute.
• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• (Mapping[ str, viam.utils.ValueTypes]): : Result of the executed command.

Raises:

• (NotImplementedError): Raised if the Resource does not support arbitrary commands.

Example:

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• cmd (map[string]interface{}): The command to execute.

Returns:

• (map[string]interface{}): The command response.
• (error): An error, if one occurred.

Example:

For more information, see the Go SDK Docs.

GetResourceName

Get the ResourceName for this input controller.

• Python
• Go
• TypeScript

Parameters:

• name ( str) (required): The name of the Resource.

Returns:

• ( viam.proto.common.ResourceName): : The ResourceName of this Resource.

Example:

For more information, see the Python SDK Docs.

Parameters:

• None.

Returns:

• (Name)

Example:

For more information, see the Go SDK Docs.

Parameters:

• None.

Returns:

• (string): The name of the resource.

Example:

For more information, see the TypeScript SDK Docs.

Close

Safely shut down the resource and prevent further use.

• Python
• Go

Parameters:

• None.

Returns:

• None.

Example:

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

• (error): An error, if one occurred.

Example:

For more information, see the Go SDK Docs.

API types

The input API defines the following types:

Event object

Each Event object represents a singular event from the input device, and has four fields:

1. Time: time.Time the event occurred.
2. Event: EventType indicating the type of event (for example, a specific button press or axis movement).
3. Control: Control indicating which Axis, Button, or Pedal on the controller has been changed.
4. Value: float64 indicating the position of an Axis or the state of a Button on the specified control.

EventType field

A string-like type indicating the specific type of input event, such as a button press or axis movement.

• To select for events of all type when registering callback function with RegisterControlCallback, you can use AllEvents as your EventType.
• The registered function is then called in addition to any other callback functions you’ve registered, every time an Event happens on your controller. This is useful for debugging without interrupting normal controls, or for capturing extra or unknown events.

Registered EventTypes definitions:

• Python
• Go

Copy

See the Python SDK Docs for the most current version of supported EventTypes.

Copy

See the Viam RDK for the most current version of supported EventTypes.

Control field

A string representing the physical input location, like a specific axis or button, of your Controller that the Event Object is coming from.

Registered Control types are defined as follows:

• Python
• Go

Copy

See the Python SDK Docs for the most current version of supported Control types.

Copy

See GitHub for the most current version of supported Control types.

Axis controls

Support Notice

Currently, only Absolute axes are supported.

Relative axes, reporting a relative change in distance, used by devices like mice and trackpads, will be supported in the future.

Analog devices like joysticks and thumbsticks which return to center/neutral on their own use Absolute axis control types.

These controls report a PositionChangeAbs EventType.

Value: A float64 between -1.0 and +1.0.

• 1.0: Maximum position in the positive direction.
• 0.0: Center, neutral position.
• -1.0: Maximum position in the negative direction.

AbsoluteXY axes

If your input controller has an analog stick, this is what the stick’s controls report as.

Alternatively, if your input controller has two analog sticks, this is what the left joystick’s controls report as.

AbsoluteR-XY axes

If your input controller has two analog sticks, this is what the right joystick’s controls report as.

• For Y axes, the positive direction is “nose up,” and indicates pulling back on the joystick.

Hat/D-Pad axes

If your input controller has a directional pad with analog buttons on the pad, this is what those controls report as.

Z axes (analog trigger sticks)

Info

Devices like analog triggers and gas or brake pedals use Absolute axes, but they only report position change in the positive direction. The neutral point of the axes is still 0.0.

Z axes are usually not present on most controller joysticks.

If present, they are typically analog trigger sticks, and unidirectional, scaling only from 0 to 1.0 as they are pulled, as shown above.

AbsoluteZ is reported if there is one trigger stick, and AbsoluteZ (left) and AbsoluteRZ (right) is reported if there are two trigger sticks.

Z axes can be present on flight-style joysticks, reporting yaw, or left/right rotation, as shown below. This is not common.

Button controls

Button Controls report either ButtonPress or ButtonRelease as their EventType.

Value:

• 0: released
• 1: pressed

Action buttons (ABXY)

If your input controller is a gamepad with digital action buttons, this is what the controls for these buttons report as.

Tip

As different systems label the actual buttons differently, we use compass directions for consistency.

• ButtonSouth corresponds to “B” on Nintendo, “A” on XBox, and “X” on Playstation.
• ButtonNorth corresponds to “X” on Nintendo, “Y” on XBox, and “Triangle” on Playstation.

Trigger buttons (bumpers)

If your input controller is a gamepad with digital trigger buttons, this is what the controls for those buttons report as.

Digital buttons for sticks

If your input controller is a gamepad with “clickable” thumbsticks, this is what thumbstick presses report as.

Miscellaneous buttons

Many devices have additional buttons. If your input controller is a gamepad with these common buttons, this is what the controls for those buttons report as.

Usage examples

Control a wheeled base with a Logitech G920 steering wheel controller

The following Python code is an example of controlling a wheeled base with a Logitech G920 steering wheel controller, configured as a gamepad input controller.

Drive a robot with four wheels and a skid steer platform

The following Go code is part of an example of using an input controller to drive a robot with four wheels & a skid steer platform. The motorCtl callback function controls 5 motors: left front & back FL BL, right front & back FL BL, and a winder motor that raises and lowers a front-end like a bulldozer. The event.Control logic is registered as a callback function to determine the case for setting the power of each motor from which button is pressed on the input controller.