61790c0dd2
Rather than constantly sending messages regarding my suggestions for fixes, I thought I'd try to be helpful by submitting pull requests for the things that I can figure out how to fix via configuration file changes. Having tested this modification myself with the Game Gear edition of Sonic Spinball, the only change I have made in this case is the reversal of the Game Gear's 1 and 2 inputs to match the layout of the original system: 1 → B and 2 → A, rather than the other way around as those controls are currently set. While the helpfulness of this change would vary from game to game, in Sonic Spinball it was quite helpful as 1 activates the left pinball bumper and 2 activates the right one. While this could otherwise be fixed by KEY files, as this change makes the Game Gear button mapping match that of the actual Game Gear, I think the change would make sense, and if anyone prefers the current mapping for whatever reason, I would be glad to add a general-use KEY file to swap the A and B inputs to the wiki here: https://wiki.funkey-project.com/wiki/List_of_pre-configured_KEY_files. I'll see if there's anything else in this configuration file that might be worth adjusting, but otherwise, if the other default emulators have similarly-adjustable configuration files, could I know where they are so I could conduct additional testing? Otherwise, I would also like to add a tutorial to the wiki instructing "power users" on how to use Commander to enable a few extra features such as the playlists of RetroFE, but after trying to map RetroFE functions to V, O, I, and J, several inputs normally usable via FN shortcuts but not usable outside of games, I still couldn't get those features to work. The only features I could get to work this way were the activate/deactivate favorites playlist and select random game features of RetroFE via the H (FN+DOWN) and S (START) keys, but otherwise I have not been successful in using the other features, which I would want to include in any tutorial I might write on the subject. While I used the commands listed in the RetroFE documentation, perhaps I made a mistake in implementing them, so if possible please let me know how I might implement the functionality either in the comments here or on Discord. Thanks again, -Coolie |
||
|---|---|---|
| .github | ||
| FunKey | ||
| Recovery | ||
| SDK | ||
| buildroot@1f59bd3b48 | ||
| docker | ||
| .gitignore | ||
| .gitmodules | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| genimage-prod.cfg | ||
| genimage.cfg | ||
README.md
FunKey-OS
Intro
This repository contains all the sources required to build FunKey-OS, the Open-Source firmware at the heart of the FunKey S retro-gaming console.
As the FunKey-S console is based on a sophisticated Allwinner V3s ARM Cortex-A7 1.2GHz CPU, an Operating System is mandatory in order to access all the hardware resources without re-inventing the wheel.
FunKey-OS is based on Linux, and is built from scratch using the buildroot tool that simplifies and automates the process of building a complete Linux system for an embedded system like this.
Technically, Funkey-OS is a buildroot (v2) based external tree for building the bootloader, the Linux kernel and user utilities, as well as the optimized retro-game launcher and console emulators.
Build host requirements
Even if the resulting disk image and firmware update files are relatively small (202 MB and 55MB, respectively), the size of the corresponding sources and the compilation by-products tend to be rather large, such that an available disk space of at least 12GB is required during the build.
And even if the resulting FunKey-OS boots in less than 5s, it still requires a considerable amount of time to compile: please account for 1 1/2 hour on a modern multi-core CPU with SSD drives and a decent Internet bandwidth.
As the target CPU is probably different from the one running on your build host machine, a process known as cross-compilation is required for the build, and as the target system will eventually be Linux, this is much better handled on hosts running a Linux-based operating system too.
As a matter of fact, the FunKey-OS is meant to be built on a native Ubuntu or Debian Linux host machine (Ubuntu 20.04 LTS in our case, but this should also work with other versions, too). And with only a few changes to the prerequisites, it can certainly be adapted to build on other common Linux distros.
However, if your development machine does not match this setup, there are still several available solutions:
- use a lightweight container system such as Docker and run an Ubuntu or Debian Linux container in it
- use a VM (Virtual Machine) , such as provided by VirtualBox and run an Ubuntu or Debian Linux in it
- for Windows 10 users, use the WSL2 (Windows System for Linux 2) subsystem and run an Ubuntu Linux distro in it
In order to install one of these virtualized environments on your machine, please refer to the corresponding documentation.
Build on a Physical/Virtual Machine
Prerequisites
While Buildroot itself will build most host packages it needs for the compilation, some standard Linux utilities are expected to be already installed on the host system. If not already present, you will need to install the following packages beforehand:
- bash
- bc
- binutils
- build-essential
- bzip2
- ca-certificates
- cpio
- cvs
- expect
- file
- g++
- gcc
- git
- gzip
- liblscp-dev
- libncurses5-dev
- locales
- make
- mercurial
- openssh-client
- patch
- perl
- procps
- python
- python-dev
- python3
- python3-dev
- python3-distutils
- python3-setuptools
- rsync
- rsync
- sed
- subversion
- sudo
- tar
- unzip
- wget
- which
- xxd
On Ubuntu/Debian Linux, this is achieved by running the following command:
$ sudo apt install bash bc binutils build-essential bzip2 ca-certificates cpio cvs expect file g++ gcc git gzip liblscp-dev libncurses5-dev locales make mercurial openssh-client patch perl procps python python-dev python3 python3-dev python3-distutils python3-setuptools rsync rsync sed subversion sudo tar unzip wget which xxd
How to get the sources
When using either physical or virtual Linux machines, you must clone the FunKey OS repository from Github (here we place it into a FunKey-OS directory):
$ git clone https://github.com/FunKey-Project/FunKey-OS.git FunKey-OS
Then enter into the created directory:
$ cd FunKey-OS
Build the disk image & firmware update files
You may now build your FunKey with:
$ make sdk all
This may take a while (~1h30), so consider getting yourself a cup, a glass or a bottle of your favorite beverage ;-)
Note: you will need to have access to the network, since buildroot will download the package sources.
Result of the build
After building, you should obtain the SD Card image FunKey-sdcard-X.Y.Z.img and the firmware update file FunKey-rootfs-X.Y.fwu in the images directory.
Build in a container
Prerequisites
When using a Docker container, all the prerequisites are automatically installed.
How to get the sources
When using a Docker container, you must first create a new directory (here we create a FunKey-OS directory) and get the FunKey-OS Dockerfile:
$ mkdir FunKey-OS
$ cd FunKey-OS
$ wget https://raw.githubusercontent.com/FunKey-Project/FunKey-OS/master/docker/Dockerfile -o Dockerfile
You must then build the docker image (don't forget the final dot!):
$ docker build -t funkeyproject/funkey-os .
Build the disk image & firmware update files
You may now build your FunKey with:
$ docker run --name funkey-os funkeyproject/funkey-os
Or alternatively, you can run it in the background with:
$ docker run -d --name funkey-os funkeyproject/funkey-os
If you launch it in the background, you can still follow what is going on with either:
$ docker top funkey-os
Or:
$ docker logs funkey-os
This may take a while (~1h30), so consider getting yourself a cup, a glass or a bottle of your favorite beverage ;-)
Note: you will need to have access to the network, since buildroot will download the package sources.
Result of the build
After building, you can copy the SD Card image sdcard.img and the firmware update file FunKey-rootfs-X.Y.fwu from the container into the host current directory:
$ mkdir images
$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-sdcard-X.Y.Z.img images/
$ docker cp funkey-os:/home/funkey/FunKey-OS/images/FunKey-rootfs-X.Y.Z.fwu images/
How to write to the SD card
You can copy the bootable images/sdcard.img onto an SD card using "dd":
$ sudo dd if=images/FunKey-sdcard-X.Y.Z.img of=/dev/sdX
Warning: Please make sure that /dev/sdX device corresponds to your SD Card, otherwise you may wipe out one of your hard drive partitions!
Alternatively, you can use the Balena-Etcher graphical tool to burn the image to the SD card safely and on any platform:
Once the SD card is burnt, insert it into your FunKey S console slot, and power it up. Your new system should come up now and start a console on the UART0 serial port and display the retro game launcher on the graphical screen.
How to update the FunKey S firmware
It is possible to update a FunKey-S over USB:
- Connect the FunKey S console to your host machine using the USB cable
- From the retro-game launcher, press the ON/OFF button to access the menu
- Using the Up/Down keys, select the "MOUNT USB" screen ad press the "A" key twice to mount the FunKey S on your machine as an USB mass storage drive
- Drag and drop the images/FunKey-rootfs-X.Y.fwu file into it
- When finished, eject the USB mass storage from your host machine
- Back on the FunKey S console, press the "A" key twice to eject the USB mass storage drive
- The FunKey S console will automatically detect the firmware update file and proceed with the update before returning to the retro game launcher screen once finished