joystick

README

Joystick

You can use Gobot with any USB joystick or game controller that is compatible with Simple DirectMedia Layer.

Current configurations included:

• Dualshock3 game controller
• Dualshock4 game controller
• Thrustmaster T-Flight Hotas X Joystick
• XBox360 game controller
• XBox360 "Rock Band" drum controller

How to Install

This package requires sdl2 to be installed on your system

macOS

To install sdl2 on macOS using Homebrew:

$ brew install sdl2

To use an XBox360 controller on macOS, you will most likely need to install additional software such as https://github.com/360Controller/360Controller.

Linux (Ubuntu and Raspbian)

You must be running a Linux kernel that is v4.14+ in order for the various controller mappings to work as expected.

Then you must install the latest SDL2 v2.0.8 or greater:

wget https://www.libsdl.org/release/SDL2-2.0.8.tar.gz
tar -zxvf SDL2-2.0.8.tar.gz
cd SDL2-2.0.8/
./configure && make && sudo make install

Now you can install the package with

go get -d -u gobot.io/x/gobot/...

How to Use

Controller configurations are stored in Gobot it, but you can also use external file in JSON format. Take a look at the configs directory for examples.

How to Connect

Plug your USB joystick or game controller into your USB port. If your device is supported by SDL, you are now ready.

For the Dualshock4, you must pair the device with your computers Bluetooth interface first, before running your Gobot program.

Examples

This small program receives joystick and button press events from an PlayStation 3 game controller.

package main

import (
	"fmt"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/platforms/joystick"
)

func main() {
	joystickAdaptor := joystick.NewAdaptor()
	stick := joystick.NewDriver(joystickAdaptor, "dualshock3",
	)

	work := func() {
		// buttons
		stick.On(joystick.SquarePress, func(data interface{}) {
			fmt.Println("square_press")
		})
		stick.On(joystick.SquareRelease, func(data interface{}) {
			fmt.Println("square_release")
		})
		stick.On(joystick.TrianglePress, func(data interface{}) {
			fmt.Println("triangle_press")
		})
		stick.On(joystick.TriangleRelease, func(data interface{}) {
			fmt.Println("triangle_release")
		})
		stick.On(joystick.CirclePress, func(data interface{}) {
			fmt.Println("circle_press")
		})
		stick.On(joystick.CircleRelease, func(data interface{}) {
			fmt.Println("circle_release")
		})
		stick.On(joystick.XPress, func(data interface{}) {
			fmt.Println("x_press")
		})
		stick.On(joystick.XRelease, func(data interface{}) {
			fmt.Println("x_release")
		})
		stick.On(joystick.StartPress, func(data interface{}) {
			fmt.Println("start_press")
		})
		stick.On(joystick.StartRelease, func(data interface{}) {
			fmt.Println("start_release")
		})
		stick.On(joystick.SelectPress, func(data interface{}) {
			fmt.Println("select_press")
		})
		stick.On(joystick.SelectRelease, func(data interface{}) {
			fmt.Println("select_release")
		})

		// joysticks
		stick.On(joystick.LeftX, func(data interface{}) {
			fmt.Println("left_x", data)
		})
		stick.On(joystick.LeftY, func(data interface{}) {
			fmt.Println("left_y", data)
		})
		stick.On(joystick.RightX, func(data interface{}) {
			fmt.Println("right_x", data)
		})
		stick.On(joystick.RightY, func(data interface{}) {
			fmt.Println("right_y", data)
		})

		// triggers
		stick.On(joystick.R1Press, func(data interface{}) {
			fmt.Println("R1Press", data)
		})
		stick.On(joystick.R2Press, func(data interface{}) {
			fmt.Println("R2Press", data)
		})
		stick.On(joystick.L1Press, func(data interface{}) {
			fmt.Println("L1Press", data)
		})
		stick.On(joystick.L2Press, func(data interface{}) {
			fmt.Println("L2Press", data)
		})
	}

	robot := gobot.NewRobot("joystickBot",
		[]gobot.Connection{joystickAdaptor},
		[]gobot.Device{stick},
		work,
	)

	robot.Start()
}

How to Add A New Joystick

In the bin directory for this package is a CLI utility program that scans for SDL joystick events, and displays the ID and value:

$ go run ./platforms/joystick/bin/scanner.go 
Joystick 0 connected
[6625 ms] Axis: 1       value:-22686
[6641 ms] Axis: 1       value:-32768
[6836 ms] Axis: 1       value:-18317
[6852 ms] Axis: 1       value:0
[8663 ms] Axis: 3       value:-32768
[8873 ms] Axis: 3       value:0
[10183 ms] Axis: 0      value:-24703
[10183 ms] Axis: 0      value:-32768
[10313 ms] Axis: 1      value:-3193
[10329 ms] Axis: 1      value:0
[10345 ms] Axis: 0      value:0

You can use the output from this program to create a JSON file for the various buttons and axes on your joystick/gamepad. You could also create a file similar to joystick_dualshock3.go and submit a pull request with the new configuration so others can use it as well.

Documentation

Overview

Package joystick provides the Gobot adaptor and drivers for game controllers that are compatible with SDL.

Installing:

This package requires `sdl2` to be installed on your system Then install package with:

go get gobot.io/x/gobot/platforms/joystick

Example:

package main

import (
	"fmt"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/platforms/joystick"
)

func main() {
	joystickAdaptor := joystick.NewAdaptor()
	joystick := joystick.NewDriver(joystickAdaptor,
		"./platforms/joystick/configs/dualshock3.json",
	)

	work := func() {
		joystick.On(joystick.Event("square_press"), func(data interface{}) {
			fmt.Println("square_press")
		})
		joystick.On(joystick.Event("square_release"), func(data interface{}) {
			fmt.Println("square_release")
		})
		joystick.On(joystick.Event("triangle_press"), func(data interface{}) {
			fmt.Println("triangle_press")
		})
		joystick.On(joystick.Event("triangle_release"), func(data interface{}) {
			fmt.Println("triangle_release")
		})
		joystick.On(joystick.Event("left_x"), func(data interface{}) {
			fmt.Println("left_x", data)
		})
		joystick.On(joystick.Event("left_y"), func(data interface{}) {
			fmt.Println("left_y", data)
		})
		joystick.On(joystick.Event("right_x"), func(data interface{}) {
			fmt.Println("right_x", data)
		})
		joystick.On(joystick.Event("right_y"), func(data interface{}) {
			fmt.Println("right_y", data)
		})
	}

	robot := gobot.NewRobot("joystickBot",
		[]gobot.Connection{joystickAdaptor},
		[]gobot.Device{joystick},
		work,
	)

	robot.Start()
}

For further information refer to joystick README: https://github.com/hybridgroup/gobot/blob/master/platforms/joystick/README.md

Index

• Constants
• type Adaptor
  • func NewAdaptor() *Adaptor
  • func (j *Adaptor) Connect() (err error)
  • func (j *Adaptor) Finalize() (err error)
  • func (j *Adaptor) Name() string
  • func (j *Adaptor) SetName(n string)
• type Driver
  • func NewDriver(a *Adaptor, config string, v ...time.Duration) *Driver
  • func (j *Driver) Connection() gobot.Connection
  • func (j *Driver) Halt() (err error)
  • func (j *Driver) Name() string
  • func (j *Driver) SetName(n string)
  • func (j *Driver) Start() (err error)

Constants

const (
	// left X joystick event
	LeftX = "left_x"
	// left Y joystick event
	LeftY = "left_y"
	// right X joystick event
	RightX = "right_x"
	// right Y joystick event
	RightY = "right_y"
	// L1 button joystick event
	L1 = "l1"
	// L1 button press event
	L1Press = "l1_press"
	// L1 button release event
	L1Release = "l1_release"
	// L2 joystick event
	L2 = "l2"
	// L2 button press event
	L2Press = "l2_press"
	// L2 button release event
	L2Release = "l2_release"
	// L3 button press event
	L3Press = "l3_press"
	// L3 button release event
	L3Release = "l3_release"
	// R1 button joystick event
	R1 = "r1"
	// R1 button press event
	R1Press = "r1_press"
	// R1 button release event
	R1Release = "r1_release"
	// R2 joystick event
	R2 = "r2"
	// R2 button press event
	R2Press = "r2_press"
	// R1 button release event
	R2Release = "r2_release"
	// R3 button press event
	R3Press = "r3_press"
	// R1 button release event
	R3Release = "r3_release"
	// up gamepad press event
	UpPress = "up_press"
	// up gamepad release event
	UpRelease = "up_release"
	// down gamepad press event
	DownPress = "down_press"
	// down gamepad release event
	DownRelease = "down_release"
	// left gamepad press event
	LeftPress = "left_press"
	// left gamepad release event
	LeftRelease = "left_release"
	// right gamepad press event
	RightPress = "right_press"
	// right gamepad release event
	RightRelease = "right_release"
	// square button press event
	SquarePress = "square_press"
	// square button release event
	SquareRelease = "square_release"
	// circle button press event
	CirclePress = "circle_press"
	// circle button release event
	CircleRelease = "circle_release"
	// triangle button press event
	TrianglePress = "triangle_press"
	// triangle button release event
	TriangleRelease = "triangle_release"
	// X button press event
	XPress = "x_press"
	// X button release event
	XRelease = "x_release"
	// share button press event
	SharePress = "share_press"
	// share button relase event
	ShareRelease = "share_release"
	// options button press event
	OptionsPress = "options_press"
	// options button release event
	OptionsRelease = "options_release"
	// home button press event
	HomePress = "home_press"
	// home button release event
	HomeRelease = "home_release"
	// start button press event
	StartPress = "start_press"
	// start button release event
	StartRelease = "start_release"
	// select button press event
	SelectPress = "select_press"
	// select button release event
	SelectRelease = "select_release"
	// rt button press event
	RTPress = "rt_press"
	// rt button release event
	RTRelease = "rt_release"
	// lt button press event
	LTPress = "lt_press"
	// lt button release event
	LTRelease = "lt_release"
	// Y button press event
	YPress = "y_press"
	// Y button release event
	YRelease = "y_release"
	// A button press event
	APress = "a_press"
	// A button release event
	ARelease = "a_release"
	// B button press event
	BPress = "b_press"
	// B button release event
	BRelease = "b_release"
	// rb button press event
	RBPress = "rb_press"
	// rb button release event
	RBRelease = "rb_release"
	// lb button press event
	LBPress = "lb_press"
	// lb button release event
	LBRelease = "lb_release"
	// back button press event
	BackPress = "back_press"
	// back button release event
	BackRelease = "back_release"
	// red pad press event
	RedPress = "red_press"
	// red pad release event
	RedRelease = "red_release"
	// yellow pad press event
	YellowPress = "yellow_press"
	// yellow pad release event
	YellowRelease = "yellow_release"
	// blue pad press event
	BluePress = "blue_press"
	// blue pad release event
	BlueRelease = "blue_release"
	// green pad press event
	GreenPress = "green_press"
	// green pad release event
	GreenRelease = "green_release"
	// pedal press event
	PedalPress = "pedal_press"
	// pedal release event
	PedalRelease = "pedal_release"
)

const (
	// Dualshock3 joystick configuration.
	Dualshock3 = "dualshock3"

	// Dualshock4 joystick configuration.
	Dualshock4 = "dualshock4"

	// TFlightHotasX flight stick configuration.
	TFlightHotasX = "tflightHotasX"

	// Xbox360 joystick configuration.
	Xbox360 = "xbox360"

	// Xbox360RockBandDrums controller configuration.
	Xbox360RockBandDrums = "xbox360RockBandDrums"

	// Nvidia Shield TV Controller
	Shield = "shield"
)

Types

type Adaptor

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

Adaptor represents a connection to a joystick

func NewAdaptor

func NewAdaptor() *Adaptor

NewAdaptor returns a new Joystick Adaptor.

func (*Adaptor) Connect

func (j *Adaptor) Connect() (err error)

Connect connects to the joystick

func (*Adaptor) Finalize

func (j *Adaptor) Finalize() (err error)

Finalize closes connection to joystick

func (*Adaptor) Name

func (j *Adaptor) Name() string

Name returns the Adaptors name

func (*Adaptor) SetName

func (j *Adaptor) SetName(n string)

SetName sets the Adaptors name

type Driver

type Driver struct {
	gobot.Eventer
	// contains filtered or unexported fields
}

Driver represents a joystick

func NewDriver

func NewDriver(a *Adaptor, config string, v ...time.Duration) *Driver

NewDriver returns a new Driver with a polling interval of 10 Milliseconds given a Joystick Adaptor and json button configuration file location.

Optionally accepts:

time.Duration: Interval at which the Driver is polled for new information

func (*Driver) Connection

func (j *Driver) Connection() gobot.Connection

Connection returns the Drivers connection

func (*Driver) Halt

func (j *Driver) Halt() (err error)

Halt stops joystick driver

func (*Driver) Name

func (j *Driver) Name() string

Name returns the Drivers name

func (*Driver) SetName

func (j *Driver) SetName(n string)

SetName sets the Drivers name

func (*Driver) Start

func (j *Driver) Start() (err error)

Start and polls the state of the joystick at the given interval.

Emits the Events:

Error error - On button error
Events defined in the json button configuration file.
They will have the format:
	[button]_press
	[button]_release
	[axis]