Usb controller-32

USB Controller 32

A USB HID gamepad controller built on the PIC32MX250F128B microcontroller. The firmware reads button inputs from GPIO pins, two potentiometers on the PIC32 ADC, and an MCP23017 I2C I/O expander, then reports them to a host PC as a standard USB HID gamepad. The board-level serial path uses a MAX3232 level shifter, and the MCU clock is provided by a 20 MHz crystal. Built with MPLAB Harmony 3, FreeRTOS, and C++.

Features

• USB HID gamepad with 18 button inputs (2 direct GPIO + 16 via MCP23017)
• 8-byte HID input report with 18 buttons, hat switch, and two live analog axes
• MCP23017 I2C I/O expander with interrupt-driven input detection
• MAX3232-backed debug serial / RS-232 path
• POT_1 and POT_2 sampled on AN4 / AN5 for Z and Rz
• Send-on-change HID reports for buttons and potentiometer axes
• Rate-limited serial logging for potentiometer changes with POT_1 / POT_2 identification
• FreeRTOS-based task scheduling
• UART debug logging and USB/HID diagnostics
• Green and red status LEDs

Hardware Used

Main ICs and timing parts on this design:

• PIC32MX250F128B - main microcontroller, USB device controller, ADC, GPIO, I2C, and UART
• MCP23017 - 16-bit I2C GPIO expander for the additional button inputs
• MAX3232 - UART level shifter for the board's serial / RS-232 debug path
• 20 MHz crystal - external clock source for the PIC32MX250F128B (load caps C17/C18 must be 20 pF — see Crystal Load Capacitors)
• 2x linear potentiometers - analog controls for POT_1 and POT_2, mapped to HID Z and Rz
• Mini USB breakout - USB connector breakout for the device port, such as the small Adafruit mini USB breakout the board is using

Hardware Notes

• Crystal load capacitors C17/C18 must be 20 pF. A 0.1 µF value stops the 20 MHz crystal from oscillating on the PCB (the board powers up briefly, then drops off USB). It only appeared to work on the breadboard because the long jumper wires masked the oversized caps. Full explanation: Crystal Load Capacitors.

Architecture

UML Class Diagram

State Machine

Pin Assignment Table

PIC32MX250F128B Direct I/O

MCP23017 I/O Expander (I2C address 0x20)

Input/Output Summary

Getting Started

Prerequisites

• MPLAB X IDE or the MPLAB Extension for VS Code
• XC32 Compiler (v4.x or later)
• PIC32MX DFP v1.6.369
• PICkit 5 (or compatible Microchip programmer/debugger)
• Git

Install MPLAB for VS Code

1. Open VS Code (or VS Code Insiders).
2. Go to the Extensions view (Ctrl+Shift+X).
3. Search for "MPLAB" and install the Microchip MPLAB extension pack.
4. The extension will prompt you to install the XC32 compiler and required device packs if they are not found. Follow the prompts.
5. Restart VS Code after installation.

Clone and Build

git clone https://github.com/jcksnvllxr80/usb-controller-32.git
cd usb-controller-32

1. Open the folder in VS Code.
2. The MPLAB extension should detect the project automatically via the CMake configuration in the cmake/ directory.
3. Select the usb-controller-32 project and the default configuration from the MPLAB project view.
4. Click Build (or press Ctrl+Shift+B).

Program the Device

1. Connect the PICkit 5 to the ICSP header on your board (ensure correct pin 1 orientation).
2. In the MPLAB extension, select PICkit 5 as the hardware tool.
3. Set the programming speed to Low if you encounter connection issues.
4. Click Program to flash the .hex file to the PIC32MX250F128B.

Warning: Use a native USB 2.0 port when connecting this controller to the PC. On some machines, USB 3.x ports/controllers can fail enumeration or produce a Windows Code 10 error with this hardware. If your machine does not have a USB 2.0 port, connect the controller through a USB 2.0 hub.

Verify Operation

1. After programming, the device should enumerate as a USB HID gamepad on the host PC.
2. Open Set up USB game controllers (Windows) or a gamepad tester to confirm button presses and Z / Rz potentiometer movement are registered.
3. Connect a serial terminal (115200 baud, 8N1) to UART1 to view debug logs, potentiometer change logs, and issue commands.

UART Diagnostics

Helper scripts:

• powershell -ExecutionPolicy Bypass -File .\tools\uart_query.ps1
• powershell -ExecutionPolicy Bypass -File .\tools\uart_cmd.ps1 -cmd "status"

Useful commands:

• status - GPIO, USB, and LED summary
• usb - USB device state and register dump
• enum - enumeration counters and last setup request
• hid - HID readiness, send counters, and current report bytes
• usblog - recent USB transaction log
• usbdbg - toggle live USB debug logging
• usbreset - soft detach/reattach to force re-enumeration

Automatic serial logs:

• Potentiometer changes are logged automatically as [POT] POT_1 axis=... and/or [POT] POT_2 axis=...
• Logs are only emitted when the scaled axis value changes
• Pot logs are rate-limited to 5 lines per second total

Firmware Notes

• GPIO and MCP23017 interrupts only latch state. HID reports are built and sent from APP_Tasks().
• POT_1 and POT_2 are polled in APP_Tasks(), scaled from 10-bit ADC samples to 8-bit HID axis values, and mapped to HID Z and Rz.
• Potentiometer state is cached, so a new HID report is only queued when a button changes or when the last-sent Z / Rz byte changes.
• Potentiometer serial logs identify which input changed (POT_1, POT_2, or both), skip repeated values, and are rate-limited to 5 lines per second.
• HID reports are only queued when button or axis state changes, which keeps traffic and debug noise down.

Project Structure

usb-controller-32/
├── cmake/                      # CMake build configurations
├── docs/                       # Datasheets, block diagram, images
├── tools/                      # Flash and UART helper scripts
├── usb-controller-32/
│   ├── mcc/                    # MPLAB Code Configurator files
│   └── src/
│       ├── main.cpp            # Entry point (SYS_Initialize + SYS_Tasks)
│       ├── app.cpp / app.h     # App task, GPIO/MCP state, USB HID send path
│       ├── command_handler.cpp / .h # UART command parser and diagnostics
│       ├── gamepad.cpp / .h    # USB HID gamepad driver
│       ├── mcp23017.cpp / .h   # MCP23017 I2C I/O expander driver
│       ├── logger.cpp / .h     # UART debug logger (singleton)
│       ├── usb_debug.c / .h    # USB debug logging helpers
│       ├── config/             # Harmony-generated peripheral config
│       └── third_party/rtos/   # FreeRTOS source
└── README.md

Sponsor

PCB prototyping for this project is sponsored by PCBWay.

PCBWay makes it easy to go from design files to manufactured boards. Upload your Gerber files, pick your board specs (layers, thickness, surface finish, color, etc.), and get an instant quote. Orders typically ship within a few days. Their online ordering process is straightforward — just create an account, upload your files, review the specs, and check out.

License

See Microchip's license terms in the source file headers.