Differences

This shows you the differences between two versions of the page.

--- scripting_services_rules_examples [2024/10/05 21:59] – [Filename conventions] crcerror
+++ scripting_services_rules_examples [2025/06/07 06:59] (current) – Scripts and Wikicode crcerror
@@ Line 1: / Line 1: @@
-====== Batocera Services ======
+====== Batocera services ======
-This feature was introduces in **Batocera v38 Blue Moon** and is a powerful replacement for the **custom.sh**. We can devide two setups. First the preinstalled services which should not be altered and in second instance the **Userservices** that are stored to directory: `/userdata/system/services`. In both cases the activation state can altered through EmulationStation Frontend: Main Menu --> System Settings --> Services
+Services are scripts that run at system startup and shutdown.  Services are supported in Batocera **v38** and higher, and will replace the deprecated [[launch_a_script#customlast_during_startup_first_after_shutdown|custom.sh user script]].
-Even if **custom.sh** is still working (10/2024) it is recommended to use the service section for future proof setups.
+Two types of services are supported:
+  - The **system services** are preinstalled in ''/usr/share/batocera/services/''
+  - The **user services** can be created and modified by the user in ''/userdata/system/services/''
-==== Usage ====
+====== Usage ======
-**Disabling** services (with ''batocera-services disable'' or through the UI) doesn't **stop** them. That needs to be done manually with ''batocera-services stop''. Disabling them only means that they wil not be automatically started after the next system startup.
+How to write a proper user service script:
-**Enabling** them (with ''batocera-services enable'' or through the UI) works the same. To actually **start** a service, enable it first, then restart Batocera or use ''batocera-services start''.
+  - Use shell script language like bash or sh
+  - Use UNIX LF line termination, not Windows CRLF termination
+  - Make the script executable (''chmod +x your_script'', optional)
+    * Setting executable permissions is good practice but requires a filesystem with support for those permissions
+    * If the executable bit is not set then bash interpreter is used directly, therefore it is optional
+  - Store your script in ''/userdata/system/services/''
+  - Reboot your device to make the services selectable in EmulationStation.
-==== Filename conventions ====
+Each of the services may be enabled or disabled in the EmulationStation frontend: **MAIN MENU** -> **SYSTEM SETTINGS** -> **SERVICES**.  Toggling the service state in this menu will also immediately start or stop the service, in addition to controlling whether it will start at next system boot.
-For filenames there are some rules! This is caused by the handling for this kind of usecase. Every file is exported as systemvariable so only charaters from A-Z and digits 0-9 (not as first letter!) are allowed. Spaces, dots, bracketes and regional chars like ß,œ or я are not allowed.
+**Disabling** services (with ''batocera-services disable'') doesn't **stop** them. That needs to be done manually with ''batocera-services stop''. Disabling them only means that they will not be automatically started after the next system startup.
+**Enabling** them (with ''batocera-services enable'') works the same. To actually **start** a service, enable it first, then restart Batocera or use ''batocera-services start''.
+===== Filename conventions =====
+For filenames there are some specfic rules! This is caused as every service-file is exported as systemvariable. So only charaters from A-Z (upper- and lowercase, mixed), the underscore and digits (Please avoid as first character) are allowed.
+Spaces, dots, bracketes and regional characters like ß,œ or я are not allowed in general and (as said again because of bad suprise!) do not use digits as first sign.
 Some file examples:
@@ Line 23: / Line 39: @@
   * Hallöle --> not allowed
-You can test your script names by typing `batocera-services list user` you will receive a result-list of your services.
+You can test your script-names by typing ''batocera-services list user'', then you will receive a result-list. Every invalid script name is not used and therefore can not be activated in ES frontend.
 <code>
@@ Line 35: / Line 51: @@
 </code>
-==== Conditions ====
+===== Conditions =====
-All these scripts are initiated through `/etc/init.d/S99userservices` so there is a `start` and a `stop` condition that can be used inside the scripts. S99 will wait for all scripts to be finished, so be aware of your scripts using sleep timers and infinite do-while loops.
+All these scripts are initiated through ''/etc/init.d/S99userservices'' so there is a **start** and a **stop** condition that can be used inside the scripts. S99 will wait for all scripts to be finished in stop condition, so be aware of your scripts using sleep timers and infinite do-while loops.
-As a bonus: These scripts can also be used on FAT-file systems and are started through bash-interpreter, so you don't need them executable through `chmod +x your_service_file` command.
+ ===== Script Examples =====
-==== Script Examples ====
+**Just some examples to show how powerful these kind of scripts can be.**
-<code bash|SANATIZE_SERVICE>
+This script example is able to spawn "sub-services", these spawned scripts have just one single task: Set a single value to ''batocera.conf''. The script is furthermore able to detect a setted and active value and to show this in your ES-Service-Section. The usage is simple. Place the script in ''/userdata/system/services/'' and start the service. Then leave the menu and select the Service-Section again. You'll now see that there are 2 new services are in place: ''PI_RETROFLAG'' and ''PI_RETROFLAG_ADV''. If you select one of these, then the value **RETROFLAG** or **RETROFLAG_ADV** will be written to Batoceras config file. If you activate all the spawned services then the value is used.
+By **stopping** the mainservice, all sub-services will be removed from system. I used the ''system.power.switch'' value here that is reasonable for all Raspberry Pie platforms. By **starting** the mainservice again, all sub-services will be created again. Usually a system reboot is needed to make the powerswitches work.
+<code bash| PI_POWERSWITCHES>
 #!/bin/bash
-# Sanatize Service by crcerror (second life)
+# Spawn Service Script by cyperghost (second life)
-# Selfrepair first
+# This is a crude example, but shows the ability of the new services
-grep -rlq $'\r' "$0" && dos2unix -k -q "$0" && exit 0
+switch="RETROFLAG RETROFLAG_ADV" #Add here more values
+path="/userdata/system/services"
+# First argument for condition: start=service switched on
+case ${1} in
+start)
+    # Create single scripts per echo command and place them to /services
+    # The test start inside the sub-services is needed to set the system.power.switch parameter only if service is ticked
+    for i in ${switch};
+    do
+        echo "[ \${1} == start ] && batocera-settings-set system.power.switch ${i}" > ${path}/PI_${i}
+    done
+    # Check and set indicator to on if a proper value is found in batocera.conf, if there is no value then indicator is setted to off
+    active_service=$(batocera-settings-get system.power.switch)
+    if [ -n ${active_service} ];
+    then
+        batocera-services enable PI_${active_service}
+    fi
+;;
+stop)
+    #Remove all entries from filesystem and in batocera.conf (done through batocera-services)
+    for i in ${switch};
+    do
+        rm -f ${path}/PI_${i}
+        batocera-services disable PI_${i}
+    done
+;;
+esac
+</code>
+----
+This script will check for proper filenames and automatically alter them and even make backups. The idea was born by an interesting thread on github, where a user mentioned that downloaded scripts from this wiki got Windows linebreaks. This was just caused by browser download. The question is: **How to fix Windows linebreaks without manually Code editing?** \\
+Of course it an be done.... -- Run a small Sanatizer script (tools like DOS2UNIX do their best job here)
+<code bash| SANATIZE_SERVICE>
+#!/usr/bin/env -S bash #PROTECTED
+# Sanatize Service by crcerror (second life) - or: How to fix Windows linebreaks without manually code edits?
+grep -rlq $'\r' "$0" && dos2unix -k -q "$0" && exit 0 # Selfrepair for called script
 #only on start condition
-[[ $1 == stop ]] && exit 0
+[[ $1 == start ]] || exit 0
 # Sanatize Windows-CRLF to unix-style
@@ Line 57: / Line 120: @@
 pushd /userdata/system/services > /dev/null
-find -type f -printf '%f\n' |
 while read USER_SERVICE
 do
-        SANITIZE=${SERVICE//[^0-9A-Za-z_]/}
+    grep -rlq $'\r' "${USER_SERVICE}" && dos2unix -k -q "${USER_SERVICE}"
-        SANITIZE=$(echo "$SANITIZE" | sed 's/^[[:digit:]]*//')
-        if [[ "${USER_SERVICE}" =! "${SANITIZE}" ]]
+    SANATIZE="${USER_SERVICE//[^0-9A-Za-z_]/_}"
-        then
+    SANATIZE="$(echo "$SANATIZE" | sed 's/^[[:digit:]]*//')"
-           mv -b --suffix=_backup "${USER_SERVICE}" "${SANITIZE}"
+    if [[ "${USER_SERVICE}" != "${SANATIZE}" ]]
-           grep -rlq $'\r' "${SANITIZE}" && dos2unix -kq "${SANITIZE}"
+    then
-        fi
+        mv -b --suffix=_bak "${USER_SERVICE}" "${SANATIZE}"
+    fi
-        grep -rlq $'\r' "${USER_SERVICE}" && dos2unix -kq "${USER_SERVICE}"
+done < <(find -type f -printf '%f\n')
-done
 popd > /dev/null
 </code>
+Some deeper explainations: \\
+If you download this script in a Windows-Browser and then you copy the file to your Batocera-device, then it is likely that these files are in wrong format and every codeline got a ''^M'' at it's end. Therefore every script-command and codelogic will fail (even the #!/bin/env for calling the command interpreter without setted proper seperator and environment). \\
+As the first real code line is a logic-link-chain all commands will be executed proberly. I used two trick here:
+  - A remark ''# my remark'' to avoid command breaks
+  - Setted a bash envirionment with proper seperators
+Nevertheless the script is able to "repair" itself and will work properly if you start it up a second time or reboot Batocera twice after script activation through EmulationStation. If you left this service active in background then at last on reboot, every user-added service script can be repaired now.