PiTrex Wiki - PiTrexCore_Internals editing

PiTrex Wiki

Enter password: Select file to upload:

Main Menu

Page Contents

[PiTrexCore] uses the PiCore version of [http://www.tinycorelinux.net/|Tiny Core Linux] as the basis. This has some key differences from most operating systems that run one the Pi:

* The root file system is loaded into RAM, so write access to the MicroSD card is not required for system operation.
* The base system is read-only. All software is loaded from read-only Gzip-compressed SquashFS file systems that are loop mounted with file inside them symlinked to the root filesystem. These are the "tcz" files which allow easily adding, removing, and updating software while accessing the MicroSD card from a PC.
* Minimal processes are run at start-up, and all are optimised for speed, allowing for a much faster boot process than most other Linux distros on the Raspberry Pi Zero.

Various changes have been made to the design of the base system, notably:

* Installs to a single file system from a ZIP file rather than an image file, for easier installation and a simpler release process.
* MicroSD card is mounted read-only except when saving high-score, settings, or menu entry information.
* Zstandard instead of Gzip compression is used for the initrd files that contain the root filesystem and kernel modules, because this was found to offer minor size and speed advantages relevent to start-up time. Zstardard compression of "tcz" extension files is also possible, but wasn't found to offer a significant improvement, so Gzip is still used for them.
* MicroPython was removed to save initrd space (and therefore boot time) and the few usages of it in the boot process were replaced by shell scripts.
* Filesystem check and repair programs were removed to save space because no ext filesystem is used.
* Blkid and libblkid were removed because they were not used. Automatic fstab generation is disabled in preference for a fixed fstab to speed up the boot process.
* The dwc2 USB driver module is included and used by default instead of the dwc-otg driver because it is more reliable while running the PiTrex software.
* The sha256_generic module is included for the Pi Zero 2 to prevent errors while establishing WiFi connections
* The joydev module is included for joystick support.
* The [http://www.ombertech.com/cnk/pitrex/ftp/github/distro/|shell scripts] for running the PiTrexCore system have been included in the rootfs initrd.
* No SSH server is started at boot and the OpenSSH extension is not included
* Video output from the Pi is disabled at start-up to avoid timing problems that affect the Vectrex display.

Possible future changes include:

* Load custom [GPU] driver for Vectrex display handling, thereby possibly allowing use of video output from the Pi and the dwc-otg USB driver.
* Use OverlayFS to mount large sets of software and dependencies "on top of" the root file system, to avoid the slow symlinking step while loading extensions.

PiTrex software, including VMMenu, is all loaded from ".tcz" extensions in the "tcz" directory when games are selected from the menu (similar to Tiny Core's On Demand mode). Non-PiTrex software, including dependencies of PiTrex software, is loaded from the "tce/optional" directory, which is the standard location from PiCore. Extensions in "tce/optional" are mostly from the PiCore project, however X library extensions (libX11.tcz, libXau.tcz, etc.) have been replaced with versions from XFree86 because these were smaller and may therefore load faster.

The extension system is basically the same [http://wiki.tinycorelinux.net/doku.php?id=wiki:creating_extensions|as Tiny Core Linux], but PiTrex software is installed to /opt/pitrex instead of /usr/local.  See [PiTrexCore_Extensions] for specific info on how to make new extensions.

!VMMenu
VMMenu is the basis of the menu system. It reads the automatically generated menu entries at start-up, and passes selected options to the [http://www.ombertech.com/cnk/pitrex/ftp/github/distro/vmm_pitrexcore.sh|vmm_pitrexcore].sh script which choses the method for running the program (directly or in an emulator, with the X server or without) and handles saving settings and high scores. It also configures Bluetooth audio for use with XMAME if paired with a Bluetooth speaker.

!Xvectrex
The [Xvectrex] display server is used for XMAME and some ported Linux games. It is loaded when required as a dependency of a game or emulator and started with xinit.

!Debug Mode
By default the video output from the Raspberry Pi is disabled during start-up in order to prevent timing issues that cause constant glitching of the Vectrex display. For debugging, add "debug" to the line in the cmdlinue.txt file on the MicroSD card and the display will be left enabled, allowing for error messages to be viewed, and terminal access if a USB keyboard is connected to the Pi.

In debug mode Telnet and FTP servers are also started on the Pi, so after WiFi is enabled you can connect to these if you know the IP address that it has been assigned on your network (mDNS can also be used to find it if "XMAME Local/Remote" is run from the menu, which starts the Avahi mDNS server). This can be used for developing software within the PiTrexCore system, as well as debugging.

Currently serial terminal connections to the UART on the Pi's GPIO header are not enabled because the correct configuration for this hasn't been figured out yet.

!Customising PiTrexCore
For developing software it will be convenient to add software and change the very minimal configuration of the Linux environment used in PiTrexCore. Most of the information on the [http://wiki.tinycorelinux.net/|Tiny Core Linux Wiki] is relevent, but here are some specific hints.

The MicroSD card is mounted read-only during start-up, which will prevent installing new software from the PiCore repository and making other changes. Remount it with read/write access using this command:
 sudo mount -o remount -o rw /mnt/mmcblk0p1

Now you can type "tce" to browse for and download software. Note that "installing" software there means it will be loaded at boot (added to tce/onboot.lst), slowing down start-up. You may prefer OnDemand mode, or loading extensions manually like this:
 tce-load -i <extension_name>

If you've connected a FAT-formatted USB drive to the Pi's USB port, mount it like this:
 mount /mnt/usb

Before disconnecting it, unmount it with "sudo":
 sudo umount /mnt/usb

Changes in /home and /opt can be saved and restored automatically if you run this command before rebooting, which (re)creates a tce/mydata.tgz on the MicroSD card:
 backup

If you want to modify the configuration of the system, you can add entries to /opt/.filetool.lst so that other files and directories are saved to tce/mydata.tgz (leave out the leading "/" from the path):
 echo etc/fstab >> /opt/.filetool.lst

You can exclude files/directories from mydata.tgz by adding them to /opt/.xfiletool.lst. You should really add "opt/pitrex" to this to prevent including lots of symlinks that shouldn't be there (now this is set by default, since v0.20230804).
 echo opt/pitrex >> /opt/.xfiletool.lst

The Raspberry Pi doesn't keep time between reboots, so you can set the time via NTP using this command (the default time zone is UTC). Note that it runs in the background and sometimes takes a while (run "date" to check whether it's done).
 sudo getTime.sh

As the root file system is in RAM, you can run out of RAM if you fill it up with lots of files. Large files are better kept on the SD card or a separate USB drive, which also avoids delays with saving and restoring them from mydata.tgz.