README.md.hms

--- context ---
desc: cargo metadata --format-version=1 --no-deps | jq -r .packages[0].description
usage: cargo run --quiet -- --help | sed 's/\s*$//'

--- template ---
# One-shot modifier (osm)

{{desc}}

## Installation

Pre-built binaries are available. See [releases](https://github.com/ursm/osm/releases).

Or build manually:

```
$ cargo build
$ target/debug/osm --help
```

## Usage

```
{{{usage}}}
```

### Notes

- Since osm creates a virtual keyboard device to emit key events, it must be run as root (or set the permissions of `/dev/uinput` appropriately).
- osm behaves strangely when a key is typed at startup. In other words, you can't start it from the shell with the enter key! To avoid this problem, use `sleep 1 && sudo osm ... ` or use the service manager as described below.

## Autostart

Use udev and systemd to recognize the connected keyboards and automatically start osm.

```
# /etc/udev/rules.d/99-osm.rules
ACTION=="add", KERNEL=="event*", ENV{ID_INPUT_KEYBOARD}=="1", ENV{DEVPATH}!="/devices/virtual/input/*", TAG+="systemd", ENV{SYSTEMD_ALIAS}+="/sys/devices/virtual/input/%k", ENV{SYSTEMD_WANTS}+="osm@%k.service"
```

```
# /etc/systemd/system/osm@.service
[Unit]
BindsTo=sys-devices-virtual-input-%i.device
After=sys-devices-virtual-input-%i.device

[Service]
ExecStart=/path/to/osm --device /dev/input/%I --keymap LeftShift=Home RightShift=End
```

```
$ systemctl daemon-reload
$ udevadm control --reload
$ udevadm trigger --action=add
```