diff --git a/archbee.json b/archbee.json index dfb5da8e..11df00ef 100644 --- a/archbee.json +++ b/archbee.json @@ -222,7 +222,7 @@ "path": "cpu-software/Flipper-OS.md", "children": [ { - "categoryName": "OS Profiles", + "categoryName": "Profiles CLI", "isCategory": false, "path": "cpu-software/profiles.md", "children": [] diff --git a/docs/cpu-software/Flipper-OS.md b/docs/cpu-software/Flipper-OS.md index b52f1444..2af23e6d 100644 --- a/docs/cpu-software/Flipper-OS.md +++ b/docs/cpu-software/Flipper-OS.md @@ -3,21 +3,43 @@ title: Flipper OS slug: cpu-software/flipper-os docTags: createdAt: Sun Apr 26 2026 18:22:16 GMT+0000 (Coordinated Universal Time) -updatedAt: Tue Apr 28 2026 13:17:42 GMT+0000 (Coordinated Universal Time) +updatedAt: Thu Aug 13 2026 12:00:00 GMT+0000 (Coordinated Universal Time) --- -**Flipper OS** is a Linux-based operating system we are developing for the Flipper One. This page outlines the core concept behind Flipper OS and explains how we aim to solve common challenges users face when using a Linux computer as an all-in-one multitool. +**Flipper OS** is a Linux-based operating system we are developing for Flipper One. It's an additional layer on top of a standard Debian-based Linux system that lets you switch between multiple preconfigured OS profiles for different tasks, so you can experiment freely without worrying about breaking your setup or turning it into a mess. + +This page outlines the core concept behind Flipper OS: what we want to build, and why. + +*** + +::embed[]{url="https://www.youtube.com/watch?v=yFCLM971Upw"} + +## What we want to build into Flipper OS + +- **OS profiles** — preconfigured OS images for different tasks, such as a network router, a radio lab, a desktop computer, and a TV media box. Each profile has its own settings, kernel, device tree, and set of applications. +- **An unbreakable playground** — clone any profile and modify anything inside it, from the kernel to system files, without worrying about breaking the device. +- **Reset to default** — roll back your changes and return a profile to its clean, default state at any time. +- **Atomic updates** — no matter how badly a profile has been broken, it should still be possible to update it to a new version reliably. + +*** + +## Why not just customize another OS? + +Why build Flipper OS, yet another operating system, when there are already so many? Why not simply take a standard Debian-based system — the way Raspberry Pi does — and customize it? + +Conventional Linux distributions are designed for traditional computers and servers. They aren't convenient for a multitool like Flipper One, which can be a network router, a radio lab, a desktop computer, or a TV media box, all on the same device. *** ## The messy system problem -When you try to use any Linux-based SBC as a universal “on-the-go” tool and keep changing its purpose over time, for example using it as a media server, a Wi-Fi router, or a desktop, **you eventually end up with a messy system**. You install so many packages and modify so many system configuration files that, at some point, reconfiguring the system becomes harder than reinstalling the OS and rebuilding the entire setup from scratch. +When you try to use any Linux-based SBC as a universal "on-the-go" tool and keep changing its purpose over time — for example using it as a media server, a Wi-Fi router, or a desktop — **you eventually end up with a messy system**. You install so many packages and modify so many system configuration files that, at some point, reconfiguring the system becomes harder than reinstalling the OS and rebuilding the entire setup from scratch. ![A typical scenario with the common approach](/files/pics/linux-os-classic-problem.png "A typical scenario with the common approach") -Flipper OS is designed to resolve the messy system problem. To better understand what Flipper OS does and why, let's first make an overview of other ways to approach this problem. +Containers such as Docker solve part of this problem, but only for user-space applications. They work well when you need to isolate an application, but not when you need to work close to the bare metal: patch the kernel, modify the device tree, reconfigure an HDMI port or Wi-Fi driver, or bit-bang GPIOs. In these cases, you need full access to the hardware — something containers can't give you. +Flipper OS is designed to resolve the messy system problem. To better understand what Flipper OS does and why, let's first look at other ways to approach this problem. ## Common approach and its issues @@ -32,6 +54,14 @@ Issues with the SD card approach: *** +## What is Flipper OS? + +Flipper OS is not exactly an operating system, but rather a higher-level toolset that enables centralized management of OS profiles from a single device. You can think of it as similar to Docker containers, but without virtualization — offering full access to bare metal. + +Ultimately, we aim to create a tool that hardware hackers can use to build their own versatile Linux boxes for various tasks, and share the resulting images with the community. We want Flipper OS to be usable not just on Flipper One, but on other platforms too. + +*** + ## Flipper OS architecture Flipper OS introduces the concept of **operating system profiles**, which are architecturally separated from the base system. @@ -42,9 +72,9 @@ Thus, the operating system consists of two distinct parts: **OS profiles** — an overlay on top of the base system that contains all user customizations, including installed packages, containers, and modifications to the RootFS including config files edits. By applying an OS profile to the Flipper OS base system, you get a fully configured system tailored for a specific use case. -- **Official built-in OS profiles** are distributed as part of the operating system, for example: `Minimal system`, `Wi-Fi router`, `TV media box`, `Network sniffer`, and `Desktop computer`. +- **Official built-in OS profiles** are distributed as part of the operating system, for example: `Minimal system`, `Wi-Fi router`, `TV media box`, `Network sniffer`, and `Desktop`. -- **User OS profiles** contain user-modified packages and RootFS changes. Users configure the system in the usual way by editing configs and installing packages using package manager. The process remains fully transparent to the user, while all changes are automatically stored inside the active profile. In addition to OS profiles, users can separately store personal files such as media files, documents, and other data not related to the operating system. +- **User OS profiles** contain user-modified packages and RootFS changes. Users configure the system in the usual way by editing configs and installing packages using a package manager. The process remains fully transparent to the user, while all changes are automatically stored inside the active profile. In addition to OS profiles, users can separately store personal files such as media files, documents, and other data not related to the operating system. User OS profiles can be stored on removable media, allowing users to select and boot a profile from the boot menu, for example from an SD card. @@ -54,7 +84,7 @@ Thus, the operating system consists of two distinct parts: ## OS profile selection at boot -An operating system profile can be selected directly from the boot menu without connecting an external monitor or keyboard. The menu also allows users to clone profiles and restore them to their original preconfigured state. +An operating system profile can be selected directly from the boot menu without connecting an external monitor or keyboard. The menu also allows users to clone profiles and restore them to their original preconfigured state, and it shows each profile's last-used timestamp. ![Boot menu with OS profile selection](/files/pics/flipper-os-switching-os-profile-on-boot.png "Boot menu with OS profile selection") @@ -62,6 +92,30 @@ Official built-in OS profiles cannot be deleted, but they can be cloned and used *** +## Boot stages + +Flipper One has a dual-processor architecture (MCU + CPU), so you can interact with the device via its LCD screen and buttons even when Linux and the CPU are powered off. Because of this, the device goes through several distinct stages before an OS profile is up and running: + +- **MCU Mode** — the CPU and Linux are powered down, and only the microcontroller firmware is active. It starts the CPU and hands over control of the screen to the software running at the CPU level. +- **Boot Menu** — a standalone program that runs on the CPU and displays the OS profile selection menu; the full Linux system hasn't loaded yet. The boot menu can render graphics on the LCD screen and process button input, read profile metadata such as size and last-used date, and manage profiles by resetting, deleting, or cloning them. We currently use U-Boot for this; in the future, we plan to switch to a lightweight Linux distribution with the boot menu program compiled into it. +- **Profile started** — the selected OS profile is now running as a full-fledged operating system without restrictions. See [Unbreakable profiles](#unbreakable-profiles) below. + +:::hint{type="info"} +See [Operation modes](../user-interface/Operation-modes.md) for the full set of Flipper One's power and display states, including Power OFF and Linux Mode. +::: + +*** + +## Unbreakable profiles + +We want to give you complete freedom within a loaded profile — the ability to break and tinker with the system however you please: installing packages, modifying system files, and altering the kernel and device tree. That means a profile's root filesystem must be writable, with no restrictions placed on the user. + +At the same time, we want the ability to roll back all changes and revert a profile to its default state. All modifications to the original profile are stored on a separate overlay layer, which can be deleted to reset the profile to default. + +Changes are saved seamlessly, without the need to run specific commands to preserve them: if you keep booting into the same profile and modifying it, those **changes persist across reboots** — just as they would on a standard, traditional operating system. + +*** + ## Managing OS profiles on running system On a running system, the user can: @@ -74,12 +128,50 @@ On a running system, the user can: *** +## Cloning and sharing profiles + +Say you've spent a long time fine-tuning a `Router` profile and you're happy with the result. From the boot menu, you can select `Edit`, clone the profile, and save it under a unique name, such as `[MyTravelRouter]`. We call this a **user profile**, and mark it by enclosing its name in square brackets to distinguish it from the built-in profiles. + +:::hint{type="info"} +The bracket notation (`[Name]`) is the boot menu's display naming for user profiles. At the command-line level, profiles use a separate `@Name` convention — see [Profiles CLI](profiles.md) for the CLI reference. +::: + +With this approach, you don't have to worry about losing a successful configuration — you can keep experimenting in a separate profile, similar to working with branches in Git. + +We'd also like to let users share their profiles with the community, so others can download and use them, along with deduplication so the same file isn't stored twice on disk across different profiles. + +:::hint{type="warning"} +**Not yet implemented.** Community profile sharing and deduplication are goals we want to build toward, not current features. +::: + +*** + +## User data and volatile files + +User data needs to be accessible from all profiles, so a portion of the filesystem must remain independent of any single profile. For instance, if you download a video to `/home/user/Downloads` in the `Desktop` profile, you should be able to watch it later from the `TV Media Box` profile. + +We're leaning towards keeping `/home/user` tied to a specific profile, with only a single shared folder — such as `/home/user/user_data` — common to all profiles. + +:::hint{type="warning"} +**Open question.** We haven't yet decided how to handle other volatile, profile-generated data, such as caches and settings. For example, should a Wi-Fi password saved in one desktop profile be available in another? Making all of `/home` shared would prevent distinct per-profile configurations and cause conflicts, so we're leaning against that — but the exact boundary is still undecided. +::: + +*** + ## System update -Flipper OS includes an update agent that notifies the user about available system updates from any active OS profile. Both the base system and the official built-in profiles are updated. +The main challenge with the entire Flipper OS concept lies in system updates: how do we release new profile versions and deploy them over existing ones, when the user has root access and multiple cloned profiles? -![System update UI](/files/pics/flipper-os-system-update.png "System update UI") +We don't want updating to be a complex migration between versions that could easily fail — a standard `apt upgrade` is unpredictable, and you never know where things might break when upgrading to a new distribution version. Ideally, we need an atomic update that guarantees a predictable transition to a new profile version. -We are currently exploring mechanisms for reliable atomic updates of both the operating system and OS profiles. We invite the community to help develop the best solutions. +:::hint{type="warning"} +**As of now, there is no solution to this problem.** We're experimenting with several approaches, including the [OSTree](https://ostreedev.github.io/ostree/) approach and testing [Btrfs](https://btrfs.readthedocs.io/en/latest/) images. +::: *** + +## Join the development + +We invite you to join the discussion and help us work through these open problems — from the update mechanism to how shared data should work. + +See [how to join the development](../How-to-join.md) to get started. diff --git a/docs/cpu-software/profiles.md b/docs/cpu-software/profiles.md index 70ae7291..ce3ab34f 100644 --- a/docs/cpu-software/profiles.md +++ b/docs/cpu-software/profiles.md @@ -1,64 +1,30 @@ --- -title: OS profiles and snapshots +title: Profiles CLI slug: cpu-software/profiles docTags: createdAt: Mon Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time) -updatedAt: Mon Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time) +updatedAt: Thu Aug 13 2026 12:00:00 GMT+0000 (Coordinated Universal Time) --- -This page explains OS profiles and snapshots in Flipper OS, how to use them, and how to manage them using CLI helper tools. +This page is a command-line reference for managing OS profiles in Flipper OS. For what OS profiles are, and why Flipper OS uses them, see [Flipper OS](Flipper-OS.md). -## Introduction +## Concepts -When a Linux device is used as a multitool, in roles like a Wi-Fi router, a media box, and a desktop, it gradually accumulates installed packages, modified config files, and saved data. Eventually, the system becomes too messy to use, and the only solution is to reinstall it from scratch. With a multitool, users often need to switch between setups, save a working state before experimenting, and roll back after breaking things. +An OS profile is an isolated system you can boot into and use: install new packages with `apt`, change config files, and do whatever you want with it. A profile contains a Linux kernel and a `/` root directory, including the desktop environment, installed packages, and configuration files. Every profile is fully writable and bootable — there's no separate read-only or non-bootable state. -## Flipper OS +Internally, Flipper OS uses [Btrfs](https://btrfs.readthedocs.io/en/latest/) to implement OS profiles and the common boot menu. -### OS profiles +### System profiles -Flipper OS introduces the concept of **OS profiles**. An OS profile is an isolated system you can boot into and use: install new packages with `apt`, change config files, and do whatever you want with it. +System profiles are the official, preinstalled profiles, such as `Desktop`, `Router`, `TV-Media-Box`, `Minimal`, and `No-Graphics`. You can reset a system profile to its original default state at any time, discarding any modifications you've made to it. -Flipper One has several OS profiles specialized for different roles, such as Desktop, TV media box, or Router — and you can add more. You can select OS profiles in the boot menu: +### User profiles -![Boot menu displays available OS profiles: Desktop, TV Media Box, Router, and others](/files/pics/cpu-software/boot-menu.jpeg "Boot menu displays available OS profiles") - -A profile contains a Linux kernel and a `/` root directory including the desktop environment, installed packages, and configuration files. However, several directories are shared between all profiles: - -- `/home` — user home directories -- `/var/log` — logs -- `/var/cache` — application cache - -Shared directories allow you to preserve logs and exchange files between OS profiles. For example, you can reboot Flipper One into desktop mode to study logs produced in router mode. Switching profiles changes how the system behaves without touching `/home`, and a deleted or broken profile cannot affect any of the shared volumes. - -Internally, Flipper OS uses [Btrfs](https://btrfs.readthedocs.io/en/latest/) to implement the functionality of OS profiles, snapshots, the common boot menu, and shared directories. - -### Snapshots - -While you work in an OS profile, you can save its state in a read-only copy called a snapshot. For example, you can make a snapshot as a save point before a risky change. If something goes wrong, you can always restore a profile to a working state. You can also save a successful configuration in a snapshot, and then create new profiles from it. - -Snapshots are not bootable and do not appear in the boot menu. It usually takes a few seconds to create an OS profile from a snapshot. You don't need to use an external SD card or wait for the system to install. - -### Stock snapshots - -Stock snapshots are a special type of snapshot preloaded on Flipper One and used to initialize starting OS profiles. New versions of stock snapshots can be downloaded from an update server. You can use stock snapshots to create new OS profiles. - -![OS-profiles-and-snapshots-lifecycle.jpg](/files/pics/cpu-software/OS-profiles-and-snapshots-lifecycle.jpg) - -Stock snapshot names match initial OS profile names: - -- `Desktop_stock` → `Desktop` -- `Router_stock` → `Router` -- `TV-Media-Box_stock` → `TV-Media-Box` -- `No_Graphics_stock` → `No_Graphics` -- `Minimal_stock` → `Minimal` - -However, you can rename profiles, create new ones or delete those you don't need. - -![profile-snapshot-stock-large.png](/files/pics/cpu-software/profile-snapshot-stock-large.png) +A user profile is a profile you create by cloning a system profile or another user profile. In the boot menu, user profiles are shown with their name in square brackets, e.g. `[MyTravelRouter]`, to distinguish them from system profiles — at the command-line level, they're referenced by their plain `@Name`, same as system profiles. See [Cloning and sharing profiles](Flipper-OS.md#cloning-and-sharing-profiles) for the concept. ### Disk space usage -Flipper OS uses [Btrfs](https://btrfs.readthedocs.io/en/latest/), which is a copy-on-write (CoW) file system. When you create a snapshot or a new profile, no data is duplicated on disk, so no extra space is consumed. When you make changes in a profile, only the changed blocks are written anew, and everything else is shared between the original and the copy. This means you can keep multiple profiles and snapshots without using proportionally more disk space. +Flipper OS uses [Btrfs](https://btrfs.readthedocs.io/en/latest/), which is a copy-on-write (CoW) file system. When you clone a profile, no data is duplicated on disk, so no extra space is consumed. When you make changes in a profile, only the changed blocks are written anew, and everything else is shared between the original and the copy. This means you can keep multiple profiles without using proportionally more disk space. :::::ExpandableHeading See the actual space usage with `btrfs-show-space` @@ -90,21 +56,15 @@ Id Path single DUP DUP Unallocated Total Slack Total 2.98GiB 256.00MiB 8.00MiB 56.01GiB 59.50GiB 0.00B Used 2.12GiB 153.33MiB 16.00KiB -Measuring 12 subvolume(s) (du + compsize), please wait... -== root subvolumes & snapshots == -NAME UNIQUE REFERENCED TOTAL -@snapshots/@Desktop_2026-07-14_10-15-16 0.0B 2.0GiB 3.4GiB -@snapshots/@Desktop_2026-07-14_10-16-37_Desktop-before-changes 0.0B 2.0GiB 3.4GiB -@Desktop 4.0KiB 2.0GiB 3.4GiB <- booted -@Desktop_stock 76.0KiB 2.0GiB 3.4GiB -@Minimal 0.0B 1.4GiB 2.4GiB -@Minimal_stock 0.0B 1.4GiB 2.4GiB -@No-Graphics 0.0B 1.4GiB 2.4GiB -@No-Graphics_stock 0.0B 1.4GiB 2.4GiB -@Router 0.0B 1.4GiB 2.4GiB -@Router_stock 0.0B 1.4GiB 2.4GiB -@TV-Media-Box 0.0B 1.5GiB 2.5GiB -@TV-Media-Box_stock 0.0B 1.5GiB 2.5GiB +Measuring 6 subvolume(s) (du + compsize), please wait... +== root subvolumes == +NAME UNIQUE REFERENCED TOTAL +@Desktop 4.0KiB 2.0GiB 3.4GiB <- booted +@Minimal 0.0B 1.4GiB 2.4GiB +@No-Graphics 0.0B 1.4GiB 2.4GiB +@Router 0.0B 1.4GiB 2.4GiB +@TV-Media-Box 0.0B 1.5GiB 2.5GiB +@MyTravelRouter 120.0KiB 1.5GiB 2.5GiB UNIQUE = freed if you delete that subvolume alone (uncompressed). REFERENCED = real on-disk size, compressed; counts shared extents, so NOT additive. @@ -112,154 +72,116 @@ TOTAL = apparent (uncompressed). ``` ::::: -## Profile and snapshot CLI +## Profile CLI -You can create snapshots, add new profiles, and do other things using the command line interface (CLI) from any Flipper OS profile. +You can create, clone, reset, and manage profiles using the command line interface (CLI) from any Flipper OS profile. The CLI commands are included in the Flipper OS distribution and instantly available on Flipper One. CLI commands are preinstalled system-wide, and you can run them from any directory. All commands need administrator rights, so you need to start each with `sudo`. The first time you use `sudo` in a session, it asks for your password, which is normal. ### CLI command quick reference -| I want to... | Command | -|-------------------------------------------|-------------------------------------------| -| List existing profiles | `sudo list-profiles` | -| List existing snapshots | `sudo list-snapshots` | -| See space used per profile/snapshot | `sudo btrfs-show-space` | -| Save a restore point | `sudo create-snapshot [name]` | -| Create a profile from a stock snapshot | `sudo create-profile @X_stock @New` | -| Create a profile from the current profile | `sudo create-profile @X @New` | -| Restore a profile from a snapshot | `sudo create-profile @snapshots/... @New` | -| Rename a profile | `sudo rename-profile @Old @New` | -| Delete a profile | `sudo delete-profile @Name` | -| Delete a snapshot | `sudo delete-snapshot @snapshots/...` | -| Back up to a file or USB | `sudo send-snapshot @X /path/or/dir` | -| Restore a backup file | `sudo receive-snapshot ` | -| Maintain the disk health | `sudo btrfs-maintenance all` | - -Rule of thumb: always make a snapshot before you experiment, and keep a `_stock` around as your always-safe fallback. +| I want to... | Command | +|----------------------------------------------|-----------------------------------| +| List existing profiles | `sudo list-profiles` | +| See space used per profile | `sudo btrfs-show-space` | +| Create a user profile from a system profile | `sudo create-profile @X @New` | +| Create a user profile from the booted profile | `sudo create-profile @X @New` | +| Reset a system profile to its default state | `sudo reset-profile @Name` | +| Rename a user profile | `sudo rename-profile @Old @New` | +| Delete a user profile | `sudo delete-profile @Name` | +| Back up a profile to a file or USB | `sudo send-profile @X /path/or/dir` | +| Restore a profile from a backup file | `sudo receive-profile @New` | +| Maintain the disk health | `sudo btrfs-maintenance all` | + +Rule of thumb: clone a system profile into a user profile before you experiment, and use `reset-profile` any time you want a system profile back to its factory state. Each CLI command accepts the `-h` (`--help`) flag for a quick reminder of what it does; for example, `create-profile -h`. ### List existing profiles -Use `list-profiles` to view existing OS profiles, the currently booted profile, and the profile inheritance: +Use `list-profiles` to view existing OS profiles, the currently booted profile, and which profile each user profile was cloned from: ```bash $ sudo list-profiles booted profile: @Desktop (id 265) -NAME KIND ID CREATED RO PARENT -@Desktop profile 265 2026-07-03 12:14:21 rw @Desktop_stock (264) <- booted -@Desktop_stock stock 264 2026-07-03 12:10:22 ro @Minimal_stock (262) -@Minimal profile 263 2026-07-03 12:10:22 rw @Minimal_stock (262) -@Minimal_stock stock 262 2026-07-03 12:10:22 ro - -@Router profile 269 2026-07-03 12:14:55 rw @Router_stock (268) -@Router_stock stock 268 2026-07-03 12:14:54 ro @Minimal_stock (262) -@TV-Media-Box profile 267 2026-07-03 12:14:54 rw @TV-Media-Box_stock (266) -@TV-Media-Box_stock stock 266 2026-07-03 12:14:21 ro @Minimal_stock (262) +NAME KIND ID CREATED PARENT +@Desktop system 265 2026-07-03 12:14:21 - <- booted +@Minimal system 262 2026-07-03 12:10:22 - +@Router system 268 2026-07-03 12:14:55 - +@TV-Media-Box system 266 2026-07-03 12:14:54 - +@MyTravelRouter user 271 2026-07-03 14:20:10 @Router (268) ``` -Shows the profile list, which one is currently booted, and which are built-in (stock). - -### Make a snapshot as a save point - -You can make a snapshot as a save point **before** making an important change or a risky action. -The `create-snapshot` command demonstrated below creates a snapshot based on your currently booted profile: - -```bash -$ sudo create-snapshot - -created @snapshots/@Desktop_2026-07-03_14-02-25 (read-only) -``` - -You can specify the snapshot label: - -```bash -$ sudo create-snapshot Test - -created @snapshots/@Desktop_2026-07-03_14-02-22_Test (read-only) -``` +Shows the profile list, which one is currently booted, and which are built-in system profiles versus user profiles. -### Restore a profile from a snapshot +### Make a new user profile from a system profile -The `create-profile` command takes a snapshot and turns it into a bootable profile `@MyDesktop`. This is how you "go back" to a saved state. +You can make a new user profile from a system profile using `create-profile`: ```bash -$ sudo create-profile @snapshots/@Desktop_2026-07-03_14-02-22_Test @MyDesktop +$ sudo create-profile @Router @MyTravelRouter -Create bootable profile "@MyDesktop" with a writable copy of @snapshots/@Desktop_2026-07-03_14-02-22_Test on /dev/sda2? [y/N] y -flipper-bls: wrote entry for @MyDesktop (kernel 7.1.0-g5f8b21274ff4, slot 92) -profile '@MyDesktop' created from '@snapshots/@Desktop_2026-07-03_14-02-22_Test' (writable, boot entry added) -reboot and pick '@MyDesktop' from the boot menu to use it +Create profile "@MyTravelRouter" as a writable copy of @Router? [y/N] y +flipper-bls: wrote entry for @MyTravelRouter (kernel 7.1.0-g5f8b21274ff4, slot 92) +profile '@MyTravelRouter' created from '@Router' (boot entry added) +reboot and pick '[MyTravelRouter]' from the boot menu to use it ``` -### List existing snapshots +The command above creates a fresh, bootable `@MyTravelRouter` from the `@Router` system profile. In the boot menu, it appears as `[MyTravelRouter]`. -```bash -$ sudo list-snapshots - -NAME ID CREATED PARENT -@snapshots/@Desktop_2026-07-03_14-02-22_Test 272 2026-07-03 14:02:22 @Desktop (265) -@snapshots/@Desktop_2026-07-03_14-02-25 273 2026-07-03 14:02:25 @Desktop (265) -``` -Shows every saved snapshot and which profile it came from. +### Make a new user profile from the booted profile -### Make a new profile from a stock snapshot - -You can make a new profile from a stock profile using `create-profile`: +You can also make a new user profile straight from your **currently booted** profile (including all your changes): ```bash -$ sudo create-profile @Desktop_stock @DesktopTest +$ sudo create-profile @Desktop @DesktopTest -Create bootable profile "@DesktopTest" with a writable copy of @Desktop_stock on /dev/sda2? [y/N] y +Create profile "@DesktopTest" as a writable copy of @Desktop? [y/N] y flipper-bls: wrote entry for @DesktopTest (kernel 7.1.0-g5f8b21274ff4, slot 92) -profile '@DesktopTest' created from '@Desktop_stock' (writable, boot entry added) -reboot and pick '@DesktopTest' from the boot menu to use it +profile '@DesktopTest' created from '@Desktop' (boot entry added) +reboot and pick '[DesktopTest]' from the boot menu to use it ``` +Creates `@DesktopTest` as a copy of Desktop as it is right now. -The command above creates a fresh, bootable `@DesktopTest` from the `@Desktop_stock` profile. You can now reboot and pick `@DesktopTest` from the boot menu. - -### Make a new profile from the booted profile +### Reset a profile to its default state -You can also make a new profile straight from your **currently booted** profile (including all your changes): +Use `reset-profile` to discard all modifications made to a system profile and return it to its original, preconfigured state. Only system profiles can be reset this way — a user profile has no separate default state, so if you want a clean slate, clone a fresh one from a system profile instead. ```bash -$ sudo create-profile @Desktop @DesktopTest2 +$ sudo reset-profile @Router -Create bootable profile "@DesktopTest2" with a writable copy of @Desktop on /dev/sda2? [y/N] y -flipper-bls: wrote entry for @DesktopTest2 (kernel 7.1.0-g5f8b21274ff4, slot 92) -profile '@DesktopTest2' created from '@Desktop' (writable, boot entry added) -reboot and pick '@DesktopTest2' from the boot menu to use it +Reset profile "@Router" to its default state? All modifications will be lost. [y/N] y +flipper-bls: reissued boot entry for @Router (kernel 7.1.0-g5f8b21274ff4, slot 92) +profile '@Router' reset to its default state ``` -Creates `@DesktopTest2` as a copy of Desktop as it is right now. ### Rename a profile -The `rename-profile` command renames the profile and updates its boot menu entry. Profile content stays unchanged. You cannot rename the profile you are currently booted into, so boot into another one first. +The `rename-profile` command renames a user profile and updates its boot menu entry. Profile content stays unchanged. You cannot rename a system profile, or the profile you are currently booted into — boot into another one first. ```bash -$ sudo rename-profile @DesktopTest @Playground +$ sudo rename-profile @MyTravelRouter @Playground -renamed @DesktopTest -> @Playground +renamed @MyTravelRouter -> @Playground flipper-bls: reissued boot entry for @Playground ``` -### View disk space used by profiles and snapshots +### View disk space used by profiles ```bash $ sudo btrfs-show-space Filesystem 28.00GiB, used 6.42GiB (22%) -NAME UNIQUE REFERENCED TOTAL -@Desktop 412.0MiB 3.10GiB 4.85GiB <- booted -@Desktop_stock 0.0B 2.98GiB 4.61GiB -@Minimal 8.0MiB 1.42GiB 1.90GiB -@Minimal_stock 0.0B 1.41GiB 1.88GiB +NAME UNIQUE REFERENCED TOTAL +@Desktop 412.0MiB 3.10GiB 4.85GiB <- booted +@Router 8.0MiB 1.42GiB 1.90GiB +@MyTravelRouter 120.0MiB 1.50GiB 1.95GiB ``` -Profiles and snapshots share most of their data, so they take far less room than the sizes suggest. The columns: +Profiles share most of their data, so they take far less room than the sizes suggest. The columns: - **UNIQUE**: data only this one holds. This is roughly what you get back if you delete **just this one** and keep the rest. - **REFERENCED**: its real on-disk size (compressed). Because data is shared, these don't add up across rows. @@ -268,34 +190,25 @@ Profiles and snapshots share most of their data, so they take far less room than Add `-q` (`sudo btrfs-show-space -q`) for a faster run that skips the REFERENCED column. -### Delete a profile or snapshot - -Use `delete-profile` to delete a profile and remove it from the boot menu: - -```bash -# sudo delete-profile @DesktopTest2 - -Delete profile '@DesktopTest2'? [y/N] y -deleted @DesktopTest2 -removed boot entry /boot/loader/entries/92-DesktopTest2-flipperos-DesktopTest2-7.1.0-g5f8b21274ff4.conf -``` +### Delete a profile -Use `delete-snapshot` to delete a snapshot you no longer need: +Use `delete-profile` to delete a user profile and remove it from the boot menu. System profiles cannot be deleted, only reset. ```bash -$ sudo delete-snapshot @snapshots/@Desktop_2026-07-03_14-08-44_Minimal-DeleteMe +# sudo delete-profile @DesktopTest -Delete restore-point snapshot '@snapshots/@Desktop_2026-07-03_14-08-44_Minimal-DeleteMe'? [y/N] y -deleted @snapshots/@Desktop_2026-07-03_14-08-44_Minimal-DeleteMe +Delete profile '@DesktopTest'? [y/N] y +deleted @DesktopTest +removed boot entry /boot/loader/entries/92-DesktopTest-flipperos-DesktopTest-7.1.0-g5f8b21274ff4.conf ``` -Each command asks for a `y/N` confirmation first, so a typo won't wipe anything by accident. You will need to confirm twice to delete a read-only target, and three times to delete a stock snapshot. +Each command asks for a `y/N` confirmation first, so a typo won't wipe anything by accident. --- ### Maintain the disk health -`btrfs-maintenance` runs housekeeping across all your profiles and snapshots. For everyday maintenance, use the `all` parameter: +`btrfs-maintenance` runs housekeeping across all your profiles. For everyday maintenance, use the `all` parameter: ```bash sudo btrfs-maintenance all @@ -304,50 +217,33 @@ sudo btrfs-maintenance all This command does three actions in the following order: - **check**: a read-only scrub that verifies every checksum (finds silent corruption, changes nothing). -- **dedup**: reclaims space by sharing identical data between profiles and snapshots. +- **dedup**: reclaims space by sharing identical data between profiles. - **balance**: tidies partly-empty storage chunks so free space is usable again. You can also run any action on its own: `sudo btrfs-maintenance check`, `dedup`, or `balance`. There is also the `fix` action, a scrub that repairs damage where a good copy exists. The full `btrfs-maintenance all` call can take a while on a busy disk, so it's best to run it when you don't need the device urgently. --- -### Advanced: "move" a snapshot into a profile - -The `create-profile -m` command **moves** the snapshot into the new profile instead of copying it: the snapshot is consumed (gone afterward), but its parent link is kept. Most people don't need this. It's mainly useful for incremental backup transfers (see below). If in doubt, use the normal copy above. +### Advanced: back up and restore a profile to a file or USB -```bash -$ sudo create-profile -m @snapshots/@Desktop_2026-07-03_14-02-22_Test @MyDesktop2 +You can keep your profiles backed up off the device: -Create bootable profile "@MyDesktop2" by MOVING @snapshots/@Desktop_2026-07-03_14-02-22_Test into it (source consumed, parent preserved) on /dev/sda2? [y/N] y -flipper-bls: wrote entry for @MyDesktop2 (kernel 7.1.0-g5f8b21274ff4, slot 92) -profile '@MyDesktop2' moved from '@snapshots/@Desktop_2026-07-03_14-02-22_Test' (writable, boot entry added) -reboot and pick '@MyDesktop2' from the boot menu to use it -(source consumed; parent_uuid preserved) -``` ---- +- The `send-profile` command writes a profile out to a file (or a folder, or straight over `ssh`). +- The `receive-profile` command reads a profile back in as a new profile. -### Advanced: back up and restore profile to a file or USB - -You can keep your profiles and snapshots backed up off the device: - -- The `send-snapshot` command writes a profile or snapshot out to a file (or a folder, or straight over `ssh`). -- The `receive-snapshot` command reads a profile or snapshot back in. - -Back up a profile to a USB stick (a read-write profile is snapshotted read-only for you first, and that restore point is kept): +Back up a profile to a USB stick: ```bash -sudo send-snapshot @Desktop /mnt/usb/ +sudo send-profile @Desktop /mnt/usb/ ``` -Restore it later, on this or another Flipper One: +Restore it later, on this or another Flipper One, as a new profile: ```bash -sudo receive-snapshot /mnt/usb/Desktop_2026-07-03_14-02-22_pack.zst +sudo receive-profile /mnt/usb/Desktop_2026-07-03_14-02-22_pack.zst @DesktopRestored ``` -The restored copy lands under `@snapshots` as read-only; turn it into a bootable profile with `create-profile`. - -For backup chains you can send only what changed since a previous backup with `-i` (against the profile's `_stock` base) or `-p PARENT` (against a specific earlier snapshot). Incremental restores need that parent to already exist on the receiving device. +The restored profile is immediately bootable — pick it from the boot menu. ## Explanation @@ -373,23 +269,15 @@ See the list of Btrfs subvolumes using `btrfs subvol list` ```bash $ sudo btrfs subvol list / -ID 256 gen 97 top level 5 path @Minimal_stock +ID 256 gen 97 top level 5 path @Minimal ID 257 gen 132 top level 5 path boot ID 258 gen 137 top level 5 path @home -ID 259 gen 115 top level 5 path @snapshots -ID 260 gen 150 top level 5 path @var-log -ID 261 gen 121 top level 5 path @var-cache -ID 262 gen 145 top level 5 path @Minimal -ID 263 gen 86 top level 5 path @Desktop_stock -ID 265 gen 93 top level 5 path @TV-Media-Box_stock -ID 266 gen 146 top level 5 path @TV-Media-Box -ID 267 gen 96 top level 5 path @Router_stock -ID 268 gen 146 top level 5 path @Router -ID 269 gen 99 top level 5 path @No-Graphics_stock -ID 270 gen 145 top level 5 path @No-Graphics -ID 271 gen 112 top level 259 path @snapshots/@Desktop_2026-07-14_10-15-16 -ID 272 gen 114 top level 259 path @snapshots/@Desktop_2026-07-14_10-16-37_Desktop-before-changes -ID 273 gen 150 top level 5 path @Desktop +ID 259 gen 150 top level 5 path @var-log +ID 260 gen 121 top level 5 path @var-cache +ID 263 gen 86 top level 5 path @Desktop +ID 265 gen 93 top level 5 path @TV-Media-Box +ID 267 gen 96 top level 5 path @Router +ID 269 gen 99 top level 5 path @No-Graphics +ID 271 gen 150 top level 5 path @MyTravelRouter ``` ::::: - diff --git a/docs/files/pics/cpu-software/flipper-os.png b/docs/files/pics/cpu-software/flipper-os.png new file mode 100644 index 00000000..07f5acb0 Binary files /dev/null and b/docs/files/pics/cpu-software/flipper-os.png differ