Updated PORTING.md

PORTING.md

@@ -1,51 +1,46 @@
-# Porting Retro-Go
-This document describes the process of adding support for a new ESP32 device (what retro-go calls a *target*).
+# Table of contents
+- [Prerequisites](#prerequisites)
+- [Targets](#targets)
+- [Porting](#porting)
 
 
+# Introduction
 
-# 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.
+This document describes the process of adding support for a new ESP32 device (what retro-go calls a *target*).
 
 
-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
-```
+# Prerequisites
+Before doing anything, make sure that your development environment is working properly and that you can build retro-go for the default target. Please read [BUILDING.md](BUILDING.md) carefully for more information.
 
-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.
 
+# Targets
+A target in retro-go is a set of files that describes a hardware device (drivers to use, GPIOs, button mapping, etc). Targets are folders located in `components/retro-go/targets/` and usually contain the following files:
 
-**Make sure a basic setup is working before continuing to patch the code for your setup**
+| Name          | Description |
+|---------------|-------------|
+| config.h      | This is the retro-go configuration file, it describes your hardware to retro-go |
+| env.py        | This is imported by rg_tool.py, it is used to set environment variables required by tooling, such as the esp32 chip type or baudrates or binary formats |
+| sdkconfig     | This is the esp-idf configuration file for your board/device |
 
-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
+# Porting
 Retro-Go uses reusable hardware components, so it is easy to set it up for your own hardware.
 
+To get started, locate a target that is the most similar to your device and use it as a starting point. Clone the target's folder and give it a new name, then add your new target to `components/retro-go/config.h`.
 
-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.
 
+## Target files
 
-## config.h
-
-
-`config.h` has the bulk of your configurations.
+### config.h
 
+This file contains 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**
+
+##### 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).
 
@@ -74,44 +69,38 @@ You will need to create that file for your display. Unfortunately, there is no o
 Make this driver in `components/retro-go/drivers/display`
 
 
-___
-**Input**
+##### 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`
 
+This file is used by ESP-IDF to build the code for the ESP32 itself. Its content will depend on your needs and the needs of the chip/board used.
 
-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)
-```
+ESP-IDF provides a tool to edit it, namely `menuconfig`, but to use it in retro-go you must follow the following steps:
 
+1. Build the launcher for your target (this will make sure you have the correct ESP32 board selected and generate a default sdkconfig)
+    - `./rg_tool.py clean`
+    - `./rg_tool.py --target <targetname> build launcher`
+2. Enter the launcher directory: `cd launcher`
+3. Run `idf.py menuconfig` and make the changes that you need. Make sure to save the changes and exit.
+4. Optionally test the app with the new config (but do NOT run `rg_tool.py clean` at this point, your new config will be deleted)
+    - `cd ..`
+    - `./rg_tool.py --target <targetname> run launcher`
+4. When you're satisfied, copy the `sdkconfig` file from the launcher to the target folder, so that it's used by all apps
+    - `cd ..`
+    - `mv  -f launcher/sdkconfig components/retro-go/targets/<targetname>/sdkconfig`
 
-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
+Note that any time you modify your target's `sdkconfig` file, you must run `./rg_tool.py clean` to ensure it will be applied.
 
 
 ### 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`**
-