diff options
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/joystick.md | 51 |
1 files changed, 50 insertions, 1 deletions
diff --git a/docs/features/joystick.md b/docs/features/joystick.md index 69db4655d5..cbf6c6daf7 100644 --- a/docs/features/joystick.md +++ b/docs/features/joystick.md @@ -1,6 +1,6 @@ # Joystick {#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](../drivers/adc), or can be virtual, so that its value is provided by your code. +This feature provides game controller input as a joystick device supporting up to 6 axes, 32 buttons and a hat switch. Axes can be read either from an [ADC-capable input pin](../drivers/adc), or can be virtual, so that its value is provided by your code. An analog device such as a [potentiometer](https://en.wikipedia.org/wiki/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. @@ -37,6 +37,42 @@ By default, two axes and eight buttons are defined, with a reported resolution o 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. ::: +### Hat Switch {#hat-switch} + +To enable the 8-way hat switch, add the following to your `config.h`: + +```c +#define JOYSTICK_HAS_HAT +```` + +The position can be set by calling `joystick_set_hat(value)`. The range of values moves clockwise from the top (ie. north), with the default "center" position represented by a value of `-1`: + +``` + 0 + 7 N 1 + NW .--'--. NE + / \ +6 W | -1 | E 2 + \ / + SW '--.--' SE + 5 S 3 + 4 +``` + +Alternatively you can use these predefined names: + +|Define |Value|Angle| +|------------------------|-----|-----| +|`JOYSTICK_HAT_CENTER` |`-1` | | +|`JOYSTICK_HAT_NORTH` |`0` |0° | +|`JOYSTICK_HAT_NORTHEAST`|`1` |45° | +|`JOYSTICK_HAT_EAST` |`2` |90° | +|`JOYSTICK_HAT_SOUTHEAST`|`3` |135° | +|`JOYSTICK_HAT_SOUTH` |`4` |180° | +|`JOYSTICK_HAT_SOUTHWEST`|`5` |225° | +|`JOYSTICK_HAT_WEST` |`6` |270° | +|`JOYSTICK_HAT_NORTHWEST`|`7` |315° | + ### Axes {#axes} When defining axes for your joystick, you must provide a definition array typically in your `keymap.c`. @@ -149,6 +185,8 @@ Contains the state of the joystick. A bit-packed array containing the joystick button states. The size is calculated as `(JOYSTICK_BUTTON_COUNT - 1) / 8 + 1`. - `int16_t axes[]` An array of analog values for each defined axis. + - `int8_t hat` + The hat switch position. - `bool dirty` Whether the current state needs to be sent to the host. @@ -222,3 +260,14 @@ Set the value of the given axis. The axis to set the value of. - `int16_t value` The value to set. + +--- + +### `void joystick_set_hat(int8_t value)` {#api-joystick-set-hat} + +Set the position of the hat switch. + +#### Arguments {#api-joystick-set-hat-arguments} + + - `int8_t value` + The hat switch position to set. |