add documentation for HID joystick Add joystick_task to read analog axes values even when no key is pressed or release. update doc Update docs/feature_joystick.md Manage pin setup and read to maintain matrix scan after analog readgc_switch
achol
7 years ago
committed by
a-chol
parent
d8f3c28a37
commit
3cf7611139
@ -0,0 +1,85 @@ |
|||||||
|
## Joystick HID Device |
||||||
|
|
||||||
|
The keyboard can be made to be recognized as a joystick HID device by the Operating System. |
||||||
|
|
||||||
|
This is enabled by adding the following to `rules.mk` |
||||||
|
|
||||||
|
``` |
||||||
|
JOYSTICK_ENABLE = yes |
||||||
|
``` |
||||||
|
|
||||||
|
### Configuring the joystick |
||||||
|
|
||||||
|
The default joystick has 2 axes and and 8 buttons. This can be changed from the config.h file : |
||||||
|
|
||||||
|
``` |
||||||
|
//max 32 for JOYSTICK_BUTTON_COUNT |
||||||
|
#define JOYSTICK_BUTTON_COUNT 16 |
||||||
|
//max 6 for JOYSTICK_AXES_COUNT |
||||||
|
#define JOYSTICK_AXES_COUNT 3 |
||||||
|
``` |
||||||
|
|
||||||
|
When defining axes for your joystick, you have to provide a definition array for it. You can do this from your keymap.c file. |
||||||
|
A joystick will either be read from an input pin that allows the use of an ADC, or can be virtual, so that its value is provided by your code. |
||||||
|
You have to define an array of type ''joystick_config_t'' and of proper size, in the following way : |
||||||
|
|
||||||
|
``` |
||||||
|
//joystick config |
||||||
|
joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = { |
||||||
|
[0] = {A1, D7, 65280, 65472}, |
||||||
|
[1] = {JS_VIRTUAL_AXIS, JS_VIRTUAL_AXIS, 65280, 65472} |
||||||
|
}; |
||||||
|
``` |
||||||
|
|
||||||
|
In this example, the first axis will be read from the D7 pin while A1 is set high, using an analogRead, whereas the second axis will not be read. |
||||||
|
If you connected the your analog component to Vcc instead of an output pin, you can set the output setting to JS_VIRTUAL_AXIS. |
||||||
|
In order to give a value to the second axis, you can do so in any customizable entry point of quantum : as an action, in process_record_user or in matrix_scan_user, or even in joystick_task(void) which is called even when no key has been pressed. |
||||||
|
You assign a value by writing to joystick_status.axes[axis_index] a signed 8bit value (-127 to 127). Then it is necessary to assign the flag JS_UPDATED to joystick_status.status in order for the change to be taken into account. |
||||||
|
|
||||||
|
The following example writes two axes based on keypad presses, with KP_5 as a precision modifier : |
||||||
|
|
||||||
|
``` |
||||||
|
#ifdef JOYSTICK_ENABLE |
||||||
|
static bool precision_on; |
||||||
|
#endif |
||||||
|
|
||||||
|
bool process_record_user(uint16_t keycode, keyrecord_t *record) { |
||||||
|
switch(keycode){ |
||||||
|
#ifdef JOYSTICK_ENABLE |
||||||
|
// virtual joystick |
||||||
|
case KC_P8: |
||||||
|
joystick_status.axes[1] -= (record->event.pressed ? 1 : -1) * (precision_on ?70 : 127); |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
break; |
||||||
|
case KC_P2: |
||||||
|
joystick_status.axes[1] += (record->event.pressed ? 1 : -1) * (precision_on ?70 : 127); |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
break; |
||||||
|
case KC_P4: |
||||||
|
joystick_status.axes[0] -= (record->event.pressed ? 1 : -1) * (precision_on ?70 : 127); |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
break; |
||||||
|
case KC_P6: |
||||||
|
joystick_status.axes[0] += (record->event.pressed ? 1 : -1) * (precision_on ?70 : 127); |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
break; |
||||||
|
case KC_P5: |
||||||
|
precision_on = record->event.pressed; |
||||||
|
joystick_status.axes[0] *= record->event.pressed ? 70/127.f : 127/70.f; |
||||||
|
joystick_status.axes[1] *= record->event.pressed ? 70/127.f : 127/70.f; |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
break; |
||||||
|
#endif |
||||||
|
} |
||||||
|
|
||||||
|
return true; |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
### Triggering joystick buttons |
||||||
|
|
||||||
|
Joystick buttons are normal quantum keycode, defined as JS_BUTTON0 to JS_BUTTON_MAX, which depends on the number of buttons you have configured. |
||||||
|
To trigger a joystick button, just add the corresponding keycode to your keymap. |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -0,0 +1,11 @@ |
|||||||
|
#include "joystick.h" |
||||||
|
|
||||||
|
joystick_t joystick_status = {
|
||||||
|
.buttons = {0}, |
||||||
|
.axes = {0}, |
||||||
|
.status = 0 |
||||||
|
}; |
||||||
|
|
||||||
|
//array defining the reading of analog values for each axis
|
||||||
|
__attribute__ ((weak)) |
||||||
|
joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = {}; |
||||||
@ -0,0 +1,48 @@ |
|||||||
|
#ifndef JOYSTICK_H |
||||||
|
#define JOYSTICK_H |
||||||
|
|
||||||
|
#ifndef JOYSTICK_BUTTON_COUNT |
||||||
|
#define JOYSTICK_BUTTON_COUNT 8 |
||||||
|
#endif |
||||||
|
|
||||||
|
#ifndef JOYSTICK_AXES_COUNT |
||||||
|
#define JOYSTICK_AXES_COUNT 4 |
||||||
|
#endif |
||||||
|
|
||||||
|
#include <stdint.h> |
||||||
|
|
||||||
|
//configure on input_pin of the joystick_axes array entry to JS_VIRTUAL_AXIS
|
||||||
|
// to prevent it from being read from the ADC. This allows outputing forged axis value.
|
||||||
|
//
|
||||||
|
#define JS_VIRTUAL_AXIS 0xFF |
||||||
|
|
||||||
|
typedef struct { |
||||||
|
uint8_t output_pin; |
||||||
|
uint8_t input_pin; |
||||||
|
|
||||||
|
//the AVR ADC offers 10 bit precision, with significant bits on the higher part
|
||||||
|
uint16_t min_digit; |
||||||
|
uint16_t max_digit; |
||||||
|
} joystick_config_t; |
||||||
|
|
||||||
|
extern joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT]; |
||||||
|
|
||||||
|
enum joystick_status{ |
||||||
|
JS_INITIALIZED = 1, |
||||||
|
JS_UPDATED = 2 |
||||||
|
}; |
||||||
|
|
||||||
|
typedef struct { |
||||||
|
|
||||||
|
uint8_t buttons[JOYSTICK_BUTTON_COUNT/8+1]; |
||||||
|
|
||||||
|
int8_t axes[JOYSTICK_AXES_COUNT]; |
||||||
|
uint8_t status:2; |
||||||
|
} joystick_t; |
||||||
|
|
||||||
|
extern joystick_t joystick_status; |
||||||
|
|
||||||
|
//to be implemented in the hid protocol library
|
||||||
|
void send_joystick_packet(joystick_t* joystick); |
||||||
|
|
||||||
|
#endif //JOYSTICK_H
|
||||||
@ -0,0 +1,79 @@ |
|||||||
|
#include "process_joystick.h" |
||||||
|
|
||||||
|
#include <quantum/joystick.h> |
||||||
|
#include <quantum/quantum_keycodes.h> |
||||||
|
|
||||||
|
#ifdef __AVR__ |
||||||
|
# include <drivers/avr/analog.h> |
||||||
|
#endif |
||||||
|
|
||||||
|
#include <string.h> |
||||||
|
|
||||||
|
bool process_joystick_buttons(uint16_t keycode, keyrecord_t *record); |
||||||
|
|
||||||
|
bool process_joystick(uint16_t keycode, keyrecord_t *record){ |
||||||
|
|
||||||
|
if (process_joystick_buttons(keycode, record)
|
||||||
|
&& (joystick_status.status & JS_UPDATED)>0){ |
||||||
|
send_joystick_packet(&joystick_status); |
||||||
|
joystick_status.status &= ~JS_UPDATED; |
||||||
|
} |
||||||
|
|
||||||
|
return true; |
||||||
|
} |
||||||
|
|
||||||
|
__attribute__ ((weak)) |
||||||
|
void joystick_task(void){ |
||||||
|
if (process_joystick_analog() && (joystick_status.status & JS_UPDATED)){ |
||||||
|
send_joystick_packet(&joystick_status); |
||||||
|
joystick_status.status &= ~JS_UPDATED; |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
bool process_joystick_buttons(uint16_t keycode, keyrecord_t *record){ |
||||||
|
|
||||||
|
if (keycode < JS_BUTTON0 || keycode > JS_BUTTON_MAX){ |
||||||
|
return true; |
||||||
|
} else { |
||||||
|
if (record->event.pressed){ |
||||||
|
joystick_status.buttons[(keycode-JS_BUTTON0)/8] |= 1<<(keycode%8); |
||||||
|
} else { |
||||||
|
joystick_status.buttons[(keycode-JS_BUTTON0)/8] &= ~(1<<(keycode%8)); |
||||||
|
} |
||||||
|
|
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
} |
||||||
|
|
||||||
|
return true; |
||||||
|
} |
||||||
|
|
||||||
|
__attribute__ ((weak)) |
||||||
|
bool process_joystick_analog(){ |
||||||
|
#if JOYSTICK_AXES_COUNT > 0 |
||||||
|
for (int axis_index=0 ; axis_index<JOYSTICK_AXES_COUNT ; ++axis_index){ |
||||||
|
if (joystick_axes[axis_index].output_pin==JS_VIRTUAL_AXIS || joystick_axes[axis_index].input_pin==JS_VIRTUAL_AXIS){ |
||||||
|
continue; |
||||||
|
} |
||||||
|
|
||||||
|
setPinOutput(joystick_axes[axis_index].output_pin); |
||||||
|
writePinHigh(joystick_axes[axis_index].output_pin); |
||||||
|
|
||||||
|
//disable pull-up resistance
|
||||||
|
setPinInput(joystick_axes[axis_index].input_pin); |
||||||
|
writePinLow(joystick_axes[axis_index].input_pin); |
||||||
|
|
||||||
|
#ifdef __AVR__ |
||||||
|
int16_t axis_val = analogReadPin(joystick_axes[axis_index].input_pin); |
||||||
|
#else |
||||||
|
int16_t axis_val = 0; |
||||||
|
#endif |
||||||
|
if (axis_val!=joystick_status.axes[axis_index]){ |
||||||
|
joystick_status.axes[axis_index] = axis_val; |
||||||
|
joystick_status.status |= JS_UPDATED; |
||||||
|
} |
||||||
|
|
||||||
|
writePinLow(joystick_axes[axis_index].output_pin); |
||||||
|
} |
||||||
|
#endif |
||||||
|
return true; |
||||||
|
} |
||||||
@ -0,0 +1,13 @@ |
|||||||
|
#ifndef PROCESS_JOYSTICK_H |
||||||
|
#define PROCESS_JOYSTICK_H |
||||||
|
|
||||||
|
#include <stdint.h> |
||||||
|
#include "quantum.h" |
||||||
|
|
||||||
|
bool process_joystick(uint16_t keycode, keyrecord_t *record); |
||||||
|
|
||||||
|
void joystick_task(void); |
||||||
|
|
||||||
|
bool process_joystick_analog(void); |
||||||
|
|
||||||
|
#endif //PROCESS_JOYSTICK_H
|
||||||
Loading…
Reference in new issue