ovos-PHAL-plugin-hotkeys 0.1.3a2

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.

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.

 "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 file.

 "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.

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.

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 package.

License

This plugin is available under the Apache-2.0 license.