Table of Contents

Use cartridges and run programs

include_toc

include_toc
true

Use cartridges and run programs

A bay number identifies a physical slot, from 01 through 12. It stays tied to the slot rather than the order in which Linux discovers USB disks.

Cartridge	Role
SYSTEM	Supplies the read-only operating system used at boot
PROGRAM	Supplies applications and their runtime dependencies
DATA	Stores your writable files at `/data`
ENVIRONMENT	Requests an installed desktop profile, such as WindowMaker

Inspect a bay

Insert the cartridge, then run:

fds bays
fds bay 01

USB discovery takes place asynchronously. fds bay shows its state, identity, mount location, running process count and software catalogue. fds --json bay 01 returns structured details, including command aliases. fds rescan refreshes the inventory. No application starts merely because a PROGRAM cartridge is inserted.

State	Meaning and next action
EMPTY	No cartridge is detected
MOUNTED READ ONLY	Contents are available; PROGRAM commands can run
MOUNTED READ WRITE	DATA is active at `/data`
SAFE	Storage is released; remove the cartridge
PROTECTED	This cartridge supplies the running SYSTEM; shut down before removal
UNCONFIGURED	The physical slot needs a bay mapping
ERROR / AMBIGUOUS	Read the detail; correct the media or mapping before use

Run a software command

For the included hello/report cartridge:

hello 'Hello from my cartridge'
report
fds run 01 -- demo.hello:hello 'Hello from my cartridge'

Direct commands run in the foreground with your terminal, input/output streams, arguments, working directory and exit code. Pipes and redirection work normally. fds run starts a managed background program and prints its PID; its output is written to /run/log/cartridged/current. Both forms run as the ordinary FDS user and are tracked for cartridge removal.

New cartridges run directly from read-only payload partitions. They require no program extraction or compilation on FDS. The stable /run/fds/bin directory is already in the console and terminal PATH, so existing shells see inserted commands.

If cartridges export the same command name, the lowest numbered bay wins. Within a bay, the first software selector in lexical order wins. System commands appear earlier in PATH and retain their usual meanings. To select a specific cartridge command, use its qualified alias:

b01:demo.hello:hello 'Explicit bay and software'
fds run 01 -- demo.hello:hello

Legacy PROGRAM media uses b01:COMMAND for a qualified direct alias. Commands are removed on eject/unplug; a shared name falls back to the next available bay. After the final cartridge is removed, a shell may remember the old executable path; hash -r clears Bash's command cache.

Eject safely

cd "$HOME"
fds eject 01
fds bay 01

Eject stops managed programs, flushes writable storage and releases its mounts. Remove the cartridge after SAFE is reported. If eject fails, close files, shells or extra mounts using that cartridge and retry. Never treat a timeout as permission to pull writable media. Use fds poweroff to stop the whole computer; swap the running SYSTEM only after shutdown.

The control panel provides the same safe-eject action. For writable storage behavior, see DATA and files.

Configure physical bay numbering

Run fds topology with one identifiable USB device inserted in each slot in turn. Record the controller/hub topology for both USB 2 and USB 3 connections, then map those stable identities in the machine's bays.toml. Do not map /dev/sda names or enumeration order. The emulator supplies its own known map.

Use machine settings to validate, export and install the configuration. The detailed wiring/calibration procedure is in the hardware engineering reference.

FDS/OS

Home · Overview · All pages

Start here

Use the computer

Install and maintain

Build and contribute

Home · All pages · Edit the wiki · Source repository

Maintained directly in the fds-os.wiki repository. Historical acceptance applies only to the source and artifacts identified in each record.