LPHK (LaunchPad HotKey)

A Novation Launchpad macro scripting system.

Update 4

Table of Contents

LPHK HomepageLPHK HomepageLPHK HomepageLPHK HomepageLPHK Discord ChatLPHK Discord ChatLPHK Discord ChatLPHK PatreonLPHK PatreonLPHK PatreonLPHK Patreon

Links [Table of Contents]

What does it do? [Table of Contents]

The goal of this project is to implement a macro scripting system for the Novation Launchpad, in order to use the launchpad as a scriptable, general purpose macro keyboard.

It uses "LPHKscript", a very simple scripting language similar to DuckyScript, and has a GUI to enter scripts, set colors, and to save/load your setup.

LPHK can be used for the following:

LPHK has all of its core features functional and ready to use! There are a lot of new features wanted, and there are massive bugs that need fixing, and it needs some more polish, but you can still do quite a lot with it as it is currently!

LPHK is still a work-in-progress, so things will be changing often. See below for a todo list. I have a life (a crazy one at that), so no promises on a delivery date. Feel free to offer your help! You can see project updates and ask questions on the official Discord server! You can also donate on the official Patreon page to help speed up development, or just say thanks!

Compatibility [Table of Contents]

I have specifically chosen to do my best to develop this using as many cross platform libraries as possible, with a hard requirement that Linux and Windows be supported, and a strong preference for Mac as well. The GUI is driven by TK, which works on all of the above plus Unix. The interface with the launchpad and several script functions are built on pygame, which is compatible with basically everything ever. Pretty much everything else is standard Python 3.

Current compatibility:

Installation [Table of Contents]

Note: Files used in the installation are named with a version number, and will change with each new release. The word VERSION is used in the below filenames and paths to denote where this version number will be. When going to https://github.com/nimaid/LPHK/releases/latest, it will redirect to the page with the latest versions of these files, so the correct value of VERSION should be plainly obvious. Note: Because pyautogui is used you may need to install some extra libraries to your machine, more info on this page: https://pyautogui.readthedocs.io/en/latest/install.html

Windows Install/Run Instructions [Table of Contents]

Is these pre-built binaries do not work for you, please share the issue in the Discord or as a GitHub issue. In the meantime, advanced users can use INSTALL\environment.yml to install the LPHK conda environment, and then run python LPHK.py after activating it.

Linux Install/Run Instructions [Table of Contents]

The following instructions are for a beta version installer that aims to be fairly easyto use. Eventually, once Linux stability improves, there will be pre-built binaries released. Until then, if this installer fails, please share the issue in the Discord or as a GitHub issue. In the meantime, advanced users can use INSTALL\environment.yml to install the LPHK conda environment, and then run python LPHK.py after activating it.

THE FOLLOWING INSTRUCTIONS ARE FOR THE BETA INSTALLER, WHICH AIMS TO BE PAINLESS TO USE. IT IS GOING TO SOON BE REPLACED BY BINARY RELEASES. IF THIS INSTALLER FAILS, TRY MANUALLY INSTALLING CONDA AND THE CONDA ENVIRONMENT IN INSTALL/environment.yml. THEN, RUN LPHK.py INSIDE THE LPHK CONDA ENVIRONMENT.

How do I use it? (Post-Install) [Table of Contents]

The whole GUI is still rough around the edges, so don't be too surprised if something breaks. If it does, kindly open a detailed issue on GitHub so I can fix the error. :) And don't feel shy making feature requests, either!

What is LPHKscript? [Table of Contents]

LPHKscript is a simple macro scripting language tailor made for LPHK. Syntax is closer to a shell/batch script than, say, JavaScript.

Comments [Table of Contents]

Any line that starts with a dash - will be considered a comment, and will be ignored by the syntax validator/script parser. Useful to add notes for yourself or others!

Scheduling [Table of Contents]

Only one script runs at a time, and there is a scheduling system for them. If a script is scheduled, it's button will pulse red. If the script is running, the button will flash red quickly. This is true for the 8x8 grid, however, the function keys cannot flash or pulse, as a hardware limitation. These keys will be bright orange for scheduled and bright red for running.

When you press a script button, if there is a script running, it adds the script to the queue. If no scripts are running, the script is added to the queue and the queue execution is started. Tapping a scheduled script's button will unschedule it, and tapping a running scripts button will kill it. If that sounds confusing, load up user_layouts/examples/all_delays_all_day.lpl and press a bunch of buttons.

Headers [Table of Contents]

Headers are commands that start with @ and go on the first line of a script. They are used to put the scripting engine into different "modes", allowing you to do some interesting things.

The @ASYNC Header [Table of Contents]

There is one exception to the scheduling system. If the script has the @ASYNC header, it will run in the background and will not interact with the other scripts. It can still be prematurely killed by tapping the button. If this is used, it must come before any other commands. Only comments and blank lines can come before it.

The @SIMPLE Header [Table of Contents]

This is a quick way to bind a controller button to a simple keypress of (argument 1). This has the equivalent code to:

@ASYNC
PRESS (argument 1)
WAIT_UNPRESSED
RELEASE (argument 1)

If this is used, all other lines in the file must either be blank lines or comments.

Commands List [Table of Contents]

Commands follow the format: COMMAND arg1 arg2 .... Scripts are just a text file with newlines separating commands.

Utility [Table of Contents]

Keypresses [Table of Contents]

Mouse Movement [Table of Contents]

Key Names [Table of Contents]

For the PRESS, RELEASE, and TAP commands, all single character non-whitespace keys and the following key names are allowed:

Known Issues / Troubleshooting [Table of Contents]

TODO List [Table of Contents]

In order of priority:

DONE List [Table of Contents]