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