Skip to content

Device data

Some features need data from your phone’s original system. FPLinux does not download this data. UMS9117 phones use a read-only NAND backup; Qin reads selected sound files from eMMC. RAM launches prepare required data automatically on first use, both from a checkout and from a standalone archive. Importing Qin’s optional radio data is a separate developer procedure.

Data Used for Without it
Bluetooth Bluetooth firmware Bluetooth is unavailable
External radio wireless firmware, calibration, addresses and controller settings external-radio functions are unavailable
FM radio FM receiver settings FM radio is unavailable
Audio profile phone-specific audio gains, equalizer, automatic level control, and speaker-driven vibration where supported UMS9117 headphones use generic volume levels without speaker output; Qin audio is unavailable

A UMS9117 RAM launch prepares its complete required set from NAND. Qin requires its audio profile; optional radio files can be imported separately and are preserved when audio data is refreshed. Device data does not establish hardware support; check the support status and phone page for its limits.

Prepare data from the same physical phone you will run. Do not reuse data from another handset, even of the same model.

Board initialization and the Linux keymap belong to the target’s source configuration. They are not prepared phone data. Contributors can extract a separate board report from a backup.

Source checkouts and standalone archives use the same personal data store for each target:

Host Default directory
Linux $XDG_DATA_HOME/fplinux/phones/<target>, or ~/.local/share/fplinux/phones/<target> when XDG_DATA_HOME is unset
Windows %LOCALAPPDATA%\FPLinux\phones\<target>

For UMS9117, the store contains the complete backup nand.bin and its receipt nand.bin.json. Qin stores its selected original sound files in originals/; this is not a full storage backup. Prepared files are in phone/groups/, with any preparation reports in phone/reports/. Compatible saved inputs and prepared data are reused across archives, source checkouts and new builds. Deleting an extracted archive or pruning a checkout’s build cache does not remove this store.

Use each store with one physical phone. FPLinux selects it by target name and does not detect a unique handset identifier. For another phone of the same target, add --phone-data PATH to select a separate store. PATH is the exact store directory; no target subdirectory is added. Use the same selection with build, run, console, verify, nand backup, nand identify and device-data prepare, or with Run.sh and Run.cmd in an archive. For example:

PC
./fplinux run nokia-ta1618 --phone-data /path/to/my-phone

Private connection keys remain separate in the selected working data directory, under an installation-specific runtime directory. Normal and reader sessions stay together there. Keep the working directory and installation location unchanged while reconnecting to a running phone; changing them does not move the session or its keys.

Build the default RAM image, then follow Run FPLinux from a checkout or First run from an archive. The launcher first checks your saved phone data. When the required inputs are absent or incompatible, it reads the complete NAND on UMS9117 or the selected sound files on Qin. Wait for its safe-disconnect instructions, then start the same command again with the phone powered off. The next RAM boot uses the prepared data without rebuilding the kernel or root filesystem.

With compatible saved inputs, the launcher reuses current prepared data or prepares it again from those inputs, then continues the normal boot in the same invocation. Changes to preparation, including parsing, ECC correction or audio policy, require preparation again. Changes to acquisition, its selected files or NAND geometry require another read from the phone. A new archive or build alone does not require another read.

The reader does not erase, restore or write the phone’s internal storage or NV data. Qin temporarily mounts the selected partitions read-only without replaying their journals, then unmounts them before finishing. Saved inputs are reused when preparation must be retried. Targets with no required runtime groups boot directly.

If storage inspection fails or a removable filesystem is still mounted or used as swap, the command retains the local reader-session keys. Keep the phone powered and retain those keys. Run the launcher again to reconnect and repeat the storage check; do not remove power while storage safety is unresolved. PC console commands require a normal session and cannot reopen this preparation session. Cancelling the command does not power the phone off.

To explicitly prepare or replace the selected UMS9117 data during development:

PC
./fplinux device-data prepare nokia-ta1618

This command builds the default RAM bundle when needed and uses the same preparation workflow. It is not needed for an ordinary first run.

RAM boots send the prepared data separately from the reusable kernel and root filesystem. A microSD build stores prepared data in its kernel and system-card image: run device-data prepare from the checkout you will build, then explicitly build that profile and write its new card image. Another checkout may have refreshed the shared store with different preparation inputs. A RAM launch does not update an existing system card. Keep images and archives containing prepared data private.

If you already saved a complete backup of this phone’s internal storage with nand backup, select it for a RAM launch:

PC
./fplinux run nokia-ta1618 --from-dump nand.bin

Keep nand.bin.json beside the backup. The command uses this receipt to check the backup’s layout and SHA-256, and refuses an incomplete backup or incompatible storage chip. It leaves your input files unchanged, but importing them can replace the backup and prepared data in your personal store.

This form uses an existing default RAM bundle. It admits the explicitly selected backup for that bundle, reuses current prepared data or prepares it from the saved backup, then continues the normal boot in the same invocation. Start with the phone disconnected and connect it only when the loader asks. Only a live reader session ends with instructions to disconnect and start the launcher again.

To prepare data without booting or requiring an existing bundle, use the developer command:

PC
./fplinux device-data prepare nokia-ta1618 --from-dump nand.bin

The developer form prepares any required extraction tools from local inputs in the pinned environment and finishes after preparation. Run ./fplinux setup nokia-ta1618 first if the target’s dependencies are missing. It preserves a known acquisition receipt when importing the backup; a raw file without one remains without an acquisition receipt, so a later automatic RAM launch may require a fresh live backup. Saved backups in other directories can be used through --from-dump; preparation leaves those directories unchanged.

Run ./fplinux device-data prepare --help for the remaining options.

For Qin, --from-dump accepts a complete eMMC USER-area image with its GPT, rather than physical NAND pages:

PC
./fplinux device-data prepare xiaomi-qin-1s-plus --from-dump qin-user-area.bin

This command builds the selected reader bundle when needed, then extracts only the required files on your PC. It leaves the image unchanged and does not copy the whole image into your personal store. Both GPT copies must agree, and all required sound files must be present. You can also pass this image to run --from-dump or an archive launcher.

Preparation accepts 2048 main bytes per page, 64 pages per block and 65536 pages in total, with each page’s main bytes followed by its OOB bytes. It determines the layout from the target’s chip declaration or the backup receipt, never from file length alone. When both declarations are present, they must agree.

A target that declares its NAND chip accepts an explicitly selected raw backup without a receipt. In that case, there is no saved digest to check the complete backup against. The developer preparation command keeps such an import without an acquisition receipt; a later automatic RAM launch may need a new live backup. Keep the receipt from nand backup whenever it is available.

For a target that accepts named original files, use the complete file set listed on its phone page. This command reads those local files; it does not build an image, connect to the phone or read its storage:

PC
./fplinux device-data prepare xiaomi-qin-1s-plus --from-originals originals.json

The UTF-8 JSON manifest has these fields:

Field Value
target The exact target passed to the command
directory The directory containing the originals; a relative path is resolved beside the manifest
files An array containing one record for every required original
files[].name The original’s filename, without directories
files[].size Its positive size in bytes
files[].sha256 Its SHA-256 digest as 64 hexadecimal characters

The manifest records the originals you selected. The command checks every size and digest before preparing data, but these checks do not authenticate a handset or establish where a file came from. Do not combine files from different phones. Linked source files or directories are rejected. --from-originals, --from-dump and --events are mutually exclusive.

Preparation leaves the supplied files and manifest unchanged, replaces the selected prepared group and preserves other complete groups already in the store. Start a fresh RAM session to use optional imported radio data; rebuild a microSD system card before using the data there. Importing data alone does not enable a radio feature that the phone page lists as unsupported.

For UMS9117 bring-up, extract a report from a saved complete backup:

PC
./fplinux device-data report <target> --from-dump nand.bin

This developer command works independently of runtime firmware and audio groups. It prepares the required host tool from local inputs and writes diagnostics/device-data/<target>/report-*/board-report.json inside the working data directory; it does not prepare runtime board maps. Use ./fplinux setup <target> for missing dependencies. Keep the backup’s geometry receipt beside it, especially for a new target with no declared chip geometry. See Bring up a new phone for the complete workflow.

Start the selected build using Run FPLinux, then save the complete physical NAND page stream:

PC
./fplinux nand backup nokia-ta1618 nand.bin

Pass the profile and build type of the running session. The command writes nand.bin and its geometry receipt nand.bin.json, readable only by you. Keep them together and treat the backup as private phone data. The NAND backup reference describes chip checks, replacement behavior and the receipt format.

To identify the chip without saving a backup:

PC
./fplinux nand identify nokia-ta1618
PC
./fplinux nand identify <target> [--profile NAME] [--build-type TYPE]
./fplinux nand backup <target> PATH [--profile NAME] [--build-type TYPE]

Both commands need a phone that is running a build of <target>. They open the phone’s read-only NAND reader, which identifies the fitted chip. Select the profile and build type of the running session; TYPE is release or debug. Saving to the same path replaces the previous backup.

nand identify prints the reader’s report unchanged, one key=value line each for id_bytes, chip, page_main_bytes, oob_bytes, pages_per_block, block_count, raw_bytes, geometry_source, feature_a0, feature_b0 and feature_c0. For a chip that the running kernel does not identify, it shows chip=unknown, zero geometry values and geometry_source=unknown, together with the chip’s ID bytes and feature register values.

nand backup stops before reading any page when the running kernel does not identify the chip, or when the chip or its page size differs from the one the target declares. The expected image size comes from the reported geometry. The command checks that the complete stream has that size, computes its SHA-256 digest and only then puts the file in place, with mode 0600. It then writes the geometry receipt PATH.json beside it, also with mode 0600. Once the complete stream is checked, it removes any old receipt before replacing the backup. If writing the new receipt fails, the complete new backup remains without a receipt; a target that declares its NAND chip can still use it for device-data preparation. The receipt is a JSON object with these fields:

Field Value
id_bytes chip ID bytes as hexadecimal, manufacturer byte first
chip chip name reported by the reader
page_main_bytes, oob_bytes main and OOB bytes per page
pages_per_block, block_count pages per erase block and number of blocks
raw_bytes size of the saved image
sha256 SHA-256 digest of the saved image
target target used for the backup
acquisition_recipe identity of the reader and acquisition inputs, used to decide whether this backup can be reused

The digest identifies the saved bytes; the command does not compare them with a second read from the phone. The receipt contains no NAND contents and can be attached to an issue. An incomplete transfer leaves an existing backup and receipt unchanged. Restoring the NAND is not supported.