📖 本文由 Batocera 官方 Wiki 翻译整理，内容可能随版本更新而变化。

---

Batocera-settings 使用指南

简介

Batocera-settings 是一个命令行工具（Command-line tool），专门用于读取或修改配置文件内容。它对编写脚本非常有用——例如，如果你把硬盘插在不同的机器上，需要根据硬件自动调整配置，这个工具就能大显身手。

生活化类比：如果说手动编辑配置文件是直接打开记事本“动手术”，那么 Batocera-settings 就像是一个远程遥控器，让你不需要打开文件，就能精准地发送指令去修改其中的某项开关。

【注意】：这个命令目前已经有些“落伍”了。现在绝大多数（甚至所有）设置都可以在 Batocera 的 EmulationStation 界面（也就是你选游戏的那个主图形界面）直接调整，或者通过手动编辑文本文件完成。部分旧指令可能已经失效。在旧版本的 Batocera 中，你可以直接输入 Batocera-settings 并回车来查看它还能支持哪些功能。

---

手动编辑 Batocera.conf 教程

系统的核心设置大多保存在 /userdata/system/Batocera.conf 这个文件中，它遵循一套标准的语法规范。当你准备手动修改这个文件时，请遵循以下步骤和规则：

• 第一步：添加注释
  如果你想在文件中写点备注给自己看，请使用 ## 这是一段文本注释 的格式。
• 第二步：禁用特定数值
  如果你想暂时关掉某个设置项而不是彻底删除它，可以在变量名前加一个 # 号，例如：#enable.godmode=hallelujah。
• 第三步：做好备忘录
  【提示】：在添加新功能或自定义内容时，建议在注释里详细描述它的用途，方便日后维护。
• 第四步：归类整理
  虽然系统没有硬性规定，但为了文件整洁，建议将新增内容添加至对应的功能区块中。

以下是配置文件的一个简短示例：

# ------------ B - 网络设置（Network） ------------ #

## 设置系统主机名（Hostname）
system.hostname=Batocera
## 激活 Wi-Fi 开关 (0 代表关闭，1 代表开启)
wifi.enabled=0
## Wi-Fi 名称（SSID）
#wifi.ssid=输入你的网络名称
## Wi-Fi 密码
## 重启系统后，这里的明文密码会被自动替换为加密值 "enc:xxxxx"
## 如果想更改密码，可以直接修改这个加密值。再次重启后，新密码会重新被加密
## 【提示】：如果密码包含特殊字符（如 # ; $），请在前面加上反斜杠进行转义。例如：$ 需写成 $
#wifi.key=输入你的新密码

---

推荐使用的命令与表达式

在操作时，我们主要使用 Batocera-setting-get（读取设置）和 Batocera-setting-set（写入设置）这两个指令。

【注意】：在输入以下语法时，请将方括号 [] 及其内部的内容替换为你实际想要修改的设置项，不要保留方括号本身。

1. 如何读取设置值（Reading values）

你可以通过以下指令查看当前的配置：

Batocera-settings-get -f [配置文件路径] [设置项关键词]
Batocera-settings-get [设置项关键词]

• 第一步：执行读取命令
  系统会从你指定的配置文件中找到对应的关键词（KEY）并显示其当前数值。
• 第二步：默认路径说明
  如果你没有使用 -f 参数指定特定的文件，系统会默认在 /userdata/system/Batocera.conf 中进行搜索。

2. 如何修改设置值（Setting values）

如果你需要更改某项配置，请使用以下语法：

Batocera-settings-set -f [配置文件路径] [设置项关键词] [新数值]
Batocera-settings-set [设置项关键词] [新数值]

生活化类比：这就像是在图书馆找书。get 指令是问管理员：“《射击游戏指南》在哪个书架？”而 set 指令则是直接下令：“把《射击游戏指南》搬到 3 号书架去。”

执行该指令后，系统会在配置文件中搜索指定的关键词（Key），并将其旧值替换为你设定的新值。

生活化类比：这就像是在手机通讯录里找人。如果“张三”已经存在，系统会把他的旧号码改成新号码；如果通讯录里根本没有“张三”，系统会自动新建一个联系人。

在 Batocera v36 及更高版本中，如果你想读取当前硬件板卡的默认设置，可以使用以下专用指令：

Batocera-settings-get-master [key]

这会直接调取系统内置的板卡配置文件（路径为 /usr/share/Batocera/sysconfigs/Batocera.conf.${BOARD_MODEL}）。

---

错误代码处理（Error code handling）

当你通过脚本调用这些指令时，系统会返回一个退出状态码（Exit code）。这就像是机器给你的“回执单”，通过它你可以快速判断操作是否成功，或是在哪里出了岔子。

【提示】：如果需要更详细的调试信息，可以使用 status 命令来查看更具体的输出内容。

文件与键值错误对照表

错误代码	代码含义	排除故障
EC 0	无错误，已找到对应数值	恭喜！操作成功。
EC 1	常规错误（如命令行输入错误）	请检查指令中的参数是否拼写正确。

---

在脚本中使用（Handling in scripts）

为了让大家更直观地理解如何将 Batocera-settings 集成到自动化脚本中，这里提供了一些简单的 Shell 脚本（Shell script） 示例：

Bash 环境：获取配置数值

• 第一步：编写获取指令
  在脚本中调用 get 命令来提取你需要的参数。
• 第二步：处理返回数据
  将获取到的值存入变量，以便后续的逻辑判断。

本节将通过几个具体的脚本案例，教你如何像专业开发者一样使用这些工具。

【提示】：脚本操作涉及系统底层配置，请务必谨慎操作，风险自担！

---

1. Bash 脚本：读取配置数值

如果你想在脚本中引用某个设置项（例如检查当前的电源开关设备），可以参考以下逻辑：

• 第一步：调用读取指令
  使用 Batocera-settings-get 获取指定关键词的数值。
• 第二步：逻辑判断
  根据返回的成功或失败状态码，决定下一步操作。

#!/bin/bash
# 这是一个演示如何从 /userdata/system/Batocera.conf 中读取数值的示例文件

# 获取电源开关设备设置
value="$(Batocera-settings-get power.switch.device)"
ret=$?

# 判断是否获取成功（状态码为 0 表示成功）
if [ $ret -eq 0 ]; then
    echo "检测到电源开关设备: '$value'"
else
    echo "未检测到电源开关设置！"
fi

---

2. Bash 脚本：在引导配置中激活 UART 接口

通用异步收发传输器（UART） 常用于串行通信。如果需要在 /boot/config.txt 文件中激活它，步骤如下：

• 第一步：解除只读锁定
  系统分区通常是只读的。我们需要先检查文件权限，并使用“瑞士军刀”工具（Batocera-es-swissknife）重新挂载（Remount）分区为可写模式。
• 第二步：修改配置文件
  指定文件路径并修改 enable_uart 的值为 1。

生活化类比：这就像是给一个带锁的日记本写新内容。你必须先掏出钥匙（重新挂载）把锁打开，才能拿起笔（设置指令）在里面写字。

#!/bin/bash
# 演示如何利用脚本在 /boot/config.txt 中激活 UART

# 检查文件状态，并将其设为可写
[ ! -w /boot/config.txt ] && Batocera-es-swissknife --remount

# 尝试将 enable_uart 设置为 1
Batocera-settings-set -f /boot/config.txt enable_uart 1
ret=$?

if [ $ret -eq 0 ]; then
    echo "UART 已激活，已取消 enable_uart 的注释"
else
    echo "未找到 enable_uart 关键词"
    echo "这可能不是树莓派（Raspberry Pi）系统？"
fi

---

3. Bash 脚本：创建新的配置项

如果你想在配置文件里插入一条之前不存在的全新规则，可以使用以下脚本模板：

#!/bin/bash
# 这是一个演示如何利用 Batocera-settings-set 创建新键值的示例文件

• 第一步：确认目标文件
  确定你要修改的配置文件路径。

• 第二步：执行写入
  直接运行 set 指令。如果系统发现这个配置项不存在，它会自动在文件末尾为你“开辟新行”。

• 第一步：执行写入操作
  使用 Batocera-settings-set 命令，指定你想添加的键（Key）和值（Value）。

• 第二步：确认执行结果
  通过判断返回的状态码，确认新配置是否已成功注入系统文件。

#!/bin/bash
# 演示如何在 /userdata/system/Batocera.conf 中设置一个全新的配置项

# 尝试设置 PS5 核心的模拟器参数
value=$(Batocera-settings-set core.PS5.emulator SONY5EVER)
ret=$?

if [ $ret -eq 0 ]; then
    echo "PS5 核心已开启！"
else
    echo "发生了其他错误！"
fi

---

4. Python 脚本：获取配置键值

如果你更习惯使用 Python 编程语言，也可以通过调用子进程（Subprocess）的方式来读取系统设置。

生活化类比：这就像是 Python 脚本派出了一个“跑腿小弟”（subprocess），让他去系统后台询问某个设置的值，然后再把答案带回来给脚本处理。

• 第一步：导入必要模块
  引入 Python 的 subprocess 库，这是脚本与系统命令沟通的桥梁。
• 第二步：发送查询指令
  构建查询命令并运行。如果“跑腿小弟”带回的返回码（rc）为 0，说明查询成功。
• 第三步：解码并显示结果
  将系统返回的二进制数据解码成普通文字（UTF-8 编码），并打印在屏幕上。

#!/usr/bin/python
# 这是一个演示如何使用 Python 调用 Batocera-settings-get
# 从 /userdata/system/Batocera.conf 中读取数值的示例文件

import subprocess

# 定义查询系统电源开关设置的命令
command=(["Batocera-settings-get", "system.power.switch"])

# 运行命令，并将标准输出暂时重定向至空设备
rc = subprocess.call(command, stdout=subprocess.DEVNULL)

if rc == 0:
    # 如果返回码为 0，则正式提取数值并解码
    value = subprocess.check_output(command).decode("utf-8")
    print("检测到电源开关设置: ", value)
else:
    print("未检测到电源开关设置！")

---

原文: batocera-settings命令行工具 • 翻译: DIY8 Bot