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.

Copyright: GPLv3

Function Documentation

◆ addEmulator()

addEmulator	(	default	,
		id	,
		name	,
		cmd
	)

Adds a new emulator for a system.

Parameters

default	1 to make the emulator / command default for the system if no default already set
id	unique id of the module / command
name	name of the system to add the emulator to
cmd	commandline 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

line	line to add
file	file to add line to

◆ addPort()

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

Adds a port to the emulationstation ports menu.

Parameters

id	id of the module / command
port	name of the port
name	display name for the launch script
cmd	commandline to launch
game	rom/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

system	system to add
fullname	optional fullname for the frontend (if not present in platforms.cfg)
exts	optional 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

src	src folder on local system - eg "$__tmpdir/stats/"
dest	destination folder on remote system - eg "stats/"
params	additional 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

patch filename of patch to apply

This is used for applying patches against upstream code.

Return values

0	on success
1	on failure

◆ aptInstall()

aptInstall ( packages )

Calls apt-get install with the packages provided.

Parameters

packages package / space separated list of packages to install

◆ aptRemove()

aptRemove ( packages )

Calls apt-get remove with the packages provided.

Parameters

packages package / space separated list of packages to install

◆ compareVersions()

compareVersions	(	version	,
		operator
	)

version second version to compare

Parameters

version	first version to compare
operator	operator to use (lt le eq ne ge gt)

Return values

0	if the comparison was true
1	if the comparison was false

◆ copyDefaultConfig()

copyDefaultConfig	(	from	,
		to
	)

Copies a default configuration.

Parameters

from	source file
to	destination 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

system	system 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

id	id of emulator to delete
system	system 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

system system to delete

deletes a system from all frontends.

◆ diffFiles()

diffFiles	(	file1	,
		file2
	)

Compares two files using diff.

Parameters

file1	file to compare
file2	file to compare

Return values

0	if the files were the same
1	if they were not
>1	an error occurred

◆ dirIsEmpty()

dirIsEmpty	(	path	,
		files_only
	)

Parameters

path	path to directory
files_only	set to 1 to ignore sub directories

Return values

0	if the directory is empty
1	if the directory is not empty

◆ dkmsManager()

dkmsManager ( mode )

Parameters

mode	dkms 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

url	url of file
dest	destination 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

0	on success

◆ downloadAndExtract()

downloadAndExtract	(	url	,
		dest	,
		optional
	)

Download and extract an archive.

Parameters

url	url of archive
dest	destination folder for the archive
optional	additional parameters to pass to the decompression tool.

Download and extract an archive.

Return values

0	on success

◆ downloadAndVerify()

downloadAndVerify	(	url	,
		dest
	)

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

Parameters

url	url of file
dest	destination 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

0	on success

◆ editFile()

editFile ( file )

Opens an editing dialog for specified file.

Parameters

file	file to edit

◆ ensureFBMode()

ensureFBMode	(	res_x	,
		res_y
	)

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

Parameters

res_x	width of mode
res_y	height 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

system system 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

message string or array of messages to display

◆ getBackend()

getBackend ( emulator. cfg )

Get a backend rendering driver for a module.

Parameters

emulator.cfg key 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

packages package / space separated list of packages to install

Return values

0	on success
1	on failure

◆ getIPAddress()

getIPAddress ( dev )

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

Parameters

dev	optional 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

key	key 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

dest	destination directory
repo	repository to clone or pull from
branch	branch to clone or pull from (optional)
commit	specific commit to checkout (optional - requires branch to be set)
depth	depth 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

string	string to search in
flag	flag to search for

Return values

0	if the flag was found
1	if the flag was not found

◆ hasPackage()

hasPackage	(	package	,
		version	,
		comparison
	)

Test for an installed Debian package / package version.

Parameters

package	name of Debian package
version	requested version (optional)
comparison	type of comparison - defaults to `ge` (greater than or equal) if a version parameter is provided.

Return values

0	if the requested package / version was installed
1	if 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

delim	ini file delimiter eg. ' = '
quote	ini file quoting character eg. '"'
config	ini 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

title	title of dialog
text	default text
minchars	minimum 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

0	when 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

0	on success
1	on 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

left	mapping for left
right	mapping for right
up	mapping for up
down	mapping for down
but1	mapping for button 1
but2	mapping for button 2
but3	mapping for button 3
butX	mapping 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

params space 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

dir	rom directory to create

◆ mkUserDir()

mkUserDir ( dir )

Creates a directory owned by the current user.

Parameters

dir	directory to create

◆ moveConfigDir()

moveConfigDir	(	from	,
		to
	)

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

Parameters

from	source directory
to	destination directory

◆ moveConfigFile()

moveConfigFile	(	from	,
		to
	)

Moves the file and symlinks to the new location.

Parameters

from	source file
to	destination file

◆ patchVendorGraphics()

patchVendorGraphics ( filename )

Parameters

filename file 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

message string or array of messages to display

◆ printMsgs()

printMsgs	(	type	,
		message
	)

Prints messages in a variety of ways.

Parameters

type	style of display to use - dialog, console or heading
message	string or array of messages to display

◆ renameModule()

renameModule	(	from	,
		to
	)

Renames an existing module.

Parameters

from	source file
to	destination 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

dir	directory to remove

◆ rpSwap()

rpSwap	(	command	,
		memory
	)

Adds additional swap to the system if needed.

Parameters

command	on to add swap if needed and off to remove later
memory	total memory needed (swap added = memory needed - available memory)

◆ runCmd()

runCmd ( command )

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

Parameters

command command 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

curl	return value

◆ setBackend()

setBackend	(	emulator.	cfg,
		backend	,
		force
	)

Set a backend rendering driver for a module.

Parameters

emulator.cfg	key to configure backend for
backend	name of the backend to set
force	set 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

dir	directory 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_id	name of module to add dispmanx flag for
status	initial 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

fullname	full name of system
name	short name of system
path	rom path
extension	file extensions to show
command	command to run
platform	name of platform (used by es for scraping)
theme	name of theme to use

◆ setRetroArchCoreOption()

setRetroArchCoreOption	(	option	,
		value
	)

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

Parameters

option	option to set
value	value to set

◆ signFile()

signFile ( file )

signs file with $__gpg_signing_key

Parameters

file	path to file to sign

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

Functions

Detailed Description

Function Documentation

◆ addEmulator()

◆ addLineToFile()

◆ addPort()

◆ addSystem()

◆ addUdevInputRules()

◆ adminRsync()

◆ applyPatch()

◆ aptInstall()

◆ aptRemove()

◆ compareVersions()

◆ copyDefaultConfig()

◆ defaultRAConfig()

◆ delEmulator()

◆ delSystem()

◆ diffFiles()

◆ dirIsEmpty()

◆ dkmsManager()

◆ download()

◆ downloadAndExtract()

◆ downloadAndVerify()

◆ editFile()

◆ ensureFBMode()

◆ ensureSystemretroconfig()

◆ fatalError()

◆ getBackend()

◆ getDepends()

◆ getIPAddress()

◆ getPlatformConfig()

◆ gitPullOrClone()

◆ hasFlag()

◆ hasPackage()

◆ iniFileEditor()

◆ inputBox()

◆ isConnected()

◆ isPlatform()

◆ joy2keyStart()

◆ loadModuleConfig()

◆ mkRomDir()

◆ mkUserDir()

◆ moveConfigDir()

◆ moveConfigFile()

◆ patchVendorGraphics()

◆ printHeading()

◆ printMsgs()

◆ renameModule()

◆ rmDirExists()

◆ rpSwap()

◆ runCmd()

◆ runCurl()

◆ setBackend()

◆ setConfigRoot()

◆ setDispmanx()

◆ setESSystem()

◆ setRetroArchCoreOption()

◆ signFile()