usb64

.github/workflows/build.yml

@@ -0,0 +1,57 @@
+name: Build
+
+on:
+  pull_request:
+    branches:
+      - master
+      - dev
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_TAG: 0
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v1
+      with:
+        submodules: recursive
+
+    - name: Set up Python
+      uses: actions/setup-python@v1
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install platformio
+        export BUILD_TAG=build-$(date -u +'%Y%m%d%H%M')
+        echo "::set-env name=BUILD_TAG::$BUILD_TAG"
+
+    - name: Compile code
+      run: platformio run -e teensy41
+
+    - if: github.event_name == 'push' 
+      name: Create Release
+      id: create_release
+      uses: "actions/create-release@v1"
+      with:
+        tag_name: ${{ env.BUILD_TAG }}
+        release_name: ${{ env.BUILD_TAG }}
+        draft: false
+        prerelease: false
+
+    - if: github.event_name == 'push' 
+      name: Upload binary to release
+      id: upload-release-asset 
+      uses: actions/upload-release-asset@v1
+      with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: .pio/build/teensy41/firmware.hex
+          asset_name: firmware-teensy41.hex
+          asset_content_type: application/hex

.gitignore

@@ -0,0 +1,4 @@
+.pio
+.vscode
+include
+test

.gitmodules

@@ -0,0 +1,11 @@
+[submodule "src/printf"]
+	path = src/printf
+	url = https://github.com/mpaland/printf
+
+[submodule "src/tinyalloc"]
+	path = src/tinyalloc
+	url = https://github.com/thi-ng/tinyalloc.git
+
+[submodule "src/USBHost_t36"]
+	path = src/USBHost_t36
+	url = https://github.com/Ryzee119/USBHost_t36.git

COMPILE.md

@@ -0,0 +1,24 @@
+## Compile
+### CLI (Requires python and python-pip)
+```
+git clone https://github.com/Ryzee119/usb64.git --recursive
+python -m pip install --upgrade pip
+pip install platformio
+cd usb64
+platformio run -e teensy41
+```
+### Visual Studio Code
+* Download and install [Visual Studio Code](https://code.visualstudio.com/).
+* Install the [PlatformIO IDE](https://platformio.org/platformio-ide) plugin.
+* Clone this repo recursively `git clone https://github.com/Ryzee119/usb64.git --recursive`
+* In Visual Studio Code `File > Open Folder... > usb64`
+* Hit build on the Platform IO toolbar (`✓`).
+
+## Program
+### Teensy (using Teensy Loader)
+* Connect the Teensy to your PC using a MicroUSB cable.
+* Run the [Teensy Loader Application](https://www.pjrc.com/teensy/loader.html).
+
+### Teensy (using Visual Studio Code)
+* Setup Visual Studio Code as per the Compile instructions.
+* Hit the program button on the Platform IO toolbar (`→`).

INSTALL.md

@@ -0,0 +1,25 @@
+# Hardware Setup
+* Install up to two PSRAM chips on the designated footprint. Note one is optional, two is recommended.
+* Install a 5 x 0.1" pin header on the USB OTG Header.  
+
+<img src="./images/install_setup.png" alt="setup" width="75%"/>
+
+# Quick Start
+* Program the usb64 as per [compilation instructions](./COMPILE.md).
+* Connect a usb64 compatible USB controller.
+* Connect the player data lines, atleast one ground line and one 3.3V line to/from the N64 Console
+* Power on the Nintendo 64 console.
+* Power on the usb64 (5V via MicroUSB cable).  
+
+<img src="./images/install_basic.png" alt="basic" width="75%"/>
+
+# Advanced Usages
+* Use a USB hub to connect up to four usb64 compatible controllers. An externally powered hub may be required.  
+* Hardwire a custom N64 controller to the designated IO (Each digital pin is internally pulled-up, Analog input respect to VCC, VCC/2 is central position).
+* Hook up a Raspberry Pi or similar via I2C and send button presses via I2C.  
+
+<img src="./images/install_advanced.png" alt="advanced" width="75%"/>
+
+## License and Attribution
+usb64 is shared under the [MIT license](https://github.com/Ryzee119/usb64/blob/dev/LICENSE), however this project includes code by others. Refer to the list below.
+* [N64 Console artwork](https://icon-library.net/icon/nintendo-64-icon-23.html) shared under [CC0 Public Domain Licence](https://creativecommons.org/publicdomain/zero/1.0/).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Ryan Wendland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,69 @@
+<img src="./images/usb64_logo.png" alt="basic" width="208px"/>  
+
+![Build](https://github.com/Ryzee119/usb64/workflows/Build/badge.svg) ![badge](https://img.shields.io/badge/license-MIT-green)  
+A project developed to use USB controllers on the Nintendo 64 console.  
+Precompiled binaries can be downloaded from [Releases](https://github.com/Ryzee119/usb64/releases).  
+**NOTE: This project is still in development and bugs are certainly still present. I plan to play alot of N64 to test :smile:.**
+
+- [x] N64 controller emulation (up to four controllers at once!).
+- [x] Rumblepak emulation.
+- [x] Mempak emulation with four selectable banks. Technically unlimited.
+- [x] Transferpak emulation. Put Gameboy ROMS on an SD Card!
+- [x] N64 mouse emulation. Use a USB Mouse!
+- [x] Configurable deadzones and sensitivity from the N64 Console.
+- [x] True dual analog sticks with GoldenEye and Perfect Dark.
+- [x] SD card driver with FATFS support for storage/backup of Gameboy ROMS, mempaks etc.
+- [x] A single hardwired controller interface for ultimate hacking.
+
+## Todo
+- [ ] Raspberry Pi interface or equivalent for all other USB controllers.
+- [ ] More inbuilt USB controller drivers.
+- [ ] Touch LCD Support.
+
+## Supported Controllers
+- Bluetooth 8bitdo/compatible controllers via the [8BitDo Wireless USB Adapter](https://www.8bitdo.com/wireless-usb-adapter/)
+- Xbox one Wired (Genuine Only)
+- Xbox 360 Wired
+- Xbox 360 Wireless (Via PC USB Receiver)
+- Raspberry Pi interface or equivalent for all other USB controllers.
+- A hardwired controller, use your own buttons etc.
+
+## Controls
+- Back + D-Pad = Insert Mempak banks 1 to 4
+- Back + LB = Insert Rumblepak
+- Back + RB = Insert Transferpak
+- Back + Start = Select *virtual pak* (Use in-game mempak managers to configure the device)
+- Back + B = Switch to true dual-analog stick more for GoldenEye 007/Perfect Dark
+- Back + A = Backup buffered memory to SD Card **(DO THIS BEFORE POWER OFF!)**
+
+## Needed Parts
+| Qty | Part Description | Link |
+|--|--|--|
+| 1 | Teensy 4.1 | https://www.pjrc.com/store/teensy41.html |
+| 1 | USB Host Cable | https://www.pjrc.com/store/cable_usb_host_t36.html |
+| 3 | 0.1" Pin Header | https://www.pjrc.com/store/header_24x1.html |
+| 2 | 64Mbit PSRAM  SOIC-8 | https://www.pjrc.com/store/psram.html |
+| 4 | N64 Controller Extensions | [AliExpress](https://www.aliexpress.com/wholesale?catId=0&SearchText=n64%20controller%20extension) |
+| 1 | MicroSD Card | - |
+| 1 | Case | To do |
+| 1 | PCB breakout board | To do |
+
+Note: PSRAM model numbers are IPS6404L-SQ-SPN or ESP-PSRAM64H.
+
+## Compile and Program
+See [COMPILE.md](./COMPILE.md).
+
+## Install
+See [INSTALL.md](./INSTALL.md).
+
+## How to Use
+See [USAGE.md](./USAGE.md).
+
+## License and Attribution
+usb64 is shared under the [MIT license](https://github.com/Ryzee119/usb64/blob/dev/LICENSE), however this project includes code by others. Refer to the list below.
+* [mpaland](https://github.com/mpaland)/**[printf](https://github.com/mpaland/printf)** shared under the [MIT License](https://github.com/mpaland/printf/blob/master/LICENSE).
+* [thi-ng](https://github.com/thi-ng)/**[tinyalloc](https://github.com/thi-ng/tinyalloc)** shared under the [Apache-2.0 License](https://github.com/thi-ng/tinyalloc/blob/master/LICENSE).
+* [FatFs by ChaN](http://elm-chan.org/fsw/ff/00index_e.html) shared under a [BSD-style license](https://github.com/Ryzee119/usb64/blob/dev/src/fatfs/LICENSE.txt).
+* [USBHost_t36 fork](https://github.com/Ryzee119/USBHost_t36) shared under an '[MIT or MIT-like license](https://forum.pjrc.com/threads/29382-open-source-license-issues-when-using-teensy-products?p=79667&viewfull=1#post79667)'.
+* [Teensy cores](https://github.com/PaulStoffregen/cores) shared under an '[MIT or MIT-like license](https://forum.pjrc.com/threads/29382-open-source-license-issues-when-using-teensy-products?p=79667&viewfull=1#post79667)'.
+* [MBC emulation code](src/n64/n64_transferpak_gbcarts.c) is adapted from [Peanut-GB](https://github.com/deltabeard/Peanut-GB) shared under an MIT License.

USAGE.md

@@ -0,0 +1,50 @@
+# Usage
+* [Mempaks](#mempaks)
+* [Rumblepaks](#rumblepaks)
+* [Transferpaks](#transferpaks)
+* [Virtualpak](#virtualpak)
+* [Dual Stick Mode](#dual-stick-mode)
+* [N64 Mouse](#n64-mouse)
+* [Debug](#debug)
+
+## Mempaks
+* usb64 can simulate four Mempaks simultaneously. To select a Mempak press `BACK+D-PAD` direction to select the respective bank.
+* Two controllers cannot have the same bank selected. The second controller will revert to a Rumblepak.
+* Mempak saves are managed in RAM, so you need to be flushed to the SD card. You can do this by holding BACK then pressing A. usb64 will also sense when the n64 is powered off and automatically flush the RAM to the SD card.
+* Inserting the SD card into your PC will show Mempaks as `MEMPAKXX.MPK` where XX is the bank number. You can back these up to your PC.
+
+## Rumblepaks
+* usb64 can simulate four Rumblepaks simultaneously. Rumblepaks are the default peripheral on power up. To select a Rumblepak press `BACK+LB`.
+* The usb controller must support force feedback.
+
+## Transferpaks
+* usb64 can simulate four transferpaks simulateneously. The select a Transferpak press `BACK+RB`. The transferpak will attempt to load the previously set Gameboy or Gameboy Colour ROM from the SD Card.
+* To select the ROM to load, you must first use the [*VirtualPak*](#virtualpak). If a ROM isn't selected, or fails to load, it will revert to a Rumblepak.
+* Avoid having two controllers access the same ROM at once.
+* Gameboy ROMS that save the SRAM, can be backed up to the SD Card by pressing `BACK+A`. Note: Don't do this mid game as it causes the controller to disconnect briefly and the game might error out.
+* Gameboy saves can be copied over to the SD Card for use with the Transferpak. The file name must match the ROM save with a `.SAV` extension.
+* You can simulate four transferpaks, with four difference ROMS, with four different save files! <p align="center"><img src="./images/tpak_6.png" alt="tpak_6" width="35%"/>  <img src="./images/tpak_7.png" alt="tpak_7" width="35%"/></p> <p align="center"><img src="./images/silver.gif" alt="silver" width="35%"/>  <img src="./images/tpak_1.png" alt="tpak_1" width="35%"/></p> <p align="center"><img src="./images/tpak_5.png" alt="tpak_5" width="35%"/>  <img src="./images/tpak_8.png" alt="tpak_8" width="35%"/></p> 
+
+## Virtualpak
+* The Virtualpak is one of my favourite features. It's like a Mempak, but is not used for save files. It exploits the Mempak managers built into some N64 games to configure the usb64 device!
+* To select the Virtualpak press `BACK+START`.
+* To use the Virtualpak, boot into a game that has a Mempak manager. Some games will work better than others. `Army Men: Air Combat` is a good one. `Perfect Dark` works well too. Hold START whilst the game is booting to access the Mempak manager. The follow screens show `Army Men: Air Combat` and `Perfect Dark` as an example. <p align="center"><img src="./images/vp_main.png" alt="vp_main" width="35%"/>  <img src="./images/vp_perfectdark.png" alt="vp_perfectdark" width="35%"/></p>
+* To select an item, you actually delete that note from the Mempak. usb64 detects what row you selected as if navigating a menu!
+* **TPAK SETTINGS** is used to configure what ROM to load into the Transferpak. This will scan the SD card for files with `.gb` and `.gbc` extensions. A `*` will print next to the currently set ROM. You can have up to ten ROMs on the SD card. After this they will just get ignored. <p align="center"><img src="./images/vp_tpak.png" alt="vp_tpak" width="35%"/></p>
+* **CONT SETTINGS** is used to configure the controller. You can change deadzone, Sensitivity, toggle on/off snapping to 45deg angles and toggle on/off a octagonal N64 stick correction. The set values is shown as a number next to the row. Each controller can be configured individually. Note: Some controllers will have deadzones or 45 degree angle snapping built in. For these, usb64 can't disable it. <p align="center"><img src="./images/vp_cont.png" alt="vp_cont" width="35%"/></p>
+* **USB64 INFO1** shows what controller is connected to that port. <p align="center"><img src="./images/vp_info1.png" alt="vp_info1" width="35%"/></p>
+* **USB64 INFO2** is currently a placeholder.
+
+## Dual Stick Mode
+* Dual stick mode exploits a feature present and Perfect Dark and GoldenEye 007 to use two controllers at once for true dual analog stick input.
+* To use, the usb64 must be connected to controller port one and two as a minimum. It works by simulating two controllers with one and injecting the 2nd analog stick into port two. If a 2nd controller is connected to the usb64 when using this mode, it will get pushed to slot 3.
+* To enable press `START+B`.
+* Set the game controller input for dual stick mode. It has been designed to work best with `Layout 2.4`. <p align="center"><img src="./images/dual_goldeneye.png" alt="dual_goldeneye" width="35%"/>  <img src="./images/dual_perfectdark.png" alt="dual_perfectdark" width="35%"/></p>
+
+## N64 Mouse
+* usb64 can simulate four N64 Mouse peripherals simulateneously!
+* Just plug in a USB mouse and the usb64 will auto detect it and emulate a N64 Mouse.
+* The middle mouse button is mapped to START. <p align="center"><img src="./images/mouse_2.png" alt="mouse_2" width="35%"/> <img src="./images/mouse_1.png" alt="mouse_1" width="35%"/></p>
+
+## Debug
+* There's alot going, and currently it may not be clear what the usb64 is doing. Until something better is implemented, you can connect the usb64 to your PC via a MicroUSB cable. This will enumerate as a serial comport. Connect to it with your favourite terminal to get some feedback. The code can be recompiled with [additional debug flags](./src/usb64_conf.h). <p align="center"><img src="./images/debug.png" alt="debug" width="65%"/></p>

platformio.ini

@@ -0,0 +1,69 @@
+; MIT License
+; 
+; Copyright (c) [2020] [Ryan Wendland]
+; 
+; Permission is hereby granted, free of charge, to any person obtaining a copy
+; of this software and associated documentation files (the "Software"), to deal
+; in the Software without restriction, including without limitation the rights
+; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+; copies of the Software, and to permit persons to whom the Software is
+; furnished to do so, subject to the following conditions:
+; 
+; The above copyright notice and this permission notice shall be included in all
+; copies or substantial portions of the Software.
+; 
+; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+; SOFTWARE.
+;
+
+[common_env_data]
+src_filter =
+    +<*.cpp> +<*.c>
+    +<fatfs/*.c>
+    +<fatfs/*.cpp>
+    +<n64/*.c>
+    +<printf/*.c>
+    +<tinyalloc/*.c>
+
+build_flags =
+    -O2
+    -Wall
+    -Isrc/
+    -Isrc/fatfs
+    -Isrc/n64
+    -Isrc/printf
+    -Isrc/tinyalloc
+
+    ; Printf Configuration
+    -DPRINTF_DISABLE_SUPPORT_FLOAT
+    -DPRINTF_DISABLE_SUPPORT_EXPONENTIAL
+    -DPRINTF_DISABLE_SUPPORT_LONG_LONG
+    -DPRINTF_DISABLE_SUPPORT_PTRDIFF_T
+
+    ; Tinyalloc Configuration
+    -DTA_DISABLE_COMPACT
+
+[env:teensy41]
+platform = teensy
+board = teensy41
+framework = arduino
+monitor_port = COM25
+monitor_speed = 256000
+
+; Disable the inbuilt framework lib so I can use my own fork
+lib_ignore = USBHost_t36
+
+src_filter =
+    ${common_env_data.src_filter}
+    +<USBHost_t36/*.cpp>
+
+build_flags =
+    ${common_env_data.build_flags}
+    -Isrc/USBHost_t36
+    ; -DUSBHOST_PRINT_DEBUG
+    ; -DDEBUG_JOYSTICK