Add real magenboy docs to the repo

Improve the readme too
alloncm · Oct 6, 2022 · b89ec6c · b89ec6c
1 parent c76f570
commit b89ec6c
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -19,16 +19,33 @@ The main goal of this project is to be able to play Pokemon on my own emulator.
 cargo build --release --features [optional_features]
 ```
 #### Optional features:
-* `static-sdl` - will link statically to sdl2.
-On by default (to turn off pass `--no-default-features`)
+* `sdl` - Link to sdl2 (On by default, other features turn on)
+* `static-sdl` - will link statically to sdl2 
+On by default 
 * `sdl-resample` - Use the audio resampler from sdl2 library and a manual one I wrote
 * `push-audio` - Use a push methododlogy instead of pull for the delivery of the sound samples to sdl2
 * `static-scale` - Will use a fixed scale values for the renderer instead of addapting to the screen size
 * `u16pixel` - pixels are represented by 16 bits and not 32 bits - neccessary for interfacing the ili9341 spi lcd
+* `apu` - Turn on the apu (On by default, other features turn on)
 * `rpi` - Input is from the RPI GPIO pins and output is to an ili9341 spi lcd connected to the RPI GPIO pins, activates the `u16pixel` feature.
 * `mmio` - Will interface the spi lcd screen using the Memory Mapped IO interface of the RPI for better performance (uses the DMA peripherals as well, activates the `rpi` feature.
 * `terminal-menu` - replace the gui menu with a terminal menu, since it is more capable this is the defualt
 
+> **Note** to turn off on by default features pass `--no-default-features` when building
+
+### Key bindings:
+
+| Joypad     | Keyboard    |
+| ---------- | ----------- |
+| A          | X           |
+| B          | Z           |
+| Start      | S           |
+| Select     | A           |
+| Dpad Up    | Up arrow    |
+| Dpad Down  | Down arrow  |
+| Dpad Left  | Left arrow  |
+| Dpad Right | Right arrow |
+
 ### Running
 
 #### Desktop
@@ -37,7 +54,7 @@ magenboy [path_to_rom] [other_optional_flags]
 ```
 
 #### Raspberry Pi
-Coming soon!
+See - [RealMagenBoy](RealMagenBoy.md)
 
 ### Optional flags
 
@@ -47,6 +64,7 @@ Coming soon!
 * `--no-vsync` - Disable vsync
 * `--bootrom [path to bootrom file]` - Specify the path for a bootrom (If not specified the emualtor will look for `dmg_boot.bin` at the cwd)
 * `--rom-menu [path to roms folder]` - Opens an interactive dialog uopn start to choose the rom from the folder
+Choose a game with the Joypad bindings (Dpad and A to confirm)
 
 ## GameBoy
 

diff --git a/RealMagenBoy.md b/RealMagenBoy.md
@@ -0,0 +1,116 @@
+# RealMagenBoy!
+
+This doc conatain notes and instructions on how to make a real life gameboy using the MagenBoy emulator, a RaspberryPi, an SPI display and a few buttons
+
+## Compatability 
+I have tested this on the following devices:
+* Raspberry Pi 4 model B 
+* Raspberry Pi zero2 W 
+
+So theoritacly the following devices should also work:
+* Raspberry Pi 3 model B 
+* Raspberry Pi 3 model B+
+* Raspberry Pi 400
+
+Currently MagenBoy isn't fast enough to run on older RPi's
+
+## Required parts
+* Fast enough Raspberry Pi (See Compatability)
+* An ili9341 spi display - [The one I use](http://www.lcdwiki.com/3.2inch_SPI_Module_ILI9341_SKU:MSP3218), can be found on aliexpress or ebay for about 10$
+* Buttons - I recommend to buy gameboy buttons and connect them with tactile switch buttons also recommend to get soft tactile switch buttons for the dpad
+* Resistors - Im not an EE but it is recommended to not connect the buttons directly to the GPIO but instead add a resistor to protect the Pi (Again not a EE)
+* Jumper cables - to connect all the parts together 
+* Prototype PCB - The green flat ones with holes, to connect to buttons to
+* Solderer - to connect the buttons and the resistors to the prototype PCB
+* A case - this is optional, but if you have a case (or a way to make one) it will make it way more awsome
+
+## Assembling
+After we gathered all the parts lets start assembling.
+
+### Connect the SPI display
+Right now Im ignoring the touch control and connecting like this table to the RPi
+
+```
+lcd | RPI   |   comment
+1   |   1   |   power - connected to the 3.3 pin
+2   |   9   |   ground
+3   |   24  |   spi chip select - connected to the spi0 compatible pin
+4   |   8   |   reset - pin (chose pin randomaly) GPIO BCM 14
+5   |   10  |   dc pin (chose pin randomaly) GPIO BCM 15
+6   |   19  |   spi bus write data signal - connected to the spi0 compatible pin
+7   |   23  |   sck - spi bus clock signal
+8   |   22  |   led - configurable, connected to power GPIO BCM 25
+9   |   21  |   spi bus read data signal - connected to the spi0 compatible pin
+```
+
+> **Notice** The RPi peripherals speed is coupled to main CPU speed to in order to get consistent performance Im setting it a fix value
+
+Edit `/boot/config.txt` with the following configurations
+```
+core_freq=300
+core_freq_min=300
+```
+Make sure that dtparam=spi is turned of, should be commented out or be like this `dtparam=spi=off` (MagenBoy interface the SPI peripherlas directly without the linux driver for better transfer times)
+
+### Buttons
+I created (using the prototypes PCB's and a solderer) 2 PCB's one for the Dpad and one for A, B, Start, Select buttons, each contains 4 buttons and exposes 6 pins to be connected to a jumper cable.
+
+#### Dpad connection
+```
+Pin | RPI |comment
+1   | 40  | DPAD left connected to GPIO 21
+2   | 38  | DPAD right connected to GPIO 20
+3   | 36  | DPAD down connected to GPIO 16
+4   | 39  | ground pin
+5   | 17  | power connected to 3.3v
+6   | 35  | DPAD up connected to GPIO 19
+```
+I used soft tactile buttons for a better authentic feel 
+
+#### A, B, Start, Select
+```
+Pin | RPI | comment
+1   | 16  | Select button connected to GPIO 23
+2   | 15  | Start button connected to GPIO 22
+3   | 11  | B button connected to GPIO 17
+4   | 6   | ground pin
+5   | 12  | A button connected to GPIO 18
+6   | 17  | power connected to 3.3v
+```
+Tried to use soft buttons here too but the gameboy buttons didnt fit well to the ones I bought so I went with regular clicky tactile buttons
+
+Of course you can design the boards any way you want but this how I did it but
+> **Notice** That any change to the data pins in the buttons or the display will result in modification and recompilation of the MagenBoy source code
+
+##### RPi Key bindings
+
+> **Notice** Im using BCM and not actual physical pin number - for more about [What is BCM](https://iot4beginners.com/difference-between-bcm-and-board-pin-numbering-in-raspberry-pi/)
+
+| Joypad     | Keyboard    |
+| ---------- | ----------- |
+| A          | BCM 18      |
+| B          | BCM 17      |
+| Start      | BCM 22      |
+| Select     | BCM 23      |
+| Dpad Up    | BCM 19      |
+| Dpad Down  | BCM 16      |
+| Dpad Left  | BCM 21      |
+| Dpad Right | BCM 20      |
+
+## Compiling MagenBoy
+* install Rust on the RPi
+* Run `cargo b -r --no-default-features --features mmio`
+* Make sure it runs `sudo ./target/release/magenboy [path_to_rom]` - notice that the `mmio` feature (Memory Mapped IO) needs root access to access some RPi peripherals
+
+## Running 
+Edit /etc/rc.local and add the following line
+
+`sudo /home/[path_to_magenboy_root_folder]/target/release/magenboy --rom-menu [path_to_roms_folder] --bootrom [path_to_bootrom]`
+
+The bootrom flag is not neccessary but can complete the experience, it is also recommended to use [MagenBoot](https://github.com/alloncm/MagenBoot) for the best MagenBoy experience
+
+**Now the MagenBoy rom menu will open every time you turn on the RPi!**
+
+## Plans for the future
+* Sound support - corrently the APU is disabled due to the RPi zero2 is too slow and dont have a normal audio output 
+* Power button - There is no easy way to turn on or off the device (beside cutting the power or pluging to power)