Instructions for porting retro-go to custom hardware (#156)

* PATCHING.md and some instructions for building imgs

* Add Custom Hardware to the table of contents

* Github Markdown formatting changes

* Update BUILDING.md

I'm not too keen on your changes in BUILDING.md. Once a .img/.fw has been flashed, flash/run/monitor will work regardless of the initial format but your addition implies that those don't apply to .img but they do.

I think what should be done instead is move your new "Flashing" section to be right after the "Build everything" section. Maybe rename it "Initial Flashing" or "First Installation" or something along those lines. Then describe how to flash a .img or a .fw for the first time on a new device.


I'm doing a commit just to quickly show you what I have in mind, feel free to revert or entirely rewrite and continue with your vision :)

* Remove redundant changes in README.md
While previous changes in the README.md introduced unnececary info, I do want to keep some links.

One thing is that a link to building/installing should definetly be higher up, as I wasn't sure where to get started with retro-go until I scrolled down the whole README

Another thing is that I added a link to PATCHING in the "Generic ESP32" install instructions as their was already a mention about porting in it

* Rename PATCHING and replace all occurances/refs

Yup, this name makes much more sense

* Fill in blank info and reorganize rg_tool info

This fills in instructions for the esp_tool info.
Also, it made more sense to describe rg_tool in BUILDING.md as it isn't only used for porting

* Consitency with Links and commands

This adds links (to the relevent section) to unlinked text. Also makes the difference between `./rg_tool.py` and `python rg_tool.py` a little more consistant

* Remove Unused Title in README

* Remove redundant spaces and lines

---------

Co-authored-by: ducalex <[email protected]>

BUILDING.md

@@ -13,6 +13,7 @@ Patching esp-idf may be required for full functionality. Patches are located in
 
 ## Obtaining the code
 
+
 Using git is the preferred method but you can also download a zip from the project's front page and extract it if you want, Retro-Go has no external dependencies.
 
 There are generally two active git branches on retro-go:
@@ -22,44 +23,79 @@ There are generally two active git branches on retro-go:
 `git clone -b <branch> https://github.com/ducalex/retro-go/`
 
 
-## Build everything and generate .fw:
+# rg_tool
+ESP-IDF doesn't support managing multiple apps in one environment (launcher, prboom-go, etc). `rg_tool.py` is used instead, which passes correct arguments to `idf.py` and other tools.
+
+
+To get started, run
+```
+./rg_tool.py
+```
+or 
+```
+python rg_tool.py
+```
+
+## Build everything and generate a firmware image:
 - Generate a .fw file to be installed with odroid-go-firmware (SD Card):\
-    `python rg_tool.py build-fw` or `python rg_tool.py release` (clean build)
+   `python rg_tool.py build-fw` or `python rg_tool.py release` (clean build)
 - Generate a .img to be flashed with esptool.py (Serial):\
-    `python rg_tool.py build-img` or `python rg_tool.py release` (clean build)
+   `python rg_tool.py build-img` or `python rg_tool.py release` (clean build)
+
 
 For a smaller build you can also specify which apps you want, for example the launcher + DOOM only:
 1. `python rg_tool.py build-fw launcher prboom-go`
 
+
 Note that the app named `retro-core` contains the following emulators: NES, PCE, G&W, Lynx, and SMS/GG/COL. As such, these emulators cannot be selected individually. The reason for the bundling is simply size, together they account for a mere 700KB instead of almost 3MB when they were built separately.
 
 
+## Flashing an image for the first time
+
+Once we have successfully built an image file (`.img` or `.fw`), it must be flashed to the device.
+
+To flash a `.img` file with `rg_tool.py`, run:
+```
+python rg_tool.py --target (target) --port (usbport) install (apps)
+```
+
+To flash a `.img` file with `esptool.py`, run:
+```
+esptool.py write_flash --flash_size detect 0x0 retro-go_*.img
+```
+
+To flash a `.fw` file: 
+
+Instructions depend on your device, refer to [README.md](README.md#installation).
+
 ## Build, flash, and monitor individual apps for faster development:
-It would be tedious to build, move to SD, and flash a full .fw all the time during development. Instead you can:
+
+A full Retro-Go image must be flashed at least once (refer to previous section), but, after that, it is possible to flash and monitor individual apps for faster development time.
+
 1. Flash: `python rg_tool.py --port=COM3 flash prboom-go`
 2. Monitor: `python rg_tool.py --port=COM3 monitor prboom-go`
 3. Flash then monitor: `python rg_tool.py --port=COM3 run prboom-go`
 
-
 ## Environment variables
 rg_tool.py supports a few environment variables if you want to avoid passing flags all the time:
 - `RG_TOOL_TARGET` represents --target
 - `RG_TOOL_BAUD` represents --baud
 - `RG_TOOL_PORT` represents --port
 
-
 ## Changing the launcher's images
-All images used by the launcher (headers, logos) are located in `launcher/main/images`. If you edit them you must run the `launcher/main/gen_images.py` script to regenerate `images.c`. Magenta (rgb(255, 0, 255) / 0xF81F) is used as the transparency colour.
-
+All images used by the launcher (headers, logos) are located in `launcher/main/images`. If you edit them you must run the `launcher/main/gen_images.py` script to regenerate `images.c`. Magenta (rgb(255, 0, 255) / 0xF81F) is used as the transparency color.
 
 ## Capturing crash logs
 When a panic occurs, Retro-Go has the ability to save debugging information to `/sd/crash.log`. This provides users with a simple way of recovering a backtrace (and often more) without having to install drivers and serial console software. A weak hook is installed into esp-idf panic's putchar, allowing us to save each chars in RTC RAM. Then, after the system resets, we can move that data to the sd card. You will find a small esp-idf patch to enable this feature in tools/patches.
 
-To resolve the backtrace you will need the application's elf file. If lost, you can recreate it by building the app again **using the same esp-idf and retro-go versions**. Then you can run `xtensa-esp32-elf-addr2line -ifCe app-name/build/app-name.elf`.
 
+To resolve the backtrace you will need the application's elf file. If lost, you can recreate it by building the app again **using the same esp-idf and retro-go versions**. Then you can run `xtensa-esp32-elf-addr2line -ifCe app-name/build/app-name.elf`.
 
 ## Porting
-I don't want to maintain non-ESP32 ports in this repository but let me know if I can make small changes to make your own port easier! The absolute minimum requirements for Retro-Go are roughly:
+Instructions to port to new ESP32 devices can be found in [PORTING.md](PORTING.md).
+
+
+I don't want to maintain non-ESP32 ports in this repository, but let me know if I can make small changes to make your own port easier! The absolute minimum requirements for Retro-Go are roughly:
 - Processor: 200Mhz 32bit little-endian
 - Memory: 2MB
 - Compiler: C99 (and C++03 for handy-go)

PORTING.md

@@ -0,0 +1,118 @@
+# Patching Retro-Go
+Adjust retro-go to use your drivers and hardware
+
+
+
+
+# Prerequisites
+You will need a working installation of [esp-idf](https://docs.espressif.com/projects/esp-idf/en/release-v4.3/esp32/get-started/index.html#get-started-get-prerequisites). Versions 4.3 to 5.2 are supported.
+
+
+Before using your own patch of retro-go, make a clean build of retro go using bare configurations
+```
+./rg_tool.py build-img launcher --target esp32s3-devkit-c
+```
+
+Since we aren't using other setups, like ODROID-GO, we will be building `/img` files, not `.fw`. Use `./rg_tool.py build-img` to build imgs.
+
+
+**Make sure a basic setup is working before continuing to patch the code for your setup** 
+
+If it doesn't, refer to [BUILDING.md](BUILDING.md). Also check your `esp-idf` installation and make sure you have it set up in your environment (run `idf.py --version` to check)
+```
+./rg_tool.py build-img launcher --target esp32s3-devkit-c
+```
+
+# Patching
+Retro-Go uses reusable hardware components, so it is easy to set it up for your own hardware.
+
+
+You will find the targets (configs for each device) in `components/retro-go/targets`
+
+
+To make a base one, copy `esp32s3-devkit-c` and rename it.
+
+
+## config.h
+
+
+`config.h` has the bulk of your configurations.
+
+
+First, change `RG_TARGET_NAME` to match the name of your target folder.
+
+
+
+
+Most of it, you will need to figure out the correct parameters for (eg. Storage and Audio)
+
+**Display**
+
+If you aren't using the ILI9341 screen driver, you will need to change the `SCREEN_DRIVER` parameter. (Otherwise, just change the following settings and continue).
+
+
+(You will find more display configuration in the `SPI Display` section below)
+
+
+For now, only the ILI9341 is included. Increment the number. Then in `components/retro-go/rg_display.c`, find this part
+```
+#if RG_SCREEN_DRIVER == 0 /* ILI9341 */
+#include "drivers/display/ili9341.h"
+#elif RG_SCREEN_DRIVER == 99
+#include "drivers/display/sdl2.h"
+#else
+#include "drivers/display/dummy.h"
+#endif
+```
+
+
+Add a `#elif` for your SCREEN_DRIVER. In the body, use `#include "drivers/display/(YOUR DISPLAY DRIVER).h"` (eg. `st7789.h`).
+
+
+You will need to create that file for your display. Unfortunately, there is no one-for-all way to make this. It will need the same template as the other display drivers there, but it will differ for each display. To start, check the Retro-Go issues on GitHub and try searching on Google.
+
+
+Make this driver in `components/retro-go/drivers/display`
+
+
+___
+**Input**
+
+Back in `config.h`, you will see the configuration for an I2C gamepad. If you aren't using that, you can make your own parameters based on the existing input forms in `components/retro-go/rg_input.c`
+
+
+You can also write your own input driver for unique input forms. Just look at the existing code in `rg_input.c` and match that
+
+
+
+
+### sdkconfig
+`sdkconfig` is used by ESP-IDF to build the code for the ESP32 itself. It is hard to manually write it all out, so you can use `menuconfig`
+
+
+For this, go back to your root folder. Build the launcher for your target (this will make sure you have the correct ESP32 board selected).
+```
+./rg_tool.py clean
+./rg_tool.py build launcher --target (YOUR TARGET)
+```
+
+
+Then `cd` into `launcher` and run `idf.py menuconfig`. Navigate to Serial Flasher Config and adjust it all to your board. Make sure to save the changes and exit.
+
+
+Use this generated sdkconfig in your target with
+```
+cd ..
+mv  -f launcher/sdkconfig components/retro-go/targets/retrotoids/sdkconfig
+```
+This will configure ESP-IDF to run on your board
+
+
+### env.py
+
+
+Change the target board in `env.py` to match yours
+
+
+After completing all these steps, you should be able to build your apps with `rg_tool`. See [BUILDING.md](BUILDING.md#flashing-an-image-for-the-first-time) for more info about this and flashing. **Make sure to use the steps for `.img`, NOT `.fw`**
+

README.md

@@ -12,7 +12,9 @@
 Retro-Go is a firmware to play retro games on ESP32-based devices (officially supported are
 ODROID-GO and MRGC-G32). The project consists of a launcher and half a dozen applications that
 have been heavily optimized to reduce their cpu, memory, and flash needs without reducing
-compatibility!
+compatibility! 
+
+Get started in [BUILDING.md](BUILDING.md)
 
 ### Supported systems:
 - Nintendo: **NES, SNES (slow), Gameboy, Gameboy Color, Game & Watch**
@@ -55,8 +57,9 @@ compatibility!
 
 ### Generic ESP32
 This method is intended to be used when .fw support isn't available (when porting to a new device) or undesirable (devices with smaller flash).
-  1. Build a .img file (refer to [Building Retro-Go](#building) below)
-  2. Flash the image: `esptool.py write_flash --flash_size detect 0x0 retro-go_*.img`
+  1. (optional) Port retro-go to your device ([PORTING.md](PORTING.md))
+  2. Build a .img file (refer to [Building Retro-Go](#building) below)
+  3. Flash the image: `esptool.py write_flash --flash_size detect 0x0 retro-go_*.img`
       _Note: Your particular device may require extra steps (like holding a button during power up), different esptool flags, or modifying base.sdkconfig._
 
 
@@ -167,8 +170,7 @@ Instructions moved to [THEMING.md](THEMING.md).
 
 
 # Building
-Instructions moved to [BUILDING.md](BUILDING.md).
-
+To build retro-go, refer to [BUILDING.md](BUILDING.md).
 
 # Acknowledgements
 - The NES/GBC/SMS emulators and base library were originally from the "Triforce" fork of the [official Go-Play firmware](https://github.com/othercrashoverride/go-play) by crashoverride, Nemo1984, and many others.