Zerone Laboratories / operating systems

ztOS

A phone operating system with Windows Phone 8.1's look and motion, on Arch Linux ARM and mainline Linux.

ztOS is the ztMETRO shell, its own apps, an updater and an SDK for apps, on an ordinary Arch Linux ARM system. It runs on the phones in the device list and in the QEMU emulator. Everything that moves is drawn by the GPU.

It is beta software. Since BETA-1 ztOS is a generic system image (GSI) plus a small layer per phone, the two meeting at ztOSIAL (Zerone Technologies Operating System Interface Abstraction Layer), its hardware interface layer. The S9 port runs a mainline 7.1 kernel with the phone's GPU, display, touch, Wi-Fi, 4G data, sound and sensors working. ztConflo, its image builder, is how it reaches other phones.

Installing

From nothing to ztOS, in the emulator or on a phone.

There are three ways in. Pick one, then follow its steps from the top: each step says what to type, what you'll see, and how long it takes.

Try itIn the emulator on your computer. Nothing is flashed, nothing is erased. About an hour, mostly waiting.
A listed phoneA phone in the device list. Replaces Android and erases the phone.
Another phoneA phone that runs postmarketOS on mainline Linux, built with ztConflo. For people comfortable porting.

Get the computer ready

Every way starts here. You need a Linux computer, x86-64 or ARM, with about 15 GB free and an internet connection: the build downloads Arch Linux ARM and about 2 GB of packages. It never asks for sudo; only installing the tools below does.

  1. Install the toolsOn Arch Linux (tested):
    sudo pacman -S --needed git util-linux libarchive dosfstools mtools e2fsprogs qemu-user-static qemu-user-static-binfmt qemu-system-aarch64 edk2-aarch64 qemu-hw-display-virtio-gpu-pci qemu-ui-gtk android-tools socat
    On Debian or Ubuntu (not yet tested), the same tools are: sudo apt install git uidmap libarchive-tools dosfstools mtools e2fsprogs qemu-user-static binfmt-support qemu-system-arm qemu-efi-aarch64 adb socat
  2. Give your account a range of user IDsThe build runs as you, in a user namespace. grep $USER /etc/subuid should print a line. If it prints nothing: sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER, then log out and back in.
  3. Get ztOSgit clone https://github.com/Zerone-Laboratories/ztOS.git
    cd ztOS
    For a phone whose entry says so, also git submodule update --init (the phone's kernel tree).
  4. Checkinstaller/ztos doctor should say this computer can build ztOS, and list what the emulator and phones over USB still need. Fix anything it names before going on.

Try it in the emulator

  1. Build itinstaller/ztos install --target qemu --mode build-install
    It asks for a user name, a password (for logging in and sudo), a name for the phone and your time zone, then Start?: answer yes.
  2. Wait30 to 60 minutes the first time: ARM programs run emulated. Later builds reuse what was downloaded; --fresh starts again from scratch. If the network drops, run the same command again.
  3. Start itAnswer yes to Start it now?. A phone-shaped window opens (540×1110) and ztOS starts in about a minute.
  4. Use itThe mouse is your finger: click to tap, drag to swipe, hold to hold. Escape is the back button, and the computer's keyboard types. ssh -p 2222 <user>@localhost gets a shell.
  5. Next timeinstaller/ztos emulator starts it again. --gl draws with your computer's GPU (faster; some NVIDIA laptops refuse it), and --headless runs it without a window, on VNC at 127.0.0.1:5905.

The emulator has no modem, sensors or battery, so those parts of ztOS stay off there.

Install it on a listed phone

This erases the phoneAndroid and everything in its storage are replaced. Back up first. Each phone's entry says what is never touched (on Samsung phones, the IMEI and modem calibration).
  1. Open your phone's entryFind it on devices.ztos.online and check the model number matches yours exactly: a phone sold under the same name with another chip will not boot. Read its What works table and quirks.
  2. Unlock the bootloader and install the recovery it namesUsually in Android: Settings > About phone, tap Build number seven times, then Developer options > OEM unlocking. Then flash the recovery (TWRP on Samsung phones) the way the entry says. Unlocking erases the phone once already.
  3. Follow its installation guideEach phone's page has a full guide, written by its maintainer, with every command to copy. For most phones they come down to: start the recovery, plug the phone in, run installer/ztos install --target <phone>, confirm writing the boot image, type ERASE to write the system, and restart.
  4. First startAbout a minute while ztOS grows to fill the storage, then the Welcome app shows how ztOS is used. Android apps are set up in the background the first time (Waydroid downloads its images once, about 1 GB).

Port it to another phone

ztOS is a generic system image (GSI) plus a device layer for each phone (see GSI and ztOSIAL). For a phone postmarketOS already boots on mainline Linux, ztConflo builds an image from the GSI with a device layer made for it.

  1. Build the GSIinstaller/ztos build --target gsi makes build/ztos/gsi/ztos-gsi-0.2.0-aarch64.tar.zst, with its .sha256.
  2. Get ztConflogit clone https://github.com/Zerone-Laboratories/ztconflo.git, then in it python -m ztconflo lookup <codename> says whether your phone can be built. The codename is on the phone's postmarketOS wiki page.
  3. Try it firstpython -m ztconflo build <codename> --gsi <path to the GSI> --dry-run checks the phone's kernel against what ztOS needs and shows every command, without running them.
  4. Build and flashThe same without --dry-run writes out/<codename>/; python -m ztconflo flash <codename> shows the partitions and asks before writing.
  5. See what worksOn the phone, ztos-ial status and ztos-ial test. The ztOSIAL porting guide shows how to fix what doesn't.
  6. Share itAdd it to the device list with its photo, steps and what works, so others can install it too.

If something goes wrong

What you seeWhat to do
doctor names a missing toolInstall it (the list above), then run installer/ztos doctor again.
a /etc/subuid range for …sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER, then log out and back in.
The build stops while downloadingRun the same command again: it carries on. --fresh throws the old build away first.
the phone is not in TWRP over adbStart the recovery and plug the phone in; adb devices should show it as recovery. Try another cable or USB port; some cables only charge.
Writing the system waits for the phone on 172.16.42.1The phone is on a USB network and hands your computer 172.16.42.2. If ip addr shows no such address, set that USB network connection to automatic (DHCP) in your network settings, then run the install again: it carries on where it stopped.
The phone sits in ztOS Rescueinstaller/ztos, then choose 3, Reboot the phone from ztOS Rescue.
The phone goes back to the recovery by itselfztOS didn't start, and the phone fell back safely. Run the install again from the recovery step.
The emulator window stays black or QEMU stopsLeave out --gl; with it, some graphics drivers fail with EGL_BAD_ACCESS.

Still stuck? Ask in #porting on the ztOS Mobile Discord, or open an issue with the installer's last lines.

Screenshots

Taken from the live display of a Galaxy S9.

Start: live tiles in the Windows Phone layout
Start
The alphabetical app list
App list
Settings, cellular and SIM, with signal and registration
Cellular and SIM
ZrnDevTest showing live sensor readings
Sensors, in ZrnDevTest
Settings, about: the device and ztOS version
About

The shell, and the only one installed.

Logo by

@x10michion Instagram

ztMETRO is a Wayland compositor, built on wlroots, that is also the whole phone interface: Start with its live tiles, the app list and search, the action centre, the app switcher, the lock screen and the on-screen keyboard. Its look and motion are Windows Phone 8.1's, measured frame by frame against screen recordings of real Lumias.

It renders itself with OpenGL ES: every tile, bar and app surface is a textured quad with its own matrix, which is what lets tiles tilt under a finger and whole screens swing. Text is drawn once and kept as a texture, and frames are drawn only while something moves.

Start and tiles
Pin, move and resize tiles; the turnstile when an app opens and when you come back.
Action centre
Notifications, quick actions, brightness, and a media banner.
Keyboard
On-screen, lifting the app so the text box stays in sight.
Animation speed
One setting for the whole interface, shell and apps, 75% by default.
Haptics
Strength per kind of touch, set in Settings.
Other apps
Firefox, Chromium and any Linux app run as windows inside it.

Apps

What comes installed.

AppWhat it doesWritten with
SettingsWi-Fi, cellular and SIM, haptics, quick actions, theme, developer optionsZrnMetroCore (C)
Phone, Messaging, PeopleCalls, SMS and contacts, in the same styleZrnMetroCore (C)
ZrnDevTestWhat the hardware reports: system, sensors live, the journal and kernel logZrnMetroCore (C)
WelcomeThe first-start tour: Start, getting around, your apps, making appsztOS SDK (Python)
UpdatesShows available updates and installs themztOS SDK (Python)
Firefox, Chromium, terminalOrdinary Linux apps, shown as windowsArch packages

The native apps share ZrnMetroCore, a small toolkit with the shell's own widgets, page turns, pivots and press tilt.

The SDK

Make apps in C, C++, Rust or Python.

The new SDK is zrn-sdk: one small GPU toolkit, libzrnui, under all four languages, in Metro or DotMatrix, whichever the system is set to. Apps ship as one signed .zexec file, and the store builds them from your source. It runs on a computer today and has not yet run on a phone.

zrn new "Notes" --lang c  # or cpp, rust, python
cd notes && zrn build
zrn render out.png        # see it with no phone, no display

Open the SDK wiki

The wiki at sdk.ztos.online covers every way to make an app, every UI element with real renders and code in each language, every animation running live with its real numbers (swivel, turnstile, fade, tilt), publishing to the store, and what is still missing.

The older Python SDK

The ztOS SDK builds an app into a single file: a small C launcher with the app's Python code, pages, pictures and the ztos runtime zipped behind it. Pages, lists, pivots, entries, toggles, round buttons, app bars and dialogs all come from the runtime, with the toolkit's own numbers for every motion.

ztos-sdk new "Notes"     # a new app, from the template
ztos-sdk run             # try it on the computer
ztos-sdk deploy          # build, install on the phone, open it
ztos-sdk logs -f         # what it prints, on the phone

Keeping it fast

  • Motion on the GPU. While a page turns, a list scrolls or a button leans, a GPU layer over the app shows pictures of the pages as textured quads, drawn by a small C renderer. Widgets are rasterised once, not every frame.
  • A warm runtime. ztos-zygote loads Qt for Python once and forks each app from itself, which saves about a second of CPU per launch.
  • Compiled code. Apps ship with their Python already compiled, so the phone never compiles it on start.

System services

ztOS's parts below the shell.

NameWhat it does
ztOSCoreSensorFrameworkStarts and watches every piece of hardware support and reports what fails; runs the sensor hub and the sensors
ztOSCoreNetworkingThe modem, calls, messages and mobile data, and joining Wi-Fi
ztOSCirrusAudioSound: the audio DSP and the Cirrus speaker amplifiers
zrnperfdPower: dynamic boost from the efficiency cores up, and core power-down
ztos-ialdztOSIAL: serves the phone's hardware to the rest of ztOS over D-Bus, the same on every phone
WaydroidAndroid apps, in a stripped-down Android 13 fetched and set up on first boot
ztos-updateThe updater: a daily check, a notification, and the Updates app

GSI and ztOSIAL

How ztOS is put together since BETA-1.

ztOS is built as one generic system image (GSI) for every aarch64 phone: the shell, the apps, the services and Waydroid, with no kernel, no user and nothing specific to a phone. Each phone adds a device layer: its kernel, firmware, drivers, and a manifest saying how its hardware is reached. The two meet at ztOSIAL, the Zerone Technologies Operating System Interface Abstraction Layer: a set of D-Bus interfaces (org.ztos.ial) served by ztos-iald.

Interfaces
13: device, power, performance, display, sleep, sensors, haptics, lights, modem, call audio, audio devices, acceleration and Android.
Backends
Each interface is served by a generic backend (enough on a phone with full mainline support), the generic one with parameters, a Python backend in the device layer, or a separate service.
Device layer
/vendor/ztos/manifest.toml and what it names. Porting a phone means writing this, not changing ztOS.
Kernel contract
The GSI lists the kernel options it needs; ztConflo checks a phone's kernel against it before building.
Checking a port
ztos-ial status and ztos-ial test on the phone show what works.
RepositoryWhat it holds
ztos-coreztMETRO, the apps, the SDK, Android support and the system files in the GSI
ztos-ialThe interfaces, ztos-iald, the command line and the C and Python clients; the porting guide
ztos-buildThe installer: ztos build --target gsi builds the GSI
ztos-device-samsung-starlteThe Galaxy S9's device layer, and the example for new ones
ztos-devicesztConflo's registry of phones
ztOSEverything in one tree, as before the split

Device list

Phones ztOS runs on: ported by people, or built by ztConflo.

Every phone has its own page on devices.ztos.online: what works, its specifications, and a step-by-step installation guide with every command to type. Phones are sorted by maker, and you can search them.

Community Ports

Ported, installed and checked on the phone itself, and reviewed by moderators.

Cross-Ports EXPERIMENTAL

Phones ztConflo can build ztOS for, from postmarketOS's ports on mainline Linux. Most are untried; the list updates itself every day.

ztConflo: other phones

How ztOS reaches more phones.

ztConflo takes a phone's codename and builds a flashable ztOS image for it: Arch Linux ARM with ztMETRO, on a kernel and boot setup that postmarketOS already boots. Given the GSI (--gsi), it adds a device layer generated for the phone and checks the phone's kernel against the GSI's kernel contract. It looks in the ztOS device registry first and falls back to postmarketOS for phones nobody has ported ztOS to yet. It never ports new hardware.

Eligible phones
135 today, with a mainline aarch64 kernel; 71 of them archived by postmarketOS, and flagged.
GPU check
Phones without a Mesa GPU driver still build, with a warning that ztMETRO won't start.
Registry
One TOML file per phone; a phone moves from untested to boots to tested through a hardware checklist.
Interface
A command line and a terminal UI in ztOS's own look, which installs its tools on first run.

Status and next

Where ztOS is today.

Beta ztOS 0.2.1 beta 1.1 runs daily on one Galaxy S9, as the GSI and the S9's device layer. The installer's phone path is implemented but not yet validated end to end on a fresh install, and no ztConflo image has booted on another phone yet.
  • The first phone besides the S9 booting a ztConflo build from the GSI.
  • Calls, messages and sensors in the apps through ztOSIAL, rather than the S9's own services.
  • The sound of calls, and receiving SMS.
  • Suspend on the S9, for idle battery life closer to Android's.
  • Native apps drawing with OpenGL ES the way the shell does, and a ztOS package repository for updates.

See also