Metadata-Version: 2.4
Name: ovos-PHAL-plugin-hotkeys
Version: 0.1.3a2
Summary: map keypresses to OVOS bus events
Author-email: JarbasAi <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-PHAL-plugin-hotkeys
Keywords: OVOS,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
Dynamic: license-file

## Hotkeys PHAL plugin

This plugin maps keyboard hotkeys to OVOS bus events. You define key combinations, and the plugin sends the matching bus event when you press or release the keys.

## Install

Add your user to the `tty` and `input` groups.

`sudo usermod -a -G tty,input $USER`

You can find more information in [this issue](https://github.com/boppreh/keyboard/issues/312).

Then install the plugin.

`pip install ovos-PHAL-plugin-hotkeys`

## Configuration

Add a bus message and a key combo under `"key_down"` or `"key_up"`.

Use `"key_down"` to react when a key is pressed. Use `"key_up"` to react when a key is released.

Here is a complete example based on events from a generic G20 USB remote.

```json
 "PHAL": {
    "ovos-PHAL-plugin-hotkeys": {
        "debug": false,
        "key_down": {
            "mycroft.mic.listen": 582,
            "mycroft.mic.mute.toggle": 190,
            "mycroft.mic.mute": "shift+m",
            "mycroft.mic.unmute": "shift+u",
            "mycroft.volume.increase": 115,
            "mycroft.volume.decrease": 114,
            "mycroft.volume.mute.toggle": 113,
            "mycroft.volume.mute": "ctrl+shift+m",
            "mycroft.volume.unmute": "ctrl+shift+u",
            "homescreen.manager.show_active": 144,
            "ovos.common_play.play_pause": 164
       }
    }
}
```

For the Mark2 drivers, you can find the emitted key events in the [sj201-buttons-overlay.dts](https://github.com/OpenVoiceOS/VocalFusionDriver/blob/main/sj201-buttons-overlay.dts#L18) file.

```json
 "PHAL": {
    "ovos-PHAL-plugin-hotkeys": {
        "key_down": {
            "mycroft.mic.listen": 582,
            "mycroft.mic.mute": 248,
            "mycroft.volume.increase": 115,
            "mycroft.volume.decrease": 114
       },
        "key_up": {
            "mycroft.mic.unmute": 248
       }
    }
}
```

> gpios 22-24 are the momentary switches. gpio 25 is MuteMic SW, connected to 3.3v or GND.

## Finding keys

You can find a list of valid key scancodes [here](http://wiki.linuxcnc.org/cgi-bin/wiki.pl?Scancodes).

Some key presses are not detected correctly and show up as "unknown". Some devices also emit the wrong keycodes.

In this case, enable the `debug` flag in the config, then check the logs.

```commandline
DEBUG {"event_type": "down", "scan_code": 57, "name": "space", "time": 1711050758.24674, "device": "/dev/input/event4", "is_keypad": false, "modifiers": []}
DEBUG {"event_type": "down", "scan_code": 24, "name": "o", "time": 1711050758.510758, "device": "/dev/input/event4", "is_keypad": false, "modifiers": []}
DEBUG {"event_type": "down", "scan_code": 115, "name": "unknown", "time": 1711050858.940323, "device": "/dev/input/event3", "is_keypad": false, "modifiers": []}
DEBUG {"event_type": "down", "scan_code": 114, "name": "unknown", "time": 1711050864.262953, "device": "/dev/input/event3", "is_keypad": false, "modifiers": []}
```

Use the `scan_code` integer in your config instead of the `name` string.

## Credits

- Keyboard handling comes from the [boppreh/keyboard](https://github.com/boppreh/keyboard) package.

## License

This plugin is available under the [Apache-2.0](LICENSE) license.
