Skip to content

Run FPLinux

./fplinux run <target> selects an already-built bundle, prepares required phone data on first use, and loads FPLinux over USB. Once Linux starts, it opens a shell over a private USB network link. The same command reopens the authenticated connection to a phone that is still running. It does not build an image.

For a packaged archive, follow Standalone archive. The instructions below use a source checkout on Linux.

Running FPLinux: from the PC to a shell on the phone PC ./fplinux run waiting for the phone Boot ROM mode USB device 1782:4d00 Linux starts USB network device 0525:a4a6 Hold boot key connect USB Loader copies FPLinux into RAM SSH shell over the private USB network
From PC to phone shell
  • A finished build for your phone; see Build FPLinux.
  • On the PC: GNU stdbuf from coreutils, ip from iproute2, and the OpenSSH client tools ssh, ssh-keygen, ssh-keyscan and sftp.
  • A network manager that automatically runs IPv4 DHCP on a newly attached USB network interface. NetworkManager does this.
  • A USB data cable that fits your phone.
  • Your phone’s exact target and boot key, from its phone page. Check its support status and power limits before starting.

Do this once per PC. Install the USB rules from the checkout, then reload them:

PC
sudo install -m 0644 common/60-fplinux.rules /etc/udev/rules.d/60-fplinux.rules
sudo udevadm control --reload-rules

If the phone is connected, disconnect it so the new rules apply on the next connection.

The rules let the user logged in at the desktop open the phone’s two USB devices: the boot ROM device 1782:4d00 during loading and the FPLinux device 0525:a4a6 after Linux starts. Keep the 60- prefix: the rules must stop the desktop’s MTP probe before the system libmtp rule runs.

On a headless PC without a desktop login, edit your installed copy to use a local group with MODE="0660" instead of TAG+="uaccess". Never make either device world-writable.

Run the loader as your regular user, not as root.

  1. Power the phone off and disconnect USB.

  2. Start the loader:

    PC
    ./fplinux run nokia-ta1618

    This example uses nokia-ta1618; use your phone’s exact target. If you built with --profile or --build-type, add the same options here.

  3. Wait until the loader asks for the phone:

    Output
    Power the phone off, hold *, then connect USB while keeping * pressed.
  4. Only now hold your phone’s boot key and connect the USB cable to the powered-off phone, keeping the key pressed. The Nokia example uses *.

  5. Keep USB connected while the loader works. It reuses compatible saved phone data when available. Otherwise, UMS9117 phones make a complete read-only NAND backup, while Qin reads selected sound files from eMMC. During preparation, the phone shows its progress instead of Home; the PC keeps the detailed log.

  6. After reading new data from the phone, wait for Disconnect USB. before disconnecting. If the phone stays on, briefly remove and reinsert its battery. Start again from step 1 with the same command. No rebuild is needed. With compatible saved inputs, the loader prepares data as needed and continues without this restart.

  7. Wait for Linux and the SSH session. Targets without required phone data boot directly on their first run.

On a fresh session, run tries to set the phone’s clock from the PC and prints the result. A clock-setting failure leaves the session usable. From an interactive terminal, it then opens a shell on the phone. Without a terminal, for example in a script, it returns as soon as the session is ready. See Clock and alarms.

Exiting the shell does not stop Linux. The phone keeps running while it has power.

Run the same ./fplinux run <target> command with the same profile and build type. It authenticates the saved session before reopening SSH. A present connection that cannot be authenticated causes an error.

Use console when you require an existing session, run one command, copy files or type with the PC keyboard; see Connect from your PC.

The backup and prepared data use the personal phone data store, shared with other checkouts and archives. Use each store with the same physical phone; --phone-data PATH selects a separate store. Private connection keys stay in the selected working data directory, separate from the shared data and from other installations’ sessions.

Each launch prints its log path. Its runtime.log and run.json are kept under logs/run/<target>/ in the working data directory, with an additional profiles/<profile>/ directory for a selected profile. Interactive SSH commands and terminal output are not recorded. Only one launcher can use the same target session directory at a time; close the active launcher before reopening it.

PC
./fplinux verify nokia-ta1618
Output
verify: the phone runs the current release build (…)

verify compares the system running on the phone with your current local build. It refuses when the phone runs a different image or profile. Installing or rebuilding optional packages does not require a new load. verify checks identity only; it does not test the phone’s hardware.

To end the session without losing data on a microSD card, follow Power. Linux reboot is not supported; for the next session, start again from step 1 with the phone powered off.

The phone did not start in boot ROM mode. The loader stops when its 300-second connection deadline expires. Power the phone off, disconnect USB, start the loader again and hold the selected phone’s boot key before and while you connect USB.

Install the rules from Allow USB access, reload them, then disconnect and reconnect the phone. The boot ROM device and the running FPLinux device need separate rules; install the whole file.

Follow the message printed by the loader. On Linux, the UMS9117 loader can request up to three attempts within one 300-second deadline; disconnect and power off the phone before reconnecting when prompted. The Qin loader stops on a failed upload. If the command has stopped, start it again before connecting the powered-off phone. Read the runtime.log path printed at startup for the complete USB loader diagnostics.

Reconnect with the same run command or with console. Start a fresh load only from a powered-off phone.

Linux starts but the shell does not connect

Section titled “Linux starts but the shell does not connect”

Check that the network manager gave the new USB network interface an IPv4 address, and that the OpenSSH tools listed in Before you start are installed. Keep the complete loader output for a bug report.

Check that you passed the same profile and build type as the running session. If the image on the phone is outdated, rebuild it and start a fresh session.

--events PATH writes machine-readable progress for a fresh load:

PC
./fplinux run nokia-ta1618 --events loader.jsonl

The file is overwritten. Each line is one JSON object with event, target, profile, build_type and a UTC time. A successful load writes these events in order: waiting-for-device, device-found, ram-loader-start, ram-loader-complete, linux-start, linux-transition, linux-usb, ssh-ready and complete. A loader retry can repeat device-found and ram-loader-start. A failure event adds the last stage, a short cause and the exit_status. complete is written before the interactive shell opens. The events contain no SSH credentials. The loader-first sequence above still applies.

linux-usb records the first observation of the exact device bound to this load; ssh-ready records session authentication. Live NAND reading ends after the backup and data are ready; a later launch performs the normal boot. Reusing or preparing a saved compatible backup continues into the normal boot in the same invocation. Live device-data preparation and fresh standalone loads accept the same option. device-data prepare rejects --events with --from-dump; standalone --reconnect also rejects --events.