Skip to content

System Configuration (/etc/system_conf.toml, /etc/wifi.toml)

Two files in /etc decide how the system starts and behaves. Both are TOML, both live on the device's flash, and both can be edited with the on-device editor.

File Holds
/etc/system_conf.toml Screen, input, theme, autostart, shortcuts, remote desktop
/etc/wifi.toml Your network's name and password

Flashing replaces them

Writing firmware rewrites the whole flash image, /etc included. Copy anything you have customised off the device first — see Console.

Editing

From the Config dialog. The system menu → Config covers the settings people actually change (below), and writes them back line by line, so your comments and everything else in the file survive. On hardware it also offers Save & Reboot, because several of these only take effect at startup.

From the editor. For anything the dialog does not offer, open the file in the Editor, change it, save, and reboot from Reset.

/etc/system_conf.toml

Display

Key Type Meaning
system_name string Name shown at boot and in About
display_width / display_height int Framebuffer size. 426 x 240 on Modern, 320 x 240 on Retro
display_margin_x / display_margin_y int Pixels to keep clear at the edges. Retro needs a margin because a CRT hides the border under overscan; Modern shows the whole framebuffer, so both are 0
default_user_app_width / default_user_app_height int Window size an app gets when its .app.toml does not say
display_mode string Which display driver to use (below)

display_mode is one of ntsc_ipc (Retro, composite video via the second chip), tab5_dsi (Modern, the built-in panel), sdl2 (the Linux simulator), spi_direct, atom_display, headless.

A typo here is silent

An unrecognised display_mode falls back to ntsc_ipc without complaining. If a Modern board reports ntsc_ipc in its boot log, the value is misspelt.

Input

Key Type Meaning
keyboard_layout "jp" / "us" Which keyboard you have. Get this wrong and the symbols land in the wrong places
mouse_scale_x / mouse_scale_y float Pointer speed. 0.5 halves it, 2.0 doubles it
wheel_lines int How many text rows one notch of the mouse wheel moves. It is the machine's setting, not each app's opinion

System

Key Type Default Meaning
language "en" / "ja" "en" UI language. Apps that provide app_screen_name_<lang> follow it
timezone string POSIX timezone, e.g. JST-9, UTC, EST5
debug_mode bool true Extra logging
max_apps int (the build's ceiling) How many app slots this machine hands out. A value above what the firmware was built for is clamped, not refused
ble_auto_start bool true Start BLE at boot. It means different things on the two machines -- see below
wifi_auto_start bool false Start Wi-Fi at boot
app_spawn_margin_kb int 30 Internal RAM, in KB, a starting app has to leave for the rest of the machine. A start that would eat into it is refused. Boards only
boot_splash bool true The logo and the jingle at power-on. false skips both and saves about 2.7 seconds
startup_app string "" One app to open as soon as the desktop is up, by path (/app/game/blockgame.app.rb). Empty means the ordinary desktop
wallpaper string "" Desktop picture. Empty means whatever the theme says, "none" leaves a plain colour, and a path wins over both. Any .png in /home/backgrounds shows up in Config's list

On Retro these two conflict

The ESP32-S3 has one radio. If ble_auto_start is true, Wi-Fi will not start no matter what wifi_auto_start says. Modern's ESP32-C6 runs both. See Connecting to Wi-Fi.

ble_auto_start = false does something different on each machine

On Retro it means BLE never starts, and the desktop menu can start it later. On Modern the radio is on the C6 rather than on this chip, so false only means that nothing is advertised and nothing can connect: the link to the C6 is still raised, because Wi-Fi needs it. Set wifi_auto_start to false as well to leave the C6 down entirely. Either way the change takes effect at the next boot.

[theme]

Nine colours, each an RGB332 byte:

[theme]
desktop_bg = 0xF6
menu_bg    = 0xC5
window_bg  = 0xFF
text       = 0x00
text_light = 0xFF
highlight  = 0xEE
border     = 0x60
button     = 0x60
dir_color  = 0x03

The Config dialog offers three presets — light, dark, cyberpunk — and expands the one you pick into these nine entries on save. Edit them by hand for anything else.

Apps can read the same values as FmrbConst::THEME_*, so a well-behaved app follows the system theme. See Constants & System Info.

[[shortcuts]]

Single letters that start an app from the desktop:

[[shortcuts]]
key = "l"
app = "launcher"

[[shortcuts]]
key = "e"
app = "default/editor"

[[shortcuts]]
key = "n"
app = "app/tool/nsf_player.app.rb"

app is either a built-in name (launcher, file_manager, log_viewer), a system app path (default/shell, default/editor), or a path to a file. See The Desktop.

[[sync_files]]

Files the core copies to the graphics side at boot, for assets that have to live over there:

[[sync_files]]
src  = "/usr/share/sounds/nsf/test.nsf"
dest = "/flash/data/test.nsf"

The copy is skipped when the destination already matches, so this costs nothing on a normal boot.

[remote_desktop]

Modern only. Serving the device's screen over Wi-Fi:

[remote_desktop]
enable = true
mode = "h264"              # "h264" or "mjpeg"
fps_cap = 15
jpeg_quality = 80
h264_bitrate_kbps = 1000
h264_gop = 30

Each key is explained in Remote Desktop.

/etc/wifi.toml

[wifi]
enable = true
ssid = "your-ssid"
password = "your-password"
hostname = "fmruby"
Key Meaning
enable false keeps the credentials but does not connect
ssid / password Your network. 2.4 GHz only
hostname mDNS name. Leave it out and the board names itself fmruby-XXXXXX.local, after the last three bytes of its Wi-Fi MAC, so two boards can be told apart. Every board also answers to fmruby.local

Released firmware ships without this file — a public build cannot carry your password — so you create it once on the device. Full instructions are in Connecting to Wi-Fi.

It is not in the repository either

flash/etc/wifi.toml is in .gitignore, so credentials never reach a commit. If you build the firmware yourself, put yours in config/wifi_p4.toml and the build copies it into the image.