Module: Scripts

Note

This module is a WIP and not in the release version yet

Lets you run your own .sh scripts from 240-MP, so it can act as a remote-friendly front end for anything else on the machine. Things like FieldStation42, RetroArch, or everyday maintenance like updating yt-dlp.

Features

• Lists the .sh files in a folder of your choosing and runs them with a remote/controller
• Two run modes options for each script: console (240-MP stays on screen and shows the script's output) or takeover (the script gets the whole display)
• A .txt sidecar file beside each script sets its display name and options (one is created for you automatically the first time a script is seen with metadata format structured for you to fill out)
• Mark a script as a favorite to put it on the main menu alongside other native 240-MP modules
• Set a script to auto-run when 240-MP starts
• Add a confirmation prompt per script, for anything you don't want to trigger by accident
• Provide extra arguments per script through the .txt sidecar file

To Enable

1. Place your .sh files in the scripts directory, the default locations are:
   • RaspberryPi/SteamOS/Linux: ~/.local/share/240-MP/user_scripts
   • macOS: ~/Library/Application Support/240-MP/user_scripts
   • To use a different folder you can modify Settings > Scripts > Scripts Directory
2. Go to Settings > Scripts and run Rescan Scripts to generate sidecar .txt files for each of your scripts
   • These file define the metadata for how each of your scripts should run
   • You can also manually create these files if you prefer.
3. Edit each script's sidecar file to give it your preferred name name and choose how it should run (see below)
4. Go to Settings > Scripts and set Enabled to On

Note

Scripts run as the same user as 240-MP and only .sh files are displayed.

Sidecar metadata files

(i.e. per-script settings)

Each script gets a sidecar .txt file beside it (e.g. launch-retroarch.sh → launch-retroarch.txt) to hold details about how to run the script and how it should display in 240-MP. Script settings live in these files rather than inside the .sh so you won't have to edit a script you didn't write (for example; a FieldStation42 launcher pulled from git).

Setting	Values	Default	What it does
name	any text	the filename	The label shown in 240-MP
mode	console or takeover	console	See the Mode section below for details on each mode
favorite	yes / no	no	If yes is set it will show the script on the main module list
confirm	yes / no	no	Sets if you would like to get a confirmation before running
args	any text	empty	Set extra arguments you'd like passed to the script
wait	pgroup or child	pgroup	Takeover only, see the Mode section below
tty	yes / no	no	Takeover only, see the Mode section below

• Lines starting with # are ignored, and your comments are always preserved
• yes/no, on/off, true/false and 1/0 all work for the yes/no settings
• Settings 240-MP doesn't recognise are ignored, so a file written by a newer version will still works
• Delete the .txt file to get a fresh one with defaults and all the options explained in comments

Example: a RetroArch launcher labeled as "Launch RetroArch" and set as a favorite to display on the main module list:

name = Launch RetroArch
mode = takeover
favorite = yes
confirm = no

Modes

Scripts can run in 1 of 2 modes: Console or Takeover

Console mode

When a script is run with this mode 240-MP stays on screen and streams its output into a scrolling view.

It's good for scripts where you want to see what happened:

• yt-dlp -U to update yt-dlp
• sudo apt update && sudo apt full-upgrade -y
• git -C ~/some-project pull
• a backup or file-tidying script

Details:

• Output appears live, with stderr included. Progress bars that redraw a line (yt-dlp, curl, apt) update in place rather than filling the screen.
• Only the last 500 lines are kept so a long-running job can't run away with memory.
• [Up/Down] scrolls the output. By default it follows the newest output unless you scroll up, and resumes following when you scroll back down.
• When a script finishes, the view stays open showing EXIT 0 (or the failing exit code) so you can read the tail.
• Simply press [ESC/Back] to return to the list when you are done.

Takeover mode

A script run as mode = takeover will get the whole display, and 240-MP will come back when it completes running.

This mode is good for scripts that end up drawing their own full-screen interface (e.g. RetroArch, FieldStation42)

The actual screen takeover functions differently depending on the system:

• Raspberry Pi OS with no desktop: 240-MP genuinely hands the screen over and then takes it back when the script exits
• macOS, Steam Deck, or Linux with a desktop: the script you launch simply opens its window in front of 240-MP

Details:

• When a script has the screen, 240-MP shows a black card naming the script and indicates that its "Running...". That card stays on screen until the script draws something of its own so a takeover script that produces no visuals will simply show this screen with its name on it until it completes running.
• When a script exits cleanly, 240-MP returns to the list by itself. If it fails, the view stays so you can read the exit code and any output.
• Ideally write your script to run in the foreground using wait = pgroup (the default). If your script starts something in the background and exits immediately then 240-MP will wait for everything it started to finish before taking the screen back (this was done so you won't get the display pulled out from under a program that's still running). Set wait = child if you deliberately want to leave something running in the background.
• tty = yes is only for a program that reads typed input from a terminal. Most scripts hopefully won't need this but I added it as an option just in case.

Your script is given these environment variables in case you need them:

Variable	Value
MP240_MODE	console or takeover
MP240_VT	the virtual terminal it was given (takeover on a Pi only)
APP_ROOT	where 240-MP is installed
DATA_ROOT	240-MP's data directory

The working directory is the script's own folder, so relative paths next to your script will work.