{"id":13761110,"url":"https://github.com/dokutan/macrodevice","last_synced_at":"2026-04-04T20:50:49.649Z","repository":{"id":110202441,"uuid":"247496220","full_name":"dokutan/macrodevice","owner":"dokutan","description":"Turn any input device into a dedicated macrodevice.","archived":false,"fork":false,"pushed_at":"2022-05-07T17:24:58.000Z","size":199,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-16T18:34:18.890Z","etag":null,"topics":["evdev","fennel","keyboard-listeners","keyboard-shortcuts","libevdev","libusb","lua","macros"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/dokutan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2020-03-15T15:38:48.000Z","updated_at":"2023-11-22T02:37:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"74281486-d4fb-48e7-b842-8e0a4b34caee","html_url":"https://github.com/dokutan/macrodevice","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokutan%2Fmacrodevice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokutan%2Fmacrodevice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokutan%2Fmacrodevice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokutan%2Fmacrodevice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dokutan","download_url":"https://codeload.github.com/dokutan/macrodevice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253415232,"owners_count":21904819,"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":["evdev","fennel","keyboard-listeners","keyboard-shortcuts","libevdev","libusb","lua","macros"],"created_at":"2024-08-03T13:01:38.847Z","updated_at":"2026-04-04T20:50:49.599Z","avatar_url":"https://github.com/dokutan.png","language":"Lua","readme":"# macrodevice\nTurn any input device into a dedicated macrodevice. This is a rewrite of [macroKeyboard](https://github.com/dokutan/macroKeyboard).\n\n## What is the purpose of this program?\nThis program is designed to execute a command at the press of a button (or other input) from a dedicated device (e.g keyboard, gamepad, Arduino (over serial), keyboard indicators, etc.). The configuration is done in [Lua](https://www.lua.org/) or [Fennel](https://fennel-lang.org/), so a complex configuration is possible. It is possible to open multiple devices simultaneously.\n\n## Installing\n- Install all dependencies (on some distros you might need a dev package for the header files)\n  - Lua\n  - Take a look at the available [backends](https://github.com/dokutan/macrodevice/blob/master/doc/backends.md) and install the dependencies for the backends you want. Or install all of them: libevdev, libusb, hidapi, libx11\n- Clone this repository\n- If you don't want all backends, comment out or remove the appropriate lines at the beginning of the makefile\n- Build and install with\n```\nmake\nsudo make install\n```\n\n## Running\n\n### Basic usage\n\nGet a list of all options\n```\nmacrodevice-lua -h\n```\n\nStart the program\n```\nmacrodevice-lua -c your-config.lua\n```\n\nRun in the background\n```\nmacrodevice-lua -c your-config.lua -f\n```\n\nSpecify the language of your config if you are using Fennel\n```\nmacrodevice-lua -l fennel -c your-config.fnl\n```\n\n### Config\n\nTo handle the incoming events and execute commands a Lua or Fennel script is needed. For the details look at the files in ``examples`` and ``doc/api.md``.\n\nTo easily create the input handler function for your Lua script, edit ``examples/create-config.lua`` and execute\n```\nmacrodevice-lua -c examples/create-config.lua\n```\n\n### Starting automatically\nIf you want the program to be started automatically and are using systemd:\n1. edit ``macrodevice.service`` to include the correct path to your config\n2. copy it to ``~/.config/systemd/user/macrodevice.service``\n3. run ``systemctl --user enable --now macrodevice.service``\n\n### Dealing with permissions\nIn most cases root privileges are needed to directly open an input device, however running this program as root creates a major security risk, as all macros are executed with root privileges as well. There are multiple ways to deal with this problem.\n\n1. Start the program with root privileges, and drop these as soon as the device has been opened. This works in all cases where no root privileges are needed once all devices have been opened. See ``examples/example.lua`` for details.\n2. If the device is represented by a file, as with the libevdev backend, you can change the file permissions, or add your user to a group with access to the files of interest.\n3. In case of the libusb and hidapi backends, you can create a [udev](https://wiki.archlinux.org/index.php/Udev) rule that allows read and write access to the device from your normal user.\n\n## License\nThis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.\n\nFennel (src/fennel.lua) is licensed under the MIT/X11 license. See Fennel.LICENSE for the full license.\n","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokutan%2Fmacrodevice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdokutan%2Fmacrodevice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokutan%2Fmacrodevice/lists"}