3.8 KiB
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.