# HOWTO: Gamepad and FreeBSD



## serjsk8 (Oct 11, 2010)

Hi everyone!
This is my first HOWTO!

Sometimes I play different games on the emulator SNES9x and play on the keyboard is not very convenient. I remembered that I have a USB Gamepad (Logitech Dual Action â„¢ Gamepad).
http://www.logitech.com/en-us/gaming...rs/devices/288
So I decided to connect it ....

I heve OS:


```
FreeBSD 8.1-RELEASE
```

First, Install X. Org joystick input driver:


```
# pkg_add -r xf86-input-joystick
```

Next, install uhidd (USB HID daemon). uhidd is a userland driver/daemon for USB HID devices like mouse, keyboard etc...


```
# cd /usr/ports/sysutils/uhidd
# make install clean
```

To start "uhidd" automatically, add the following lines to the file /etc/rc.conf


```
uhidd_flags="-kmohs"
uhidd_enable="YES"
```

More info about "uhidd" you can read hear:
http://wiki.freebsd.org/uhidd

Connect gamepad and restart your computer.
When you start you can see something like this:


```
ugen1.2: <vendor 0x046d> at usbus1
uhid0: <vendor 0x046d product 0xc216, class 0/0, rev 1.10/3.00, addr 2> on usbus1
```

This is may gamepad! System has found it!

Now we add our device in /etc/X11/xorg.conf
Need to mapping the buttons and axis.
Explane:
"MapAxis1","MapAxis2" - POV control, cross of four buttons with the left. I assign to them the following keys from the keyboard: UP - w, DOWN - s, LEFT - a, RIGHT-d.
"MapAxis3","MapAxis4" - right analog sticks will work like mouse.
"MapAxis5","MapAxis6" - left analog sticks will work like ARROW up, down, left, right on the keyboard.
Four button whith the right will work like buttons of keyboard "1", "2", "3", "4".
Two buttons in the middle, it will be "space" and "enter".
Buttons LU y RU - "5", "6"
Buttons LD y RD - will be mouse click.


```
Section "ServerLayout"
    Identifier     "Layout0"
    Screen      0  "Screen0"
    InputDevice    "Keyboard0" "CoreKeyboard"
    InputDevice    "Mouse0" "CorePointer"
    # Add Gamepad 
    [B]InputDevice    "Logitech" "SendCoreEvents"[/B]
EndSection

Section "InputDevice"
    Identifier     "Logitech"
    Option         "Vendor" "Logitech"
    Driver         "joystick"
    Option         "Path" "/dev/uhid0"
    Option         "Device" "/dev/uhid0"
    Option         "DebugLevel" "99"
    # Right Buttons
    # Button w(Up)/s(Down)
    # Button a(Left)/s(Right)
    Option         "MapAxis1" "mode=accelerated keylow=38 keyhigh=40"
    Option         "MapAxis2" "mode=accelerated keylow=25 keyhigh=39"
    # Right joystick: Like mouse
    Option         "MapAxis3" "mode=relative axis=+1x deadzone=5000"
    Option         "MapAxis4" "mode=relative axis=+1y deadzone=5000"
    # Left joystick: 
    # axis X - Left/Right
    # axis Y - Up/Down
    Option "MapAxis5"       "mode=relative deadzone=28000 keylow=100 keyhigh=102 axis=0.15key"
    Option "MapAxis6"       "mode=relative deadzone=28000 keylow=98 keyhigh=104 axis=0.15key"
    #
    Option         "MapButton1" "key=10"
    Option         "MapButton2" "key=11"
    Option         "MapButton3" "key=12"
    Option         "MapButton4" "key=13"
    Option         "MapButton5" "key=14"
    Option         "MapButton6" "key=15"
    # mouse button: left
    Option         "MapButton7" "button=1"
    # mouse button: right
    Option         "MapButton8" "button=3"
    # button "Space"
    Option         "MapButton9" "key=65"
    # button "Enter"
    Option         "MapButton10" "key=36"
EndSection
```

That's all... setting is finished!
Restart X.

For check the gamepad you can use "xev".
Now run the emulator Snes9x or the other, assign buttons and play!

Thank all! 
	
	



```

```


----------



## Eponasoft (Oct 11, 2010)

If MapAxis1 and MapAxis2 correspond to the D-pad on the left, then it's called a POV or "hat" control. I'd personally assign it differently, but this layout would be fine for many applications. Good tutorial, we need more like this.  I personally have a PS to USB adapter so I use my PS controllers on my computers.


----------



## serjsk8 (Oct 11, 2010)

Thank you!
I have changed name of 4 buttons, and wrote POV!


----------



## noz (Oct 25, 2010)

I can't believe I can finally use my controllers on FreeBSD.  Thanks!


----------



## Acetilene (Apr 23, 2012)

Hi guys! I'm an *I*talian user of freebsd FreeBSD. I'm very new to this beautiful system, so I have started with GhostBSD (a freebsd FreeBSD version with gnome already started). I have tried to follow this howto but when I add the gamepad to xorg.conf the mouse stops working correctly and I must press ctrl+alt+F2 for enter in a shell and restore xorg.conf.
Here are the sections of xorg.conf that I have changed:


```
Section "ServerLayout"
    Identifier     "Layout0"
    Screen      0  "Screen0"
    InputDevice    "Keyboard0" "CoreKeyboard"
    InputDevice    "Mouse0" "CorePointer"
    InputDevice    "Joy0" "SendCoreEvents"
EndSection

Section "InputDevice"
    Identifier     "Joy0"
    Driver         "joystick"
    Option         "Path" "/dev/uhid0"
    Option         "Device" "/dev/uhid0"
EndSection
```

When I restart I can see this: 

```
ugen3.2: <vendor 0x0079> at usbus3
uhid0: <vendor 0x0079 usbgamepad, class 0/0, rev 1.00/1.06, addr 2> on usbus3
```

Any idea? Thanks to everyone.


----------



## serjsk8 (Apr 24, 2012)

Hello.
Please publish "All/fully" your configuration file.


----------



## Acetilene (Apr 25, 2012)

Ok! Actually I have removed the changes because with them I wasn't in able to use xserver.


```
# nvidia-xconfig: X configuration file generated by nvidia-xconfig
# nvidia-xconfig:  version 285.05.09  (root@GhostBSD)  Ven  9 Mar 2012 00:59:30 CET


Section "ServerLayout"
    Identifier     "Layout0"
    Screen      0  "Screen0" 0 0
    InputDevice    "Keyboard0" "CoreKeyboard"
    InputDevice    "Mouse0" "CorePointer"
EndSection

Section "Files"
    FontPath        "/usr/local/lib/X11/fonts/TTF/"
EndSection

Section "InputDevice"

    # generated from default
    Identifier     "Mouse0"
    Driver         "mouse"
    Option         "Protocol" "auto"
    Option         "Device" "/dev/sysmouse"
    Option         "Emulate3Buttons" "no"
    Option         "ZAxisMapping" "4 5"
EndSection

Section "InputDevice"

    # generated from default
    Identifier     "Keyboard0"
    Driver         "keyboard"
EndSection

Section "Monitor"
    Identifier     "Monitor0"
    VendorName     "Unknown"
    ModelName      "Unknown"
    HorizSync       28.0 - 33.0
    VertRefresh     43.0 - 72.0
    Option         "DPMS"
EndSection

Section "Device"
    Identifier     "Device0"
    Driver         "nvidia"
    VendorName     "NVIDIA Corporation"
EndSection

Section "Screen"
    Identifier     "Screen0"
    Device         "Device0"
    Monitor        "Monitor0"
    DefaultDepth    24
    SubSection     "Display"
        Depth       24
    EndSubSection
EndSection
```


----------



## sidetone (Feb 20, 2016)

I realize this is an old thread.

I understand that x11-drivers/xf86-input-joystick is required for it to work with Xorg. Does generic driver sysutils/uhidd work with any USB game-pad/joystick?


----------



## gofer_touch (Feb 20, 2016)

Thanks for reviving this. I tried to use the aforementioned joystick x11 drivers and it didn't work for some reason under 10.2. I never had the time to investigate why. Now that I've seen this I'm going to do so.


----------



## serjsk8 (Feb 22, 2016)

sidetone said:


> I realize this is an old thread.
> 
> I understand that x11-drivers/xf86-input-joystick is required for it to work with Xorg. Does generic driver sysutils/uhidd work with any USB game-pad/joystick?



Hi Sidetone, hi Gofer_touch,
I can not say whether it works with all usb devices or not.
You can try x11/antimicro
When I wrote the article, then the port is not yet there.
I tried x11/antimicro with my gamepad Logitech and PlayStation DualShok4, they both worked.


----------



## sidetone (Oct 15, 2016)

I didn't try this yet, but I was wondering about Bluetooth gamepads. I haven't bought any yet. The above sysutils/uhidd driver is for usb gamepads.

There is only sysutils/btsixad in ports that is described as a Bluetooth driver for a gamepad, which is only for the sixaxis, which is a PlayStation style gamepad. There is Hidromancer in the github repository, but it doesn't seem to have a range of bluetooth gamepad support.

An overall Bluetooth gamepad driver, doesn't seem to be in ports. I don't know if x11-drivers/xf86-input-joystick from x11-drivers/xorg-drivers, a Bluetooth module and x11/antimicro would work with a Bluetooth gamepad. There is comms/anyremote, but it looks like antimicro and a Bluetooth module take its place?

There is https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-bluetooth.html in the handbook. Like any other module in FreeBSD, Bluetooth must be loaded in /boot/loader.conf according to the correct driver. The drivers do have a wide range, that happened to cover many hardware devices, namely Bluetooth v1.1 and UART. The drivers mentioned from the handbook don't specifically Bluetooth version 2.1.

*edit - I see a generic Bluetooth module in the next section of the Handbook, ng_hci(4)


----------



## Dan MacDonald (Jul 16, 2017)

I have a Trust Predator USB gamepad (which works fine under Linux) that I'm struggling to get fully working under FreeBSD.

I have tried both the steps in the OP (ie modifying xorg.conf) and using antimicro. Modifying xorg.conf didn't work at all - xev shows no input after restarting X and pushing buttons etc on my pad. I may need to use different values in my xorg.conf but this guide doesn't explain how sejsk8 discovered what the correct values to enter are, in case the user isn't using the same controller. Also, will/should users always use /dev/uhidX in xorg.conf vs /dev/ugenX.X?

antimicro is looking more promising - I can assign all my buttons but I have been unable to assign the dpad directions to keys. Anyone else had this problem? How did you overcome it?

Getting my USB joypad to work is the first real failing on the FreeBSD handbook for me - everything else I've wanted to do has been covered in there. I suppose that's because so few people do any gaming under FreeBSD and because it lacks proper USB joypad support.

EDIT

I can see Axis 1 and Axis 2 receiving input when I move my dpad up/down or left/right on the default antimicro screen, but when I come to assigning the dpad directions under options -> Game Controller Mapping, antimicro doesn't register the dpad input.


----------



## oops (Jul 17, 2017)

Dan MacDonald said:


> I'm struggling to get fully working under FreeBSD.


Where are you trying to use the gamepad? On BSDs the common way to access USB joysticks/gamepads is via libusbhid(3) but you can also use libusb(3). For one, SDL_Joystick API uses it under the hood. Some applications/libraries (e.g., devel/godot, emulators/wine) don't use a platform abstraction and write their own backends but libusbhid(3) is often overlooked. What you can do in such a case is raise the issue upstream, CC the port maintainer and ask fellow users to vote (e.g., via "Add your reaction" on GitHub).



Dan MacDonald said:


> xev shows no input after restarting X


xev stands for X events and mostly used for keyboard/pointer actions. xf86-input-joystick, antimicro, etc. are ways to emulate such actions but applications would still treat those as keyboard/mouse. However, libusbhid(3) consumers don't use X events for joysticks.


----------



## Dan MacDonald (Jul 17, 2017)

Hi oops!

I mainly want it for godot which I want to learn but it would also be nice for ppsspp, advancemame and wine.

So you say I can use libusbhid OR libusb? All the guides I've found only use libushhid. Do you know of any docs that cover configuring a joypad using libusb under FreeBSD?

You say "libusbhid consumers don't use X events for joysticks" - doesn't that contradict the guide above? I know that I've never had to edit xorg.conf to get a joypad working under Linux but thats Linux which has 'proper' joypad support.


----------



## sidetone (Jul 17, 2017)

So, sysutils/uhidd uses libusb(8), and not libusbhid(3)? uhidd(8), also comes with a configuration file, uhidd.conf(5), which I don't know if it replaces x11/xev or xf86-input-joystick. sysutils/usbhid-dump looks like a tool for this, because it uses libusb.

I notice, there's a separate uhid(4), which comes with the base system, and it uses usbhidctl(1) to configure it. Is this what libusbhid(3) uses? I notice that libusbhid and usbhidctl both refer to /usr/share/misc/usb_hid_usages. uhidd.conf(5) uhidd(8) says that it will try to detach if the base system's uhid is enabled. Is uhid accessible by comms/hidapi?

It looks like the better way would be to enable uhid, instead of uhidd.
/boot/loader.conf:

```
uhid_load="YES"
```
/etc/rc.conf:

```
#uhidd_flags="-kmohs"
#uhidd_enable="YES"
```


----------



## Dan MacDonald (Jul 20, 2017)

I opened a github ticket for my dpad problem with antimicro four days ago but thats not had any reply yet.

https://github.com/AntiMicro/antimicro/issues/162

I have also written to HPS to ask about joypads under FreeBSD. He's on vacation right now so he seems reluctant, understandably, to spend his vacation troubleshooting or writing guides but he says webcamd should be able to support USB joypads, which makes no sense to me.


----------



## Wozzeck.Live (Jul 20, 2017)

Thanks for this useful post, happy to learn new things everyday.

But, reading further here :

https://wiki.freebsd.org/uhidd

It seems very clear that ums, uhid from base system may conflcts with uhidd
And in fact yes, with FreeBSD 11 starting UHIDD has absolutely no effect

One must KLDUNLOAD first the two modules above and before that deactivate the DEVD rules attached to theses modules in
/etc/devd/usb.conf.

If not, after KLDUNLOAD, DEVD will automatically reload the module.

For UBKD kernel module, one can kldunload it or we can also use UKBD concurrently with UHIDD as explained

However the best use is to simply call the option "-u"
With the -u option, UHIDD will first detach any existing kernel device, and this is the sole option really working for me, so no need to worry with the above modules, they can keep running, and stopping UHIDD will restart the USB devices with the default base system.

so I would advise all to change the flags in rc.conf and use the following :

`uhidd_flags="-ukmohs"`

I must check if UHIDD, as promised in the documentation, will bring me better support of Logitech Keyboards (notably for the media keys), so it would also be possible te "reassign" the Windows key for any function


----------



## sidetone (Jul 20, 2017)

There are a few separate choices to use: the base system's uhid(4), base system's bthidd(8) for bluetooth HID's, or sysutils/uhidd from ports. There's insight into uhid and uhidd from what oops described above.


Wozzeck.Live said:


> It seems very clear that ums, uhid from base system may conflcts with uhidd





> And in fact yes, with FreeBSD 11 starting _UHIDD_ has absolutely no effect


 Did you mean uhid? or uhidd not conflicting?


Wozzeck.Live said:


> reading further here :
> 
> https://wiki.freebsd.org/uhidd


 Coexists/Conflicts with kernel drivers. Also, uhidd(8).


I found bthidd(8) for HID devices on bluetooth, which uses bthidcontrol(8). Its configuration file, supposed to be at /etc/bluetooth/bthidd.conf, has no formal manpage as of now, but it is partially documented at https://gist.github.com/waitman/d77440b82dcb2463e5c3.


For those compiling the base system with src.conf, it seems that 
	
	



```
WITHOUT_LEGACY_CONSOLE
```
 must not be used for many usb devices. In other words, many usb devices seem to use LEGACY_CONSOLE.


----------



## sidetone (Jul 21, 2017)

Wozzeck.Live said:


> If we use the flags : ukhoms at startup
> 
> sysutils/uhidd process  seems to take a complete control of the USB HID devices.
> 
> ...



According to https://wiki.freebsd.org/uhidd and uhidd(8), ukbd(4), ums(4) and uhid(4) can be removed from /etc/devd/usb.conf, if compiled into the kernel (and likely in your case too) via devd(8). "To recover from such issues, you can restart uhidd by /usr/local/etc/rc.d uhidd restart."


> So during the boot it seems that FreeBSD 11 UKBD module is intelligent enough to combine itself with UHIDD from port, but this occurs only at boot.


That is also described in uhidd(8) under _Caveats_. I wouldn't be too surprised if uhidd can take over for the keyboard and mouse drivers.


> For some obvious reasons, one can't unload UKBD, this would be dangerous as disconnecting the keyboard and you loose the local control of the machine. But one can unload UMS and UHID kernel modules stopping before DEVD.



My ukbd driver is compiled into my kernel. When I tried `kldunload ums`, for the mouse, it seemed to have restarted immediately, because `kldstat` listed it later. When it can't unload a device, it will just tell you. Usually, you can plug a usb cable back in, and kld will load it automatically. The only problem is if a usb component crashes the system.


----------



## Dan MacDonald (Jul 21, 2017)

Seems I hit a bit of a hornets nest in reviving this topic!

I'm less certain about how I might go about getting my joypad working under FreeBSD now than when I first posted in this thread.

Could anyone comment on webcamd vs joypads and joysticks? webcamd isn't just for webcams?


----------



## Dan MacDonald (Jul 23, 2017)

It may be better or easier to fix the dpad config issue within antimicro but it looks like I've found another potential joypad fixer, rejoystick:

http://rejoystick.sourceforge.net

rejoystick should let me map my joypad to X keystrokes but its not been updated since 2008 and its going to require a bit of tweaking to build it under FreeBSD.


----------



## Dan MacDonald (Jul 26, 2017)

I think I have worked out what my problem with antimicro is and how to work around it although I haven't actually got antimicro to work with anything to prove it yet.

I have updated my anitmicro github ticket with my workaround:

https://github.com/AntiMicro/antimicro/issues/162


----------



## Dan MacDonald (Jul 26, 2017)

I'm not confident I have antimicro working properly yet. If I understand the way it is supposed to work, after configuring and starting antimicro by editing my *~/.config/antimicro/antimicro_settings.ini* and appending what I believe to be the correct dpad direction axes values like so:



```
[Mappings]
4a6f79737469636b2028302900000000="4a6f79737469636b2028302900000000,Joystick (0),platform:FreeBSD,a:b2,b:b1,x:b3,y:b0,start:b9,leftshoulder:b6,rightshoulder:b7,lefttrigger:b4,righttrigger:b5,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,"
```

( I created the first part of the string using the controller mapping window and then I manually added "dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0," to the end)

I should be able to see my joypad as a SDL2 device by running:


```
sdl-jstest --list
```

After building sdl-jsest from https://github.com/Grumbel/sdl-jstest . I've tried that but it says:


```
No joysticks were found
```

Which would explain why its also not working under PPSSPP for me, which I've checked with ldd is built against SDL2.

antimicro users - what apps have you successfully used am with? What is the best way to test your antimicro config?


----------



## Dan MacDonald (Jul 28, 2017)

SUCCESS!

(With PPSSPP anyway, not antimicro)

I built PPSSPP from ports and did a `make config` to enable the OLDJOY build option. After building and installing that version, my joypad works under fine under PPSSPP without any configuration under TrueOS or PPSSPP.

The controllermap package/port includes testjoystick and testgamepad but it doesn't fake keyboard input too like antimicro claims it can and I had no luck getting its (or anitmicros) SDL2 controller string working with PPSSPP.


----------



## Dan MacDonald (Aug 7, 2017)

The antimicro dev has responded to my bug report - its not just me or FreeBSD:


```
Hi @danboid, sorry for taking so long to get back to you. Yes, I have the same issue with the D-pad on my PS1 controller. Not sure where the confusion is coming from. Probably either the low-level driver or SDL, since we just use whatever the system tells us.

Very handy work around! We have the ability to build your own string via Options->Game Controller Mapping, but it might be nice if we had a more user-friendly way of adjusting the configuration. I'll think on it. For now, I'll update the title to reflect this.

As to your second point about the axes starting up at -256 instead of 0, yes, this affects me too. I am able to clear things by going to Options->Properties and doing a quick 'circle' on the D-pad. I suspect this is related to the fact that the *NIXes don't provide a mechanism to calibrate controllers like Windows does.
```


----------



## serjsk8 (Aug 21, 2017)

Dan MacDonald said:


> I may need to use different values in my xorg.conf but this guide doesn't explain how sejsk8 discovered what the correct values to enter are


Hello Dan MacDonald,
How are you?
What "values" do you mean?
I think that my method is outdated, I did this for FreeBSD 8.1-RELEASE.


----------

