docs/install-windows.md

Installing from Windows

On this page

From a rooted TB323FU to Ubuntu with GNOME on the microSD card, using one Ubuntu terminal on Windows and one script. The build runs in a WSL distribution of its own, which you remove afterwards; an Ubuntu you already use in WSL is not touched. Everything happens in that terminal; the script tells you what it is doing, asks before each step and can be run again after any failure. Installing Linux shows where this fits; Installing by hand has the individual commands.

Status: followed end to end (labels) again on 2026-11-05 from Windows 11 with no WSL distribution before it, the tb323fu distribution of step 1 and a wiped card (kernel t58, helper 0.4.6; first on 2026-10-04). The first start, Wi-Fi, SSH, switching to Android and wsl --unregister tb323fu were checked; the speakers, the sensors and both cameras on 2026-10-29. If something does not match what you see, stop and open an issue.

What you need#

  • The tablet rooted: rooting.md steps 1–3 done. That means your own EDL dump kept somewhere other than this PC, KernelSU with Shell allowed, and the OTA apps disabled.
  • A microSD card of 64 GB or more in the tablet. It will be wiped.
  • A USB-C data cable, battery above 50 %.
  • About 30 GB free on the Windows drive that holds WSL (normally C:).
  • About 1–2 hours, most of it an unattended build on the PC.

1. A WSL distribution for the installer#

In PowerShell (as administrator if WSL is not installed yet):

wsl --install Ubuntu-26.04 --name tb323fu

Restart Windows if asked. The new Ubuntu starts and asks for a user name and password (your Linux user in it; you will type the password when the script installs packages). Later you open it with wsl -d tb323fu in PowerShell. Check that it is WSL 2:

wsl -l -v          # tb323fu, VERSION 2

It holds the packages the script installs and about 30 GB of build files, and nothing of yours: when Linux runs on the tablet, you remove it in one command (step 6). Running the script in a WSL distribution you already use also works; it then keeps those packages and files.

2. Install adb on Windows#

WSL cannot see USB devices; the script uses the Windows adb.exe from Android platform-tools. If you used adb while rooting, you already have it. Otherwise, in PowerShell:

winget install Google.PlatformTools

(or unzip platform-tools somewhere; the script asks for the path of adb.exe if it does not find it). Then close all terminals, run wsl --shutdown in PowerShell, and open it again (wsl -d tb323fu), so that it sees the new program.

3. Prepare the tablet#

  1. Start the tablet in Android. (If it runs this project's Linux: Open Device Helper → Android → Restart into Android.)
  2. USB debugging: Settings → About tablet → tap the build number seven times; then Developer options → USB debugging on.
  3. Connect it to the PC. On the tablet, allow USB debugging for this computer (tick Always allow).
  4. In the KernelSU app → Superuser: allow Shell.

Check in PowerShell: adb devices lists the tablet as device.

4. Run the installer#

In the tb323fu terminal (wsl -d tb323fu, then cd):

sudo apt update && sudo apt install -y git
git clone https://github.com/joonhoekim/tb323fu-linux.git
cd tb323fu-linux
tools/install/install.sh

Keep the clone in your home directory there (as above), not under /mnt/c. Another system instead of Ubuntu: DISTRO=arch tools/install/install.sh (or fedora, nixos, steamos; which system).

To see everything the script would do without doing it: tools/install/install.sh --dry-run.

5. What the script asks#

Each step explains itself first. Steps that write to the tablet make you type a word (WRITE BOOT_B, ERASE, WRITE, FLASH BOOT_A); anything else stops without writing. Finished steps are remembered (in ~/tb323fu-install/state): if a step fails, fix what it says and run tools/install/install.sh again; it carries on where it stopped. tools/install/install.sh STEP runs one step again.

StepWhat happensWhat you doTime
hostinstalls the Ubuntu packages it needs (debootstrap, qemu-user-binfmt, gdisk, …), checks that arm64 programs run through qemu, finds adb.exeyour Ubuntu password1–10 min
tabletchecks the tablet: TB323FU, slot _a, root for Shell, the microSD card, batteryanswer the prompts on the tablet; confirm you have your EDL dump1 min
firmwarecopies the firmware Linux needs from Android's /vendor to the PC (nothing on the tablet changes)—1 min
waybackmakes sure boot_b holds your Android boot image (the way back), installs the Switch to Linux KernelSU module, saves the hash and your stock boot imagetype WRITE BOOT_B only if boot_b needs the copy1 min
downloadthe newest kernel release and the Ubuntu packages for the tablet from GitHub Releases, checked against SHA256SUMS(browser download only without a GitHub login, see above)1–3 min
bootimgpacks the release kernel into your own stock boot image (why)—seconds
sdcardbuilds a partition table on the PC and writes it to the card from Android: one partition baldur-root-sd (64 GB on a large card, else the whole card)pick the size; type ERASE1 min
rootfsbuilds Ubuntu 26.04 with GNOME into an image file on the PC (arm64 through qemu), then shrinks and packs ityour user name for the tablet; a password for it (needed for sudo, asked after the build)20–60 min
writecopies the image to the tablet and writes it into the card's partition, then reads it back and comparestype WRITE3–10 min
bootwrites the Linux boot image to boot_a (checked; on a bad write it puts Android back first) and restarts into Linuxtype FLASH BOOT_A1 min
firstbootprints what a good first start looks like and what to check——

The tablet is not needed during the rootfs build; it can stay connected.

6. First start#

The script restarts the tablet into Linux. What a good first start looks like, Wi-Fi and the clock, the checks to run and both ways back to Android are in After installing; try the way back once while you are at the desk.

At the end the script copies the files worth keeping (stock-boot.img, your stock boot image; linux-boot.img; config/) to %USERPROFILE%\tb323fu-install on Windows. Nothing needs cleaning on the tablet: the script removes its copies from Android's /data/local/tmp itself. If you no longer need the installer's distribution, remove it with everything in it, in PowerShell:

wsl --unregister tb323fu

If you ran the script in a distribution you keep, delete ~/tb323fu-install instead. The WSL disk does not shrink by itself when files are deleted; Microsoft's way to give the space back is sparse mode, still marked experimental (WSL settings). It returns only space freed after it was turned on, so turn it on first (wsl --shutdown, then wsl --manage <name> --set-sparse true), then delete; the space shows up as free space on C:, not as a smaller ext4.vhdx.

Troubleshooting#

ProblemWhat to do
adb.exe not foundInstall platform-tools (step 2), then wsl --shutdown in PowerShell and reopen it (wsl -d tb323fu). Or type the path of adb.exe when the script asks (C:\…\platform-tools\adb.exe is fine), or start it as ADB=/mnt/c/…/adb.exe tools/install/install.sh.
No tabletadb devices in PowerShell must list it. If PowerShell does not see it either, it is the cable, USB debugging, or the Windows driver — not WSL. If it runs Linux, switch it to Android first.
unauthorizedUnlock the tablet and accept the USB debugging prompt (tick Always allow). No prompt: Developer options → Revoke USB debugging authorizations, replug.
No root for adb's shellKernelSU app → Superuser → Shell → allow.
arm64 programs not registered (binfmt)sudo systemctl restart systemd-binfmt. If WSL runs without systemd: add [boot] / systemd=true to /etc/wsl.conf, wsl --shutdown, reopen. Check: cat /proc/sys/fs/binfmt_misc/qemu-aarch64 says enabled and its flags contain F.
Disk spaceThe build needs about 30 GB inside WSL. df -h ~ shows what is free.
The build stoppedUsually a network hiccup while downloading packages: run the script again, it continues in the same image. To start the root over: sudo umount ~/tb323fu-install/mnt; rm ~/tb323fu-install/root.img, then run tools/install/install.sh rootfs.
Downloads failUsually the network, or the GitHub API's limit for anonymous requests: run the step again later, or set GITHUB_TOKEN=… (any GitHub token); otherwise the script shows which files to download in the browser.
adb push fails on a file in WSLThe script retries through a folder in your Windows temp directory by itself.
Android says the card is unsupportedExpected after the sdcard step: Android cannot read the Linux partition.
Linux does not startHold volume up + volume down 10 s for Android; if nothing reacts, see Recovery.

Once Linux runs: After installing (switching, updates, removing Linux). On a Linux PC: Installing from Linux. Other distributions, your own kernel and a root on the internal storage are in Installing by hand.

View this page's Markdown on GitHub