Config file: Difference between revisions

From Zaparoo Wiki

← Older edit
VisualWikitext
No edit summary
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
The '''config file''' is the main configuration file of the [[Zaparoo Core|Core software]] service.
The '''config file''' is the main configuration file of the [[Zaparoo Core|Zaparoo Core software]] service.


Where it's located depends on the [[:Category:Platform|platform]] on which the service is running. On [[MiSTer FPGA|MiSTer]], it's located in the <code>/media/fat/zaparoo</code> folder or <code>zaparoo</code> folder in the root of the SD card. The file is always called <code>config.toml</code> on every platform.
Its location depends on the [[:Category:Platform|platform]] where the service is running. On [[MiSTer FPGA|MiSTer]], it's located in the <code>/media/fat/zaparoo</code> folder (i.e. <code>zaparoo</code> folder in the root of the SD card).


The config file is written in [https://toml.io/en/ TOML]. Be aware that although comments are supported in TOML, they will be lost if Core makes updates to this file (e.g. when adjusting settings using the Zaparoo App) and should be avoided for important information.
The file is always called <code>config.toml</code> on every platform.
 
The config file is written in [https://toml.io/en/ TOML]. Be aware that although comments are supported in TOML, ''they will be lost if Core makes updates to this file'' (e.g. when adjusting settings using the Zaparoo App) and should be avoided for important information.


Any changes made to the config file while the Core service is running require the service to be restarted before changes will take effect.
Any changes made to the config file while the Core service is running require the service to be restarted before changes will take effect.


== Options ==
== Options ==
Options in the config file are grouped by sections which start with a header. For example, the [[Config file#audio|audio]] section begins with <code>[audio]</code> and continues until the next header is encountered.
Options in the config file are grouped by sections which start with a header. For example, the [[Config file#audio|audio]] section begins with <code>[audio]</code> and continues until the next header is encountered.


=== Root ===
=== Root ===


The root section does not start with a section header and is the only section that behaves this way. It's reserved for certain options that affect all parts of Core or the config file itself.  
The root section does not start with a section header and is the only section that behaves this way. It's reserved for certain options that affect all parts of Core or the config file itself. <syntaxhighlight lang="toml">
 
config_schema = 1
debug_logging = true
</syntaxhighlight>
==== config_schema ====
==== config_schema ====


Line 45: Line 48:
|}
|}


<code>debug_logging</code> enables or disables logging debug messages to Core log files. It's useful for troubleshooting issues but can make log files difficult to read. This option should be enabled when attempting to reproduce issues for reporting.
<code>debug_logging</code> enables or disables logging debug messages to Core log files. It's useful for troubleshooting issues but can make log files noisy.
 
This option should be enabled when attempting to reproduce issues for reporting.


=== audio ===
=== audio ===
 
<syntaxhighlight lang="toml">
[audio]
scan_feedback = true
</syntaxhighlight>
==== scan_feedback ====
==== scan_feedback ====


Line 65: Line 73:


=== readers ===
=== readers ===
 
<syntaxhighlight lang="toml">
[readers]
auto_detect = true
</syntaxhighlight>
==== auto_detect ====
==== auto_detect ====


Line 79: Line 90:
|}
|}


<code>auto_detect</code> enables or disables Core automatically searching for and probing possible connected readers on the host device. It may be useful to disable this option if auto-detection is causing problems with unrelated connected devices.
<code>auto_detect</code> enables or disables automatically searching for and probing possible connected readers on the host device.
 
It may be required to disable this option if auto-detection is causing problems with unrelated connected devices.


==== readers.scan ====
==== readers.scan ====


<code>readers.scan</code> is a sub-section of <code>readers</code> and must be defined with the header: <code>[readers.scan]</code>
<code>readers.scan</code> is a sub-section of <code>readers</code> and must be defined with the header: <code>[readers.scan]</code><syntaxhighlight lang="toml">
 
[readers.scan]
mode = 'hold'
exit_delay = 3.0
ignore_system = [ 'PC', 'MSX' ]
</syntaxhighlight>
===== mode =====
===== mode =====


Line 100: Line 117:
<code>mode</code> defines the behavior of scans. It has two options:
<code>mode</code> defines the behavior of scans. It has two options:


- <code>tap</code> is the default mode and simply means when a token is tapped used with a reader it can be removed without affecting anything else. If a token is tapped, removed and then tapped again it will relaunch playing media even if it's the exact same media.
* <code>tap</code> is the default mode and means when a token is used with a reader it can be removed again without affecting the playing media. If a token is tapped, removed and then tapped again it will relaunch the already playing media.
 
* <code>hold</code> mode makes it so a token must be held to the reader for as long as any launched media will play. That is, after a token is removed from the reader, it will exit the media. This makes a token act more like real physical media. '''Core does not currently make any attempt to save before exiting media.'''
- <code>hold</code> mode makes it so a token must be held to the reader for as long as any launched media will run. That is, after a token is removed from the reader, it will exit. This makes a token act more like real physical media. '''Core does not currently make any attempt to save before exiting media.'''


===== exit_delay =====
===== exit_delay =====
Line 117: Line 133:
|}
|}


<code>exit_delay</code> adds a delay, in seconds, before media is exited after a token is removed from a reader. It's only active if <code>hold</code> mode is also active.
<code>exit_delay</code> adds a delay, in seconds, before media is exited after a token is removed from a reader. It's only active if <code>hold</code> [[Config file#mode|mode]] is also active.
 
For example, if <code>exit_delay</code> was set to <code>2.3</code>, it would mean when a token is removed from a reader, instead of immediately exiting the media, a timer is started for 2.3 seconds first. If the same token is placed back on the reader before the timer is complete, the timer will be cleared and the media won't exit.


For example, if <code>exit_delay</code> was set to <code>2.3</code>, it would mean when a token is removed from a reader, instead of instantly exiting the media, a timer is started for 2.3 seconds first. If the same token is placed back on the reader before the timer is complete, it will be cleared and the media won't exit.
This feature can be useful if you want to, using a single reader, scan other tokens such as adding credit without exiting the current game.


===== ignore_system =====
===== ignore_system =====
Line 134: Line 152:
|}
|}


<code>ignore_system</code> is a list of systems which will not be affected by the <code>exit_delay</code> option. It's only applicable in <code>hold</code> mode.
<code>ignore_system</code> is a list of systems which will not exit playing media on token removal. It's only active in <code>hold</code> mode.


==== readers.connect ====
==== readers.connect ====


<code>readers.connect</code> manually defines a reader which is physically connected to the host device and is not auto-detected. It's a sub-section that can be defined multiple times, and must have this header: <code>[[readers.connect]]</code>
<code>readers.connect</code> manually defines a reader which is physically connected to the host device and is not auto-detected. It's a sub-section that can be defined multiple times, and must have this header: <code><nowiki>[[readers.connect]]</nowiki></code>


Pay attention to the double pairs of square brackets. Each defined <code>readers.connect</code> section must have its own header.
Pay attention to the double pairs of square brackets. Each defined <code>readers.connect</code> section must have its own header.<syntaxhighlight lang="toml">
[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB0'


[[readers.connect]]
driver = 'file'
path = '/tmp/some_file'
</syntaxhighlight>
===== driver =====
===== driver =====


Line 155: Line 180:
|}
|}


<code>driver</code> specifies which reader driver should be used to attempt connection to the reader device. See reader drivers for a list of possible options.
<code>driver</code> specifies which reader driver should be used to attempt connection to the reader device. See [[reader drivers]] for a list of possible options.


===== path =====
===== path =====
Line 170: Line 195:
|}
|}


<code>path</code> is an argument for the specified reader driver for how the device should be found. See reader drivers for what this argument should look like for the selected driver.  
<code>path</code> is an argument for the specified reader driver for how the device should be found. See [[reader drivers]] for what this argument should look like for the driver.  


=== systems ===
=== systems ===
Line 176: Line 201:
==== systems.default ====
==== systems.default ====


<code>systems.default</code> overrides the default behavior of the specified system. It's a sub-section that can be defined multiple times, and must have this header: <code>[[systems.default]]</code>
<code>systems.default</code> overrides the default behavior of the specified system. It's a sub-section that can be defined multiple times, and must have this header: <code><nowiki>[[systems.default]]</nowiki></code>
 
Pay attention to the double pairs of square brackets. Each defined <code>systems.default</code> section must have its own header.


Pay attention to the double pairs of square brackets. Each defined <code>systems.default</code> section must have its own header.<syntaxhighlight lang="toml">
[[systems.default]]
system = 'SNES'
launcher = 'SindenSNES'
before_exit = '**input.keyboard:{f12}||**delay:2000'
</syntaxhighlight>
===== system =====
===== system =====


Line 193: Line 222:
|}
|}


ID of the system this default override entry applies to.
ID of the [[system]] this default override entry applies to.


===== launcher =====
===== launcher =====
Line 208: Line 237:
|}
|}


ID of the launcher that should be used by default when media in this system is launched.
ID of the [[launcher]] that should be used by default when media in this system is launched.
 
===== before_exit =====
{| class="wikitable"
|+
!Key
!Type
!Default
|-
|before_exit
|string
|
|}
A snippet of [[ZapScript]] to be run before media exits if [[Config file#readers.scan|hold mode]] is enabled. Blocks before moving onto exit so commands like [[ZapScript#Delay Command Execution (delay)|delay]] can be used.


=== launchers ===
=== launchers ===
 
<syntaxhighlight lang="toml">
[launchers]
index_root = [
    '/media/alt_mount/games'
]
allow_file = [
    '^/media/fat/something.mgl$'
]
</syntaxhighlight>
==== index_root ====
==== index_root ====


Line 225: Line 275:
|}
|}


<code>index_root</code> is a list of paths on the host device that should also be searched when indexing media during a media database updated.
<code>index_root</code> is a list of paths on the host device that should ''also'' be searched when indexing media during a media database update.


For example, if <code>index_root</code> was set to <code>[ '/media/fat/other_place' ]</code>, a database update will search all standard places like normal but then also attempt to search ''/media/fat/other_place/SNES'', ''/media/fat/other_place/Genesis'', etc. for potential media.
For example, if <code>index_root</code> was set to <code>[ '/media/fat/other_place' ]</code>, a database update will search all standard locations like normal but then also attempt to search ''/media/fat/other_place/SNES'', ''/media/fat/other_place/Genesis'', etc. for potential media.


==== allow_file ====
==== allow_file ====
Line 242: Line 292:
|}
|}


<code>allow_file</code> explicitly allows a file to be launched from a token even if it hasn't been indexed as part of a system.
<code>allow_file</code> allows certain files to be launched if their assigned launcher requires it.
 
This is used on platforms like [[Windows]] to allow executable files to be launched with tokens, where this ability is useful but would be a security issue if allowed globally.
 
Each entry in this option is a [https://github.com/google/re2/wiki/Syntax Regular Expression]. Notes on usage here:


This is used on platforms like Windows to allow executable files to be launched with tokens, where this ability is useful but would be a security concern if allowed globally. Paths are case-insensitive one the Windows platform.
* An entry is considered a '''partial match''' unless it's surrounded by a <code>^</code> and <code>$</code>.
* On Windows, file path separators must be escaped: <code>C:\\Test\\Thing.exe</code>
* An entry can be made case-insensitive by putting <code>(?i)</code> at the beginning.


=== zapscript ===
=== zapscript ===
 
<syntaxhighlight lang="toml">
==== allow_shell ====
[zapscript]
allow_execute = [
    '^touch /tmp/tap_time$',
    '^/media/fat/linux/mplayer .+'
]
</syntaxhighlight>
==== allow_execute ====


{| class="wikitable"
{| class="wikitable"
Line 256: Line 318:
!Default
!Default
|-
|-
|allow_shell
|allow_execute
|string[]
|string[]
|[]
|[]
|}
|}


<
<code>allow_execute</code> allows specific executables and arguments to be run using the <code>**execute</code> ZapScript command. By default, the command does not allow anything to be run.
 
Each entry in this option is a [https://github.com/google/re2/wiki/Syntax Regular Expression]. Notes on usage here:
 
* An entry is considered a '''partial match''' unless it's surrounded by a <code>^</code> and <code>$</code>.
* On Windows, file path separators must be escaped: <code>C:\\Test\\Thing.exe</code>


=== service ===
=== service ===
 
<syntaxhighlight lang="toml">
[service]
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_run = [
    '^\*\*launch\.random:.+$'
]
</syntaxhighlight>
==== api_port ====
==== api_port ====


Line 277: Line 351:
|7497
|7497
|}
|}
<code>api_port</code> specifies which port the [[API]] of Core should be accessible from.
'''Don't change this unless you know what you're doing. It will currently break external tools that rely on it being the default value.'''


==== device_id ====
==== device_id ====
Line 287: Line 364:
|-
|-
|device_id
|device_id
|string
|string (UUID)
|
|''<generated at first start>''
|}
|}
<code>device_id</code> is a [[wikipedia:Universally_unique_identifier|UUID]] that is used to uniquely identify the instance of the Core service running on a host device.
It's currently reserved for future use when devices can communicate with each other and external services. '''It should not be changed once set.'''


==== allow_launch ====
==== allow_run ====


{| class="wikitable"
{| class="wikitable"
Line 299: Line 379:
!Default
!Default
|-
|-
|allow_launch
|allow_run
|string[]
|string[]
|[]
|[]
|}
|}
<code>allow_run</code> explicitly allows [[ZapScript]] to be run using the [[API#Run Endpoint|run REST endpoint]] of the [[Core API]]. By default, nothing is allowed.
Each entry in this option is a [https://github.com/google/re2/wiki/Syntax Regular Expression]. Notes on usage here:
* An entry is considered a '''partial match''' unless it's surrounded by a <code>^</code> and <code>$</code>.
* Characters <code>*</code>, <code>|</code> and <code>.</code> common in both ZapScript and Regular Expressions must be escaped like in the example file below.


== Example file ==
== Example file ==
An example config file with all fields filled:<syntaxhighlight lang="toml" line="1">
An example <code>config.toml</code> file with all fields filled, using the example sections shown above.<syntaxhighlight lang="toml" line="1">
config_schema = 1
config_schema = 1
debug_logging = true
debug_logging = true
Line 337: Line 423:
]
]
allow_file = [
allow_file = [
     '/media/fat/something.mgl'
     '^/media/fat/something.mgl$'
]
]


[zapscript]
[zapscript]
allow_shell = [
allow_execute = [
     'touch /tmp/tap_time',
     '^touch /tmp/tap_time$',
     '/media/fat/linux/mplayer something.mp4'
     '^/media/fat/linux/mplayer .+'
]
]


Line 349: Line 435:
api_port = 7497
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_launch = [
allow_run = [
     '*'
     '^\*\*launch\.random:.+$'
]
]


</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 00:30, 16 January 2025

The config file is the main configuration file of the Zaparoo Core software service.

Its location depends on the platform where the service is running. On MiSTer, it's located in the /media/fat/zaparoo folder (i.e. zaparoo folder in the root of the SD card).

The file is always called config.toml on every platform.

The config file is written in TOML. Be aware that although comments are supported in TOML, they will be lost if Core makes updates to this file (e.g. when adjusting settings using the Zaparoo App) and should be avoided for important information.

Any changes made to the config file while the Core service is running require the service to be restarted before changes will take effect.

Options

Options in the config file are grouped by sections which start with a header. For example, the audio section begins with [audio] and continues until the next header is encountered.

Root

The root section does not start with a section header and is the only section that behaves this way. It's reserved for certain options that affect all parts of Core or the config file itself. 

config_schema = 1
debug_logging = true

config_schema

Key Type Default
config_schema integer 1

This option should not be changed or removed.

config_schema is used internally by Core to track what version of itself last wrote to the file. This makes it possible to perform migrations between versions if the layout of the config file must be changed.

debug_logging

Key Type Default
debug_logging boolean false

debug_logging enables or disables logging debug messages to Core log files. It's useful for troubleshooting issues but can make log files noisy.

This option should be enabled when attempting to reproduce issues for reporting.

audio

[audio]
scan_feedback = true

scan_feedback

Key Type Default
scan_feedback boolean true

scan_feedback enables or disables playing a sound from the host device when a scan is successful or results in an error.

readers

[readers]
auto_detect = true

auto_detect

Key Type Default
auto_detect boolean true

auto_detect enables or disables automatically searching for and probing possible connected readers on the host device.

It may be required to disable this option if auto-detection is causing problems with unrelated connected devices.

readers.scan

readers.scan is a sub-section of readers and must be defined with the header: [readers.scan]

[readers.scan]
mode = 'hold'
exit_delay = 3.0
ignore_system = [ 'PC', 'MSX' ]
mode
Key Type Default
mode string tap

mode defines the behavior of scans. It has two options:

  • tap is the default mode and means when a token is used with a reader it can be removed again without affecting the playing media. If a token is tapped, removed and then tapped again it will relaunch the already playing media.
  • hold mode makes it so a token must be held to the reader for as long as any launched media will play. That is, after a token is removed from the reader, it will exit the media. This makes a token act more like real physical media. Core does not currently make any attempt to save before exiting media.
exit_delay
Key Type Default
exit_delay float 0.0

exit_delay adds a delay, in seconds, before media is exited after a token is removed from a reader. It's only active if hold mode is also active.

For example, if exit_delay was set to 2.3, it would mean when a token is removed from a reader, instead of immediately exiting the media, a timer is started for 2.3 seconds first. If the same token is placed back on the reader before the timer is complete, the timer will be cleared and the media won't exit.

This feature can be useful if you want to, using a single reader, scan other tokens such as adding credit without exiting the current game.

ignore_system
Key Type Default
ignore_system string[] []

ignore_system is a list of systems which will not exit playing media on token removal. It's only active in hold mode.

readers.connect

readers.connect manually defines a reader which is physically connected to the host device and is not auto-detected. It's a sub-section that can be defined multiple times, and must have this header: [[readers.connect]]

Pay attention to the double pairs of square brackets. Each defined readers.connect section must have its own header.

[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB0'

[[readers.connect]]
driver = 'file'
path = '/tmp/some_file'
driver
Key Type Default
driver string

driver specifies which reader driver should be used to attempt connection to the reader device. See reader drivers for a list of possible options.

path
Key Type Default
path string

path is an argument for the specified reader driver for how the device should be found. See reader drivers for what this argument should look like for the driver.

systems

systems.default

systems.default overrides the default behavior of the specified system. It's a sub-section that can be defined multiple times, and must have this header: [[systems.default]]

Pay attention to the double pairs of square brackets. Each defined systems.default section must have its own header.

[[systems.default]]
system = 'SNES'
launcher = 'SindenSNES'
before_exit = '**input.keyboard:{f12}||**delay:2000'
system
Key Type Default
system string

ID of the system this default override entry applies to.

launcher
Key Type Default
launcher string

ID of the launcher that should be used by default when media in this system is launched.

before_exit
Key Type Default
before_exit string

A snippet of ZapScript to be run before media exits if hold mode is enabled. Blocks before moving onto exit so commands like delay can be used.

launchers

[launchers]
index_root = [
    '/media/alt_mount/games'
]
allow_file = [
    '^/media/fat/something.mgl$'
]

index_root

Key Type Default
index_root string[] []

index_root is a list of paths on the host device that should also be searched when indexing media during a media database update.

For example, if index_root was set to [ '/media/fat/other_place' ], a database update will search all standard locations like normal but then also attempt to search /media/fat/other_place/SNES, /media/fat/other_place/Genesis, etc. for potential media.

allow_file

Key Type Default
allow_file string[] []

allow_file allows certain files to be launched if their assigned launcher requires it.

This is used on platforms like Windows to allow executable files to be launched with tokens, where this ability is useful but would be a security issue if allowed globally.

Each entry in this option is a Regular Expression. Notes on usage here:

  • An entry is considered a partial match unless it's surrounded by a ^ and $.
  • On Windows, file path separators must be escaped: C:\\Test\\Thing.exe
  • An entry can be made case-insensitive by putting (?i) at the beginning.

zapscript

[zapscript]
allow_execute = [
    '^touch /tmp/tap_time$',
    '^/media/fat/linux/mplayer .+'
]

allow_execute

Key Type Default
allow_execute string[] []

allow_execute allows specific executables and arguments to be run using the **execute ZapScript command. By default, the command does not allow anything to be run.

Each entry in this option is a Regular Expression. Notes on usage here:

  • An entry is considered a partial match unless it's surrounded by a ^ and $.
  • On Windows, file path separators must be escaped: C:\\Test\\Thing.exe

service

[service]
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_run = [
    '^\*\*launch\.random:.+$'
]

api_port

Key Type Default
api_port integer 7497

api_port specifies which port the API of Core should be accessible from.

Don't change this unless you know what you're doing. It will currently break external tools that rely on it being the default value.

device_id

Key Type Default
device_id string (UUID) <generated at first start>

device_id is a UUID that is used to uniquely identify the instance of the Core service running on a host device.

It's currently reserved for future use when devices can communicate with each other and external services. It should not be changed once set.

allow_run

Key Type Default
allow_run string[] []

allow_run explicitly allows ZapScript to be run using the run REST endpoint of the Core API. By default, nothing is allowed.

Each entry in this option is a Regular Expression. Notes on usage here:

  • An entry is considered a partial match unless it's surrounded by a ^ and $.
  • Characters *, | and . common in both ZapScript and Regular Expressions must be escaped like in the example file below.

Example file

An example config.toml file with all fields filled, using the example sections shown above.

config_schema = 1
debug_logging = true

[audio]
scan_feedback = true

[readers]
auto_detect = true

[readers.scan]
mode = 'hold'
exit_delay = 3.0
ignore_system = [ 'PC', 'MSX' ]

[[readers.connect]]
driver = 'pn532_uart'
path = '/dev/ttyUSB0'

[[readers.connect]]
driver = 'file'
path = '/tmp/some_file'

[[systems.default]]
system = 'SNES'
launcher = 'SindenSNES'

[launchers]
index_root = [
    '/media/alt_mount/games'
]
allow_file = [
    '^/media/fat/something.mgl$'
]

[zapscript]
allow_execute = [
    '^touch /tmp/tap_time$',
    '^/media/fat/linux/mplayer .+'
]

[service]
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_run = [
    '^\*\*launch\.random:.+$'
]
Retrieved from "https://wiki.zaparoo.org/index.php?title=Config_file&oldid=718"