{"id":17283644,"url":"https://github.com/danomatika/joyosc","last_synced_at":"2025-08-28T04:35:05.995Z","repository":{"id":139775076,"uuid":"2255756","full_name":"danomatika/joyosc","owner":"danomatika","description":"(maintained) hid device to osc event daemon used in the robotcowboy project","archived":false,"fork":false,"pushed_at":"2025-08-15T09:57:36.000Z","size":10287,"stargazers_count":47,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-15T11:34:30.980Z","etag":null,"topics":["game-controller","joystick","osc","sdl2"],"latest_commit_sha":null,"homepage":"http://robotcowboy.com","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danomatika.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-08-23T14:53:58.000Z","updated_at":"2025-08-15T09:57:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"3e0b83dd-64c7-47ec-a8fd-a33632c5625c","html_url":"https://github.com/danomatika/joyosc","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/danomatika/joyosc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Fjoyosc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Fjoyosc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Fjoyosc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Fjoyosc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danomatika","download_url":"https://codeload.github.com/danomatika/joyosc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danomatika%2Fjoyosc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272438859,"owners_count":24935272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-controller","joystick","osc","sdl2"],"created_at":"2024-10-15T09:51:50.942Z","updated_at":"2025-08-28T04:35:05.989Z","avatar_url":"https://github.com/danomatika.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"joyosc\n======\n\n![joyosc icon](data/icon/joyosc_icon_small.jpg)\n\njoystick \u0026 game controller hid device event to Open Sound Control daemon and associated tools\n\nCopyright (c) [Dan Wilcox](https://danomatika.com) 2007 - 2025\n\nDESCRIPTION\n-----------\n\nUSB joysticks \u0026 game controllers are a cheap, ubiquitous source for alternate interfaces and can be easily hacked with custom switches, buttons, and analog sensors. Furthermore, physical computing platforms such as Arduino \u0026 Teensy can be configured to appear as USB HID (Human Interface Devices). joyosc provides a quick OSC event interface for such devices into your favorite creative coding environments (Pure Data, Max MSP, Processing, OpenFrameworks, etc).\n\nThe joyosc package contains the following parts:\n\n1. joyosc: device event daemon\n2. lsjs: joystick \u0026 game controller info tool\n\nThis group of tools allows any OSC capable program to receive joystick \u0026 game controller event data aka button presses, axis movements, etc. Specific joysticks \u0026 game controllers can be mapped by name or Globally Unique ID to specific OSC send addresses and button, axis, etc ids can be remapped or ignored.\n\nThese tools were developed for the robotcowboy project, a wearable computer\nmusic system using [Pure Data](https://puredata.info) in GNU/Linux, macOS, and [iOS](https://danomatika.com/code/pdparty). See \u003chttps://robotcowboy.com\u003e and the initial version, then named \"rc-unitd\" in _[robotcowboy: A One Man Band Musical Cyborg](https://danomatika.com/publications/robotcowboy_thesis_07.pdf)_ Master’s thesis, Chalmers University of Technology 2007.\n\nQUICK START\n-----------\n\nDownload a release tarball from \u003chttps://docs.danomatika.com/releases/joyosc\u003e. _Do not download a release zip from GitHub as the submodule files will not be included._\n\nOtherwise, if cloning this repo, you will also need to check out the submodules using then run `autogen.sh` to create the configure script:\n\n    git clone https://github.com/danomatika/joyosc.git\n    cd joyosc\n    git submodule init\n    git submodule update\n    ./autogen.sh\n\nOn the macOS command line, use Homebrew to install libraries, then build and install to the `/usr/local` prefix via:\n\n    brew install sdl2 liblo tinyxml2\n    ./configure\n    make\n    make install\n\nand the same goes for Ubuntu/Debian:\n\n    sudo apt-get install libsdl2-dev liblo-dev libtinyxml2-dev\n    ./configure\n    make\n    sudo make install\n\nIf everything finished successfully, you're good to go.\n\nIf you're using Pure Data, check out the joyosc abstraction library in `data/pd` and installed into `$(prefix)/share/doc/joyosc/pd/joyosc`.\n\nBUILD REQUIREMENTS\n------------------\n\nThe following libraries are required:\n\n* **SDL2**: input device events\n* **liblo**: OSC (Open Sound Control) communication\n* **tinyxml2**: XML file reading\n\n### Linux\n\nInstall the required development versions of the libraries using your distro's package manager.\n\nFor Debian/Ubuntu, you can use use `apt-get` on the command line:\n\n    sudo apt-get install libsdl2-dev liblo-dev libtinyxml2-dev\n\n### macOS\n\nOn macOS, they can be installed easily using [Homebrew](http://brew.sh) or [Macports](http://macports.org)\n\n#### Homebrew\n\n* install the Homebrew environment\n* go to the Terminal and install the libs:\n\n~~~\nbrew install sdl2 liblo tinyxml2\n~~~\n\n#### Macports\n\n* install the Macports binary and setup the Macports environment\n* go to the Terminal and install the libs:\n\n~~~\nsudo port install libsdl2 liblo tinyxml2\n~~~\n\nIf you use the default Macports install location of `/opt/local`, you will need to set the Macports include and lib dirs before running ./configure:\n\n    export CXXFLAGS=-I/opt/local/include \u0026\u0026 export LDFLAGS=-L/opt/local/lib\n\n### Windows\n\n_Thanks to Fede Camara Halac for the following steps._\n\nOn Windows, it is recommended to use [Msys2](https://www.msys2.org) to install the required build system and library dependencies. Msys2 provides both 32 and 64 MinGW and command shells.\n\n_Note: Msys2 development seems to change frequently, so some of the package names below may have changed after this document was written._\n\nOpen an Msys2 shell and install the compiler chain \u0026 autotools via:\n\n    # 32 bit\n    pacman -S mingw-w64-i686-toolchain mingw-w64-i686-clang autotools\n\n    # 64 bit\n    pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-clang autotools\n\nNext install SDL2 and TinyXML2:\n\n    # 32 bit\n    pacman -S mingw-w64-i686-SDL2 mingw-w64-i686-liblo mingw-w64-i686-tinyxml2\n\n    # 64 bit\n    pacman -S mingw-w64-x86_64-SDL2 mingw-w64-x86_64-liblo mingw-w64-x86_64-tinyxml2\n\nIf your version of Msys2 does not have a package for liblo, you can download the source from https://github.com/radarsat1/liblo/releases then build \u0026 install it manually, for example:\n\n    cd liblo-0.32\n    ./configure --disable-debug --disable-dependency-tracking --disable-tests --disable-network-tests --disable-tools --disable-examples\n    make\n    make install\n\nBUILD AND INSTALLATION\n----------------------\n\nAs this is an GNU autotools project, simply run the following on the command line:\n\n    ./configure\n    make\n    sudo make install\n\n_Note: If you have cloned joyosc from a git repo, you may need to generate the configure script by running `./autogen.sh` first and you will need autoconf, automake, and libtool installed as well._\n\nThis readme, example config files, and the pd library are also installed to your doc dir, something like `$(prefix)/share/doc/joyosc`.\n\nBy default, the configure script installs to `/usr/local`. To change this behavior, specify a new dir before building the project:\n\n    ./configure --prefix=/path/to/install/dir\n\n### macOS\n\nIf using Macports on macOS, it is recommended to use the Macports default prefix of `/opt/local`. Similarly, new Homebrew installs (Apple Silicon) also use `/opt/local`. In the case of older Homebrew installs (Intel), `/usr/local` is used so you won't need to set the prefix. To check the Homebrew prefix, use `brew --prefix`.\n\nUSAGE\n-----\n\nAll applications have a full help usage printout, use -h or --help.\n\n----\n\n### joyosc\n\n\tjoyosc\n\nStarts device daemon with the default settings.\n\n#### Config File\n\n    joyosc config_file.xml\n\nStarts device daemon using the given config file.\n\nThe config file sets the OSC connection information as well as device name or GUID (Globally Unique ID) to OSC address mappings. A custom config file will allow you to specify:\n\n* setup info such as listening and sending ports\n* OSC send addresses for specific device names or GUIDs\\*\n* axis dead zone values for jittery thumb sticks\n* button, axis, hat, \u0026 trackball re-mappings\n* extended controller button \u0026 axis re-mappings for additional unmapped joystick events\n* which button, axis, hat, \u0026 trackball events to ignore\n* custom SDL2 game controller mapping strings for devices only detected as joysticks\n* which device names and GUIDs to exclude\n\nLook at the `example_config.xml` file installed to the doc folder or in the `data` folder of the source distribution for details.\n\n\\* _Note: GUIDs are not guaranteed to be different between devices of the same model and may be different between platforms. \"Your mileage may vary.\" See the [SDL GUID doc](https://wiki.libsdl.org/SDL2/SDL_GUID) for details._\n\n#### Options\n\nYou can also specify values on the command line which override values in the config file.\n\nThe `joyosc` help output:\n~~~\nUsage: joyosc [options] [FILE...]\n\n  joystick device event to osc bridge\n\nOptions:\n  -h, --help           print usage and exit\n  --version            print version and exit\n  -l, --listening-port listening port (default: 7770)\n  -m, --multicast      multicast listening group address (off by default)\n  -i, --ip             ip address, hostname, or multicast group to send to\n                       (default: 127.0.0.1)\n  -p, --port           port to send to (default: 8880)\n  -e, --events         print incoming events, useful for debugging\n  -j, --joysticks-only disable game controller support, joystick interface only\n  -w, --window         open window, helps on some platforms if device events are\n                       not being found, ex. MFi controllers on macOS\n  --window-size        set window size on open (default: 240x240)\n  --sleep              sleep time in usecs (default: 10000)\n  -t, --triggers       report trigger buttons as axis values\n  -s, --sensors        enable controller sensor events (accelerometer, gyro)\n  -r, --rate           sensor rate limit in hz (default: 0)\n  -n, --normalize      normalize axis and sensor values\n  --norm-axes          normalize axis values\n  --norm-sensors       normalize sensor values\n  --start              default address start index, ie. /gc# (default: 0)\n  -v, --verbose        verbose printing, call twice for debug printing -vv\n\nArguments:\n  FILE                 optional XML config file(s)\n~~~\n\nNote: Enabling event printing is useful when debugging:\n~~~\n% joyosc -e\n...\n/js2 Saitek P990 Dual Analog Pad axis: 0 32767\n/js2 Saitek P990 Dual Analog Pad axis: 1 -32768\n/js2 Saitek P990 Dual Analog Pad axis: 2 -32768\n/js2 Saitek P990 Dual Analog Pad axis: 3 -32768\n/js2 Saitek P990 Dual Analog Pad button: 8 1\n/js2 Saitek P990 Dual Analog Pad button: 9 1\n/js2 Saitek P990 Dual Analog Pad button: 10 1\n/js2 Saitek P990 Dual Analog Pad button: 11 1\n/js2 Saitek P990 Dual Analog Pad button: 0 1\n/js2 Saitek P990 Dual Analog Pad button: 3 1\n/js2 Saitek P990 Dual Analog Pad button: 0 0\n/js2 Saitek P990 Dual Analog Pad button: 3 0\n/js2 Saitek P990 Dual Analog Pad button: 0 1\n/js2 Saitek P990 Dual Analog Pad button: 3 1\n/js2 Saitek P990 Dual Analog Pad button: 0 0\n/js2 Saitek P990 Dual Analog Pad button: 3 0\n/js2 Saitek P990 Dual Analog Pad button: 3 1\n/js2 Saitek P990 Dual Analog Pad button: 3 0\n/js2 Saitek P990 Dual Analog Pad button: 0 1\n~~~\n\nA similar printout for a game controller:\n~~~\n% joyosc -e\n...\n/gc0 Logitech F510 Gamepad (DInput) button: a 1\n/gc0 Logitech F510 Gamepad (DInput) button: a 0\n/gc0 Logitech F510 Gamepad (DInput) button: b 1\n/gc0 Logitech F510 Gamepad (DInput) button: b 0\n/gc0 Logitech F510 Gamepad (DInput) button: x 1\n/gc0 Logitech F510 Gamepad (DInput) button: x 0\n/gc0 Logitech F510 Gamepad (DInput) axis: righty 3469\n/gc0 Logitech F510 Gamepad (DInput) axis: rightx 5782\n/gc0 Logitech F510 Gamepad (DInput) axis: righty 7324\n/gc0 Logitech F510 Gamepad (DInput) axis: leftx -3470\n~~~\n\n#### Game Controllers vs. Joysticks\n\nAs of SDL 2, there are two joystick event interfaces:\n\n1. Joystick: original low level HID interface with buttons, axes, hats, \u0026 balls (aka trackballs)\n2. Game Controller: higher level interface that maps button, axis, etc ids to generic button \u0026 axis names\n\nJoystick devices report all input events with a numeric button, axis, hat, \u0026 trackball id which may vary between devices.\n\nGame Controllers map underlying joystick inputs to generic button and axis name strings if the device is detected by SDL as having a game controller mapping. If a device is *not* detected, you can add a custom SDL mapping string via the XML config file or an external text file. See the following for more info: [SDL_GameControllerAddMapping](http://wiki.libsdl.org/SDL_GameControllerAddMapping) \u0026 [SDL Game Controller DB](https://github.com/gabomdq/SDL_GameControllerDB).\n\nSDL Game Controller button names: a, b, x, y, start, back, guide, leftshoulder, lefttrigger, rightshoulder, righttrigger, leftstick, rightstick, dpup, dpdown, dpleft, dpright (dp = digital pad), touchpad\n\nSDL Game Controller axis names: leftx, lefty, rightx, righty\n\n_Note: Game Controller names seem to follow the general Playstation DualShock layout. Devices with more than 4 axes and ~20 buttons are probably best used as Joysticks._\n\nIf you do not want to use the Game Controller interface and stick with Joysticks only, use the `-j/--joysticks-only` commandline option.\n\n#### Game Controller Extended Mappings\n\nThe SDL Game Controller mappings do *not* expose additional axes or buttons which fall outside of the general layout. This is true for controllers which provide button pressure values as well as on/off state, ex. the PS3 controller.\n\njoyosc can optionally remap these extra button or axes events, for example PS3 axis 6 (button a pressure) -\u003e axis \"a\":\n~~~\n/ps3 PS3 Controller button: a 1\n/ps3 PS3 Controller axis: a -32768\n/ps3 PS3 Controller axis: a -17862\n/ps3 PS3 Controller axis: a -15549\n/ps3 PS3 Controller axis: a -10152\n/ps3 PS3 Controller axis: a -2956\n/ps3 PS3 Controller axis: a 5782\n/ps3 PS3 Controller axis: a 17861\n/ps3 PS3 Controller axis: a 30968\n/ps3 PS3 Controller axis: a 32767\n/ps3 PS3 Controller axis: a 31482\n/ps3 PS3 Controller axis: a 7838\n/ps3 PS3 Controller axis: a -22488\n/ps3 PS3 Controller button: a 0\n/ps3 PS3 Controller axis: a -32768\n~~~\n\n#### Game Controller Touchpad events\n\nOn devices with a touchpad, such as the Playstation 4 controllers, joyosc reports touchpad down, up, and xy (motion) events.\n\nSDL Game Controller touchpad event names: down, xy, up\n\n#### Game Controller Sensor Events\n\njoyosc can report raw accelerometer or gyro (rotation) x, y, z data on supported devices when enabling sensors via the `-s/--sensors` option or in a config file. Some split devices have sensors on both sides such as the Nintendo Joy-Cons.\n\nSDL Game Controller sensor event names: accel, gyro, leftaccel, leftgyro, rightaccel, rightgyro\n\n_Note: Sensors will generate **lots** of events when enabled._\n\n#### Event Streaming\n\nSee the [Pure Data](https://puredata.info) patches installed to the system doc folder or the `data/pd` folder of the source distribution for info on how to receive events from joyosc, although any software that can receive Open Sound Control messages will work.\n\njoyosc streams device event information in the following OSC address format:\n\n    /joyosc/devices/NAME/INPUT ID VALUE\n\n* _NAME_ is the mapped name to the device as specified in the config file, otherwise it is \"gc#\" or \"js#\" with # being the current device id\n* _INPUT_ can be `button`, `axis`, `ball`, or `hat` for joysticks and `button`, `axis`, `touchpad`, or `sensor` for game controllers\n* _ID_ is the joystick id number or game controller name string for the control (aka joystick button 1, axis 2, etc / game controller button x, axis lefty, sensor gyro, etc); these are likely different between joystick devices but largely the same between game controllers\n* _VALUE_ is the current value of the control:\n  * button state: 1 or 0 for pressed \u0026 released\n  * axis values: -32768 to 32767 (signed 16 bit)\n    - triggers reported as axes use 0 to 32767 range\n  * touchpad: index, finger, x, y, pressure\n    - x \u0026 y are normalized 0 to 1 (upper left 0,0)\n    - pressure is normalized 0 to 1 (0 no press, 1 \"full\" press))\n  * sensor: x, y, z\n    - floating point values in m/s^2 (accelerometer) or radians/s (gyro)\n    - see the [SDL docs](https://wiki.libsdl.org/SDL2/SDL_SensorType#remarks) for details\n  * hat: binary bitmask representing the hat buttons:\n    - cardinal directions: 0 center, 1 up, 2 right, 4 down, 8 left\n    - corner directions: 3 rightup, 6 rightdown, 9 leftup, 12 leftdown\n    - see the [SDL docs](https://wiki.libsdl.org/SDL3/SDL_GetJoystickHat)\n  * (track)ball: relative x \u0026 y movement in pixels (I think, SDL docs don't go into details)\n\nExample joystick messages:\n~~~\n/joyosc/devices/js2/button 2 1\n/joyosc/devices/js2/button 2 0\n/joyosc/devices/js2/axis 0 32767\n~~~\n\nExample game controller messages:\n~~~\n/joyosc/devices/gc0/button lefttrigger 1\n/joyosc/devices/gc0/button lefttrigger 0\n/joyosc/devices/gc0/axis righty 32767\n~~~\n\n#### Notifications\n\njoyosc also sends status notification messages:\n~~~\n/joyosc/notifications/startup\n/joyosc/notifications/ready\n/joyosc/notifications/open TYPE INDEX NAME\n/joyosc/notifications/close TYPE INDEX NAME\n/joyosc/notifications/shutdown\n~~~\n\n`TYPE` is either \"joystick\" or \"controller\"  \n`INDEX` is the assigned index based on order of connection, indices are reused when available  \n`NAME` is the device address name, ie. `gc0`, `js1`, etc\n\n#### Device Queries\n\nIn response to a query control message (see below), joyosc will send connected device info messages:\n~~~\n/joyosc/query/count numDevs\n/joysoc/query/device controller INDEX NAME buttons axes touchpads sensors rumble led\n/joyosc/query/device joystick INDEX NAME buttons axes balls hats rumble\n~~~ \n\nDevice count: number of currently connected *and* active devices\n\nDevice controller query info:\n* buttons, axes, touchpads: int, number of each type of input\n* sensors: int, number of sensors (available and enabled)\n* rumble: bool, 1 if rumble available\n* led: bool, 1 if controller has a color LED\n\nDevice joystick query info:\n* buttons, axes, balls, hats, touchpads: int, number of each type of input\n* rumble: bool, 1 if rumble available\n\nFor example, the output from querying the count and a single connected PS4 controller: \n~~~\n/joyosc/query/count 1\n/joyosc/query/device controller 0 ps4 16 6 1 0 1 1\n~~~\n\nThe PS4 controller has 16 buttons, 6 axes, 1 touchpad, a color LED, can rumble.\n\n#### Control Messages\n\njoyosc also listens for OSC control messages on a specified listening port (default: 7770).\n\nThe current messages are:\n~~~\n/joyosc/quit\n/joyosc/devices/NAME/color r g b\n/joyosc/devices/NAME/rumble strength duration\n/joyosc/devices/NAME/normalize enable\n/joyosc/devices/NAME/axes/triggers enable\n/joyosc/devices/NAME/axes/normalize enable\n/joyosc/devices/NAME/sensors enable\n/joyosc/devices/NAME/sensors/normalize enable\n/joyosc/devices/NAME/sensors/rate hz\n/joyosc/query/count\n/joyosc/query\n/joyosc/query INDEX\n/joyosc/query NAME\n~~~\n\n`INDEX` is the assigned index based on order of connection, indices are reused when available  \n`NAME` is the device address name, ie. `gc0`, `js1`, etc\n\n##### Quit joyosc\n\nExit joyosc externally via `/joyosc/quit`.\n\n##### Game Controller LED Color\n\nFor game controllers with an LED such as PS4 and PS5 controllers, the color can be set over OSC. The color value range is 0-255.\n\nFor example, to set the color of the device at OSC address \"gc0\" to cyan:\n~~~\n/joyosc/devices/gc0/color 0 255 255\n~~~\n\nTo turn the LED off, set \"black\": `0 0 0`. This message is ignored for joysticks and controllers without an LED.\n\n##### Device Haptic Rumble\n\nFor devices which support haptic \"rumble\" aka have vibration motors, rumble events can be started over OSC. The rumble strength is a normalized percentage 0-1 and the duration is in ms from 0-5000 (5 seconds).\n\nTo rumble device at OSC address \"gc0\" at 75% for 500 ms (a half second):\n~~~\n/joyosc/devices/gc0/rumble 0.75 500\n~~~\n\nTo stop current rumble event, set strength and duration to `0 0`. This message is ignored for unsupported devices.\n\n##### Axes and Sensors\n\nAxis and sensor settings can be configured over OSC:\n* axis normalization\n* triggers as axes\n* enable/disable sensors\n* sensor normalization\n* sensor rate in hz\n\nFor example, to normalize both axes and sensors:\n~~~\n/joyosc/devices/gc0/normalize 1\n~~~\n\nTo enable sensors and set the rate to 60 hz:\n~~~\n/joyosc/devices/gc0/sensors 1\n/joyosc/devices/gc0/sensors/rate 60\n~~~\n\n##### Device Queries\n\nThe currently active devices can be queried over OSC.\n\nTo get active device count:\n~~~\n/joyosc/query/count\n~~~\n\nTo query all active devices:\n~~~\n/joyosc/query\n~~~\n\nTo query a single device by device address name, ie. \"gc0\", or assigned index:\n~~~\n/joyosc/query NAME\n/joyosc/query INDEX\n~~~\n\n---\n\n### lsjs\n\nThe lsjs tool lists the names of currently plugged in joysticks \u0026 game controllers, which you can then use to create your device mappings.\n\nExample output:\n~~~\n% lsjs\n0 Controller: \"Logitech F510 Gamepad (DInput)\" 6d0400000000000018c2000000000000\n~~~\n\nYou can also print detailed info using the -d or --details flags.\n~~~\n% lsjs -d\n\n0 Controller: \"Logitech F510 Gamepad (DInput)\" 6d0400000000000018c2000000000000\n  num axes: 4\n  num buttons: 12\n\n~~~\n\nHere is the same device as a joystick when disabling the game controller interface:\n~~~\n% lsjs -dj\n\n0 Joystick: \"Logitech RumblePad 2 USB\" 6d0400000000000018c2000000000000\n  num axes: 4\n  num buttons: 12\n  num balls: 0\n  num hats: 1\n\n~~~\n\nIf you want to customize an SDL game controller mapping, you can print the default mapping string for a plugged in device:\n~~~\n% lsjs -m\n0 Controller: \"Logitech F510 Gamepad (DInput)\" 6d0400000000000018c2000000000000\n\n6d0400000000000018c2000000000000,Logitech F510 Gamepad (DInput),a:b1,b:b2,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a2,righty:a3,start:b9,x:b0,y:b3,\n\n~~~\n\n#### Options\n\nThe `lsjs` help output:\n~~~\nUsage: lsjs [options]\n\n  print the available joysticks \u0026 game controllers\n\nOptions:\n  -h, --help           print usage and exit\n  --version            print version and exit\n  -d, --details        print device details (buttons, axes, GUIDs, etc)\n  -m, --mappings       print game controller mappings\n  -j, --joysticks-only disable game controller support, joystick interface only\n  -w, --window         open window, helps on some platforms if devices are not\n                       being found, ex. MFi controllers on macOS\n~~~\n\nPURE DATA LIBRARY\n-----------------\n\nA small library of Pure Data abstractions is provided in the `data/pd` folder for OSC message parsing when using the Pd 0.46+ oscparse object. This library set is also installed to `share/doc/joyosc/pd/joyosc`.\n\nKNOWN ISSUES\n------------\n\n### macOS Game Controller Button Opens Launchpad\n\nNewer versions of macOS 14.5+ map the Home or \"logo\" button to automatically open the Launchpad app selector. This behavior can be disabled in Systems Settings:\n\nGame Controllers -\u003e Controller Shortcuts -\u003e uncheck Press Home button to open Launchpad\n\n### macOS \"MFi\" Controllers Not Detected On Start\n\nAs of spring 2024, game controllers designed to work with iOS, ie. Apple \"MFi-certified\", are supported by SDL2 on newer versions of macOS circa 10.15+, however they are often not detected if connected *before* starting joyosc. In order for controllers to be recognized, open joyosc or lsjs with an optional window using the `-w/--window` flag in order the OS to deliver events:\n\n    joyosc --window\n\n_This requirement may change in the future._\n\n### Console Error on SSH\n\nAs joyosc \u0026 lsjs use SDL, they will not work over a SSH connection and you'll get the following error:\n\n    Error: could not init SDL: Unable to open a console terminal\n\nRun them from a real terminal on the machine.\n\nDEVELOPING\n----------\n\nThis is an GNU autotools project. When working with the git repo directly, the configure script must be generated using autoconf:\n\n    ./autogen.sh\n\nYou can enable a debug build using:\n\n    ./configure --enable-debug\n\nAfter making changes, run `make distcheck` to make sure the distributable package can be built successfully.\n\nTo ensure a full clean when making changes to configure.ac, etc run:\n\n    ./autoclean.sh\n\nFor debugging, configure with `--enable-debug` and (re) build. Run in gdb or lldb to pinpoint crashes. For example:\n\n    lldb -- ./src/joyosc/joyosc -ev data/example_config.xml\n    ...\n    process launch\n\nNotes\n-----\n\n_Note: joyosc was originally named \"rc-unitd\" (the robotcowboy unit daemon) in versions prior to 0.4.0_\n\n[How to connect PS3 controller on macOS, PC, etc](https://gist.github.com/hlung/8385683)\n\n[Use Osculator + HID extension for Wiimote support on macOS](http://www.osculator.net)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanomatika%2Fjoyosc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanomatika%2Fjoyosc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanomatika%2Fjoyosc/lists"}