RetroPie-Setup  4.8.6
Functions
helpers.sh File Reference

RetroPie helpers library. More...

Functions

 printMsgs (type, message)
 Prints messages in a variety of ways. More...
 
 printHeading (message)
 Calls PrintMsgs with "heading" type. More...
 
 fatalError (message)
 Calls PrintMsgs with "heading" type, and exits immediately. More...
 
 runCmd (command)
 Calls command and record any non zero return codes for later printing. More...
 
 hasFlag (string, flag)
 Checks for a flag in a string (consisting of space separated flags). More...
 
 isPlatform ()
 Test for current platform / platform flags. More...
 
 addLineToFile (line, file)
 Adds a new line of text to a file. More...
 
 editFile (file)
 Opens an editing dialog for specified file. More...
 
 inputBox (title, text, minchars)
 Opens an inputbox dialog and echoes resulting text. Uses the OSK if installed. More...
 
 hasPackage (package, version, comparison)
 Test for an installed Debian package / package version. More...
 
 aptUpdate ()
 Calls apt-get update (if it has not been called before).
 
 aptInstall (packages)
 Calls apt-get install with the packages provided. More...
 
 aptRemove (packages)
 Calls apt-get remove with the packages provided. More...
 
 getDepends (packages)
 Installs packages if they are not installed. More...
 
 rpSwap (command, memory)
 Adds additional swap to the system if needed. More...
 
 gitPullOrClone (dest, repo, branch, commit, depth)
 Git clones or pulls a repository. More...
 
 rmDirExists (dir)
 Removes a directory and all contents if it exists. More...
 
 mkUserDir (dir)
 Creates a directory owned by the current user. More...
 
 mkRomDir (dir)
 Creates a directory under $romdir owned by the current user. More...
 
 moveConfigDir (from, to)
 Moves the contents of a folder and symlinks to the new location. More...
 
 moveConfigFile (from, to)
 Moves the file and symlinks to the new location. More...
 
 diffFiles (file1, file2)
 Compares two files using diff. More...
 
 compareVersions (version, operator)
 version second version to compare More...
 
 dirIsEmpty (path, files_only)
 
 copyDefaultConfig (from, to)
 Copies a default configuration. More...
 
 renameModule (from, to)
 Renames an existing module. More...
 
 addUdevInputRules ()
 Creates a udev rule to adjust input device permissions. More...
 
 setBackend (emulator.cfg, backend, force)
 Set a backend rendering driver for a module. More...
 
 getBackend (emulator.cfg)
 Get a backend rendering driver for a module. More...
 
 setDispmanx (module_id, status)
 Sets a dispmanx flag for a module. This function is deprecated. More...
 
 iniFileEditor (delim, quote, config)
 Allows editing of ini files with a user friendly dialog based gui. More...
 
 setESSystem (fullname, name, path, extension, command, platform, theme)
 Adds a system entry for Emulation Station (to /etc/emulationstation/es_systems.cfg). More...
 
 ensureSystemretroconfig (system)
 Deprecated - use defaultRAConfig. More...
 
 defaultRAConfig (system,...)
 Creates a default retroarch.cfg for specified system in $md_root_dir/$system/retroarch.cfg. More...
 
 setRetroArchCoreOption (option, value)
 Sets a retroarch core option in $configdir/all/retroarch-core-options.cfg. More...
 
 setConfigRoot (dir)
 Sets module config root $md_conf_root to subfolder from $configdir More...
 
 loadModuleConfig (params)
 Load the settings for a module. More...
 
 applyPatch (patch)
 Apply a patch if it has not already been applied to current folder. More...
 
 runCurl ()
 Run curl with chosen parameters and handle curl errors. More...
 
 download (url, dest)
 Download a file. More...
 
 downloadAndVerify (url, dest)
 Download a file and a corresponding .asc signature and verify the contents. More...
 
 downloadAndExtract (url, dest, optional)
 Download and extract an archive. More...
 
 ensureFBMode (res_x, res_y)
 Add a framebuffer mode to /etc/fb.modes. More...
 
 joy2keyStart (left, right, up, down, but1, but2, but3, butX)
 Start joy2key process in background to map joystick presses to keyboard. More...
 
 joy2keyStop ()
 Stop previously started joy2key process.
 
 getPlatformConfig (key)
 gets a config from a platforms.cfg ini More...
 
 addSystem (system, fullname, exts)
 adds an emulator entry / system More...
 
 delSystem (system)
 Deletes a system. More...
 
 addPort (id, port, name, cmd, game)
 Adds a port to the emulationstation ports menu. More...
 
 addEmulator (default, id, name, cmd)
 Adds a new emulator for a system. More...
 
 delEmulator (id, system)
 Deletes an emulator entry / system. More...
 
 patchVendorGraphics (filename)
 
 dkmsManager (mode)
 
 getIPAddress (dev)
 Obtains the current externally routable source IP address of the machine. More...
 
 isConnected ()
 Simple check to see if there is a connection to the Internet. More...
 
 adminRsync (src, dest, params)
 Rsyncs data to remote host for admin modules. More...
 
 signFile (file)
 signs file with $__gpg_signing_key More...
 

Detailed Description

RetroPie helpers library.

Function Documentation

◆ addEmulator()

addEmulator ( default  ,
id  ,
name  ,
cmd   
)

Adds a new emulator for a system.

Parameters
default1 to make the emulator / command default for the system if no default already set
idunique id of the module / command
namename of the system to add the emulator to
cmdcommandline to launch

This is the primary function for adding emulators to a system which can be switched between via the runcommand launch menu

addEmulator 1 "vice-x64" "c64" "$md_inst/bin/x64 %ROM%"
addEmulator 0 "vice-xvic" "c64" "$md_inst/bin/xvic %ROM%"

Would add two optional emulators for the c64 - with vice-x64 being the default if no default was already set. This adds entries to $configdir/$system/emulators.cfg with

id = "cmd"
default = id

Which are then selectable from runcommand when launching roms

For libretro emulators, cmd needs to only contain the path to the libretro library.

eg. for the lr-fcuemm module

addEmulator 1 "$md_id" "nes" "$md_inst/fceumm_libretro.so" 

◆ addLineToFile()

addLineToFile ( line  ,
file   
)

Adds a new line of text to a file.

Parameters
lineline to add
filefile to add line to

◆ addPort()

addPort ( id  ,
port  ,
name  ,
cmd  ,
game   
)

Adds a port to the emulationstation ports menu.

Parameters
idid of the module / command
portname of the port
namedisplay name for the launch script
cmdcommandline to launch
gamerom/game parameter (optional)

Adds an emulators.cfg entry as with addSystem but also creates a launch script in $datadir/ports/$name.sh.

Can also optionally take a game parameter which can be used to create multiple launch scripts for different games using the same engine - eg for quake

addPort "lr-tyrquake" "quake" "Quake" "$emudir/retroarch/bin/retroarch -L $md_inst/tyrquake_libretro.so --config $md_conf_root/quake/retroarch.cfg %ROM%" "$romdir/ports/quake/id1/pak0.pak"
addPort "lr-tyrquake" "quake" "Quake Mission Pack 2 (rogue)" "$emudir/retroarch/bin/retroarch -L $md_inst/tyrquake_libretro.so --config $md_conf_root/quake/retroarch.cfg %ROM%" "$romdir/ports/quake/id1/rogue/pak0.pak"

Would add an entry in $configdir/ports/quake/emulators.cfg for lr-tyrquake (setting it to default if no default set) and create a launch script in $romdir/ports for each game.

◆ addSystem()

addSystem ( system  ,
fullname  ,
exts   
)

adds an emulator entry / system

Parameters
systemsystem to add
fullnameoptional fullname for the frontend (if not present in platforms.cfg)
extsoptional extensions for the frontend (if not present in platforms.cfg)

Adds a system to one of the frontend launchers

◆ addUdevInputRules()

addUdevInputRules ( )

Creates a udev rule to adjust input device permissions.

Creates a udev rule in /etc/udev/rules.d/99-input.rules to make everything in /dev/input it writable by any user in group input.

◆ adminRsync()

adminRsync ( src  ,
dest  ,
params   
)

Rsyncs data to remote host for admin modules.

Parameters
srcsrc folder on local system - eg "$__tmpdir/stats/"
destdestination folder on remote system - eg "stats/"
paramsadditional rsync parameters - eg –delete

Used to rsync data to our server for admin modules. Default remote user is retropie, host is $__binary_host and default port is 22. These can be overridden with env vars __upload_user __upload_host and __upload_port

The default parameters for rsync are "-av --delay-updates" - more can be added via the 3rd+ argument

◆ applyPatch()

applyPatch ( patch  )

Apply a patch if it has not already been applied to current folder.

Parameters
patchfilename of patch to apply

This is used for applying patches against upstream code.

Return values
0on success
1on failure

◆ aptInstall()

aptInstall ( packages  )

Calls apt-get install with the packages provided.

Parameters
packagespackage / space separated list of packages to install

◆ aptRemove()

aptRemove ( packages  )

Calls apt-get remove with the packages provided.

Parameters
packagespackage / space separated list of packages to install

◆ compareVersions()

compareVersions ( version  ,
operator   
)

version second version to compare

Parameters
versionfirst version to compare
operatoroperator to use (lt le eq ne ge gt)
Return values
0if the comparison was true
1if the comparison was false

◆ copyDefaultConfig()

copyDefaultConfig ( from  ,
to   
)

Copies a default configuration.

Parameters
fromsource file
todestination file

Copies from the source file to the destination file if the destination file doesn't exist. If the destination is the same nothing is done. If different the source is copied to $destination.rp-dist.

◆ defaultRAConfig()

defaultRAConfig ( system  ,
  ... 
)

Creates a default retroarch.cfg for specified system in $md_root_dir/$system/retroarch.cfg.

Parameters
systemsystem to create retroarch.cfg for
...optional key then value parameters to be used in the config

Additional default configuration values can be provided as parameters to the function - eg. "fps_show" "true" as two parameters would add a default entry of fps_show = "true" to the default configuration. This function uses $md_conf_root as a base, so there is no need to use "ports/$system" for libretro ports as with the older ensureSystemretroconfig

◆ delEmulator()

delEmulator ( id  ,
system   
)

Deletes an emulator entry / system.

Parameters
idid of emulator to delete
systemsystem to delete from

Delete the entry for the id from $configdir/$system/emulators.cfg. If there are no more emulators for the system present, it will also delete the system entry from the installed frontends.

◆ delSystem()

delSystem ( system  )

Deletes a system.

Parameters
systemsystem to delete

deletes a system from all frontends.

◆ diffFiles()

diffFiles ( file1  ,
file2   
)

Compares two files using diff.

Parameters
file1file to compare
file2file to compare
Return values
0if the files were the same
1if they were not
>1an error occurred

◆ dirIsEmpty()

dirIsEmpty ( path  ,
files_only   
)
Parameters
pathpath to directory
files_onlyset to 1 to ignore sub directories
Return values
0if the directory is empty
1if the directory is not empty

◆ dkmsManager()

dkmsManager ( mode  )
Parameters
modedkms operation type @module_name name of dkms module @module_ver version of dkms module Helper function to manage DKMS modules installed by RetroPie

◆ download()

download ( url  ,
dest   
)

Download a file.

Parameters
urlurl of file
destdestination name (optional), use - for stdout

Download a file - if the dest parameter is omitted, the file will be downloaded to the current directory. If the destination name is a hyphen (-), then the file will be outputted to stdout, for piping to another command or retrieving the contents directly to a variable. If the destination is a folder, extract with the basename from the url to the destination folder.

Return values
0on success

◆ downloadAndExtract()

downloadAndExtract ( url  ,
dest  ,
optional   
)

Download and extract an archive.

Parameters
urlurl of archive
destdestination folder for the archive
optionaladditional parameters to pass to the decompression tool.

Download and extract an archive.

Return values
0on success

◆ downloadAndVerify()

downloadAndVerify ( url  ,
dest   
)

Download a file and a corresponding .asc signature and verify the contents.

Parameters
urlurl of file
destdestination file (optional)

Download a file and a corresponding .asc signature and verify the contents. The .asc file will be downloaded to verify the file, but will be removed after downloading. If the dest parameter is omitted, the file will be downloaded to the current directory

Return values
0on success

◆ editFile()

editFile ( file  )

Opens an editing dialog for specified file.

Parameters
filefile to edit

◆ ensureFBMode()

ensureFBMode ( res_x  ,
res_y   
)

Add a framebuffer mode to /etc/fb.modes.

Parameters
res_xwidth of mode
res_yheight of mode

Useful for adding specific resolutions used by emulators so SDL1 can use them and utilise the RPI hardware scaling. Without for example a 320x240 mode in fb.modes many of the emulators that output to the framebuffer and were not set to use the dispmanx SDL1 backend would just show in a small area of the screen.

◆ ensureSystemretroconfig()

ensureSystemretroconfig ( system  )

Deprecated - use defaultRAConfig.

Parameters
systemsystem to create retroarch.cfg for

Creates a default retroarch.cfg for specified system in $configdir/$system/retroarch.cfg.

◆ fatalError()

fatalError ( message  )

Calls PrintMsgs with "heading" type, and exits immediately.

Parameters
messagestring or array of messages to display

◆ getBackend()

getBackend ( emulator.  cfg)

Get a backend rendering driver for a module.

Parameters
emulator.cfgkey to get backend for

Get a backend rendering driver for a module The function echos the result so the value can be captured using var=$(getBackend "$module_id")

◆ getDepends()

getDepends ( packages  )

Installs packages if they are not installed.

Parameters
packagespackage / space separated list of packages to install
Return values
0on success
1on failure

◆ getIPAddress()

getIPAddress ( dev  )

Obtains the current externally routable source IP address of the machine.

Parameters
devoptional specific network device to use for address lookup

This function first tries to obtain an external IPv4 route and otherwise tries an IPv6 route if the IPv4 route can not be determined. If no external route can be determined, nothing will be returned. This function uses Google's DNS servers as the external lookup address.

◆ getPlatformConfig()

getPlatformConfig ( key  )

gets a config from a platforms.cfg ini

Parameters
keykey to look up

gets a config from a platforms.cfg ini first looking in $configdir/all/platforms.cfg then $scriptdir/platforms.cfg allowing users to override any parts of $scriptdir/platforms.cfg

◆ gitPullOrClone()

gitPullOrClone ( dest  ,
repo  ,
branch  ,
commit  ,
depth   
)

Git clones or pulls a repository.

Parameters
destdestination directory
reporepository to clone or pull from
branchbranch to clone or pull from (optional)
commitspecific commit to checkout (optional - requires branch to be set)
depthdepth parameter for git. (optional)

depth parameter will default to 1 (shallow clone) so long as __persistent_repos isn't set. A depth parameter of 0 will do a full clone with all history.

◆ hasFlag()

hasFlag ( string  ,
flag   
)

Checks for a flag in a string (consisting of space separated flags).

Parameters
stringstring to search in
flagflag to search for
Return values
0if the flag was found
1if the flag was not found

◆ hasPackage()

hasPackage ( package  ,
version  ,
comparison   
)

Test for an installed Debian package / package version.

Parameters
packagename of Debian package
versionrequested version (optional)
comparisontype of comparison - defaults to ge (greater than or equal) if a version parameter is provided.
Return values
0if the requested package / version was installed
1if the requested package / version was not installed

◆ iniFileEditor()

iniFileEditor ( delim  ,
quote  ,
config   
)

Allows editing of ini files with a user friendly dialog based gui.

Parameters
delimini file delimiter eg. ' = '
quoteini file quoting character eg. '"'
configini file to edit

Some arrays need to be configured before calling this, which are used to display what can be edited and the options available.

The first array is $ini_titles which provides the titles for each entry..

The second array is $ini_descs which contains a help description for each entry.

The third array is $ini_options which contains multiple space separated strings in each element to control how each entry should be managed.

The $ini_options array is constructed as follows:

If the first string is _function_ then the next string should be a function name that will handle that entry. The function will be called with a parameter get or set. The function should return the value for get via echo and should handle any gui functionality when called with set. This can be used for example to build custom dialogs.

If the first option is anything else, it is assumed to be a key name, followed by a control type and a list of parameters.

Control types are:

  • _id_ map the following values to an id
  • _string_ allow the value to be inputted by the user
  • _file_ select from a list of files. The following values are wildcard, then file path.

If none of the above, then the rest of the array element should be a list of possible values for the key.

Some examples for ini_options:

ini_options=('video_smooth true false')

Allow setting of the key video_smooth with the values of true or false

ini_options=('aspect_ratio_index _id_ 4:3 16:9 16:10)

Allow setting of the key aspect_ratio_index with the values 0 1 or 2 which correspond to the ratios. The user is shown the ratios, but the ini configuration is set to the id (4:3 = 0, 16:9 = 1, 16:10 = 2).

ini_options=('_function_ _video_fullscreen_configedit')

The function _video_fullscreen_configedit is called with get or set to manage this entry.

ini_options=("video_shader _file_ *.*p $rootdir/emulators/retroarch/shader")

The key video_shader will be able to be set to a list of files in $rootdir/emulators/retroarch/shader that match the wildcard *.*p

For more examples you can check out the code in supplementary/configedit.sh

◆ inputBox()

inputBox ( title  ,
text  ,
minchars   
)

Opens an inputbox dialog and echoes resulting text. Uses the OSK if installed.

Parameters
titletitle of dialog
textdefault text
mincharsminimum chars to accept

The input dialog has OK/Cancel buttons and can be cancelled by the user. The dialog will enforce the minimum number of characters expected, re-prompting the user.

Return values
0when the user entered the text and chose the OK button
!=0 when the user chose the Cancel button

◆ isConnected()

isConnected ( )

Simple check to see if there is a connection to the Internet.

Uses the getIPAddress function to check if we have a route to the Internet. Also sets __NET_ERRMSG with an error message for use in packages / setup to display to the user if not.

Return values
0on success
1on failure

◆ isPlatform()

isPlatform ( )

Test for current platform / platform flags.

Parameters
platform

◆ joy2keyStart()

joy2keyStart ( left  ,
right  ,
up  ,
down  ,
but1  ,
but2  ,
but3  ,
butX   
)

Start joy2key process in background to map joystick presses to keyboard.

Parameters
leftmapping for left
rightmapping for right
upmapping for up
downmapping for down
but1mapping for button 1
but2mapping for button 2
but3mapping for button 3
butXmapping for button X ...

Arguments are curses capability names or hex values starting with '0x' see: http://pubs.opengroup.org/onlinepubs/7908799/xcurses/terminfo.html

◆ loadModuleConfig()

loadModuleConfig ( params  )

Load the settings for a module.

Parameters
paramsspace separated list of key=value parameters

This allows modules to quickly load some settings from an ini file. It can provide a shortcut way to load a set of keys from an ini file into variables.

It requires iniConfig to be called first to specify the format and file. eg.

iniConfig " = " '"' "$configdir/all/mymodule.cfg"
eval $(loadModuleConfig \
   'some_option=1' \
   'another_option=2'

This would load the keys some_option and another_option into local variables some_option and another_option. If the keys did not exist in mymodule.cfg the variables would be initialised to 1 and 2.

◆ mkRomDir()

mkRomDir ( dir  )

Creates a directory under $romdir owned by the current user.

Parameters
dirrom directory to create

◆ mkUserDir()

mkUserDir ( dir  )

Creates a directory owned by the current user.

Parameters
dirdirectory to create

◆ moveConfigDir()

moveConfigDir ( from  ,
to   
)

Moves the contents of a folder and symlinks to the new location.

Parameters
fromsource directory
todestination directory

◆ moveConfigFile()

moveConfigFile ( from  ,
to   
)

Moves the file and symlinks to the new location.

Parameters
fromsource file
todestination file

◆ patchVendorGraphics()

patchVendorGraphics ( filename  )
Parameters
filenamefile to patch

replace declared dependencies of old vendor graphics libraries with new names Temporary compatibility workaround for legacy software to work on new Raspberry Pi firmwares.

◆ printHeading()

printHeading ( message  )

Calls PrintMsgs with "heading" type.

Parameters
messagestring or array of messages to display

◆ printMsgs()

printMsgs ( type  ,
message   
)

Prints messages in a variety of ways.

Parameters
typestyle of display to use - dialog, console or heading
messagestring or array of messages to display

◆ renameModule()

renameModule ( from  ,
to   
)

Renames an existing module.

Parameters
fromsource file
todestination file

Renames an existing module, moving it's install folder to the new location and changing any references to it in emulators.cfg.

◆ rmDirExists()

rmDirExists ( dir  )

Removes a directory and all contents if it exists.

Parameters
dirdirectory to remove

◆ rpSwap()

rpSwap ( command  ,
memory   
)

Adds additional swap to the system if needed.

Parameters
commandon to add swap if needed and off to remove later
memorytotal memory needed (swap added = memory needed - available memory)

◆ runCmd()

runCmd ( command  )

Calls command and record any non zero return codes for later printing.

Parameters
commandcommand to run
Returns
whatever the command returns.

◆ runCurl()

runCurl ( )

Run curl with chosen parameters and handle curl errors.

@params ... commandline arguments to pass to curl

Runs curl with the provided parameters, whilst also capturing the output and extracting any error message, which is stored in the global variable __NET_ERRMSG. Function returns the return code provided by curl. The environment variable __curl_opts can be set to override default curl parameters, eg - timeouts etc.

Return values
curlreturn value

◆ setBackend()

setBackend ( emulator.  cfg,
backend  ,
force   
)

Set a backend rendering driver for a module.

Parameters
emulator.cfgkey to configure backend for
backendname of the backend to set
forceset to 1 to force the change

Set a backend rendering driver for a module - can be currently default, dispmanx or x11. This function will only set a backend if

  • It's not already configured, or
  • The 3rd parameter (force) is set to 1 The emulator.cfg key is usually the module_id but some modules add multiple emulator.cfg entries which are all handled separately. A module can use a _backend_set_MODULE function hook which is called from the backends module to handle calling setBackend for additional emulator.cfg entries. See "fuse" scriptmodule for an example.

◆ setConfigRoot()

setConfigRoot ( dir  )

Sets module config root $md_conf_root to subfolder from $configdir

Parameters
dirdirectory under $configdir to use

This is used for ports that are not actually in scriptmodules/ports as they would get the wrong config root otherwise.

◆ setDispmanx()

setDispmanx ( module_id  ,
status   
)

Sets a dispmanx flag for a module. This function is deprecated.

Parameters
module_idname of module to add dispmanx flag for
statusinitial status of flag (0 or 1)

Set a dispmanx flag for a module as to whether it should use the sdl1 dispmanx backend by default or not (0 for framebuffer, 1 for dispmanx). This function is deprecated and instead setBackend should be used.

◆ setESSystem()

setESSystem ( fullname  ,
name  ,
path  ,
extension  ,
command  ,
platform  ,
theme   
)

Adds a system entry for Emulation Station (to /etc/emulationstation/es_systems.cfg).

Parameters
fullnamefull name of system
nameshort name of system
pathrom path
extensionfile extensions to show
commandcommand to run
platformname of platform (used by es for scraping)
themename of theme to use

◆ setRetroArchCoreOption()

setRetroArchCoreOption ( option  ,
value   
)

Sets a retroarch core option in $configdir/all/retroarch-core-options.cfg.

Parameters
optionoption to set
valuevalue to set

◆ signFile()

signFile ( file  )

signs file with $__gpg_signing_key

Parameters
filepath to file to sign

signs file with $__gpg_signing_key creating corresponding .asc file in the same folder