import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js"; const __pageData = JSON.parse('{"title":"Joystick","description":"","frontmatter":{},"headers":[],"relativePath":"features/joystick.md","filePath":"features/joystick.md"}'); const _sfc_main = { name: "features/joystick.md" }; const _hoisted_1 = /* @__PURE__ */ createStaticVNode('

Joystick ​

This feature provides game controller input as a joystick device supporting up to 6 axes and 32 buttons. Axes can be read either from an ADC-capable input pin, or can be virtual, so that its value is provided by your code.

An analog device such as a potentiometer found on an analog joystick's axes is based on a voltage divider, where adjusting the movable wiper controls the output voltage which can then be read by the microcontroller's ADC.

Usage ​

Add the following to your rules.mk:

make
JOYSTICK_ENABLE = yes

By default the joystick driver is analog, but you can change this with:

make
JOYSTICK_DRIVER = digital

Configuration ​

By default, two axes and eight buttons are defined, with a reported resolution of 8 bits (-127 to +127). This can be changed in your config.h:

c
// Min 0, max 32\n#define JOYSTICK_BUTTON_COUNT 16\n// Min 0, max 6: X, Y, Z, Rx, Ry, Rz\n#define JOYSTICK_AXIS_COUNT 3\n// Min 8, max 16\n#define JOYSTICK_AXIS_RESOLUTION 10

TIP

You must define at least one button or axis. Also note that the maximum ADC resolution of the supported AVR MCUs is 10-bit, and 12-bit for most STM32 MCUs.

Axes ​

When defining axes for your joystick, you must provide a definition array typically in your keymap.c.

For instance, the below example configures two axes. The X axis is read from the A4 pin. With the default axis resolution of 8 bits, the range of values between 900 and 575 are scaled to -127 through 0, and values 575 to 285 are scaled to 0 through 127. The Y axis is configured as a virtual axis, and its value is not read from any pin. Instead, the user must update the axis value programmatically.

c
joystick_config_t joystick_axes[JOYSTICK_AXIS_COUNT] = {\n    JOYSTICK_AXIS_IN(A4, 900, 575, 285),\n    JOYSTICK_AXIS_VIRTUAL\n};

Axes can be configured using one of the following macros:

The low and high values can be swapped to effectively invert the axis.

Virtual Axes ​

The following example adjusts two virtual axes (X and Y) based on keypad presses, with KC_P0 as a precision modifier:

c
joystick_config_t joystick_axes[JOYSTICK_AXIS_COUNT] = {\n    JOYSTICK_AXIS_VIRTUAL, // x\n    JOYSTICK_AXIS_VIRTUAL  // y\n};\n\nstatic bool precision = false;\nstatic uint16_t precision_mod = 64;\nstatic uint16_t axis_val = 127;\n\nbool process_record_user(uint16_t keycode, keyrecord_t *record) {\n    int16_t precision_val = axis_val;\n    if (precision) {\n        precision_val -= precision_mod;\n    }\n\n    switch (keycode) {\n        case KC_P8:\n            joystick_set_axis(1, record->event.pressed ? -precision_val : 0);\n            return false;\n        case KC_P2:\n            joystick_set_axis(1, record->event.pressed ? precision_val : 0);\n            return false;\n        case KC_P4:\n            joystick_set_axis(0, record->event.pressed ? -precision_val : 0);\n            return false;\n        case KC_P6:\n            joystick_set_axis(0, record->event.pressed ? precision_val : 0);\n            return false;\n        case KC_P0:\n            precision = record->event.pressed;\n            return false;\n    }\n    return true;\n}

Keycodes ​

KeyAliasesDescription
QK_JOYSTICK_BUTTON_0JS_0Button 0
QK_JOYSTICK_BUTTON_1JS_1Button 1
QK_JOYSTICK_BUTTON_2JS_2Button 2
QK_JOYSTICK_BUTTON_3JS_3Button 3
QK_JOYSTICK_BUTTON_4JS_4Button 4
QK_JOYSTICK_BUTTON_5JS_5Button 5
QK_JOYSTICK_BUTTON_6JS_6Button 6
QK_JOYSTICK_BUTTON_7JS_7Button 7
QK_JOYSTICK_BUTTON_8JS_8Button 8
QK_JOYSTICK_BUTTON_9JS_9Button 9
QK_JOYSTICK_BUTTON_10JS_10Button 10
QK_JOYSTICK_BUTTON_11JS_11Button 11
QK_JOYSTICK_BUTTON_12JS_12Button 12
QK_JOYSTICK_BUTTON_13JS_13Button 13
QK_JOYSTICK_BUTTON_14JS_14Button 14
QK_JOYSTICK_BUTTON_15JS_15Button 15
QK_JOYSTICK_BUTTON_16JS_16Button 16
QK_JOYSTICK_BUTTON_17JS_17Button 17
QK_JOYSTICK_BUTTON_18JS_18Button 18
QK_JOYSTICK_BUTTON_19JS_19Button 19
QK_JOYSTICK_BUTTON_20JS_20Button 20
QK_JOYSTICK_BUTTON_21JS_21Button 21
QK_JOYSTICK_BUTTON_22JS_22Button 22
QK_JOYSTICK_BUTTON_23JS_23Button 23
QK_JOYSTICK_BUTTON_24JS_24Button 24
QK_JOYSTICK_BUTTON_25JS_25Button 25
QK_JOYSTICK_BUTTON_26JS_26Button 26
QK_JOYSTICK_BUTTON_27JS_27Button 27
QK_JOYSTICK_BUTTON_28JS_28Button 28
QK_JOYSTICK_BUTTON_29JS_29Button 29
QK_JOYSTICK_BUTTON_30JS_30Button 30
QK_JOYSTICK_BUTTON_31JS_31Button 31

API ​

struct joystick_t ​

Contains the state of the joystick.

Members ​

struct joystick_config_t ​

Describes a single axis.

Members ​

void joystick_flush(void) ​

Send the joystick report to the host, if it has been marked as dirty.

void register_joystick_button(uint8_t button) ​

Set the state of a button, and flush the report.

Arguments ​

void unregister_joystick_button(uint8_t button) ​

Reset the state of a button, and flush the report.

Arguments ​

int16_t joystick_read_axis(uint8_t axis) ​

Sample and process the analog value of the given axis.

Arguments ​

Return Value ​

A signed 16-bit integer, where 0 is the resting or mid point.

void joystick_set_axis(uint8_t axis, int16_t value) ​

Set the value of the given axis.

Arguments ​

', 58); const _hoisted_59 = [ _hoisted_1 ]; function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { return openBlock(), createElementBlock("div", null, _hoisted_59); } const joystick = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); export { __pageData, joystick as default };