Config file: Difference between revisions
No edit summary |
No edit summary |
||
| Line 9: | Line 9: | ||
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 97: | 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 | <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 117: | Line 73: | ||
=== readers === | === readers === | ||
<syntaxhighlight lang="toml"> | |||
[readers] | |||
auto_detect = true | |||
</syntaxhighlight> | |||
==== auto_detect ==== | ==== auto_detect ==== | ||
| Line 131: | Line 90: | ||
|} | |} | ||
<code>auto_detect</code> enables or disables | <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 152: | 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 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.''' | |||
===== exit_delay ===== | ===== exit_delay ===== | ||
| Line 169: | 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. | |||
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 186: | Line 152: | ||
|} | |} | ||
<code>ignore_system</code> is a list of systems which will not | <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 207: | 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 222: | 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 | <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 228: | 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>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.<syntaxhighlight lang="toml"> | |||
[[systems.default]] | |||
system = 'SNES' | |||
launcher = 'SindenSNES' | |||
</syntaxhighlight> | |||
===== system ===== | ===== system ===== | ||
| Line 245: | Line 221: | ||
|} | |} | ||
ID of the system this default override entry applies to. | ID of the [[system]] this default override entry applies to. | ||
===== launcher ===== | ===== launcher ===== | ||
| Line 260: | Line 236: | ||
|} | |} | ||
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. | ||
=== launchers === | === launchers === | ||
<syntaxhighlight lang="toml"> | |||
[launchers] | |||
index_root = [ | |||
'/media/alt_mount/games' | |||
] | |||
allow_file = [ | |||
'/media/fat/something.mgl' | |||
] | |||
</syntaxhighlight> | |||
==== index_root ==== | ==== index_root ==== | ||
| Line 277: | Line 261: | ||
|} | |} | ||
<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 | <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 | 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 296: | Line 280: | ||
<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> explicitly allows a file to be launched from a token even if it hasn't been indexed as part of a system. | ||
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 | 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. | ||
Paths are case-insensitive one the Windows platform. | |||
=== zapscript === | === zapscript === | ||
<syntaxhighlight lang="toml"> | |||
[zapscript] | |||
allow_shell = [ | |||
'touch /tmp/tap_time', | |||
'/media/fat/linux/mplayer something.mp4' | |||
] | |||
</syntaxhighlight> | |||
==== allow_shell ==== | ==== allow_shell ==== | ||
| Line 313: | Line 305: | ||
|} | |} | ||
allow_shell | <code>allow_shell</code> explicitly allows specific commands to be run on the host system shell from a token. | ||
=== service === | === service === | ||
<syntaxhighlight lang="toml"> | |||
[service] | |||
api_port = 7497 | |||
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518' | |||
allow_launch = [ | |||
'*' | |||
] | |||
</syntaxhighlight> | |||
==== api_port ==== | ==== api_port ==== | ||
| Line 329: | Line 328: | ||
|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, as it will currently break many external tools that rely on it being the default value.''' | |||
==== device_id ==== | ==== device_id ==== | ||
| Line 339: | Line 341: | ||
|- | |- | ||
|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_launch ==== | ||
| Line 355: | Line 358: | ||
|[] | |[] | ||
|} | |} | ||
<code>allow_launch</code> explicitly allows specified [[ZapScript]] to be run using the [[API#Launch Endpoint|launch endpoint]] of the [[API]]. | |||
== Example file == | |||
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 | |||
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_shell = [ | |||
'touch /tmp/tap_time', | |||
'/media/fat/linux/mplayer something.mp4' | |||
] | |||
[service] | |||
api_port = 7497 | |||
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518' | |||
allow_launch = [ | |||
'*' | |||
] | |||
</syntaxhighlight> | |||
Revision as of 00:43, 23 December 2024
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:
tapis 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.holdmode 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'
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.
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 explicitly allows a file to be launched from a token even if it hasn't been indexed as part of a system.
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.
Paths are case-insensitive one the Windows platform.
zapscript
[zapscript]
allow_shell = [
'touch /tmp/tap_time',
'/media/fat/linux/mplayer something.mp4'
]
allow_shell
| Key | Type | Default |
|---|---|---|
| allow_shell | string[] | [] |
allow_shell explicitly allows specific commands to be run on the host system shell from a token.
service
[service]
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_launch = [
'*'
]
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, as it will currently break many 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_launch
| Key | Type | Default |
|---|---|---|
| allow_launch | string[] | [] |
allow_launch explicitly allows specified ZapScript to be run using the launch endpoint of the API.
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_shell = [
'touch /tmp/tap_time',
'/media/fat/linux/mplayer something.mp4'
]
[service]
api_port = 7497
device_id = '4d01c19f-09ba-4871-a58a-82fb49f5b518'
allow_launch = [
'*'
]
