Merge remote-tracking branch 'upstream/develop'

1 files changed, 77 insertions, 16 deletions

diff --git a/quantum/joystick.h b/quantum/joystick.h
index 5d81b14ef2..0ac99aa590 100644
--- a/quantum/joystick.h
+++ b/quantum/joystick.h
@@ -1,31 +1,56 @@
+/* Copyright 2022
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 #pragma once
 
+#include <stdbool.h>
 #include <stdint.h>
+
 #include "gpio.h"
 
+/**
+ * \defgroup joystick
+ *
+ * HID Joystick
+ * \{
+ */
+
 #ifndef JOYSTICK_BUTTON_COUNT
 #    define JOYSTICK_BUTTON_COUNT 8
 #elif JOYSTICK_BUTTON_COUNT > 32
 #    error Joystick feature only supports up to 32 buttons
 #endif
 
-#ifndef JOYSTICK_AXES_COUNT
-#    define JOYSTICK_AXES_COUNT 4
-#elif JOYSTICK_AXES_COUNT > 6
+#ifndef JOYSTICK_AXIS_COUNT
+#    define JOYSTICK_AXIS_COUNT 2
+#elif JOYSTICK_AXIS_COUNT > 6
 #    error Joystick feature only supports up to 6 axes
 #endif
 
-#if JOYSTICK_AXES_COUNT == 0 && JOYSTICK_BUTTON_COUNT == 0
+#if JOYSTICK_AXIS_COUNT == 0 && JOYSTICK_BUTTON_COUNT == 0
 #    error Joystick feature requires at least one axis or button
 #endif
 
-#ifndef JOYSTICK_AXES_RESOLUTION
-#    define JOYSTICK_AXES_RESOLUTION 8
-#elif JOYSTICK_AXES_RESOLUTION < 8 || JOYSTICK_AXES_RESOLUTION > 16
-#    error JOYSTICK_AXES_RESOLUTION must be between 8 and 16
+#ifndef JOYSTICK_AXIS_RESOLUTION
+#    define JOYSTICK_AXIS_RESOLUTION 8
+#elif JOYSTICK_AXIS_RESOLUTION < 8 || JOYSTICK_AXIS_RESOLUTION > 16
+#    error JOYSTICK_AXIS_RESOLUTION must be between 8 and 16
 #endif
 
-#define JOYSTICK_RESOLUTION ((1L << (JOYSTICK_AXES_RESOLUTION - 1)) - 1)
+#define JOYSTICK_MAX_VALUE ((1L << (JOYSTICK_AXIS_RESOLUTION - 1)) - 1)
 
 // 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.
@@ -52,20 +77,56 @@ typedef struct {
     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 };
+extern joystick_config_t joystick_axes[JOYSTICK_AXIS_COUNT];
 
 typedef struct {
     uint8_t buttons[(JOYSTICK_BUTTON_COUNT - 1) / 8 + 1];
-
-    int16_t axes[JOYSTICK_AXES_COUNT];
-    uint8_t status : 2;
+    int16_t axes[JOYSTICK_AXIS_COUNT];
+    bool    dirty;
 } joystick_t;
 
-extern joystick_t joystick_status;
+extern joystick_t joystick_state;
+
+void joystick_task(void);
 
+/**
+ * \brief Send the joystick report to the host, if it has been marked as dirty.
+ */
 void joystick_flush(void);
 
+/**
+ * \brief Set the state of a button, and flush the report.
+ *
+ * \param button The index of the button to press, from 0 to 31.
+ */
 void register_joystick_button(uint8_t button);
+
+/**
+ * \brief Reset the state of a button, and flush the report.
+ *
+ * \param button The index of the button to release, from 0 to 31.
+ */
 void unregister_joystick_button(uint8_t button);
+
+/**
+ * \brief Sample and process the analog value of the given axis.
+ *
+ * \param axis The axis to read.
+ *
+ * \return A signed 16-bit integer, where 0 is the resting or mid point.
+ */
+int16_t joystick_read_axis(uint8_t axis);
+
+void joystick_read_axes(void);
+
+/**
+ * \brief Set the value of the given axis.
+ *
+ * \param axis The axis to set the value of.
+ * \param value The value to set.
+ */
+void joystick_set_axis(uint8_t axis, int16_t value);
+
+void host_joystick_send(joystick_t *joystick);
+
+/** \} */