docs/after-install.md

After installing

On this page

What to know once Linux runs on the tablet: the first start, switching between Android and Linux, updates, more systems on the card, how to remove Linux again, and where to look when something is wrong. The install itself is in Installing Linux.

First start#

The Lenovo logo, then a text summary on the panel, then the desktop. The first start takes a little longer (the root grows to fill the partition); after that the desktop is up some seconds after the kernel starts (measured times per system: Distributions). GNOME logs you in automatically.

Wi-Fi: top right → Wi-Fi → pick your network → a notification asks for the password. Until then the clock is wrong (Android keeps the real time in a place Linux cannot read); it sets itself once the network is up. The time zone comes from the PC you built on. A Wi-Fi icon with a ? means the internet check failed; it usually clears within a minute.

In GNOME's Terminal:

tb323fu-check                           # each part PASS / WARN / FAIL, with a hint for each failure
cat /etc/tb323fu/android-boot.sha256    # the hash the script printed in the wayback step

tb323fu-check comes with platform 0.4.5 or newer; on older installs use systemctl --failed. If something fails and the hint does not help, open an issue and paste tb323fu-check --markdown into it: it holds no device IDs, addresses or network names. Look it over before posting all the same.

Then try the way back to Android and back to Linux once, while you are at the desk (next section).

In mainline Linux the power button alone does not force the tablet off; hold power + volume down.

Switching between Android and Linux#

The tablet boots whatever is in boot_a. Android's boot image is kept in boot_b; switching copies one or the other into boot_a and restarts. Every way below checks hashes before and after writing and stops without restarting on a mismatch. How it works: android/README.md.

DirectionHowChecked
Linux → AndroidOpen Device Helper → Android → Restart into Android, or the Android tile in the quick settings (helper); in a terminal back-to-android <hash> as rootyes
Linux → Android, emergencyhold volume up + volume down for 10 s; works with a frozen desktop as long as the kernel runs; letting go earlier cancelsyes (Debian; Ubuntu through the guided installer)
Android → LinuxKernelSU app → Modules → Switch to Linux → Action. Writes the last Linux image that ran (or the staged one) to boot_a, verifies it, restarts; on a bad write it copies Android back from boot_b firstyes

A switch takes under a minute (about 40 s measured on the author's tablet). If the Linux image that ran last is a kernel still on trial (below) or one that failed, the Switch to Linux module writes the last confirmed kernel instead and says so.

From a PC
DirectionHowChecked
from a PC, Linux runningtools/flash-boot.sh over SSH (USB network: tablet 192.168.7.2, PC 192.168.7.1)yes
from a PC, through Androidtools/cycle.sh: back to Android if needed, write boot_a over adb, reboot, wait for SSHyes, many times

If neither way works: Recovery (EDL with your own backup from rooting).

Updates#

Kernel. Open Device Helper → About → Kernel Updates, or tb323fu-ctl kernel update. The helper checks the project's GitHub Releases once a day (it only checks; downloading and installing are your choice) and packs the new kernel into your own stock boot image from boot_b. The channel is Stable by default: it offers the newest stable release (the latest release); Testing also offers testing releases (marked "Pre-release" on GitHub), which carry new features before they become stable. tb323fu-ctl kernel install kernel-tNN installs one release by name, whatever the channel. A kernel from a file you built: Install Kernel from File… (custom-kernel.md).

Trial and Keep. A new kernel is first on trial. Before writing it, the helper saves the running one as linux-good.img. On the stable channel the kernel is confirmed by itself once the system has been up for 90 s. On the Testing channel, for testing releases and for kernels from a file, only Keep (in the app, or tb323fu-ctl kernel keep) confirms it. A kernel that is not confirmed by its third start is replaced by linux-good.img and the tablet restarts. A kernel that dies before the initramfs runs cannot be caught this way; then the way back is EDL (recovery). Details: helper.md → Kernel updates.

Helper. Releases tagged helper-vX.Y.Z show in About → Helper Updates and in tb323fu-ctl helper. Who installs them depends on who installed the helper (helper.md → Helper updates):

System (guided script)How the helper was installedUpdating it
Ubuntuthe release's .deb packages, owned by aptthe helper does not replace itself; it shows the new version and the command: install the new release's .deb files (sudo apt install ./tb323fu-helper_*.deb …)
Arch Linux ARMthe release's .deb files, unpacked without a package managernobody owns the files, which helper.md counts as self: the helper updates itself
NixOSNix packages from this repositorynix flake update tb323fu-linux && sudo nixos-rebuild switch

On other systems Open Device Helper shows the command when a package manager owns the helper.

The distribution updates the usual way (apt, pacman, nixos-rebuild, …). The kernel and its modules come with the boot image, not from the distribution's packages.

Optional: the project's Mesa for Vulkan and OpenCL#

After the install, every application uses the distribution's Mesa, and nothing changes that by itself. The project also offers its own Mesa build for this GPU — Turnip (Vulkan) and rusticl (OpenCL) — which is much faster for GPU compute (OpenCL programs, Vulkan compute; Geekbench 7 OpenCL about 2.7 times the score with Debian's Mesa, see Performance → GPU). OpenGL and the desktop itself keep using the distribution's Mesa either way. It is optional and comes as a binary release only.

The scores were measured on one tablet (the author's) and are for orientation only; yours may differ.

  • Try it: Open Device Helper → Performance → Graphics Drivers → Check Now, then Download and Install…, and switch on Use the Project's Mesa; or tb323fu-ctl mesa update and tb323fu-ctl mesa on. It is used by applications started after the next login. The distribution's Mesa stays installed next to it.
  • On trial: a version you switch on has to be confirmed with Keep (the banner on the Performance page, or tb323fu-ctl mesa keep). Without Keep, the third start switches back to the distribution's Mesa by itself.
  • Going back: switch it off (tb323fu-ctl mesa off, used from the next login), or Go Back… to the previously installed version.
  • One program only: tb323fu-mesa run COMMAND runs one program with the project's Mesa and tb323fu-mesa distro COMMAND with the distribution's, whatever the setting — handy for comparing, or when one application misbehaves.

Details, and using a release without the helper: helper.md → Graphics drivers. Measured results: Performance → GPU.

Swap (zram)#

The root images have no swap partition or file. The platform package sets up compressed swap in RAM at every start instead (tb323fu-zram.service): a zram device as large as the RAM, zstd, with vm.swappiness=100 and vm.page-cluster=0. Memory that programs leave idle is compressed (about 4.5 times in our test), so a working set larger than the RAM keeps running instead of a program being closed by the out-of-memory killer. In our test, 15–17 GB on the 15 GB tablet were killed every time without swap and kept running with zram, with no measurable difference in build time or latency.

tb323fu-ctl memory zram          # active?, size, stored and compressed, swappiness
tb323fu-ctl memory zram off      # or on; also Open Device Helper → Performance → Compressed Swap
tb323fu-ctl memory zram size 8192   # MiB, or "size ram"

Without the helper, edit /etc/tb323fu/zram.conf (ENABLED=0|1, SIZE=ram|MiB, ALGORITHM=zstd) and run systemctl restart tb323fu-zram. If the system already has a zram swap (Fedora's zram-generator), the service leaves it alone. A swap file next to it is fine: zram is used first (priority 100). On NixOS it is services.tb323fu.zram.enable (default on) and services.tb323fu.zram.memoryPercent.

Other sysctls suggested for zram (vm.watermark_boost_factor=0, vm.watermark_scale_factor=125, vm.vfs_cache_pressure=50, vm.dirty_background_ratio=5, vm.dirty_ratio=10) are optional tuning: they showed no gain in our test and are not set.

Screen rotation#

The rotation sensor works on every system that has the sensor support (Distributions); whether the screen follows it is the desktop's choice:

  • GNOME turns the screen only while no keyboard or mouse is connected, and then also hides the rotation lock tile. To keep rotating with a keyboard or mouse: userspace/desktop/gnome.
  • KDE Plasma: System Settings → Display & Monitor → Orientation Automatic; clear "Only when in tablet mode" to keep rotating with a keyboard. It needs Qt Sensors (qt6-sensors or similar). Not tried on this tablet.
  • Window managers without automatic rotation (sway, niri, …): monitor-sensor shows the orientation that iio-sensor-proxy reports, for a script of your own.

Another system on the card#

Each system lives in its own partition, and all of them share the one kernel in boot_a. The guided script puts one system on the card; more are added by hand: a partition named tb323fu-<name> in the card's free space and a root built into it (Installing by hand, steps 4–5). Which systems have been tried and how each one is built: Distributions. Picking one: Open Device Helper → Systems, or tb323fu-ctl boot (Installing by hand → Multiboot).

Removing Linux#

Linux never replaces Android: Android's data, apps and system stay as they were (unless you moved the Linux root to the internal storage, last row). Going back to the stock tablet, in this order:

StepHowStatus
1. Android back in boot_aany Linux → Android way above, or EDL → LTBox Flash Partitions → boot_a ← your Android boot image (recovery)verified
2. Remove the Switch to Linux moduleKernelSU app → Modules → Switch to Linux → uninstall, restart. Its staged image stays in /data/adb/tb323fu: adb shell su -c 'rm -rf /data/adb/tb323fu'untested
3. The cardAndroid: Settings → Storage → the card → format; or delete the partition (sgdisk -d) on a PCuntested
4. boot_bnothing to do: it is never booted. A stock copy is also in your dump and in the firmware package (same version)—
5. The root (KernelSU, efisp)Recovery → Undoing the rootfrom LTBox's source
6. The OTA appsturned off while rooting; turn them on again: adb shell pm enable --user 0 com.lenovo.ota, the same for com.tblenovo.center. Before a firmware update, see Updating Android firmwareuntested
a Linux root on the internal storagewrite the saved table back (sgdisk -l lun0-gpt.bak $D) and factory-reset Android again so userdata is formatted at full size (Android: Settings → Reset, or LTBox Flash Firmware → Wipe Data)untested

Never restore a partition table backup taken before a firmware update over a newer layout, and never restore another tablet's table: the backup contains your device's unique GUIDs. A complete factory state (which wipes the tablet): Recovery → Full reinstall.

Something is wrong#

SymptomWhere to look
the install script stops or failsInstalling from Windows → Troubleshooting (most entries apply on every PC)
Linux does not start, or hangs before the desktophold volume up + volume down 10 s for Android; then Recovery → Linux does not boot
Android does not start, red "Your device is corrupt" screen, LTBox stopped half-wayRecovery (table at the top)
black screen, no reaction to buttons, no USB networkpossibly a crash dump state: Recovery → Getting into EDL
no USB network or serial shell after boot, problems of one distributionDistributions → Known problems
a feature does not work (display modes, USB devices, GPS, …)Hardware status and its Known issues
a kernel update did not come upit goes back by itself after the third start; helper.md → Kernel updates

Anything else: open an issue on GitHub with what you did and what you saw.

View this page's Markdown on GitHub