______                     ____        __ 
  / ____/___ _____ ___  ___  / __ )____  / /_
 / / __/ __ `/ __ `__ \/ _ \/ __  / __ \/ __/
/ /_/ / /_/ / / / / / /  __/ /_/ / /_/ / /_  
\____/\__,_/_/ /_/ /_/\___/_____/\____/\__/  

Authors: Elias Robinson and Jahan Khan
Logins: egrobins, jakhan
Date: 12/12/16
Class: CS1600

Project Description: 
	GameBot is an all in one retro gaming system for handheld and tabletop gameplay. Implementing RetroPie, our system is capable of emulating 52 different retro gaming systems ranging from the SEGA Genesis to the more modern PSP. Build on RetroPie's functionality, GameBot supports both handheld and table top play, with a built in LCD screen, speakers, and button pad, as well as external HDMI display output and USB controller input capabilities. When opened with an HDMI plugged in, GameBot will output video and audio to an external screen. Otherwise, GameBot can be played handheld with no external connections. The game system is streamlined to open on boot with a custom splashscreen video to give the system a futuristic feeling while still giving users the classic GameBoy experience. 

Hardware: 
	1.) Purchased Parts
		a.) Raspberry Pi 3 B
		b.) 3.5" LCD Screen - runs off of 12V. We had to make modifications to the circuit board of the LCD screen we purchased to run off of the Pi's 5V output. To do this, we ran the screen on 12V, and used a multimeter to find a voltage drop of 5V by prodding connections before and after various capacitors on the board. After finding a voltage drop around 5.2V between a pin of a capacitor and the ground, we soldered the 5V input of the Pi to the screen and it ran as planned. 
		c.) Button Pad PCB - wired to the GPIO pins of the Pi. When a pin is grounded, sends a button signal.
		d.) Audio Amplifier Chip & Speakers - wired to the composite output of the Pi. Switched on only when HDMI output is not plugged in. 
		e.) Battery Pack - 5V output to power the Pi and all subsequent parts.
		f.) USB controller
	
	2.) 3D Printing: designed shell for bottom of case to hold all parts in place. We printed two separate parts that fit together to hold all of our hardware in place. The bottom of the case holds our Raspberry Pi 3 B in place with no need for glue using pins that fit snugly into the Pi's corner holes. Above the Pi, our button pad PCB sits pressed to the polycarbonate top face for convenient GameBoy style handheld gaming. Next to the Pi, our battery is held in place with holes on the side of the case for easy charging and turning on/off. Above that, our 3.5" LCD display is mounted to the case. All designs were created using SketchUp Make, and printed with the MakerBots in Prince Lab. For the top of the case, we used a transparent polycarbonate sheet that we drilled and cut to accommodate  our buttons and speakers. 




Software: 
	1.) getRoms: program used to download and install games of your choosing from the internet to play on the GameBot. It deals with all necessary integration into emulation software to play immediately after the script terminates.

		a.) scraper.py: this script forms some of the backend of the program. It scrapes the popular ROM hosting website emuparadise.me for download links to a collection of games on 14 of the different systems supported by our emulation software. We configured the script to find the top 10 (more for some systems) most downloaded games for our favorite retro gaming systems. The script takes nothing as input and sends output to a tab-separated file for our download module to parse when run. Output takes the form of index \t game_system \t game_name \t download_link. Each link downloads a compressed ROM file when accessed. The script can be expanded to all 52 of the gaming systems supported, but we decided to limit it to 14 more popular systems based on the available ROM selection on emulationstation and to avoid the risk of downloading corrupt files.

		b.) romdl.py: this python script is used to download and extract roms from the internet. The input required to run gameBot is a tsv file that contains the system, title, and url of the games possible to download and a destination to put the game into. There are two options you can choose for downloading a game – you can see the available games for a specific system or you can see a comprehensive list of all the games that can be downloaded. Each game has a number next to its name and by entering that number into stdin you begin to download the game. The program requests the url for that game while setting several cookies to avoid having captcha and redirection issues. The request is then written into a file and runs a universal archiver on the newly written file to determine the type of file you have downloaded and then extract the file(s) to the designated folder. We then remove all unnecessary files that were downloaded during the process (.zip, etc…) and complete the script. 

		c.) Running program: after exiting RetroPie with f4, run "python getRoms" from /home/pi, where the files are stored. The terminal prompts lead you through the rest. Must have working network connection through the ethernet port. 

	2.) Extras: We also created several shell and C++ scripts to allow easy customization within the Emulation Station front-end. Some of these included scripts to allow easy switching between audio ports (hdmi to headphone jack or composite sound) and buttons in the RetroPie/EmulationStation gui that run the getRoms script or allow for easier changes between RetroPie themes. We also edited the startup script for Raspberry Pi to run our personally designed video splashcreen instead of displaying the Pi's startup scripts and terminal commands. We created the video in Adobe AfterEffects using the flare library. Much of the software is directly connected to the RetroPie code and cannot be run without a Raspberry Pi running RetroPie, so we have excluded them from the handin. 






Attributions: 
	1. RetroPie: versatile emulation software that supplements the Raspbian OS on a Raspberry Pi to allow gameplay of many different retro games for systems ranging from a GameBoy to a PSP. It is built on a set of other emulation softwares, two of which are listed below. More info can be found here: https://retropie.org.uk/
		a.) Emulation Station - the frontend for launching games on RetroPie. EmulationStation provides a customizable GUI for playing games on the various emulators that RetroPie supports.
		b.) RetroArch - the frontend for the Libretro API, which standardizes controller input for different systems and adds features for some emulators. 

	2. RetroGame: software to map the Raspberry Pi's GPIO pins to keyboard keys. Using this software enabled us to wire our button pad directly to the I/O pins of the Pi. When a pin grounded by pressing one of our buttons, RetroGame sends a button pressed signal to RetroPie. When the pin is no longer grounded, RetroGame sends a button released signal.