Back Up KNULLI Saves and Personal Data Before an Update or Card Change

Safety and scope limits: This guide creates selected archive copies and checks that those selected files appear to have copied correctly. It does not create a bit-perfect card image, capture every engine’s progress, preserve all Linux metadata, guarantee save-state compatibility, or make an old KNULLI system tree safe to restore over a new release.

Short Answer

Before updating, reimaging, or replacing a card, stop games and other writers, then copy selected personal-data folders from the active logical /userdata to two independently located destinations. Keep ordinary saves, screenshots, lawful game files, and user-supplied BIOS files separate from compatibility-sensitive items such as states, themes, scraped metadata, ports, overrides, and configuration.

For every batch, record the logical source path, tier, destination, expected names, file/subfolder counts, total bytes, errors, and whether both copies exist. Read back representative non-sensitive files. You may optionally use Windows PowerShell Get-FileHash for selected ordinary files, but matching hashes prove only those exact files.

Leave the original source card untouched. On the new installation, let KNULLI create a fresh layout, preserve its new /userdata/system, and restore Tier 1 data in small recorded batches. Treat old configurations and save states as compatibility-sensitive archives, not portable restore sets.

For broader routing, use the KNULLI troubleshooting and setup hub.

Scope and Definitions

This guide applies to an RG CubeXX/H700 KNULLI installation whose active logical /userdata is reachable. The physical card backing that path can vary; selecting or repairing that backing device is outside this article.

Backup archive

An archival copy means selected files were copied to another destination. That fact alone does not prove completeness, metadata preservation, or restorability.

Copy verification

A verified backup in this article means that, for the selected scope, recorded counts, total bytes, expected names, representative read-back, and any optional selected-file hashes agree without unresolved copy errors. This is bounded filesystem evidence, not a system-image claim.

Restore validation

Restore validation happens only after data is selectively copied into a fresh layout and the relevant application recognizes it. One ordinary save loading validates one file in one compatible context—not the archive as a whole.

Evidence labels

FACT: directly supported by authoritative documentation or tagged source.
SOURCE-CONFIRMED: supported by authoritative implementation/documentation but still limited to its stated scope.
COMMUNITY REPORT: reported behavior retained only as such.
UNCONFIRMED: evidence is insufficient for a stronger claim.

Release and Path Matrix

Release	Device scope	Logical personal-data root	Primary frontend config	Restore rule
Firefly `20241204`	RG CubeXX / tagged H700 defaults	`/userdata`	`/userdata/system/batocera.conf`	Archive for reference; do not paste its `system` tree into a later major release.
Gladiator II `20250813`	RG CubeXX lineage / tagged H700 defaults	`/userdata`	`/userdata/system/batocera.conf`	Same-release selective restore may be attempted; do not wholesale-restore across a major release.
Scarab `20260511`	Revisioned RG XX H700 support	`/userdata`	`/userdata/system/knulli.conf`	Preserve fresh Scarab defaults; do not replace them with old `batocera.conf` or an old `system` tree.

The logical /userdata contract remains the organizing root. This guide does not identify, select, format, or migrate the physical backing card.

Backup Tier Table

Tier	Supported paths/data	Backup posture	Restore posture
Tier 1 — essential personal data	`/userdata/saves`, `/userdata/screenshots`, lawful `/userdata/roms/<system>`, user-supplied `/userdata/bios`, ordinary non-executable personal files	Copy as separate named batches to both destinations.	Restore in small recorded batches to matching fresh folders; preserve newer destination files first.
Tier 2 — optional, large, reproducible, or compatibility-sensitive	save states; each system’s `gamelist.xml` plus referenced media; `/userdata/themes` with compatible `/userdata/theme-customizations`; ports/PortMaster and engine-specific data; large lawful ROM collections	Archive complete named units with version/context notes.	Restore intentionally, one category at a time, only into a same or known-compatible context.
Tier 3 — archive/reference only across major releases	`/userdata/system`; `batocera.conf`; `knulli.conf`; generated RetroArch/emulator config; old overrides, remaps, Core Options, scripts, overlays, services, hidden application homes	Store under `ARCHIVE-DO-NOT-WHOLESALE-RESTORE` with source release recorded.	Do not restore wholesale. Let the destination create defaults; re-enter settings in UI or cherry-pick one precisely understood documented item.
Exclude/generated/transient	caches, temporary downloads, logs, locks, generated runtime files	Do not present as essential backup content without authoritative evidence.	Do not restore by default.

Important `/userdata/saves` limit

/userdata/saves is the main KNULLI location for many ordinary saves and states, but it does not cover every engine. Ordinary in-game saves and save states also have different compatibility characteristics.

Pico-8 and Fake08 exception

Official Pico-8 stores its cartridge data under /userdata/system/.lexaloffle/pico-8/cdata. Fake08 uses /userdata/saves/pico8/cdata. Record which engine produced the data. For official Pico-8, restore only the exact documented cdata subtree after the matching engine is installed or selected; never restore the enclosing old system tree.

Scraped metadata and media

Keep each system’s gamelist.xml with its referenced scraped-media folders. An isolated XML file or media folder is not the documented pair. Even a complete pair may be incompatible after a frontend or theme change.

Ports and engine data

Ports and standalone engines can depend on executable bits, permissions, symlinks, dependencies, and version-specific layouts. A Windows Explorer, SMB, or SFTP copy is not proven to preserve every such property. Keep these as compatibility-sensitive archives.

Prepare and Record Context

Record:

device and exact KNULLI release;
active logical /userdata shown by the working system;
relevant emulator/core for one possible ordinary-save check;
one lawful game and known ordinary in-game save;
source path, source release, and planned destinations;
whether official Pico-8, Fake08, ports, themes, states, or scraped media need special treatment.

If the exposed /userdata is not the intended source, stop and use the second-SD storage-selection guide. Do not change storage selection here.

Stop Games and Preserve the Source

Exit content normally and return to EmulationStation. Stop scrapers, downloaders, cloud sync, MTP, and any other process that may write to the selected data. Do not copy a changing source.

Keep the original card unchanged and out of reuse. This guide does not format, repartition, repair, clone, mirror, deduplicate, or initialize it.

Choose an Already-Working Transport

If network access already works, follow Transfer Games to KNULLI from Windows: SMB and SFTP Setup for the connection and client mechanics. This article begins after transport works.

SMB/SFTP is a file-transfer route, not a metadata-preserving filesystem image. Do not copy outside the documented writable /userdata scope.

Direct-card limit on Windows

Direct Windows access is straightforward only when the data partition is exFAT. Windows does not natively read ext4. Do not install an unsupported ext4 driver just for this guide, accept a format prompt, mount system partitions, repair or rewrite a filesystem, or rewrite permissions.

For direct removable exFAT access, shut down KNULLI normally before removal and safely eject the card from Windows afterward. If Windows cannot read the card, prefer the already-working network route. This is not a failing-card recovery guide.

Selective Backup Procedure

1. Create two independent destinations

Create a dated root labeled with device and release but no private account or network details. Make a second copy on a different physical destination or independent service. Two folders on the same failing disk are not independent protection.

2. Check capacity without inventing a margin

Compare selected source folders’ reported total size with destination free space. Leave practical working room, but do not use an invented minimum percentage.

3. Copy Tier 1 in separate batches

Copy saves, screenshots, lawful game folders by system, user-supplied BIOS files, and other ordinary personal files separately. Separate batches make errors attributable and rollback bounded.

Do not publish or redistribute ROMs or BIOS files, and do not expose their names, hashes, regions, or inventory in screenshots.

4. Archive Tier 2 as complete named units

Keep a system’s gamelist.xml with its referenced media. Pair themes with compatible customizations. Label states with content, emulator/core, and version context where known. Record ports and engine data separately.

5. Archive Tier 3 with a warning label

Store /userdata/system only under a source-release folder named ARCHIVE-DO-NOT-WHOLESALE-RESTORE. This is reference material, not the default restore source.

Build a Batch Manifest

For each batch and each destination, record:

logical source path;
tier and source release;
destination label;
expected unique names or safe placeholders;
file count and subfolder count;
total bytes;
representative read-back performed;
skipped files, warnings, and errors;
whether both independent copies exist.

A clean progress dialog is not a manifest.

Optional selected-file hashes

Microsoft documents Get-FileHash for a selected file. If stronger per-file evidence is useful, compare like-for-like output for a small number of non-sensitive source and destination files. Do not expose ROM/BIOS hashes. Matching hashes prove byte identity only for those exact files; they do not prove that every expected file exists or that an application can restore it.

Verify the Backup Copy

For every selected top-level batch, compare both destinations with the source:

file count;
subfolder count;
total bytes;
expected unique names; and
recorded skips or errors.

Read back representative non-sensitive destination files, such as one screenshot or small text/XML file. Do not edit or open binary saves merely to test them.

If counts or bytes remain lower after a targeted retry, a source reports read errors, a device disconnects, or the source size changes unexpectedly, stop before updating or reusing the source card.

Matching counts, bytes, names, and representative read-back are bounded copy evidence. They do not prove every byte, Linux metadata, save-state compatibility, theme compatibility, application recognition, or future restore success.

Fresh Destination Prerequisite

Complete How to Install KNULLI on RG CubeXX where applicable, and let KNULLI create the new release’s fresh layout. Verify the intended active logical /userdata; if it is wrong, stop for article #9.

Preserve the new release’s generated defaults. Close games and all other writers before restoring data.

Selective Restore Order

Restore small, named batches in this order:

screenshots;
ordinary in-game saves;
user-supplied BIOS files;
lawful game folders as needed;
the exact applicable Pico-8/Fake08 cdata subtree after selecting the matching engine;
paired scraped metadata/media only as a complete per-system unit; and
Tier 2 categories one at a time only after Tier 1 is stable.

After each batch, compare the recorded count and total bytes. Preserve any newer or unknown destination file before replacement. Do not overwrite the fresh /userdata/system, paste an old batocera.conf over Scarab, or replace knulli.conf with an old configuration.

Themes, remaps, overrides, Core Options, ports, and states are deliberate compatibility tests—not routine restore material.

Optional Ordinary-Save Validation

Using the same lawful content and a compatible emulator/core context, open one game with a known ordinary in-game save and check whether expected progress is visible. Do not overwrite the save while testing.

Success validates that one ordinary save in that one context. Failure can reflect content, region, core, engine, path, or version mismatch; keep all backups untouched and do not broaden the restore.

Save-State Warning

Libretro distinguishes ordinary save files from state snapshots. States can depend on exact content, emulator/core, core version, and platform context. Matching names do not guarantee portability. Keep states as optional archives; state testing is non-gating and never proof that all states are portable.

Update, Card-Change, and Reimage Contexts

Major update

Retain Tier 3 only for reference. Let the new release generate /userdata/system, then restore ordinary personal data selectively.

Same-release reimage

Compatibility may be closer, but still restore in logged batches and keep fresh defaults until validation succeeds.

Card replacement

Do not reuse, format, or erase the original card until the destination has passed bounded checks and important categories have been reviewed.

Firefly or Gladiator II to Scarab

Treat the batocera.conf to knulli.conf change as a hard cross-release boundary. Do not paste an old system tree over Scarab. Scarab migration logic is not a substitute for two independent verified archives.

Rollback and Recovery

If a restore batch causes a problem:

stop further copying;
consult the manifest;
preserve the source, both archives, and fresh defaults;
quarantine or remove only the exact newly copied batch whose membership is known; and
return to the last verified state.

Never bulk-delete destination folders, rewrite permissions, repair filesystems, or modify the only archive in place. If the source reports errors, stop: this article is not data recovery.

Version Differences

Firefly `20241204`

The tagged H700 default uses /userdata/system/batocera.conf. Archive it for reference rather than treating it as a future-release replacement.

Gladiator II `20250813`

The tagged H700 default also uses /userdata/system/batocera.conf. Same-release selective restoration does not authorize a whole-tree restore.

Scarab `20260511`

The tagged configuration uses /userdata/system/knulli.conf. Preserve Scarab’s fresh configuration and restore selected personal data around it.

What this guide does not cover

This guide owns selective backup, verification, and cautious restore of saves and personal userdata. It assumes the chosen transfer route already works and does not repair installation, networking, SMB/SFTP access, storage selection, BIOS, game discovery, emulator settings, Quick Menu access, or save-state policy.

Screenshot, Privacy, and Evidence Limits

Screenshots are optional illustrations, not owner-test evidence. Redact hostnames, IP/MAC addresses, SSIDs, usernames, passwords, personal paths, account data, ROM/BIOS names and hashes, save names, screenshots, thumbnails, and identifying timestamps.

A folder listing proves visible presence, not completeness. Matching Properties values are not cryptographic identity. A selected-file hash applies only to that file. A loaded save validates one context only.

FAQ

Is copying `/userdata/saves` enough?

No universal claim is safe. It is the main location for many saves/states, but documented engines can use other paths. Record engine exceptions.

Should I copy all of `/userdata`?

You may keep a broad archive for reference, but this guide’s supported restore procedure is selective. A Windows/SMB/SFTP tree copy is not a bit-perfect or metadata-preserving system image.

Can I restore the old `/userdata/system` after an update?

Do not restore it wholesale across a major release. Preserve the fresh destination defaults and re-enter settings through the UI or cherry-pick one documented item only when its compatibility is understood.

Are save states portable?

Not guaranteed. Treat them as compatibility-sensitive archives tied to content, emulator/core, version, and platform context.

Does matching file count and total bytes prove a complete backup?

No. It is useful bounded evidence for the selected scope, not proof of every byte, metadata property, or application restore.

Can Windows read the card directly?

Direct access is simple only for exFAT. Windows does not natively read ext4. Do not install an unsupported driver or accept a format prompt for this workflow.

When can I reuse the original card?

Only after the new setup is stable and important categories have been checked. This article claims no fixed retention period; keeping the source and both archives longer reduces rollback risk.