USB Device Classes

 USB Descriptor Hierarchy
 ┌──────────────────────────────────┐
 │  Device Descriptor               │
 │  (VID, PID, USB version)         │
 │  ┌────────────────────────────┐  │
 │  │  Configuration 1           │  │
 │  │  ┌──────────────────────┐  │  │
 │  │  │  Interface 0: HID    │  │  │
 │  │  │  (Gamepad)           │  │  │
 │  │  │  ┌────────────────┐  │  │  │
 │  │  │  │ EP1 IN (INT)   │  │  │  │
 │  │  │  │ 8ms poll, 64B  │  │  │  │
 │  │  │  └────────────────┘  │  │  │
 │  │  └──────────────────────┘  │  │
 │  │  ┌──────────────────────┐  │  │
 │  │  │  Interface 1: CDC    │  │  │
 │  │  │  (Debug serial)      │  │  │
 │  │  │  EP2 IN/OUT (BULK)   │  │  │
 │  │  └──────────────────────┘  │  │
 │  └────────────────────────────┘  │
 └──────────────────────────────────┘

static const uint8_t desc_hid_report[] = {
    0x05, 0x01,        /* Usage Page (Generic Desktop)           */
    0x09, 0x05,        /* Usage (Game Pad)                       */
    0xA1, 0x01,        /* Collection (Application)               */

    /* --- Buttons --- */
    0x05, 0x09,        /*   Usage Page (Button)                  */
    0x19, 0x01,        /*   Usage Minimum (Button 1)             */
    0x29, 0x04,        /*   Usage Maximum (Button 4)             */
    0x15, 0x00,        /*   Logical Minimum (0)                  */
    0x25, 0x01,        /*   Logical Maximum (1)                  */
    0x95, 0x04,        /*   Report Count (4)                     */
    0x75, 0x01,        /*   Report Size (1 bit)                  */
    0x81, 0x02,        /*   Input (Data, Variable, Absolute)     */

    /* 4-bit padding to fill the rest of the byte */
    0x95, 0x01,        /*   Report Count (1)                     */
    0x75, 0x04,        /*   Report Size (4 bits)                 */
    0x81, 0x03,        /*   Input (Constant, Variable, Absolute) */

    /* --- Analog Axes --- */
    0x05, 0x01,        /*   Usage Page (Generic Desktop)         */
    0x09, 0x30,        /*   Usage (X)                            */
    0x09, 0x31,        /*   Usage (Y)                            */
    0x15, 0x81,        /*   Logical Minimum (-127)               */
    0x25, 0x7F,        /*   Logical Maximum (127)                */
    0x95, 0x02,        /*   Report Count (2)                     */
    0x75, 0x08,        /*   Report Size (8 bits)                 */
    0x81, 0x02,        /*   Input (Data, Variable, Absolute)     */

    0xC0               /* End Collection                         */
};

typedef struct __attribute__((packed)) {
    uint8_t buttons;   /* Bits 0-3: buttons A,B,X,Y. Bits 4-7: padding */
    int8_t  x;         /* Joystick X axis: -127 to 127 */
    int8_t  y;         /* Joystick Y axis: -127 to 127 */
} gamepad_report_t;

#ifndef TUSB_CONFIG_H
#define TUSB_CONFIG_H

#include "pico/stdlib.h"

/* Board and MCU selection (Pico SDK handles these) */
#define CFG_TUSB_MCU           OPT_MCU_RP2040
#define CFG_TUSB_OS            OPT_OS_PICO

/* USB device configuration */
#define CFG_TUD_ENABLED        1

/* Enable HID and CDC classes */
#define CFG_TUD_HID            1
#define CFG_TUD_CDC            1

/* Endpoint buffer sizes */
#define CFG_TUD_HID_EP_BUFSIZE 16
#define CFG_TUD_CDC_EP_BUFSIZE 64
#define CFG_TUD_CDC_RX_BUFSIZE 256
#define CFG_TUD_CDC_TX_BUFSIZE 256

#endif /* TUSB_CONFIG_H */

#include "tusb.h"
#include "pico/unique_id.h"

/* ---------- Device Descriptor ---------- */

static const tusb_desc_device_t desc_device = {
    .bLength            = sizeof(tusb_desc_device_t),
    .bDescriptorType    = TUSB_DESC_DEVICE,
    .bcdUSB             = 0x0200,         /* USB 2.0 */
    .bDeviceClass       = 0x00,           /* Defined at interface level */
    .bDeviceSubClass    = 0x00,
    .bDeviceProtocol    = 0x00,
    .bMaxPacketSize0    = CFG_TUD_ENDPOINT0_SIZE,
    .idVendor           = 0xCafe,         /* Test vendor ID */
    .idProduct          = 0x4001,         /* Product ID */
    .bcdDevice          = 0x0100,         /* Device version 1.0 */
    .iManufacturer      = 1,              /* String index 1 */
    .iProduct           = 2,              /* String index 2 */
    .iSerialNumber      = 3,              /* String index 3 */
    .bNumConfigurations = 1,
};

const uint8_t *tud_descriptor_device_cb(void)
{
    return (const uint8_t *)&desc_device;
}

/* ---------- HID Report Descriptor ---------- */

static const uint8_t desc_hid_report[] = {
    0x05, 0x01,        /* Usage Page (Generic Desktop)           */
    0x09, 0x05,        /* Usage (Game Pad)                       */
    0xA1, 0x01,        /* Collection (Application)               */

    /* Buttons */
    0x05, 0x09,        /*   Usage Page (Button)                  */
    0x19, 0x01,        /*   Usage Minimum (Button 1)             */
    0x29, 0x04,        /*   Usage Maximum (Button 4)             */
    0x15, 0x00,        /*   Logical Minimum (0)                  */
    0x25, 0x01,        /*   Logical Maximum (1)                  */
    0x95, 0x04,        /*   Report Count (4)                     */
    0x75, 0x01,        /*   Report Size (1 bit)                  */
    0x81, 0x02,        /*   Input (Data, Variable, Absolute)     */

    /* 4-bit padding */
    0x95, 0x01,        /*   Report Count (1)                     */
    0x75, 0x04,        /*   Report Size (4 bits)                 */
    0x81, 0x03,        /*   Input (Constant)                     */

    /* Analog axes */
    0x05, 0x01,        /*   Usage Page (Generic Desktop)         */
    0x09, 0x30,        /*   Usage (X)                            */
    0x09, 0x31,        /*   Usage (Y)                            */
    0x15, 0x81,        /*   Logical Minimum (-127)               */
    0x25, 0x7F,        /*   Logical Maximum (127)                */
    0x95, 0x02,        /*   Report Count (2)                     */
    0x75, 0x08,        /*   Report Size (8 bits)                 */
    0x81, 0x02,        /*   Input (Data, Variable, Absolute)     */

    0xC0               /* End Collection                         */
};

const uint8_t *tud_descriptor_hid_report_cb(uint8_t instance)
{
    (void)instance;
    return desc_hid_report;
}

/* ---------- Configuration Descriptor ---------- */

/*
 * Interface numbering:
 *   0 = CDC Communication Interface
 *   1 = CDC Data Interface
 *   2 = HID Interface
 *
 * Endpoint numbering:
 *   EP 0x81 = CDC Notification (interrupt IN)
 *   EP 0x02 = CDC Data OUT (bulk)
 *   EP 0x82 = CDC Data IN (bulk)
 *   EP 0x83 = HID IN (interrupt)
 */

#define ITF_NUM_CDC       0
#define ITF_NUM_CDC_DATA  1
#define ITF_NUM_HID       2
#define ITF_NUM_TOTAL     3

#define EPNUM_CDC_NOTIF   0x81
#define EPNUM_CDC_OUT     0x02
#define EPNUM_CDC_IN      0x82
#define EPNUM_HID         0x83

#define CONFIG_TOTAL_LEN  (TUD_CONFIG_DESC_LEN + TUD_CDC_DESC_LEN + \
                           TUD_HID_DESC_LEN)

static const uint8_t desc_configuration[] = {
    /* Configuration descriptor */
    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN,
                          0x00, 100),

    /* CDC: Communication + Data interfaces */
    TUD_CDC_DESCRIPTOR(ITF_NUM_CDC, 4, EPNUM_CDC_NOTIF, 8,
                       EPNUM_CDC_OUT, EPNUM_CDC_IN, 64),

    /* HID: Gamepad interface */
    TUD_HID_DESCRIPTOR(ITF_NUM_HID, 5, HID_ITF_PROTOCOL_NONE,
                       sizeof(desc_hid_report), EPNUM_HID,
                       CFG_TUD_HID_EP_BUFSIZE, 8),
};

const uint8_t *tud_descriptor_configuration_cb(uint8_t index)
{
    (void)index;
    return desc_configuration;
}

/* ---------- String Descriptors ---------- */

/* Language ID (US English) */
static const char *string_desc_arr[] = {
    [0] = (const char[]){0x09, 0x04},  /* Supported language: English */
    [1] = "Pico Workshop",             /* Manufacturer */
    [2] = "Pico Gamepad",              /* Product */
    [3] = NULL,                        /* Serial (filled from flash ID) */
    [4] = "Pico Gamepad CDC",          /* CDC interface */
    [5] = "Pico Gamepad HID",          /* HID interface */
};

static uint16_t _desc_str[32 + 1];

const uint16_t *tud_descriptor_string_cb(uint8_t index, uint16_t langid)
{
    (void)langid;

    uint8_t chr_count;

    if (index == 0) {
        memcpy(&_desc_str[1], string_desc_arr[0], 2);
        chr_count = 1;
    } else if (index == 3) {
        /* Generate serial number from the Pico's unique flash ID */
        pico_unique_board_id_t id;
        pico_get_unique_board_id(&id);

        chr_count = 0;
        for (int i = 0; i < PICO_UNIQUE_BOARD_ID_SIZE_BYTES; i++) {
            const char hex[] = "0123456789ABCDEF";
            _desc_str[1 + chr_count++] = hex[(id.id[i] >> 4) & 0x0F];
            _desc_str[1 + chr_count++] = hex[id.id[i] & 0x0F];
        }
    } else {
        if (index >= sizeof(string_desc_arr) / sizeof(string_desc_arr[0])) {
            return NULL;
        }

        const char *str = string_desc_arr[index];
        chr_count = (uint8_t)strlen(str);
        if (chr_count > 31) chr_count = 31;

        for (uint8_t i = 0; i < chr_count; i++) {
            _desc_str[1 + i] = str[i];
        }
    }

    /* First word: length and descriptor type */
    _desc_str[0] = (uint16_t)((TUSB_DESC_STRING << 8) |
                               (2 * chr_count + 2));

    return _desc_str;
}

 USB Gamepad Wiring
 ┌──────────────────┐    ┌──────────────┐
 │  Pico            │    │  Thumb       │
 │  GP26 (ADC0) ────┼────┤  Joystick   │
 │  GP27 (ADC1) ────┼────┤  VRx, VRy   │
 │  3V3 ────────────┼────┤  VCC        │
 │  GND ────────────┼────┤  GND        │
 │                  │    └──────────────┘
 │  GP10 ─┤BTN A├── GND
 │  GP11 ─┤BTN B├── GND
 │  GP12 ─┤BTN X├── GND
 │  GP13 ─┤BTN Y├── GND
 │                  │
 │      USB ────────┼──── To PC (HID Gamepad)
 └───────┤├─────────┘

#include <stdio.h>
#include <string.h>
#include <stdlib.h>

#include "pico/stdlib.h"
#include "hardware/adc.h"
#include "tusb.h"

/* ---------- Pin definitions ---------- */

#define JOY_X_PIN       26     /* ADC0 */
#define JOY_Y_PIN       27     /* ADC1 */
#define JOY_X_CHANNEL   0
#define JOY_Y_CHANNEL   1

#define BTN_A_PIN       10
#define BTN_B_PIN       11
#define BTN_X_PIN       12
#define BTN_Y_PIN       13

/* ---------- Joystick configuration ---------- */

#define ADC_CENTER      2048   /* 12-bit ADC midpoint */
#define DEAD_ZONE       100    /* Ignore values within this range of center */

/* ---------- Report structure (must match HID report descriptor) ---------- */

typedef struct __attribute__((packed)) {
    uint8_t buttons;   /* Bits 0-3: A, B, X, Y. Bits 4-7: padding (zero) */
    int8_t  x;         /* -127 to 127 */
    int8_t  y;         /* -127 to 127 */
} gamepad_report_t;

static gamepad_report_t last_report = {0, 0, 0};
static bool report_pending = false;

/* ---------- ADC helpers ---------- */

static void adc_setup(void)
{
    adc_init();
    adc_gpio_init(JOY_X_PIN);
    adc_gpio_init(JOY_Y_PIN);
}

static uint16_t adc_read_channel(uint8_t channel)
{
    adc_select_input(channel);
    return adc_read();
}

/* Convert 12-bit ADC (0-4095) to signed 8-bit (-127 to 127) with dead zone */
static int8_t adc_to_axis(uint16_t raw)
{
    int32_t centered = (int32_t)raw - ADC_CENTER;

    /* Apply dead zone: if the joystick is near center, report zero */
    if (abs((int)centered) < DEAD_ZONE) {
        return 0;
    }

    /* Scale from [-2048, 2047] to [-127, 127] */
    int32_t scaled = (centered * 127) / 2048;

    /* Clamp */
    if (scaled > 127)  scaled = 127;
    if (scaled < -127) scaled = -127;

    return (int8_t)scaled;
}

/* ---------- Button helpers ---------- */

static const uint8_t btn_pins[] = {BTN_A_PIN, BTN_B_PIN, BTN_X_PIN, BTN_Y_PIN};

static void buttons_setup(void)
{
    for (int i = 0; i < 4; i++) {
        gpio_init(btn_pins[i]);
        gpio_set_dir(btn_pins[i], GPIO_IN);
        gpio_pull_up(btn_pins[i]);
    }
}

static uint8_t buttons_read(void)
{
    uint8_t result = 0;

    for (int i = 0; i < 4; i++) {
        /* Button pressed = pin LOW (active low with pull-up) */
        if (!gpio_get(btn_pins[i])) {
            result |= (1 << i);
        }
    }

    return result;
}

/* ---------- HID report helpers ---------- */

static void send_gamepad_report(void)
{
    gamepad_report_t report;

    report.buttons = buttons_read();
    report.x = adc_to_axis(adc_read_channel(JOY_X_CHANNEL));
    report.y = adc_to_axis(adc_read_channel(JOY_Y_CHANNEL));

    /* Only send if something changed, or periodically to keep alive */
    if (memcmp(&report, &last_report, sizeof(report)) != 0 || report_pending) {
        if (tud_hid_ready()) {
            tud_hid_report(0, &report, sizeof(report));
            last_report = report;
            report_pending = false;
        }
    }
}

/* ---------- TinyUSB HID callbacks ---------- */

/* Called when a report transfer completes. Schedule the next one. */
void tud_hid_report_complete_cb(uint8_t instance, uint8_t const *report,
                                 uint16_t len)
{
    (void)instance;
    (void)report;
    (void)len;

    /* Mark that we should send another report on the next cycle */
    report_pending = true;
}

/* Called when the host sends a SET_REPORT request (e.g., LED indicators).
   Our gamepad has no outputs, so we just acknowledge it. */
void tud_hid_set_report_cb(uint8_t instance, uint8_t report_id,
                            hid_report_type_t report_type,
                            uint8_t const *buffer, uint16_t bufsize)
{
    (void)instance;
    (void)report_id;
    (void)report_type;
    (void)buffer;
    (void)bufsize;
}

/* Called when the host sends a GET_REPORT request.
   Return the current gamepad state. */
uint16_t tud_hid_get_report_cb(uint8_t instance, uint8_t report_id,
                                hid_report_type_t report_type,
                                uint8_t *buffer, uint16_t reqlen)
{
    (void)instance;
    (void)report_id;
    (void)report_type;

    uint16_t copy_len = (reqlen < sizeof(last_report)) ? reqlen
                                                       : sizeof(last_report);
    memcpy(buffer, &last_report, copy_len);
    return copy_len;
}

/* ---------- CDC debug output ---------- */

static void cdc_debug_print(const gamepad_report_t *r)
{
    if (tud_cdc_connected()) {
        char buf[64];
        int len = snprintf(buf, sizeof(buf),
                           "BTN:0x%02X X:%4d Y:%4d\r\n",
                           r->buttons, r->x, r->y);
        tud_cdc_write(buf, (uint32_t)len);
        tud_cdc_write_flush();
    }
}

/* ---------- Main ---------- */

int main(void)
{
    /* Initialize the Pico board (sets up clocks, GPIO) */
    board_init();

    /* Initialize TinyUSB device stack */
    tusb_init();

    /* Initialize ADC for joystick */
    adc_setup();

    /* Initialize button GPIOs */
    buttons_setup();

    /* Track time for periodic debug output */
    uint32_t last_debug_ms = 0;

    while (1) {
        /* Let TinyUSB process USB events */
        tud_task();

        /* Send HID report if the device is mounted and ready */
        if (tud_mounted()) {
            send_gamepad_report();
        }

        /* Print debug info over CDC every 250 ms */
        uint32_t now = board_millis();
        if (now - last_debug_ms >= 250) {
            last_debug_ms = now;
            cdc_debug_print(&last_report);
        }
    }

    return 0;
}

void tud_cdc_line_state_cb(uint8_t itf, bool dtr, bool rts)
{
    (void)itf;
    (void)rts;

    if (dtr) {
        /* Terminal connected. Optionally reset state or print a banner. */
        tud_cdc_write_str("Pico Gamepad Debug Console\r\n");
        tud_cdc_write_flush();
    }
}

cmake_minimum_required(VERSION 3.13)

# Pull in the Pico SDK
include(pico_sdk_import.cmake)

project(pico-gamepad C CXX ASM)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

# Initialize the Pico SDK
pico_sdk_init()

add_executable(pico-gamepad
    main.c
    usb_descriptors.c
)

# Include the current directory for tusb_config.h
target_include_directories(pico-gamepad PRIVATE
    ${CMAKE_CURRENT_LIST_DIR}
)

# Link against the Pico SDK and TinyUSB libraries
target_link_libraries(pico-gamepad
    pico_stdlib
    pico_unique_id
    hardware_adc
    tinyusb_device
    tinyusb_board
)

# Disable default USB and UART stdio (we handle USB ourselves via TinyUSB)
pico_enable_stdio_usb(pico-gamepad 0)
pico_enable_stdio_uart(pico-gamepad 0)

# Generate UF2 output for drag-and-drop flashing
pico_add_extra_outputs(pico-gamepad)