-
Notifications
You must be signed in to change notification settings - Fork 130
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
18 changed files
with
501 additions
and
151 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Building Retro-Go | ||
|
|
||
| ## 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). Only versions 4.1 to 4.4 are supported. Support for 5.0 is coming soon. | ||
|
|
||
| _Note: As of retro-go 1.35, I use 4.3.3. Version 4.1.x was used for 1.20 to 1.34 versions._ | ||
|
|
||
| ### ESP-IDF Patches | ||
| Patching esp-idf may be required for full functionality. Patches are located in `tools/patches` and can be applied to your global esp-idf installation, they will not break your other projects/devices. | ||
| - `sdcard-fix`: This patch is mandatory for the ODROID-GO (and clones). | ||
| - `panic-hook`: This is to help users report bugs, see `Capturing crash logs` below for more details. The patch is optional but recommended. | ||
| - `enable-exfat`: Enable exFAT support. I don't recommended it but it works if you need it. | ||
|
|
||
|
|
||
| ## Obtaining the code | ||
|
|
||
| You can simply download a zip from the project's front page and extract it, but using git is better for development. | ||
|
|
||
| There are generally two active git branches on retro-go: | ||
| - `master` contains the code form the most recent release and is usually tested and known to be working | ||
| - `dev` contains code in development that will be merged to master upon the next release and is often untested | ||
|
|
||
| `git clone -b <branch> https://github.com/ducalex/retro-go/` | ||
|
|
||
|
|
||
| ## Build everything and generate .fw: | ||
| - Generate a .fw file to be installed with odroid-go-firmware (SD Card):\ | ||
| `./rg_tool.py build-fw` or `./rg_tool.py release` (clean build) | ||
| - Generate a .img to be flashed with esptool.py (Serial):\ | ||
| `./rg_tool.py build-img` or `./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. `./rg_tool.py build-fw launcher prboom-go` | ||
|
|
||
|
|
||
| ## 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: | ||
| 1. Flash: `./rg_tool.py --port=COM3 flash prboom-go` | ||
| 2. Monitor: `./rg_tool.py --port=COM3 monitor prboom-go` | ||
| 3. Flash then monitor: `./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 | ||
|
|
||
|
|
||
| ## Windows | ||
| Running `./rg_tool.py ...` on Windows might invoke the wrong Python interpreter (causing the build to fail) | ||
| or even do nothing at all. In such cases you should use `python rg_tool.py ...` instead. | ||
|
|
||
|
|
||
| ## 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. | ||
|
|
||
|
|
||
| ## 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`. | ||
|
|
||
|
|
||
| ## 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: | ||
| - Processor: 200Mhz 32bit little-endian | ||
| - Memory: 2MB | ||
| - Compiler: C99 (and C++03 for handy-go) | ||
|
|
||
| Whilst all applications were heavily modified or even redesigned for our constrained needs, special care is taken to keep | ||
| Retro-Go and ESP32-specific code exclusively in their port file (main.c). This makes reusing them in your own codebase very easy! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # Theming Retro-Go | ||
|
|
||
| This document should document what are themes, how they're structured, and how to make them. | ||
|
|
||
|
|
||
| ## Theme Structure | ||
|
|
||
| A theme is a folder placed in `sd:/retro-go/themes` containing the following files: | ||
|
|
||
| | Name | Format | Description | Required | | ||
| |--|--|--|--| | ||
| | theme.json | JSON | Contains the theme metadata (description, author, colors, etc) | Yes | | ||
| | preview.png | PNG 160x120 | Theme preview to be displayed in the theme selector | No | | ||
| | background_X.png | PNG 320x240 | Launcher backgrounds where X is the name of the launcher tab (see launcher/main/images) | No | | ||
| | banner_X.png | PNG 272x24 | Launcher banners where X is the name of the launcher tab (see launcher/main/images) | No | | ||
| | logo_X.png | PNG 46x50 | Launcher logos where X is the name of the launcher tab (see launcher/main/images) | No | | ||
|
|
||
| ### theme.json | ||
|
|
||
| All fields are optional (you'll have to dig in the source if you need to know the default value...). | ||
|
|
||
| Colors are RGB565 and can be represented as integers or hex strings. The special value `transparent` is also accepted in some places. | ||
|
|
||
| ````json | ||
| { | ||
| "description": "Theme description", | ||
| "website": "https://example.com/retro-go-theme", | ||
| "author": "John Smith", | ||
| "dialog": { | ||
| "__comment": "This section contains global dialog colors", | ||
| "foreground": "0xFFFF", | ||
| "background": "0x0010", | ||
| "border": "0x6B4D", | ||
| "header": "0xFFFF", | ||
| "scrollbar": "0xFFFF", | ||
| "item_standard": "0xFFFF", | ||
| "item_disabled": "0x8410" | ||
| }, | ||
| "launcher_1": { | ||
| "__comment": "This section contains launcher theme variant 1", | ||
| "list_standard_bg": "transparent", | ||
| "list_standard_fg": "0x8410", | ||
| "list_selected_bg": "transparent", | ||
| "list_selected_fg": "0xFFFF" | ||
| }, | ||
| "launcher_2": { | ||
| "__comment": "This section contains launcher theme variant 2", | ||
| "list_standard_bg": "transparent", | ||
| "list_standard_fg": "0x8410", | ||
| "list_selected_bg": "transparent", | ||
| "list_selected_fg": "0xFFFF" | ||
| }, | ||
| "launcher_3": { | ||
| "__comment": "This section contains launcher theme variant 3", | ||
| "list_standard_bg": "transparent", | ||
| "list_standard_fg": "0x8410", | ||
| "list_selected_bg": "0xFFFF", | ||
| "list_selected_fg": "0x0000" | ||
| }, | ||
| "launcher_4": { | ||
| "__comment": "This section contains launcher theme variant 4", | ||
| "list_standard_bg": "transparent", | ||
| "list_standard_fg": "0xAD55", | ||
| "list_selected_bg": "0xFFFF", | ||
| "list_selected_fg": "0x0000" | ||
| } | ||
| } | ||
| ```` | ||
|
|
||
| Important: If retro-go refuses to load your theme, please run your theme.json through a JSON validator to make sure the format is correct (JSON is quite strict regarding quotes or trailing commas for example). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.