Adding a Joystick library, concurrently usable with Keyboard & Mouse (#692)

Co-authored-by: Benjamin Aigner <beni@asterics-foundation.org>

Author: Benjamin Aigner

.gitmodules

@@ -19,6 +19,9 @@
 [submodule "libraries/Mouse"]
 	path = libraries/Mouse
 	url = https://github.com/earlephilhower/Mouse
+[submodule "libraries/Joystick"]
+	path = libraries/Joystick
+	url = https://github.com/benjaminaigner/Joystick
 [submodule "libraries/Adafruit_TinyUSB_Arduino"]
 	path = libraries/Adafruit_TinyUSB_Arduino
 	url = https://github.com/adafruit/Adafruit_TinyUSB_Arduino.git

cores/rp2040/RP2040USB.cpp

@@ -91,7 +91,7 @@ const uint8_t *tud_descriptor_device_cb(void) {
         .iSerialNumber = USBD_STR_SERIAL,
         .bNumConfigurations = 1
     };
-    if (__USBInstallSerial && !__USBInstallKeyboard && !__USBInstallMouse && !__USBInstallMIDI) {
+    if (__USBInstallSerial && !__USBInstallKeyboard && !__USBInstallMouse && !__USBInstallJoystick && !__USBInstallMIDI) {
         // Can use as-is, this is the default USB case
         return (const uint8_t *)&usbd_desc_device;
     }
@@ -102,6 +102,9 @@ const uint8_t *tud_descriptor_device_cb(void) {
     if (__USBInstallMouse) {
         usbd_desc_device.idProduct |= 0x4000;
     }
+    if (__USBInstallJoystick) {
+        usbd_desc_device.idProduct |= 0x0100;
+    }
     if (__USBInstallMIDI) {
         usbd_desc_device.idProduct |= 0x2000;
     }
@@ -120,6 +123,17 @@ int __USBGetMouseReportID() {
     return __USBInstallKeyboard ? 2 : 1;
 }
 
+int __USBGetJoystickReportID() {
+    int i = 1;
+    if (__USBInstallKeyboard) {
+        i++;
+    }
+    if (__USBInstallMouse) {
+        i++;
+    }
+    return i;
+}
+
 static int      __hid_report_len = 0;
 static uint8_t *__hid_report     = nullptr;
 
@@ -131,37 +145,68 @@ static uint8_t *GetDescHIDReport(int *len) {
 }
 
 void __SetupDescHIDReport() {
-    if (__USBInstallKeyboard && __USBInstallMouse) {
-        uint8_t desc_hid_report[] = {
-            TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(1)),
-            TUD_HID_REPORT_DESC_MOUSE(HID_REPORT_ID(2))
-        };
-        __hid_report = (uint8_t *)malloc(sizeof(desc_hid_report));
-        if (__hid_report) {
-            __hid_report_len = sizeof(desc_hid_report);
-            memcpy(__hid_report, desc_hid_report, __hid_report_len);
+    //allocate memory for the HID report descriptors. We don't use them, but need the size here.
+    uint8_t desc_hid_report_mouse[] = { TUD_HID_REPORT_DESC_MOUSE(HID_REPORT_ID(1)) };
+    uint8_t desc_hid_report_joystick[] = { TUD_HID_REPORT_DESC_GAMEPAD(HID_REPORT_ID(1)) };
+    uint8_t desc_hid_report_keyboard[] = { TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(1)) };
+    int size = 0;
+
+    //accumulate the size of all used HID report descriptors
+    if (__USBInstallKeyboard) {
+        size += sizeof(desc_hid_report_keyboard);
+    }
+    if (__USBInstallMouse) {
+        size += sizeof(desc_hid_report_mouse);
+    }
+    if (__USBInstallJoystick) {
+        size += sizeof(desc_hid_report_joystick);
+    }
+
+    //no HID used at all
+    if (size == 0) {
+        __hid_report = nullptr;
+        __hid_report_len = 0;
+        return;
+    }
+
+    //allocate the "real" HID report descriptor
+    __hid_report = (uint8_t *)malloc(size);
+    if (__hid_report) {
+        __hid_report_len = size;
+
+        //now copy the descriptors
+
+        //1.) keyboard descriptor, if requested
+        if (__USBInstallKeyboard) {
+            memcpy(__hid_report, desc_hid_report_keyboard, sizeof(desc_hid_report_keyboard));
         }
-    } else if (__USBInstallKeyboard && ! __USBInstallMouse) {
-        uint8_t desc_hid_report[] = {
-            TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(1))
-        };
-        __hid_report = (uint8_t *)malloc(sizeof(desc_hid_report));
-        if (__hid_report) {
-            __hid_report_len = sizeof(desc_hid_report);
-            memcpy(__hid_report, desc_hid_report, __hid_report_len);
+
+        //2.) mouse descriptor, if necessary. Additional offset & new array is necessary if there is a keyboard.
+        if (__USBInstallMouse) {
+            //determine if we need an offset (USB keyboard is installed)
+            if (__USBInstallKeyboard) {
+                uint8_t desc_local[] = { TUD_HID_REPORT_DESC_MOUSE(HID_REPORT_ID(2)) };
+                memcpy(__hid_report + sizeof(desc_hid_report_keyboard), desc_local, sizeof(desc_local));
+            } else {
+                memcpy(__hid_report, desc_hid_report_mouse, sizeof(desc_hid_report_mouse));
+            }
         }
-    } else if (! __USBInstallKeyboard &&  __USBInstallMouse) {
-        uint8_t desc_hid_report[] = {
-            TUD_HID_REPORT_DESC_MOUSE(HID_REPORT_ID(1))
-        };
-        __hid_report = (uint8_t *)malloc(sizeof(desc_hid_report));
-        if (__hid_report) {
-            __hid_report_len = sizeof(desc_hid_report);
-            memcpy(__hid_report, desc_hid_report, __hid_report_len);
+
+        //3.) joystick descriptor. 2 additional checks are necessary for mouse and/or keyboard
+        if (__USBInstallJoystick) {
+            uint8_t reportid = 1;
+            int offset = 0;
+            if (__USBInstallKeyboard) {
+                reportid++;
+                offset += sizeof(desc_hid_report_keyboard);
+            }
+            if (__USBInstallMouse) {
+                reportid++;
+                offset += sizeof(desc_hid_report_mouse);
+            }
+            uint8_t desc_local[] = { TUD_HID_REPORT_DESC_GAMEPAD(HID_REPORT_ID(reportid)) };
+            memcpy(__hid_report + offset, desc_local, sizeof(desc_local));
         }
-    } else {
-        __hid_report = nullptr;
-        __hid_report_len = 0;
     }
 }
 
@@ -181,7 +226,7 @@ const uint8_t *tud_descriptor_configuration_cb(uint8_t index) {
 
 void __SetupUSBDescriptor() {
     if (!usbd_desc_cfg) {
-        bool hasHID = __USBInstallKeyboard || __USBInstallMouse;
+        bool hasHID = __USBInstallKeyboard || __USBInstallMouse || __USBInstallJoystick;
 
         uint8_t interface_count = (__USBInstallSerial ? 2 : 0) + (hasHID ? 1 : 0) + (__USBInstallMIDI ? 2 : 0);
 

cores/rp2040/RP2040USB.h

@@ -24,6 +24,7 @@
 // Weak function definitions for each type of endpoint
 extern void __USBInstallSerial() __attribute__((weak));
 extern void __USBInstallKeyboard() __attribute__((weak));
+extern void __USBInstallJoystick() __attribute__((weak));
 extern void __USBInstallMouse() __attribute__((weak));
 extern void __USBInstallMIDI() __attribute__((weak));
 
@@ -34,6 +35,7 @@ extern mutex_t __usb_mutex;
 // HID report ID inquiry (report ID will vary depending on the number/type of other HID)
 int __USBGetKeyboardReportID();
 int __USBGetMouseReportID();
+int __USBGetJoystickReportID();
 
 // Called by main() to init the USB HW/SW.
 void __USBStart();

docs/usb.rst

@@ -12,8 +12,9 @@ serial port, ``Serial`` as well as supporting automatic reset-to-upload
 from the IDE.
 
 The Arduino-Pico core includes ported versions of the basic Arduino
-``Keyboard`` and ``Mouse`` libraries.  These libraries allow you to
-emulate a keyboard or mouse with the Pico in your sketches.
+``Keyboard``, ``Mouse`` and ``Joystick`` libraries.  These libraries 
+allow you to emulate a keyboard, a gamepad or mouse (or all together) 
+with the Pico in your sketches.
 
 See the examples and Arduino Reference at
 https://www.arduino.cc/reference/en/language/functions/usb/keyboard/