Skip to content
AmjadAAYD
x20ctl
Public

About

Open configuration library for the EasySMX X20 gamepad and other KeyLinker-protocol controllers. Reverse engineered for interoperability.

Topics

bluetooth-low-energycontroller-configurationcontroller-remappingcsharpdesktop-appdotneteasysmxgame-controllergamepadgamepad-controllergamepad-inputsgamepad-librarygamepad-mappergamepad-supportgamepad-viewergaminghidprotocol-analysisreverse-engineeringx20ctl

Resources

Readme
GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

13 stars

Watchers

0 watching

Forks

4 forks
Report repository
BranchesTags

Repository files navigation

X20CTL: a controller studio for EasySMX padsDownload v0.018Reverse engineeringChangelogController not working?Thank you EasySMX Kiin and Team EasySMX for supplying an EasySMX X20 Pro to build and test X20CTL. Special thanks to EasySMX-Khalil for providing an EasySMX Dune.A tour of X20CTLIndependent project. X20CTL is open-source software. EasySMX supplied an X20 Pro to help develop it, but the app is not made, endorsed, sponsored or supported by EasySMX. Product names belong to theirWhat it isX20CTL is a native Windows app for EasySMX controllers. It gives every pad a console-style studio: remap buttons, shape the sticks and triggers, build macros for the back paddles, preview vibration, cEverything below is shown on the EasySMX X20 Pro.Reverse engineeringEasySMX configures its pads from a phone app (KeyLinker), and the protocol it speaks was never documented. X20CTL exists because that protocol had to be recovered, checked against real hardware, and rKeyLinker packet layout and the scramble applied on the wireResearch pipeline: decompile, capture, diff, verify, shipTransport: Bluetooth LE GATT. A configuration service with one write and one notify characteristic. The OTA firmware service is documented so it can be left alone: X20CTL does not flash firmware.; Fingerprinting: the controllers' Bluetooth address prefixes tell models apart far better than the clonedocs/research-policy.mdRead more: protocol reference(docs/01-protocol.md) · reverse-engineering log(docs/00-findings.md) · controller scan kit(docs/controller-scan-kit/)protocol referencereverse-engineering logcontroller scan kitStudio tourController ZoneThe home screen. Each of the four players has a card; the selected card grows into the hero spot on the left and the other three wait on the right. Press + on an empty card to choose a controller. TheController Zone with an X20 Pro in the first slotChoose your controllerPick the model you hold. Each card names what the pad has: stick and trigger type, lighting, screen and back buttons. Choosing a model sets the layout and tools; connecting the hardware is a separate Choosing between eight EasySMX controllersAgent XCTLA small assistant drawn as a controller, in the Studio's title bar. Tell it in your own words how you play and it sets your PC mode for you: stick and trigger curves, dead zones, hair triggers, turbo,StudioDashboardThe controller, its player slot, your draft and the games installed on this PC. The game shelf finds Steam, Epic, GOG and Riot games, plus any folder you add, and launches them with their own setup. IStudio dashboardButtonsPick a button on the controller, then press what it should do. Front and back views are included, plus a showcase of every output a control can send. Test mapping lets you feel a change before you keeRemapping A to BCurvesShape each stick and trigger separately: presets, or your own curve with inner dead zone and outer travel limit. The graph shows the response a game actually gets, and a live dot follows the real sticStick response curvesAdvanced opens the fine stick tools:dead zones in 0.1% steps, anti-deadzone and max output;; a square gate, up/down speed, or pure raw 1:1;; presets, copy to the other stick, and a table of what the game gets at each push;; Measure drift, which sets each inner dead zone just past how far the stick wanders on its own.Advanced stick toolsMacrosBuild sequences for the M back paddles, step by step, on a timeline. Each step holds buttons, stick directions or a pause, with its own timing, and you can record one by playing the moves. The X20 ProA three-step macro on M1VibrationSet motor strength and watch the preview: each grip lights along its own edge and pulses with the motors. It is a visual preview of your setting, not a reading from the motors. The X20 Pro and the DunVibration preview at 70 percentPC modePC mode gives any controller remaps, turbo, stick and trigger curves and macros on the PC. X20CTL reads the real controller, applies your settings, and hands the result to the game as a virtual Xbox cPC mode is a tab on every controller's Studio. While it's on, that controller's own Buttons, Curves and Macros tabs edit the PC mode settings, and every change applies right away.The PC mode tabBack paddles and macros. EasySMX paddles don't have a button of their own: each one sends an ordinary button. So in PC mode, each macro slot is played by a real button you pick in the Macros tab, and that button plays the macro instead of its usual job.; Up to four controllers at once, each with itsViGEmBusHidHideDeviceThe controller's battery, firmware, hardware revision and transport. Gameplay and configuration are listed as separate connections, along with what X20CTL supports on this model.Device pageDiagnosticsA live, read-only check of the controller:Sticks: a range trace with its roundness, where each stick rests (drift), and the smallest step it moves in.; Triggers: how far each one travels.; Buttons: every press, with chatter flagged, since a press too short for a finger usually means a worn switch.; Report rate: how many reports a second theCopy report puts the readings on the clipboard for a bug report. Use as dead zone puts a stick's measured drift straight into PC mode's dead zone.DiagnosticsMouseUse the controller as a mouse around Windows: from the couch, or in a game's launcher. One stick moves the pointer, the other scrolls, and every button does what you pick: clicks, back and forward, EnSwitch it on in the tab, from the tray icon, or by holding View + Y for a second.; Speed, acceleration, dead zone, slow-pointer speed and scroll speed are adjustable.; While it's on, games see a resting controller, so a click never also presses A in a game.; The idea comes from Gopher360(https://gitGopher360Controller as mouseSetupsKeep whole-controller setups in a local library: buttons, curves, macros and vibration together. Open, duplicate, rename, export and import them.Saved setupsTesterSee exactly what Windows receives from the controller: every button, both sticks and both triggers, live, with the front and back views.Input testerToolsHelp and extras: PC mode, the Controller Check, Replay Intro, About, Send feedback, Support X20CTL and the GitHub repository, plus switches for update checks and for the opening intro.Tools hubController CheckIs the controller not working? The Controller Check walks you through every button, stick and trigger, one step at a time. It shows held times, the stick report rate and resolution, battery, button chIt only reads. It never changes settings, lighting, vibration or firmware. Sending the report is your choice: before the scan starts, pick Scan and send or Scan, keep it on this PC.Controller Check introductionThe Controller Check is the Read scan. Its partner, the Write scan, learns what KeyLinker writes to a controller. You change one setting in KeyLinker on an Android phone or an iPhone while the phone'sWithout a phone log, the command line can compare the controller's own settings before and after a change: x20 state save before.json --label before, change one setting in the official app and close iFeedback and AboutSend feedback goes straight to the X20CTL inbox, and About has the credits.Send feedbackAbout X20CTLSupported controllersSupported controllers tableFor a preview model, nothing is written to the controller and nothing is stored as if it had been. A model becomes verified only once its settings can be read back from real hardware. Controller CheckDownloadWindows: download X20CTL-V0.017-windows-x64-setup.exe(https://github.com/AmjadAAYD/x20ctl/releases/download/v0.017/X20CTL-V0.017-windows-x64-setup.exe) and run it. It installs X20CTL with a Start menuX20CTL-V0.017-windows-x64-se…X20CTL-V0.017-windows-x64.exeYou need Windows 10 or 11 (x64). Everything is bundled: you don't need to install .NET, Python, a browser runtime or an account.Code signing: releases are built on GitHub Actions straight from this repository, and X20CTL has applied for free code signing for open-source projects from the SignPath Foundation(https://signpath.orSignPath FoundationLinux: X20CTL-V0.017-linux-check.zip(https://github.com/AmjadAAYD/x20ctl/releases/download/v0.017/X20CTL-V0.017-linux-check.zip). The Studio is Windows-only for now; this ZIP contains the Controller CX20CTL-V0.017-linux-check.zipEvery earlier release is on the releases page(https://github.com/AmjadAAYD/x20ctl/releases). How the version names work: docs/versions.md(docs/versions.md).releases pagedocs/versions.mdLocal firstNo account. No telemetry. The update check is on by default and you can turn it off with Keep X20CTL up to date in Tools. PC mode names its two drivers and asks before it installs them. Your setups, drafts and assignments stay in your user folder.; Every change is a local draft until it can be sent privacy policyBuild from sourceYou need the .NET 10 SDK on Windows:

git clone https://github.com/AmjadAAYD/x20ctl.git
cd x20ctl
dotnet build desktop-dotnet\X20Ctl.Product\X20Ctl.Product.csproj -c Release

The controller art is generated from the source pictures by tools/build_native_controller_layers.py, and the outlines by tools/build_controller_outlines.py. The protocol research and the earlier Pythodocs/protocol referenceCreditsSpecial thanks to Kiin from Team EasySMX for supplying a free X20 Pro controller. Real hardware is what turns a protocol guess into a verified setting.The console-style look was inspired by ApexSenseBridge by Kayn arts (ReynArts)(https://github.com/ReynArts/ApexSenseBridge). The credit is for design inspiration only; no code was taken from it. X20CTApexSenseBridge by Kayn arts…If X20CTL helps you, you can support it on Ko-fi(https://ko-fi.com/x20ctl), or simply star the repo.support it on Ko-fiLicenseFrom V0.012 (4.1.0 Preview 3), X20CTL is free software under the GNU General Public License v3.0 or later(LICENSE). You may use, study, share and change it. If you distribute a modified version, it muGNU General Public License v…Releases up to and including V0.011 (4.1.0 Preview 2) were published under MIT, and code contributed under MIT keeps its notice (licenses/(licenses/)). See NOTICE(NOTICE) for details and the full non-licenses/NOTICEX20CTL, GPL-3.0-or-later

Everything above is also available as plain, copyable text in README.plain.md.

About

Open configuration library for the EasySMX X20 gamepad and other KeyLinker-protocol controllers. Reverse engineered for interoperability.

Topics

bluetooth-low-energycontroller-configurationcontroller-remappingcsharpdesktop-appdotneteasysmxgame-controllergamepadgamepad-controllergamepad-inputsgamepad-librarygamepad-mappergamepad-supportgamepad-viewergaminghidprotocol-analysisreverse-engineeringx20ctl

Resources

Readme
GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

13 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

Packages

Used by

Contributors

Languages