Getting started

A map2 script is simply a python file that uses the map2 package. There are many good python tutorials out there, for example the W3Schools python tutorial.

Running a script

In most Linux setups, a regular user lacks the permissions to intercept input events for security reasons. If you have superuser permissions, you can simply run your script as the superuser (the -E flag is important to run in the current environment).

sudo -E python my-map2-script.py

This is somewhat risky as the script has access to copy your data, modify files and even remove system files. Use this method only for code you trust or have written yourself!

For a more secure setup see the Secure setup section.

Input devices

On Linux, all connected input devices are listed in /dev/inputX where X is a number. To get more information about a device (label, ID, etc.), the following command can be used:

udevadm info -q all -a /dev/inputX

Some devices will also show up in /dev/input/by-id and /dev/input/by-path. This devices are just symbolic links to the appropriate /dev/inputX device, but with more descriptive names.

My first map2 script

Now that we know which input device we want to map on, let’s write a short python script!

import time
import map2

# readers intercept all keyboard inputs and forward them
reader = map2.Reader(patterns=["/dev/input/by-id/my-keyboard"])

# mappers change inputs, you can also chain multiple mappers!
mapper = map2.Mapper()

# writers create new virtual devices we can write into
writer = map2.Writer(clone_from = "/dev/input/by-id/my-keyboard")

# finally, link nodes to control the event flow
map2.link([reader, mapper, writer])

mapper.map("a", "hello world")

# keep running for 7 seconds
time.sleep(7)

After running the script, pressing the a key should emit hello world instead!