{"id":19003632,"url":"https://github.com/mpaperno/lgkeys-touchportal-plugin","last_synced_at":"2025-04-22T18:16:33.826Z","repository":{"id":144830377,"uuid":"380445294","full_name":"mpaperno/LGKeys-TouchPortal-Plugin","owner":"mpaperno","description":"A Touch Portal plugin for integration with Logitech Gaming Software and devices with programmable macro (\"G\") keys. Display macros for the active game profile and/or trigger TP actions using hardware keys.","archived":false,"fork":false,"pushed_at":"2021-07-18T23:10:18.000Z","size":569,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-17T09:00:55.971Z","etag":null,"topics":["logitech-gaming","logitech-gaming-keyboard","logitech-keyboards","logitech-mouse","macro-keyboard","plugin","touch-portal","touch-portal-plugin","touchportal"],"latest_commit_sha":null,"homepage":"","language":"Python","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/mpaperno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":["mpaperno"]}},"created_at":"2021-06-26T07:45:12.000Z","updated_at":"2025-04-16T12:31:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"b2b82539-d938-435c-86c7-89415db006f6","html_url":"https://github.com/mpaperno/LGKeys-TouchPortal-Plugin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpaperno%2FLGKeys-TouchPortal-Plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpaperno%2FLGKeys-TouchPortal-Plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpaperno%2FLGKeys-TouchPortal-Plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpaperno%2FLGKeys-TouchPortal-Plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mpaperno","download_url":"https://codeload.github.com/mpaperno/LGKeys-TouchPortal-Plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250296265,"owners_count":21407037,"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","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":["logitech-gaming","logitech-gaming-keyboard","logitech-keyboards","logitech-mouse","macro-keyboard","plugin","touch-portal","touch-portal-plugin","touchportal"],"created_at":"2024-11-08T18:19:43.481Z","updated_at":"2025-04-22T18:16:33.814Z","avatar_url":"https://github.com/mpaperno.png","language":"Python","funding_links":["https://github.com/sponsors/mpaperno"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/images/banner/Banne1_fade_720x307.png\" alt=\"LGKeys Banner\"/\u003e\n\u003c/p\u003e\n\n# LGKeys Touch Portal Plugin\n\nThis is a \"plugin\" for the [Touch Portal](https://www.touch-portal.com) software, designed for integrating with Logitech\nGaming devices like keyboards and other peripherals with programmable macro keys (or \"G\" keys).\nIts main purpose is to be used as a reference to display the key mappings which have been set up in the\nLogitech Gaming Software (LGS) for each individual profile. The motivation is that I can never remember\nall the mappings, especially when frequently switching applications, and printed references are difficult\nto maintain. This solves the issue nicely, and in addition to my hardware key macros I can also have\nadditional application-specific macros provided by the regular _Touch Portal_ UI.\n\n## Features\n\n* Supports Logitech Keyboards, Mice, Headsets, and the G13 keypad with programmable macro keys on Windows and MacOS.\n* Display names of macros programmed on all \"G\" keys (or mouse buttons) for any \"game\" profile.\n* Can show macros for all memory (M) slots at once, and/or only the currently selected M slot.\n* Detects currently active LGS device profile and (optionally) automatically refreshes the display.\n* Macros for all profiles can be shown using a single generic page, and/or custom application-specific layouts can be used as well.\n* Automatically detects when current memory slot changes (Windows only).\n* Special feature option to assign custom names for the individual memory slots, per game profile.\n* Monitors game profiles for changes and automatically updates all displayed macros (manual refresh also available).\n* Option to send G key and mouse button press events back to _Touch Portal_ (Windows only).\nAllows control of TP actions via hardware keys.\n\n## Examples\n\nSome example pages are included in the plugin distribution (download). The examples are kept in this\nrepository, in the `assets` folder, and may be updated more often than the plugin releases. Be sure to\ncheck the [assets](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/tree/master/assets) folder in this repo\nfor the latest examples.\n\nSome page images are available on the [Screenshots](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/Screenshots)\nwiki page.\n\n## Setup\n\n### Requirements:\n* [Touch Portal](https://www.touch-portal.com) for Windows/MacOS, v2.3.010 or newer.\n* [Logitech Gaming Software](https://support.logi.com/hc/en-gb/articles/360025298053-Logitech-Gaming-Software)\n(latest and last version) installed. This plugin _may_ work with Logitech G Hub, but this is not tested at all.\n* Download the latest version of this plugin from the\n[Releases](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/releases) page. Grab the .zip file which matches\nyour operating system\u003cbr\u003e\n(eg. `LGKeys-TouchPortal-Plugin_v1.0_windows.zip` or `LGKeys-TouchPortal-Plugin_v1.0_macos.zip`).\nAlternatively, you can also [use the source code](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/Using-Source-Version) version.\n\n### Install:\n1. Unpack the downloaded _LGKeys_ `.zip` file to a temporary location on your computer.\n2. Import the plugin:\n    1. Start _Touch Portal_ (if not already running).\n    2. Click the \"wrench\" icon at the top and select \"Import plugin...\" from the menu.\n    3. Browse to where you unpacked this plugin's `.zip` archive, and select the `LGKeys.tpp` file.\n3. Restart _Touch Portal_\n    * When prompted by _Touch Portal_ to trust the plugin startup script, select \"Yes\" (the source code is public!).\n4. Verify proper operation. The zip file you downloaded contains some sample pages to get you started. You can import\nthese pages in the usual way: from the _Touch Portal_ _Pages_ screen -\u003e _Manage Page..._ button -\u003e _Import Page_ menu item.\n    * After importing the plugin into _Touch Portal_, the `LGKeys.tpp` file you extracted earlier is no longer\nrequired. If you don't want/need to use the other assets and tools provided in the plugin archive, those can of course\nalso be deleted.\n\n### Configure\nSeveral settings are available in the _Touch Portal_ _Settings_ window (select _Plug-ins_ on the left, then\n_LGKeys _Touch Portal_ Plugin_ from the dropdown menu). The current TP settings system for plugins is not very advanced,\nso some of these could be easier to use (hopefully this can improve in the future).\nThe options are as follows:\n\n* `Device Type(s)`: Enter the device(s) you want LGKeys to report settings for. Your profiles may contain mappings\nfor devices you don't currently use (or own anymore), which will just slow everything down and create\nun-necessary data in _Touch Portal_. This setting can list one or more devices, with multiple devices separated by commas.\nTypically you would want to use one or more of the following:\n    * `Keyboard` - for a full keyboard device like G11, G15, G510, etc. This is the default setting.\n    * `Mouse` - for a mouse, like a G700\n    * `Headset` - for a headset with macro keys like a G35\n    * `LeftHandedController` - for a G13 keypad\n\n  For example, to get key mappings for both your keyboard and your mouse, use: \"Keyboard, Mouse\" for the setting value\n  (without the quotes).\n\n  It's possible that in your game profiles, the device you want is specified with a model number after the type.\n  For example if you owned several models of keyboards or mice, your profiles may have different settings for the\n  different device models. For example my mouse device is listed as \"Mouse.G700\". You would then need to specify\n  this full device name in the _Device Type(s)_ list. The only real way to determine this is to look inside the\n  game profile files and see what's in there... which is not very convenient.\n\n  Instead, I have provided a small utility which will scan all your game profiles and find the device names\n  listed in them. It will show you which devices are in each profile, and also provides an aggregated list of\n  unique device names found across all profiles.\n\n  The utility is named `list_devices` and is included in this plugin's distribution .zip file, in the `tools` folder\n  (the code for it is in this repository as well).  Simply run this file, either from a command prompt or by\n  double-clicking it. If your profiles aren't in the standard location, run the utility from a command prompt\n  and specify the path to your profiles with the `-p` option.\n\n  So for example if the utility reports that your mouse is called \"Mouse.G700\" in the profiles, you'd want to use\n  that exact name in the _Device Type(s)_ list. Or, for example combined with a keyboard, that would be\n  \"Keyboard, Mouse.G700\".\n\n* `Unmapped Button Text`: What to show for buttons/slots which don't have a mapping set. Default is \"...\"\n(three periods). This could be any text value, or be left blank.\n\n* `Profile Change Poll Interval`: Set this to zero to disable monitoring of profiles folder for changes (edited\nprofiles would need to be refreshed manually, and profile switch detection is disabled unless _LGS Script Integration_\nis enabled). On MacOS this also controls how often the folder is scanned for changes.\n\n* `Use LGS Script Integration`: If set to \"true\", LGKeys will use optional LGS integration which requires some extra\nsetup (see below). Only works on Windows. Default is \"false\"\n\n* `Report Button Presses`: Requires _LGS Script Integration_ to also be enabled. If \"true\" then LGKeys will\nsend G key and mouse button press and release events to _Touch Portal_ as custom states. Can be used to activate TP\nactions with hardware keys, for example. Requires Windows with 64-bit Python and the optional integration as described\nbelow. Default is \"false\"\n\nThe other settings on this page are read-only and only used internally to save plugin state between runs.\nThey can be ignored.\n\n\n### Optional integration setup (Windows only):\nThis optional step provides closer integration with Logitech Gaming Software to allow the following features:\n* Quicker/more accurate and efficient game profile switch detection.\n* Detection of current memory slot (M#) on keyboards and G13 keypad.\n* Sending G key/mouse button press events to _Touch Portal_.\n\nUnfortunately this requires a special Lua script to be configured for each game profile (LGS allows for custom\nscripts in profiles). The good news is that I've provided a utility to automatically set up these scripts for all\nyour existing profiles.  However, if you already use custom scripts, you may want to do this manually.\nOnly the profiles you want to use the extra features with would need to have this special script set up.\n\n#### Integration Setup Option 1\n1. If LGKeys Plugin is already running, you should stop it. This can be done from the TP Settings -\u003e Plug-ins screen.\n2. Shut down/close the Logitech Gaming Software completely (right-click the taskbar icon and select Exit).\n3. Open a Windows command prompt in the `tools` folder where you unpacked the downloaded plugin zip archive.\n4. Run the utility by entering: `update_profiles` (you can also just double-click to run this file\nfrom Explorer, but I recommend you use a command prompt).\n    * Read the warnings. It will ask you to confirm that you want to proceed (you must answer with a \"y\" or \"yes\").\n    * By default it will also make a backup of all your profiles before it does anything else.\n    The backup will be in a uniquely-named sub-folder of your LGS profiles folder.\n    You can also specify a backup folder using the `-b` startup option.\u003cbr/\u003e\n    Eg. `update_profiles -b C:\\temp\\LGS_profiles`\n    * The utility will let you know if there are any problems or warnings.\n    * If it can't find your game profiles in the default location, you can specify one on the command line with\n    `-p` option.\u003cbr/\u003e\n    Eg. `update_profiles -p C:\\ProgramData\\Logitech\\profiles`\n    * You can update only one, or some, of your profiles, using the `--names` option.\u003cbr/\u003e\n    Eg. `update_profiles --names \"Default Profile\" \"My Game\"`\n    * Run `update_profiles -h` to see all command line options.\n5. Restart the Logitech Gaming Software application (eg. from your Start menu), and _Touch Portal_ or just the plugin\nitself (agin from the TP Settings screen).\n\nFor more integration options, especially **if you already use Lua scripting in profiles**, see the\n[LGS Script Integration Options](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/LGS-Script-Integration)\nwiki page.\n\n\n### Named Memory Slots\nWhile LGS doesn't provide any way to assign names to the M slots, I've designed a custom way to do that using the\nprofile \"description\" fields within LGS. These M slot names can then be shown dynamically in TP based on\nthe current profile, and they become another nice visual reference.\n\nTo set this up, simply edit a game profile's _Description_ field (it's in the profile's _Properties_).\nEnter something like this:\n\n    M1:EDIT; M2:DIFF; M3:DEBUG;\n\nThe syntax is simple: \u003ckbd\u003eM\u003c/kbd\u003e followed by the slot number (1-3), then a colon (\u003ckbd\u003e:\u003c/kbd\u003e) followed by the name\nfor that memory slot, and ending with a semicolon (\u003ckbd\u003e;\u003c/kbd\u003e). If you already have some other description, you could\nadd the slot names at the end.\n\nYou can then use the `\u003cDevice\u003e Memory \u003cN\u003e Name` _States_ (described below) to display the names on your LGKeys page(s).\n\nYou do not have to provide names for all memory slots. Any that are not specified in the description will\ndefault to the usual \"M1\", \"M2\", or \"M3\" names.\n\nIf you have both a \"G\" keyboard _and_ a G13 keypad, which have separate memory slots, you can provide names for\nthe specific devices by using a modified version of the above syntax:\n\n    kb.M1:EDIT; kb.M2:DIFF; kb.M3:DEBUG; lhc.M1:C++; lhc.M2:Python; lhc.M3:Lua;\n\nWhere \"kb\" is for the keyboard memory slots and \"lhc\" is for the G13 (\"LeftHandedController\" in LGS-speak).\n\n\n## Usage\nThe quickest way to get started is to use the example assets (pages/buttons) included with the plugin (and found\nin this repository). This includes several page layouts demonstrating how to use the various features. You will\nlikely want to customize these examples based on your actual devices (eg. how many G keys on your keyboard and how\nthey're laid out), but they contain all the building blocks you may need.\n\nFor further reference, we dive into what the plugin actually provides.\n\n### States\nMost of the functionality is provided by _Touch Portal_ _States_. _States_ provide the macro names to display for each\nkey and memory (M) slot, the currently active profile, M slot names, and so on.  A few of the states always\nexist regardless of which device(s) you're using (static states), but most will depend on your actual configuration.\n\n#### Static States\n* `Name of currently active LGS profile` - As the title suggests, this contains the name of the active profile.\n* `Profiles auto-switch state` - Can be \"Enabled\" or \"Disabled\" based on if automatic profile switching is active or\nnot (see also `Profile Auto-switch Toggle` action).\n* `Keyboard Memory Slot` - Reflects the current M slot number of a keyboard device. Possible values: \"1\", \"2\", or \"3\".\nSee also `Switch Memory Slot` action.\n* `Keyboard Memory \u003cN\u003e Name` - Name of the keyboard memory slot for the current profile, where `\u003cN\u003e` is one of\n\"1\", \"2\", or \"3\". (Also see \"Named Memory Slots\" section above.)\n* `G13 Memory Slot` - Reflects the current M slot number of a G13 keypad device. Possible values: \"1\", \"2\", or \"3\".\nSee also `Switch Memory Slot` action.\n* `G13 Memory \u003cN\u003e Name` - Name of the G13 memory slot for the current profile, where `\u003cN\u003e` is one of \"1\", \"2\", or \"3\".\n (Also see \"Named Memory Slots\" section above.)\n* `Status message from the LGKeys Plugin` - Short text messages sent from the plugin, usually to reflect the result\nof some action, such as profile switching.\n\n#### Dynamic States\n* `\u003cDevice\u003e \u003cButton\u003e (current M slot)` - The macro name mapped to the given `\u003cButton\u003e` on `\u003cDevice\u003e` for the current\nmemory slot. `\u003cDevice\u003e` would be one of \"Keyboard\", \"Mouse\", \"Headset\", or \"LeftHandedController\" (G13).\n`\u003cButton\u003e` would be \"G\" (for keys) or \"Button\" (for mice) followed by a number.\nMice and headsets don't have memory slots, so the \"(current M slot)\" of the title is omitted for these devices.\nThe total number of these states depends on the maximum number of buttons a device may have\n(18 on a keyboard, 20 on a mouse, 3 on a headset, and 29 on a G13).\n\n* `\u003cDevice\u003e \u003cButton\u003e M\u003cN\u003e` - Similar to above, but each of these states shows the macro mapped to each button and\neach individual memory slot (not just the current one). `\u003cN\u003e` represents the memory slot number, 1 through 3.\nSo, each G key on a keyboard would have 3 of these states, in addition to the \"current\" state explained above.\nThese states can be used to display all macros for a given profile at the same time, eg. as 3 lines on the image of a\nbutton, one for each memory slot. These states do not exist for mice and headsets (which only have one memory slot).\n\n* `\u003cDevice\u003e \u003cButton\u003e Press State` - These are sent only if the `Report Button Presses` setting described previously\nis enabled (and LGS scripting integration is used). These states represent when a particular `\u003cButton\u003e` on `\u003cDevice\u003e`\nis pressed or released. When pressed, the state value is \"1\", and when released (or not pressed) the value is \"0\".\nThese states can be used to trigger any other actions in _Touch Portal_ using the built-in\n\"When plug-in state changes\" Event.\n\n\n### Actions\n* `Switch Profile` - Loads the specified LGS profile. The list of profiles is automatically populated based on\nthe profiles found in your LGS profiles folder. If profile folder monitoring is enabled in settings, this list will\nalso automatically update when profiles are added or removed (see reload actions below for manual updates).\n* `Profile Auto-switch Toggle` - Turns on or off automatic switching of profiles based on currently active LGS\nprofile. Turning auto-switch off lets you keep one profile in view regardless of which one is actually active (for example\nvery useful when setting up macros in LGS).\n* `Switch Memory Slot` - Lets you change the currently shown memory slot for either a Keyboard or a G13 device.\nThis can be useful if you don't have LGS Script Integration enabled but still want to show only one memory slot at\na time on your button images (vs. all 3 slots at once). Note that this does **not** change the active\nmemory slot on the actual device (there's no way to do that), so this is purely for \"display purposes only.\"\n* `Reload Current Profile` - Reloads the currently active profile data from the LGS configuration file. Useful if you\nhave directory monitoring disabled, or if for some reason a change wasn't automatically detected (it happens).\n* `Reload All Profiles` - Performs a full reload of all profiles from the LGS profiles directory.\n\n\n### Events\n* `Current Profile Changed` - This has limited usefulness for now due to some limitations in the current TP plugin\nsystem.  This event should fire whenever the `Name of currently active LGS profile` _State_ (see above) changes.\nThe format is \"When profile changes to (name)\" and you have to manually type in the exact profile name you're expecting.\nIt could be useful for example if you want to load a particular TP page when a specific LGS profile is activated. But the\nbuilt-in \"When plug-in state changes\" event can be used for the same thing.\n\n\n## Troubleshooting\nCheck out the [Troubleshooting](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/Troubleshooting) wiki page.\n\n## Running From Source / Development\nPlease see the [Using Plugin Source Code Version](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/wiki/Using-Source-Version)\nwiki page.\n\n## Bugs and Support\nI've only tested this whole thing in very limited conditions so far (my main Windows 10 PC and a little in a \"hackintosh\" VM).\nYour mileage may vary, as they say!  But I'm happy to help figure out any problems and improve the plugin.\n\nOpen an [Issue](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/issues) here on GitHub or start a\n[Discussion](https://github.com/mpaperno/LGKeys-TouchPortal-Plugin/discussions).\nPlease provide as much detail as possible. Logs usually help!\n\n## Credits\nThe plugin is written, tested, and documented by myself, Maxim (Max) Paperno.\u003cbr/\u003e\nhttps://github.com/mpaperno/\n\nUses a version of [TouchPortal-API for Python](https://github.com/KillerBOSS2019/TouchPortal-API)\nwhich is included in this repository and also [published here](https://github.com/mpaperno/TouchPortal-API).\nIt is used under the MIT License.\n\nLGS Script Integration is provided by [LGS Debug Interceptor](https://gondwanasoftware.net.au/lgsdi.shtml)\nlibrary from Gondwana Software. License unspecified. Also check out their\n[G Assignments 3](https://gondwanasoftware.net.au/gassignments3.shtml) software which serves a similar purpose\nas this plugin (and some of the instructions to set up profile integration are very similar).\n\n## Copyright, License, and Disclaimer\nLGKeys TouchPortal Plugin\u003cbr/\u003e\nCopyright Maxim Paperno, all rights reserved.\n\nThis program and associated files may be used under the terms of the GNU\nGeneral Public License as published by the Free Software Foundation,\neither version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nA copy of the GNU General Public License is included in this repository\nand is aldo available at \u003chttp://www.gnu.org/licenses/\u003e.\n\nThis project may also use 3rd-party Open Source software under the terms\nof their respective licenses. The copyright notice above does not apply\nto any 3rd-party components used within.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpaperno%2Flgkeys-touchportal-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmpaperno%2Flgkeys-touchportal-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpaperno%2Flgkeys-touchportal-plugin/lists"}