Module: Scripts

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.

Video Overview

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 files 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 work
• Delete a .txt file to generate 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 hands control of the screen over and then takes it back when the script exits
• macOS, Steam Deck, or Linux with a desktop: the script you launch will simply open its window over 240-MP

Details:

• When a takeover script runs, 240-MP shows a screen with the name of the script and an indicator that its "Running...". That screen stays on screen until the script draws something of its own over it (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 will return to the script list. If it fails, the view will stay open 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.
• [Raspberry Pi OS with no desktop] tty = yes is only for a script that is both a takeover and needs typed input from a terminal. Most scripts hopefully won't need this but I added it as an option just in case.
  • Virtual consoles are root:tty mode 0620 (group write only), so handing one to a script as its controlling terminal will need read/write access. I don't include this by default because it would affect every console for the sake of an uncommon setting.
  • So if this is something you need you can run:

    echo 'KERNEL=="tty[0-9]*", GROUP="tty", MODE="0660"' \
        | sudo tee /etc/udev/rules.d/99-240mp-script-tty.rules
    sudo udevadm control --reload-rules && sudo reboot

  • But please understand what this does: it makes all virtual consoles readable and writable by the tty group. So please don't add it unless you really need it.

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.

Favorites

A script marked as favorite = yes will appear as a row on the main module list after 240-MP's built-in modules. Selecting it will run it straight away and will return you to the main module list once it completes.

The quickest way to set a favorite is to highlight a script in the list and press [Right] on your controller. You'll see * added to the row to indicate its set as a favorite. Press [Right] again to unfavorite it.

Auto-run at start up

To run a script automatically when 240-MP starts you can do the following:

1. Settings > Scripts > Auto-Run On Startup: select the script you want to run
2. Settings > Start On Module: set it to Scripts

With those 2 settings, your selected script will run right after 240-MP starts. If your script has an error and fails, then every time 240-MP starts it will run straight back into that error so please test your script before hand and know what you are doing before you set this.

Stopping a script

240-MP deliberately doesn't monitor your scripts so if you're using this module you're assumed to know how your scripts work and have tested them to make sure they run without error.

That said, it's worth knowing some ways out of a failing or stuck script just in case.

• Console Mode
  • Press Back once. 240-MP will ask the script to quit, and will stop it if it's still running 3 seconds later.
  • (Raspberry Pi only) If Back does nothing then ssh in and run pkill -TERM 240mp (or sudo systemctl restart 240mp)
• Takeover Mode
  • I deliberately don't have an escape hatch for takeover scripts because in most cases a launched application will also require ownership of input (keyboard, gamepad, controller) and I didn't want 240-MP to step on that. Imagine opening something like RetroArch and pressing the A button in a game and having it close because the A button is also the mapped back button for 240-MP =)
  • On MacOS and Linux with Desktop the takeover handoff just opens a new window over 240-MP so you should be able to simply close the new window to get back to 240-MP
  • On Raspberry Pi without a desktop env you'll likely need to reboot or pkill the takeover application to get things sorted. That said if the script is set as Auto-Run On Startup and it errors out then you can ssh in and set Auto-Run On Startup (or the app's START ON MODULE) back to None in config.json, then sudo reboot. In the worst case, open the SD card in another machine and edit the file directly that way.

Example Scripts

• YT-DLP Install/Update (Cross Platform): https://gist.github.com/anthonycaccese/214020bfbf0abee596d256ecb7efc54f