This is the source code for the USBify project, for connecting USB video
game controllers and joysticks to retro game consoles. This firmware runs
on the PIC24FJ128GB202 microcontroller.

http://www.ombertech.com/cnk/usbify/

Microcontroller: PIC24FJ64GB002 or PIC24FJ128GB202
Microcontroller Oscillator Frequency: 32MHz
Microcontroller CPU/Peripheral Clock Frequency: 16MHz
Clock Oscillator: Internal FRC oscillator
Compiler: xc16plusplus v1.33
Internal Modules Used: USB (Host), Output Compare PWM (OC1 & OC2), Program Flash Memory, UART2 (for debugging)
UART Speed: 9600 baud

DIRECTORIES

The root of the source directory contains the USB library based on USB Host
Library 2.0, but with lots of modifications to make it talk to the PIC24 USB
interface, use multiple drivers at once, and build with the XC16++ compiler.
https://github.com/felis/USB_Host_Shield_2.0/

"hid_report_parser" contains modified USB HID report parsing code from the fork
of the TinyUSB library by Fruit-Bat, which is used by the HIDJoyUSB driver
(which is the default driver used if none of the other drivers like the
attached device).
https://github.com/fruit-bat/tinyusb/tree/hid_micro_parser

"usbify" contains sub-directories for each console/adapter, which have their
own firmware builds and corresponding Makefiles inside.

"usbify/[console]/builds/" contain release builds of the current firmware in
hex format, ready for programming to a PIC24FJ128GB202 microcontroller. Build
settings for these should match the default Makefile (Bluetooth is enabled,
most serial debugging output is disabled).

BUILD REQUIREMENTS

* Microchip XC16 and the XC16++ unofficial PIC24 C++ compiler. v1.33 used.
https://www.microchip.com/en-us/tools-resources/develop/mplab-xc-compilers/xc16
https://github.com/fabio-d/xc16plusplus

* Microchip Libraries for Applications USB Host Driver v2013-06-15
https://www.microchip.com/en-us/tools-resources/develop/libraries/microchip-libraries-for-applications

* Microchip Data EEPROM Emulation Library v1.1.2
https://www.microchip.com/en-us/software-library/dspic33-pic24-data-eeprom-emulation

All build requirements are free to download and use.

BUILD

Install Microchip Libraries for Applications then enter the directory where it
was installed and apply the patch file inside the usbify-1.0 directory with
the following command:
  patch -p 1 < ../usbify-1.0/microchip_solutions_v2013-06-15_usbify_1.0.patch

Go to the desired console sub-directory inside the "usbify" directory and edit
the Makefile to point to the location where xc16 and Microchip Libraries for
Applications are installed:
XC16DIR := /opt/microchip/xc16/v1.33
MICROCHIP_USB_DIR := ../../../Microchip

You will also need to replace spaces in filenames in the Microchip Data EEPROM
Emulation Library with underscores to match the paths in the Makefile.

Comment/uncomment lines enabling Bluetooth and debugging output from the
different libraries as desired.

To build for the PIC24FJ64GB002, change the TARGET_CHIP setting. However the
firmware will need stripping down to fit in that chip. Disable Bluetooth, and
either remove unwanted drivers manually, or disabling all UART debugging and
linking to a dummy printf() function might be enough to make it fit.

Once edited to taste, run the build with the "make" command.

The resulting (hopefully) firmware.hex file can be written to the
microcontroller using pk2cmd or picpgm, if installed, with "make pkwrite" or
"make pgmwrite" respectively.

LICENSE

The USBify code and the USB Host Library 2.0 is released under the GPL v2
license. The TinyUSB "HID Micro Parser" is under the MIT license.

Microchip libraries are not included in this source code package because
their license only allows redistribution on microcontrollers, so the patch
is supplied for modifying the source code that can be downloaded for free
from the Microchip website.
