kmk_firmware/docs/en/potentiometer.md

Potentiometer module

Do you want to add joysticks or faders to your keyboard?

The potentiometer module reads analog signals from you ADC pins and gives you a value in 7 bit base.

Enabling the extension

Enabling Potentiometer gives you access to the following keycodes and can simply be added to the modules list.

from kmk.modules.potentiometer import PotentiometerHandler
potentiometer = PotentiometerHandler()

keyboard.modules.append(potentiometer)

How to use

Here is all you need to use this module in your main.py / code.py file.

1. Load the module: import the potentiometer handler and add it to keyboard modules.

from kmk.modules.potentiometer import PotentiometerHandler
potentiometer = PotentiometerHandler()
keyboard.modules.append(potentiometer)

2. Define the pins for each potentiometer: pin_a for the signal pin and defname for the name of the controlling defenition. If you want to invert the direction of the potentiometer, set the 3rd (optional) parameter is_inverted to True.

potentiometer.pins = (
    (board."pin_a", "defname", "is_inverted")
)

Example:

# Regular GPIO potentiometer
potentiometer.pins = (
    # regular direction potentiometer
    (board.A0, potentiometer_1_handler),
    # reversed direction potentiometer
    (board.A1, potentiometer_2_handler, False),
)

3. Define the mapping of keys to be called.

here we convert the incoming base values into a value 0-127 for ease of use.

This example is for a joystick mapped to WASD with a deadzone in the center. The exact deadzone values might vary depending on the potentiometers used.

*Note: this uses `keyboard.add_key` and `keyboard.remove_key` which could be considered legacy.*

def potentiometer_1_handler(state):
    joy1 = int((state.position / 127) * 127)
    if joy1 >= 0 and joy1 <= 56:
        keyboard.add_key(KC.S)
    if joy1 >= 65 and joy1 <= 127:
        keyboard.add_key(KC.W)
    if joy1 >= 57 and joy1 <= 64:
        keyboard.remove_key(KC.S)
        keyboard.remove_key(KC.W)

def potentiometer_2_handler(state):
    joy2 = int((state.position / 127) * 127)
    if joy2 >= 0 and joy2 <= 58:
        keyboard.add_key(KC.A)
    if joy2 >= 67 and joy2 <= 127:
        keyboard.add_key(KC.D)
    if joy2 >= 59 and joy2 <= 66:
        keyboard.remove_key(KC.A)
        keyboard.remove_key(KC.D)

Other examples

Computer volume

You can use a potentiometer to control the system volume easily. Here an example from ZFR_KBD's RP2.65-F

def set_sys_vol(state):
    # convert to 0-100
    new_pos = int((state.position / 127) * 64)
    level = level_lut[new_pos]
    # print(f"new vol level: {level}")
    # print(f"last: {keyboard.last_level}")

    # check if uninitialized
    if keyboard.last_level == -1:
        keyboard.last_level = level
        return

    level_diff = abs(keyboard.last_level - level)
    if level_diff > 0:
        # set volume to new level
        # vol_direction = "unknown"
        if level > keyboard.last_level:
            # vol_direction = "up"
            cmd = KC.VOLU
        else:
            # vol_direction = "down"
            cmd = KC.VOLD

        # print(f"Setting system volume {vol_direction} by {level_diff} to reach {level}")
        for i in range(int(level_diff / level_inc_step)):
            hid_report = keyboard._hid_helper.create_report([cmd])
            hid_report.send()
            hid_report.clear_all()
            hid_report.send()

        keyboard.last_level = level
    return

def potentiometer_1_handler(state):
    set_sys_vol(state)

LED brightness

You can also use a potentiometer to control the LED brightness of your keyboard. Another example from ZFR_KBD's RP2.65-F

def get_kb_rgb_obj(keyboard):
    rgb = None
    for ext in keyboard.extensions:
        if type(ext) is RGB:
            rgb = ext
            break
    return rgb

def set_led_brightness(state):
    rgb = get_kb_rgb_obj(keyboard)
    if rgb is None:
        return

    rgb.val = int((state.position / 127) * rgb.val_limit)
    rgb._do_update()
    return

def potentiometer_3_handler(state):
    set_led_brightness(state)