gobot.io/x/gobot@v1.16.0/platforms/joystick/README.md (about)

     1  # Joystick
     2  
     3  You can use Gobot with any USB joystick or game controller that is compatible with [Simple DirectMedia Layer](http://www.libsdl.org/).
     4  
     5  Current configurations included:
     6  - Dualshock3 game controller
     7  - Dualshock4 game controller
     8  - Thrustmaster T-Flight Hotas X Joystick
     9  - XBox360 game controller
    10  - XBox360 "Rock Band" drum controller
    11  
    12  ## How to Install
    13  
    14  This package requires `sdl2` to be installed on your system
    15  
    16  ### macOS
    17  
    18  To install `sdl2` on macOS using Homebrew:
    19  
    20  ```
    21  $ brew install sdl2
    22  ```
    23  
    24  To use an XBox360 controller on macOS, you will most likely need to install additional software such as [https://github.com/360Controller/360Controller](https://github.com/360Controller/360Controller).
    25  
    26  ### Linux (Ubuntu and Raspbian)
    27  
    28  You must be running a Linux kernel that is v4.14+ in order for the various controller mappings to work as expected.
    29  
    30  Then you must install the latest SDL2 v2.0.8 or greater:
    31  
    32  ```
    33  wget https://www.libsdl.org/release/SDL2-2.0.8.tar.gz
    34  tar -zxvf SDL2-2.0.8.tar.gz
    35  cd SDL2-2.0.8/
    36  ./configure && make && sudo make install
    37  ```
    38  
    39  Now you can install the package with
    40  
    41  ```
    42  go get -d -u gobot.io/x/gobot/...
    43  ```
    44  
    45  ## How to Use
    46  
    47  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.
    48  
    49  
    50  ## How to Connect
    51  
    52  Plug your USB joystick or game controller into your USB port. If your device is supported by SDL, you are now ready.
    53  
    54  For the Dualshock4, you must pair the device with your computers Bluetooth interface first, before running your Gobot program.
    55  
    56  ## Examples
    57  
    58  This small program receives joystick and button press events from an PlayStation 3 game controller.
    59  
    60  ```go
    61  package main
    62  
    63  import (
    64  	"fmt"
    65  
    66  	"gobot.io/x/gobot"
    67  	"gobot.io/x/gobot/platforms/joystick"
    68  )
    69  
    70  func main() {
    71  	joystickAdaptor := joystick.NewAdaptor()
    72  	stick := joystick.NewDriver(joystickAdaptor, "dualshock3",
    73  	)
    74  
    75  	work := func() {
    76  		// buttons
    77  		stick.On(joystick.SquarePress, func(data interface{}) {
    78  			fmt.Println("square_press")
    79  		})
    80  		stick.On(joystick.SquareRelease, func(data interface{}) {
    81  			fmt.Println("square_release")
    82  		})
    83  		stick.On(joystick.TrianglePress, func(data interface{}) {
    84  			fmt.Println("triangle_press")
    85  		})
    86  		stick.On(joystick.TriangleRelease, func(data interface{}) {
    87  			fmt.Println("triangle_release")
    88  		})
    89  		stick.On(joystick.CirclePress, func(data interface{}) {
    90  			fmt.Println("circle_press")
    91  		})
    92  		stick.On(joystick.CircleRelease, func(data interface{}) {
    93  			fmt.Println("circle_release")
    94  		})
    95  		stick.On(joystick.XPress, func(data interface{}) {
    96  			fmt.Println("x_press")
    97  		})
    98  		stick.On(joystick.XRelease, func(data interface{}) {
    99  			fmt.Println("x_release")
   100  		})
   101  		stick.On(joystick.StartPress, func(data interface{}) {
   102  			fmt.Println("start_press")
   103  		})
   104  		stick.On(joystick.StartRelease, func(data interface{}) {
   105  			fmt.Println("start_release")
   106  		})
   107  		stick.On(joystick.SelectPress, func(data interface{}) {
   108  			fmt.Println("select_press")
   109  		})
   110  		stick.On(joystick.SelectRelease, func(data interface{}) {
   111  			fmt.Println("select_release")
   112  		})
   113  
   114  		// joysticks
   115  		stick.On(joystick.LeftX, func(data interface{}) {
   116  			fmt.Println("left_x", data)
   117  		})
   118  		stick.On(joystick.LeftY, func(data interface{}) {
   119  			fmt.Println("left_y", data)
   120  		})
   121  		stick.On(joystick.RightX, func(data interface{}) {
   122  			fmt.Println("right_x", data)
   123  		})
   124  		stick.On(joystick.RightY, func(data interface{}) {
   125  			fmt.Println("right_y", data)
   126  		})
   127  
   128  		// triggers
   129  		stick.On(joystick.R1Press, func(data interface{}) {
   130  			fmt.Println("R1Press", data)
   131  		})
   132  		stick.On(joystick.R2Press, func(data interface{}) {
   133  			fmt.Println("R2Press", data)
   134  		})
   135  		stick.On(joystick.L1Press, func(data interface{}) {
   136  			fmt.Println("L1Press", data)
   137  		})
   138  		stick.On(joystick.L2Press, func(data interface{}) {
   139  			fmt.Println("L2Press", data)
   140  		})
   141  	}
   142  
   143  	robot := gobot.NewRobot("joystickBot",
   144  		[]gobot.Connection{joystickAdaptor},
   145  		[]gobot.Device{stick},
   146  		work,
   147  	)
   148  
   149  	robot.Start()
   150  }
   151  ```
   152  
   153  ## How to Add A New Joystick
   154  
   155  In the `bin` directory for this package is a CLI utility program that scans for SDL joystick events, and displays the ID and value:
   156  
   157  ```
   158  $ go run ./platforms/joystick/bin/scanner.go 
   159  Joystick 0 connected
   160  [6625 ms] Axis: 1       value:-22686
   161  [6641 ms] Axis: 1       value:-32768
   162  [6836 ms] Axis: 1       value:-18317
   163  [6852 ms] Axis: 1       value:0
   164  [8663 ms] Axis: 3       value:-32768
   165  [8873 ms] Axis: 3       value:0
   166  [10183 ms] Axis: 0      value:-24703
   167  [10183 ms] Axis: 0      value:-32768
   168  [10313 ms] Axis: 1      value:-3193
   169  [10329 ms] Axis: 1      value:0
   170  [10345 ms] Axis: 0      value:0
   171  ```
   172  
   173  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.