Technical Manual

1.1 · What Phonestra is

Phonestra brings the apps of an Android phone to a Linux PC, each in its own window, over Wi-Fi and without installing anything on the phone. SPECIFICATION.md says what it does; this manual explains how.

Each app window is a virtual display on the phone, as large as the window; the drawer, the main window, also shows the phone's real screen. Video, audio, touches, keys and clipboard go through a component written from scratch, copied to the phone at every connection and deleted at the end.

After reading this manual you should know where to work in every file, how to build the program and the phone component, build the AppImage, run the tests, and add a message or a channel without breaking the rest.

The manual assumes you know Rust and a little Java. Android and ADB concepts are explained where they are needed; the ch. 19 “Glossary” sums them up. The reason behind every choice is in the notes/ folder: here you will find the right reference when it matters (for example, “prove §49” is section 49 of notes/connection-tests.md).

1.2 · Basic concepts

A few concepts recur throughout the manual. This table introduces each of them in one line, with the chapter that covers it in depth.

1.3 · Subsystems at a glance

The code is split into cohesive parts. This is the map that the manual explores chapter by chapter; the line counts of every file are in ch. 17 “Appendix B — File map”.

src/bin/phonestra.rs, src/collegamento.rs

main, the life of the connection, the 3-second round, shutdown, data on the PC (ch. 3 “Startup and life cycle”).

src/adb/, src/rete.rs

The ADB client: messages, TLS, channels, shell,v2, sync:, pairing with the code, mDNS discovery (ch. 4 “The ADB client”).

android/helper/src/phonestra/, src/componente.rs

The component: service, channels, command channel, heartbeat, guardians, self-test, and its PC side (ch. 5 “The on-phone component”).

src/video_nostro/, SessioneVideo.java, Codifica.java

Virtual displays, mirror, H.264 encoder, resizing, app events (ch. 6 “Video”).

Pannello.java

The physical screen turned off during use from the PC, calls, drops (ch. 7 “The phone's panel”).

src/audio_nostro.rs, CanaleAudio.java

Loopback capture, AAC, playback and recording (ch. 8 “Audio”).

src/input_nostro.rs, src/appunti.rs, Input.java, Appunti.java

Touches, keys, text and clipboard in both directions (ch. 9 “Input and clipboard”).

src/cassetto.rs, src/finestra.rs, src/prepara.rs, src/procedura.rs, src/avvisi.rs

Drawer, app windows, preferences, first connection, notifications (ch. 10 “The user interface”).

src/azioni.rs, src/ricevi.rs

Installing apps, sending and receiving files (ch. 11 “Apps and files”).

src/bin/prova.rs, tests/

Tests on the PC and on the phone (ch. 12 “Testing and diagnostics”).

packaging/, android/helper/build.sh

The compiled component, the AppImage, releases (ch. 13 “Build and release”).

1.4 · The repository

The nic-fio/PHONESTRA repository is the only complete copy of the project: code, compiled component, documents, mockups and measurements.

PHONESTRA/
├── Cargo.toml  # the phonestra package: one library and two executables
├── Cargo.lock  # the exact versions of the Rust crates
├── Makefile  # make, make test, make clippy, make docs, make docs-check, make dist, make helper, make clean
├── src/  # the PC program
│   ├── adb/  # the ADB client
│   ├── video_nostro/  # PC side of the component's video
│   └── bin/  # phonestra.rs (the program) and prova.rs (phonestra-prova)
├── android/
│   ├── helper/src/phonestra/  # the phone component, in Java
│   ├── helper/stub/  # fake Android classes, for the compiler only
│   ├── helper/build.sh  # rebuilds the jar (make helper)
│   ├── phonestra-helper.jar  # the compiled component, embedded in the executable
│   └── README.md  # what runs on the phone and how it is built
├── data/instructions.toml  # per-brand instructions for the cable procedure
├── data/en/  # English translations of the interface, one table per module
├── vendor/rusb/  # rusb without the built-in libusb (dynamic linking, vendor/README.md)
├── packaging/  # container, scripts and AppRun of the AppImage, third-party licenses
├── docs/  # the two manuals and their sources (docs/sources/), index.html, README.md
├── notes/  # decisions, studies, measurements, issue log
├── tests/  # integration tests (tests/manual.rs)
├── tools/  # setup-dev.sh (what a fresh clone needs), backup.sh (the whole project as a git bundle)
├── logos/  # the Phonestra logo: icons/, icons-with-text/
├── mockup/  # design proposals, icons and the sources of the interface canvas
├── site/  # the website phonestra.nicfio.it: landing page, publish.sh
├── experiments/  # small test scripts outside the program
├── .github/workflows/ci.yml  # CI at every push: make all, make test, make docs-check
├── README.md  # the project in brief
├── CLAUDE.md  # working rules for Claude Code
├── SPECIFICATION.md  # what Phonestra does; the code's “§” references point here
├── NOTICE.md  # copyright and third-party components with their licenses
├── LICENSE.md  # Phonestra Freeware Licence, from the version after 1.0.0-rc.8
└── LICENSE-1.0.0-rc.8-and-earlier.md  # free personal use, up to 1.0.0-rc.8

1.5 · The project in numbers

How big Phonestra is, part by part. The lines are counted from the sources every time the manual is generated.

The numbers in this table and in ch. 17 “Appendix B — File map” are not written by hand, and cargo test fails if the published manual no longer matches the sources (12.5 “The manuals and their checks”).

2.1 · Architectural principles

Phonestra grew out of a few rules, written before the code and followed in every piece. They explain choices that would otherwise look odd, such as an ADB client written from scratch or a guardian for every changed setting.

2.2 · The two sides and the layers

Phonestra has two sides: the program on the PC, in Rust, and the component on the phone, in Java. They talk to each other only through ADB, over a single encrypted Wi-Fi connection.

On the PC each layer calls only the ones below it: the interface does not talk to ADB, and the ADB client knows nothing about video or audio. On the phone there is a single process per connection, the service, which serves all windows, the drawer's screen, audio and clipboard. The guardian is a separate shell process that stays alive even when the service dies; the dashed line is the pipe through which the service passes it the restore actions.

2.3 · Threads and tasks

Three worlds run together in the Phonestra process: the GTK thread, the tokio runtime and GStreamer. Each has its own job, and they talk to each other only through channels.

3.1 · Program startup

The program starts from main, in src/bin/phonestra.rs: it initializes GStreamer, creates the GTK application and hands the configured phone over to a Collegamento, which lives in a tokio task of its own.

A second launch does not open a second connection: adw::Application is unique per session and connect_activate brings the drawer back to the foreground (reopening it if it was closed). With a package name as an argument (phonestra com.android.chrome) that app opens right away too, but only on the first launch: the instance already running does not receive the argument.

Ctrl+C and SIGTERM close the windows just as the user would, so the phone is restored. When the drawer asks to switch phones (3.5 “Multiple phones”), main relaunches the program at the end: $APPIMAGE if set, otherwise the current executable.

3.2 · Life of a connection

Collegamento::mantieni is the heart of the program. It runs in a tokio task as long as Phonestra stays open and starts over at every drop.

1. Finds the phone: first the last address that worked, then the mDNS search for the _adb-tls-connect._tcp service with the saved serial number (rete::indirizzo_attivo). The port changes every time Wireless debugging is turned on, so it must always be read again.
2. Opens the connection: Adb::wifi (TCP, STLS, TLS with Phonestra's certificate), with a 30 s timeout.
3. Reads and saves the user's values (screen timeout and media volume), also in telefoni.toml. They are read only once for all reconnections; at every reconnection Phonestra checks whether the user has changed the screen timeout in the meantime.
4. Reads the screen's density and shape (wm density; wm size, first the “Override” values chosen by the user, then the “Physical” ones): the density is needed by the virtual displays, the aspect ratio by the column of portrait-only apps.
5. Starts the connection guardian: a shell exec: that raises screen timeout and volume to the maximum and restores them when the channel closes (5.6 “The two guardians”).
6. Publishes the Adb (watch) and the Collegato state: drawer and windows restart on their own.
7. Starts the component in a task (gira_componente): service on the phone, then Condiviso published for windows and drawer, then audio (after the mirror and 5 s, 8.4 “The startup order”).
8. Listens to the clipboard of the phone (appunti::ascolta).
9. 3-second round as long as the connection holds (next section).
10. Shutdown when the user closes Phonestra (3.4 “Shutdown”).

The state is published as Stato::{Cerco, Collegato, Bloccato, Perso, Chiuso}. Between one attempt and the next the wait grows from 2 to 10 s; “Reconnect now” (Riconnetti ora, riconnetti_ora) interrupts it.

3.3 · The 3-second round

A single exec: every 3 s fetches lock state, calls and notifications, and also serves as a check that the phone is responding: if it does not respond within 5 s, the connection is considered dropped. Battery and network and, with the phone “in hand”, lastUserActivityTime are separate commands, with a 5 s timeout each: if they fail, the connection does not drop.

Protected screens do not go through here: the component reports them, session by session (6.6 “App events”).

3.4 · Shutdown

When the user closes Phonestra, usa leaves the round and restores the phone to how it was, one step at a time, with a timeout for each.

1. Music or video that is playing is paused (cmd media_session dispatch pause, at most 3 s): otherwise, once the capture is removed, it would resume from the phone's speaker.
2. The Adb is withdrawn; the windows close their sessions and remove their apps from recents (waiting up to 5 s).
3. The component receives FINE and shuts down (at most 12 s); its guardian turns the panel back on.
4. The connection guardian is closed, and it restores volume and screen timeout.
5. For 3 s Phonestra checks that the screen timeout is no longer Phonestra's; if the guardian has not restored it, Phonestra restores it directly. If even that fails, it stays recorded in telefoni.toml and is restored at the next connection.

3.5 · Multiple phones

Phonestra uses one phone at a time (the option of several phones active together was discarded). The other configured phones appear in the sidebar as “not active” (non attivo); to switch to one of them the program closes and restarts.

1. Clicking an inactive phone asks for confirmation if apps are open.
2. Telefoni::metti_primo moves it to the top of telefoni.toml: it is the one opened at startup.
3. The drawer sets cassetto::RIAVVIA and closes all windows, like a normal shutdown: the previous phone is restored.
4. main relaunches the program ($APPIMAGE or the current executable), which connects to the new phone.

Forget this phone… (Dimentica questo telefono…) does the same restart if other phones remain; if none are left, Phonestra closes, and at the next start “Add a phone” (Aggiungi un telefono) opens.

3.6 · Configuration and data on the PC

Phonestra keeps its data in two folders on the PC: the configuration in ~/.config/Phonestra, things that can be recreated in ~/.cache/Phonestra. telefoni.toml and preferenze.toml are read and written in configurazione.rs (Telefoni, Preferenze).

Deleting ~/.config/Phonestra brings Phonestra back to its initial state. The configuration folder follows $XDG_CONFIG_HOME; screenshots, recordings and received files go to the XDG user folders (Pictures, Videos, Downloads).

4.1 · Why our own client

Phonestra speaks the ADB protocol on its own, in src/adb/: no adb server, no programs to install. All channels (commands, audio, the video of every window, shell) travel over a single encrypted TCP connection.

The adb_client library reads all channels from the same connection without dispatching the messages: it handles one command at a time, not video, audio and commands together. The client in src/adb/ has a reader task that dispatches each message to the right channel by local ID, and every channel honors ADB's flow control.

adb_client remains for short commands outside the actual connection: the USB cable (telefono.rs) in the fallback procedure and in phonestra-prova prepara, and the first Wi-Fi connection of “Add a phone” (Aggiungi un telefono), which after pairing reads model and version and removes the expiry from the authorization (telefono::Collegamento::wifi, 10.5 “The first connection”).

4.2 · ADB messages

ADB is made of a few messages, all with the same shape: a 24-byte little-endian header (command, arg0, arg1, data length, byte sum, command xor 0xffffffff) followed by the data (messaggio.rs).

4.3 · Wi-Fi connection and TLS

On Wireless debugging the connection starts in clear and switches to TLS right away. Adb::wifi opens it in four steps; the phone recognizes the PC by its authorized public key.

1. TCP to the address found via mDNS (5 s timeout, TCP_NODELAY).
2. CNXN in clear: the phone reads our features and the max_payload from here, not from the CNXN after TLS.
3. The phone replies STLS; we reply STLS and TLS starts (tls.rs). The client certificate is self-signed with Phonestra's RSA key (~/.config/Phonestra/adbkey): the phone recognizes the PC by the authorized public key. The phone's certificate is not checked against an authority (it is self-signed): pairing guarantees the identity.
4. After TLS comes the phone's CNXN: its arg1 is the minimum of the two max_payload values, and its text contains the phone's features.

4.4 · Channels and flow control

All channels of a connection share a single underlying connection. Each channel has its own local ID; the reader dispatches, writers wait their turn.

An Adb is cloned and passed around everywhere. One task reads from the socket and dispatches (leggi_sempre); writes go directly to the socket, one at a time under a Mutex (Adb::invia). A second task, the “posta” (mailbox), sends only the acknowledgments that cannot wait for the writers (the OKAY messages acknowledging reads).

Adb::apri(servizio) returns a Canale with scrivi, leggi (cancelable), leggi_esatti, leggi_tutto and chiudi; Canale::chiusore() returns an object that closes the channel from another task. Adb::esegui is the shortcut for a short command (the exec: service) that returns the output.

Without delayed ack each channel has only one WRTE in flight: the next one leaves after the OKAY. The transport parameters are in Trasporto:

The details of delayed ack (balance, 4-byte OKAY, adbd's behavior) are in notes/adb.md and in the pure parts of flusso.rs, tested by adb/prove.rs against a fake in-memory adbd.

4.5 · The shell,v2 service

shell.rs starts a process without a terminal, with input, output, errors and exit code kept separate. Packets id u8 · lunghezza u32 LE · dati travel on the channel.

This is how the Phonestra service starts: the output carries the ready line without mixing with the logs, the input carries the secret, the exit code tells why the service ended, and if the channel drops adbd sends SIGHUP to the process. For short commands Adb::esegui is enough (the exec: service).

4.6 · Copying files: sync:

sync.rs implements the sync: protocol in both directions.

4.7 · Pairing with the code

abbina.rs reimplements Android 11+'s adb pair from the Android and BoringSSL sources: the phone's “Pair device with pairing code” (Associa dispositivo con codice di associazione) screen shows 6 digits, and the user types them into Phonestra.

1. TLS directly on the pairing port, with Phonestra's certificate.
2. Password = the 6 digits + 64 bytes exported from TLS (label adb-label\0): nobody can get in the middle.
3. SPAKE2 over Ed25519 (curve25519-dalek), with Phonestra in the “alice” role.
4. From the shared key, with HKDF-SHA256, an AES-128-GCM key (ring).
5. Encrypted exchange of the PeerInfo: we send Phonestra's ADB public key, the phone sends its ID.

From then on the phone accepts Phonestra's key in Wi-Fi connections, as after an “Always allow” (Consenti sempre) over the cable.

4.8 · Network discovery: mDNS

rete.rs builds and parses DNS packets by hand: a PTR query for _adb-tls-connect._tcp.local (connection) or _adb-tls-pairing._tcp.local (the code screen) with the QU bit, i.e. reply sent directly to our socket. It is the method that found the phone when the discovery of adb saw nothing.

5.1 · What the component is

Everything Phonestra does on the phone goes through a Java service written from scratch, started like the ADB shell and deleted at the end. This chapter describes its infrastructure; the following chapters describe the pieces: video, panel, audio, input.

android/phonestra-helper.jar contains a classes.dex. The PC embeds it (app::AIUTO, include_bytes!), copies it to /data/local/tmp and starts it with app_process: it runs with the shell's uid (2000) and its permissions (capturing the screen and audio, injecting events, reading the clipboard). It is not an app, it is not installed, it does not appear in the settings.

The same jar has two modes of use, chosen by the first argument of phonestra.Aiuto: the service, the long-running process, one per connection, which handles audio, video, input, clipboard and panel; and the short helper commands, which print and exit. For each short command the PC copies the jar under a name of its own (phonestra-aiuto.jar.<8 cifre esadecimali>, because several requests may arrive together), runs it and deletes it (app.rs).

Java only where Android requires it: the APIs needed (MediaCodec, VirtualDisplay, AudioPolicy, InputManager) exist only in Java. Audio and video encoding is done by the phone's encoders anyway.

5.2 · Starting the service

The PC starts the service on a shell,v2 channel: it copies the jar, launches it with app_process, passes it the secret on the input and waits for the ready line. Then it opens the command channel and receives the CIAO.

The ready line is phonestra-servizio pronto protocollo=1 socket=phonestra_<32 hex> pid=<pid>; if startup fails, phonestra-servizio errore <causa> and code 1. The PC waits 20 s for the ready line and 10 s for the CIAO; if the service does not start, the PC deletes the jar itself. exec makes the service take the place of sh, so adbd's SIGHUP reaches it directly; --nice-name makes it appear in ps as phonestra-servizio.

5.3 · Channels and preamble

Each channel is a localabstract:phonestra_<32 hex> opened by the PC. The first bytes are the preamble: segreto (16 byte) · lunghezza del tipo u8 · tipo ASCII. The service reads it with a 3 s timeout and chooses the handler from the part of the type before the colon (Servizio.TIPI).

Wrong secret, uid other than 2000 or unknown type: the socket is closed without a reply.

5.4 · The command channel

The command channel carries all the short messages between PC and service, in both directions: requests with a reply, spontaneous events, the heartbeat.

Messages with an 8-byte big-endian header, tipo u8 · bandiere u8 · id u16 · lunghezza u32, and the content (16 MB at most: beyond that, the stream is corrupted and the channel is closed). id ties the reply to the request (0 = spontaneous message); the 0x01 flag marks it as a reply. The format is the same in Protocollo.java and componente.rs, checked by a test with the same bytes.

A type the service does not know receives ERRORE: the PC understands that the jar is old. PROTOCOLLO (1 today) changes only if an existing message changes meaning.

5.5 · Heartbeat and exit codes

Any message counts as a sign of life. After 5 s of silence each side considers the other gone: the PC closes the command channel (ricevi returns None; it checks every 200 ms), the service exits. This is needed because adbd on Wireless debugging does not notice by itself that a PC is gone (Wi-Fi lost, PC off).

The service exits with System.exit and, after 2 s, Runtime.halt if something hangs. Restoring the phone is the guardian's job, which is there both at an orderly end and at a sudden one. The service restores by itself only what it can restore right away: the audio policy (the audio-fine shutdown hook), the panel when it turns it back on, and min_refresh_rate as soon as the panel is off; in those cases it also removes the corresponding action from the guardian.

5.6 · The two guardians

Phonestra changes a few things on the phone and must restore them even when something goes wrong. This is done by two shell processes, each tied to the life of something else:

The screen timeout is set to the maximum (SPEGNIMENTO_LUNGO, i.e. never) while Phonestra is open: with the phone asleep, apps on virtual displays receive no input, and taps from the PC do not count as phone activity (with 30 minutes it fell asleep during use, prove §55). The volume is set to the maximum because with the volume at 0 the Facebook app does not start the audio of reels; audio comes out only from the PC anyway.

Both values are also saved in telefoni.toml: if Phonestra crashes without restoring them, the next connection restores the saved ones. The screen timeout is read from the phone at startup and restored at the end only if it is still Phonestra's value: if the user changes it during the connection, the user's value stays (prove §56). A value under 5 s is considered invalid; 30 minutes (SPEGNIMENTO_LUNGO_VECCHIO, the value of releases up to rc.3) is treated as a leftover of a crashed Phonestra.

The service guardian receives the whole list of actions at every change, between a #inizio line and a #fine line; a half list does not replace the previous one. When the service dies it runs them in ascending order (for equal order, the last added first), one per line with sh -c (one that fails does not stop the others), then deletes the service's jar and forgotten copies older than one minute, and terminates.

Virtual displays need no action: Android closes them when the process dies. Apps are not removed from recents on a drop, on purpose: when the connection comes back they return to their window with their state. Android removes the audio policy (8.5 “Who removes the capture”).

5.7 · Context, hidden APIs and self-test

Many of the APIs needed are hidden (IDisplayManager, IWindowManager, InputManagerGlobal, IClipboard, AudioPolicy). In app_process the hidden API policy is off: they are called via reflection.

5.8 · Service security

The service runs with the shell's permissions: nobody else must be able to control it, and at the end nothing must be left on the phone.

• Abstract socket with a random 128-bit name; every channel must come from uid 2000 (getPeerCredentials) and start with the secret (constant-time comparison). No TCP port open on the phone.
• The secret is passed on the process input, not on the command line: /proc/<pid>/cmdline is readable by other processes with the same uid.
• No generic command: the PC cannot make the service run arbitrary shell commands. The guardian's actions are decided by the service; test commands accept only packages and actions made of letters, digits, dots and underscores.
• Nothing is left: jar deleted at startup and by the guardian, service that exits after 5 s without a PC, guardian that terminates after restoring.

5.9 · PC side: Componente and Condiviso

Componente (in componente.rs) is a started service: avvia, apri_canale, manda, richiesta, ricevi, chiudi. In Phonestra it is always used through Condiviso, which keeps it in a task (smista) and can be cloned: one service per connection, many windows. When the last copy of Condiviso goes away, the service is closed.

Collegamento::gira_componente restarts the service if it dies while the phone is still connected, after 2 s. After CADUTE_MASSIME (3) failed starts or drops it stops trying and publishes the reason (Collegamento::guasto): drawer and windows show “Phonestra won't start on the phone” (Phonestra non parte sul telefono) with “Reconnect now” (Riconnetti ora).

6.1 · Sessions: virtual display and mirror

Every app window is a virtual display on the phone, as large as the window, with the app launched on it. The phone screen drawn in the drawer is instead the mirror of the main screen. The phone encodes in H.264 in hardware, the PC decodes with GStreamer.

On the PC the size in pixels comes from finestra::pixel: the window size in points (1 PC point = 1 phone dp) times the phone's density, within 2560 per side and in multiples of 8. The display has the same density as the phone, because some apps (Facebook) draw certain elements with the density of the real screen, and with different densities they would come out huge. For portrait-only apps in a wide window the display is a column shaped like the phone (finestra::misura).

6.2 · Video messages

Video messages sit in the 0x40–0x4f range of the command channel, with a content made of chiave=valore lines. Requests are executed in order on a video thread of the service: the command channel (heartbeat, input) never waits for video.

The PC waits for the reply only for APRI and CHIUDI; the other commands do not wait for it and an error ends up in the log. informazioni=<pacchetto> opens the “App info” (Informazioni sull'app) (App info) page of Settings instead of the app. The default codec is h264; the component also accepts h265, used only by the tests.

6.3 · The video:<id> channel

Each session has its own channel, video:<id>, which carries the encoder's packets from the phone to the PC.

The PC opens it right after VIDEO_APRI (within 10 s). The encoder starts when the channel is open, so the first packet is the size, then the parameters, then the first keyframe, and nothing is lost. The PC does not write to it; if it closes it, the session closes (without removing the app from recents). Each packet has a 12-byte big-endian header:

On the PC side video_nostro::flusso::leggi_pacchetto reads them in a dedicated task: a read interrupted halfway inside a select! would lose bytes. The phone's reader thread writes each whole packet with a single write.

6.4 · Encoder and keyframe

Codifica.java takes the first hardware encoder (not an alias) for the type, with the measured values (misure §43): 8 Mbit/s, 60 frames per second declared, keyframe every 10 s, repeat after 100 ms, real-time priority, limited range, plus prepend-sps-pps-to-idr-frames so that every keyframe carries the parameters in front; max-fps-to-encoder only with the test switch max_fps.

If configure rejects the format, it retries in this order: hardware without prepend-sps-pps-to-idr-frames, then Android's default encoder with and without it.

The keyframe is needed when a window restarts or a recording begins (ricomincia_video → VIDEO_CHIAVE). It is requested with REQUEST_SYNC_FRAME, without recreating anything: about 0.1 s instead of scrcpy's 1–2 s restarts.

6.5 · Resizing

When the window changes size, the virtual display follows it: it is resized if that is enough, recreated if the scale changes too much.

1. The window changes size. A function tied to GTK's redraw sends the new size to the session on every change, without waiting.
2. The PC decides. During a recording the size does not change (8.6 “Recording”); for the mirror nothing is done. If, with the 2560-pixel cap, the right scale drifts more than 15% from that of the display, resizing the display is not enough: the session ends with FineSessione::Ricrea and is recreated after 300 ms, once the window has stopped changing size. Otherwise VIDEO_RIDIMENSIONA.
3. The phone resizes. One size = one encoder. If the aligned size does not change, nothing happens. If it changes: the new encoder is prepared, the size is sent to the PC, VirtualDisplay.resize + setSurface, then the old one is closed; its packets still in flight are discarded.

An input event computed on the old size is discarded by the phone (9.2 “Injection”).

6.6 · App events

EventiApp.java registers a TaskStackListener as long as there is at least one session. Each event schedules a check 150 ms later (events arrive in bursts); in addition, a check every 3 s, because a protected window can appear without task events.

The protected screen is recognized without dumpsys (Protetta.java): captureDisplay shrunk to 5 % and containsSecureLayers(), with a 2 s timeout. Phonestra does not bypass protections: it shows a message.

6.7 · PC side: from session to window

On the PC a session is a SessioneNostra: the video channel, the commands and the events. finestra::vista connects it to a GStreamer pipeline that draws in the window.

let SessioneNostra { display, video: mut flusso, mut comandi, mut eventi, .. } =
    SessioneNostra::avvia(&servizio, &Opzioni { display: (l, a, dpi), ..Opzioni::default() }).await?;
comandi.avvia_app("com.android.chrome").await?;
while let Ok(p) = leggi_pacchetto(&mut flusso).await { /* Pacchetto::Dimensione or Pacchetto::Dati */ }
comandi.ridimensiona(l, a).await?;
comandi.ricomincia_video().await?;
while let Some(e) = eventi.recv().await { /* Evento::Orientamento, Protetta, Spostata, Rimosso, Fine */ }
comandi.chiudi(true).await?;   // true = remove from recents (the user closed the window)

finestra::vista holds the pipeline and redoes the session when needed: connection dropped, component restarted, display to be recreated, orientation changed (FineSessione::{Chiusa, Ricrea, Caduta}). The codec parameters (SPS/PPS) must be merged with the following frame before the appsrc.

7.1 · Turning the panel off

While apps are used from the PC the phone's screen turns off, but the phone stays awake and unlocked: that way the apps on the virtual displays keep running and receiving touches. When the user picks the phone back up, the panel turns back on; when they leave it there, it turns off again.

Pannello.java calls SurfaceControl.setDisplayPowerMode(token, 0|2) on every physical display: it acts only on the compositor, Android believes the screen is on and any change of state (power button) turns it back on. Since Android 14 the tokens live in DisplayControl, inside services.jar, loaded with a class loader on the SYSTEMSERVERCLASSPATH and the library android_servers.

The PC controls it with VIDEO_PANNELLO (6.2 “Video messages”): video_nostro::pannello sends it without waiting for the reply, ComandiVideo::pannello sends it from a session. There is one panel per phone, not one per window: the one that decides whether to turn it off is the Collegamento, with the phone “in hand” rule described below. When the service dies, the guardian's action 400 turns it back on (5.6 “The two guardians”).

7.2 · Display refresh rate when the panel is off

Samsung phones change the display refresh rate by themselves (10–120 Hz): after a moment of calm it is at 24 Hz. When the panel is turned off SurfaceFlinger switches to 60 Hz, but confirms the change only with the panel's vsyncs, which no longer arrive: its model stays at 24 Hz, takes the frames of the virtual displays at that pace, and apps that draw faster remain stuck waiting for it (Facebook, with AV1 reels decoded in software, starves the audio). Prove §59.

1. Before turning off, Pannello.java reads mDisplayModePtr and mPeriodConfirmationInProgress from dumpsys SurfaceFlinger.
2. If the model is not confirmed at 60 Hz or more, it sets min_refresh_rate=60 and registers with the guardian action 410, which restores the previous value.
3. It waits for the confirmation, at most 1 s (ATTESA_60_MS), then turns off.
4. It immediately restores min_refresh_rate as it was and removes the guardian's action.

7.3 · The phone in hand

The state is a single value in the Collegamento: a_mano, read with Collegamento::pannello_a_mano. With a_mano false, sessions that open turn the panel off; with a_mano true they leave it on. It lasts as long as the process, across reconnections: a drop does not reset it.

Turning off without touches exists because the phone's screen timeout, during the connection, is at the maximum (5.6 “The two guardians”): a phone unlocked by hand and then left on the table would never turn off. The 3-second round, as long as the phone is “in hand”, asks dumpsys power | grep -m1 lastUserActivityTime= and reads “(N ms ago)” (fermo_da): once the time chosen by the user (the one saved at the start of the connection) has passed, it turns the panel off. This also applies with no windows open: the phone stays awake and unlocked (prove §58 and §60).

7.4 · Calls

The 3-second round reads the call state with dumpsys telephony.registry | grep -o 'mCallState=[12]': 1 means it is ringing, 2 that it is in progress. With two SIMs there is one line per SIM, and one line is enough to count.

7.5 · Drops and reconnections

On Samsung phones locking the phone drops Wireless debugging: the connection reopens on unlock. But the connection also drops because of the network, with the phone still unlocked on the table. In both cases the panel is on upon return (the guardian or the user turned it back on), and Collegamento::sbloccato must figure out who did it.

1. On the drop, mantieni notes the time (caduto), only the first time and only if the connection was really open.
2. At the first lock check after the reconnection, if the phone is unlocked: if before the drop the round had seen the lock (bloccato_durante_uso), the user unlocked it: “in hand”.
3. Otherwise dumpsys power | grep -m1 mLastSleepTime= tells how long ago the phone fell asleep (dormito_da). If that happened no longer ago than the time elapsed since the drop plus MARGINE_CADUTA (15 s, generous compared with the 8 s within which the PC notices the drop: 5 s of waiting for the reply plus 3 s between checks), the phone has slept and the user unlocked it: “in hand”.
4. If it slept earlier, the drop was a network one: the panel turns off again as the sessions restart. If the line is missing or the command does not reply, when in doubt “in hand”.

“Unlocked by hand” is decided from the first lock check after the connection, not from the reconnection alone (prove §55 and §57).

7.6 · The change log

Every panel change leaves a line in Phonestra's log, which ends up in the PC's journal:

$ journalctl --user --since today | grep -i phonestra

8.1 · The recipe

The phone's audio plays from the PC's speakers, without interruptions and in sync with the video. The recipe came from measurements: loopback capture, AAC, timestamps from the sample count and a precise startup order.

On the phone (CanaleAudio.java, which uses the classes of the measuring tool Audio.java) there are four threads: audio-lettura, audio-codifica, audio-spedizione (queue of 256 packets, about 5 s, which drops the oldest ones, counted in persi) and audio-sentinella, which reads from the socket only to notice the close. Each thread catches its own errors: an audio problem closes the channel with an errore line, never the service. Only one audio channel at a time: a new one stops the old one and waits (at most 3 s) for it to have removed its policy.

8.2 · Audio packets

The audio channel goes only from the phone to the PC: orario u64 BE · lunghezza u32 BE · dati. The PC sends nothing; closing the channel stops the capture.

8.3 · Playback on the PC

On the PC three pieces give each packet its timestamp and decide when to play it; then GStreamer decodes and plays it.

audio_nostro::riproduci(apritore) is the function the connection calls; it ends if the channel closes and, when cancelled, closes it. PHONESTRA_AUDIO_CODEC=pcm (or raw) uses PCM instead of AAC.

8.4 · The startup order

Audio capture does not start together with the connection: it waits for the drawer's mirror. It is a rule found through measurements.

The drawer signals the opening of the mirror with Collegamento::specchio_aperto(), which increments a watch counter followed by the audio task. The task only looks at the mirrors opened after the current service started: after a reconnection it waits for the new mirror (prove §53).

8.5 · Who removes the capture

The capture removes itself in every way the service can end, even the most abrupt.

The guardian has no action for the audio: no shell command removes another process's policy, and none is needed. When Phonestra closes, before detaching the audio, the connection pauses the media that are playing, otherwise they would resume from the phone's speaker (3.4 “Shutdown”).

8.6 · Recording

The “Record the screen” (Registra lo schermo) button in an app's window writes an MP4: the H.264 video as it is (h264parse ! mp4mux) and the AAC audio as it is, without re-encoding. audio_nostro::ascolta() gives a copy of the packets (broadcast), caps_registrazione() the caps with the codec_data of the current audio. It starts from the first keyframe; with no AAC audio in progress the file has no audio.

During the recording the app's display does not change size and is not recreated for orientation (the window scales the image), and the button shows the elapsed time (● m:ss). The file goes to <Video di XDG>/Phonestra/<app> AAAA-MM-GG HH.MM.SS.mp4.

9.1 · Input and clipboard messages

The PC's mouse, touchpad and keyboard become fingers and keys on the app's screen; the clipboard travels in both directions, text only, never passwords.

Range 0x50–0x5f, big-endian. Events have id 0 and no response: the PC does not wait for the phone. larghezza/altezza are the size of the image on which the PC computed the coordinates.

A Rust test in input_nostro.rs reads Input.java and Video.java and checks that no message number is used twice.

9.2 · Injection

On the phone, input becomes Android events injected into the right display, in order, by a single thread.

9.3 · Keyboard and mouse on the PC

finestra.rs translates GTK events (finestra::tastiera for keys). Modifiers follow the values of KeyEvent.META_* (META_SHIFT, META_CTRL).

9.4 · Clipboard

The service talks directly to IClipboard, as the package com.android.shell: no ClipboardManager, hence no Looper to run and no detour through the Samsung service semclipboard, which rejects the write with the wrong context. Signatures change between versions: the longest variant is chosen whose parameters, after the fixed ones, are only strings and integers.

Echoes. What Phonestra puts into the phone's clipboard must not come back to the PC. The service ignores its own writes (even an identical text within 3 s, because the notice may arrive later) and Samsung sends every notice twice (discarded within 0.5 s); the PC remembers the texts it sent (Collegamento::e_un_rimbalzo). The service rereads the clipboard only if the current clip is its own: reading another app's clip would make the “ha incollato dagli appunti” (pasted from the clipboard) notice appear.

10.1 · Interface architecture

The interface uses GTK4 and libadwaita, with a style faithful to libadwaita (GNOME title bar, boxed lists, pill buttons). Phonestra follows the system's light or dark theme: segui_tema applies to all windows, the SCURO palette of cassetto.rs to the drawer, “Add a phone” (Aggiungi un telefono) and the wizard (the app windows have rules of their own); the mockups are light only. No .desktop file is installed. The design proposals every screen comes from are in mockup/; the rules in notes/interface.md.

10.2 · The drawer

cassetto.rs is the main window, the drawer. It subscribes to four watch of the Collegamento: stato(), guasto(), info() (battery and network) and notifiche(); it reaches the component through finestra::vista.

The app list comes from the helper (app::elenco, command app <lato>) and is valid only if it ends with the line fine\t<n>: a list interrupted by a drop is not used and is reread on reconnection (elenco_intero). The app menu (right click) has Open (Apri; or Bring to front, Porta in primo piano, if it is already open), Close app (Chiudi app) if it is open, favorites, App info (Informazioni sull'app) and Uninstall… (Disinstalla…; disabled for system apps).

10.3 · App windows

finestra.rs: one window per app, with finestra::vista in the center (video, mouse, keyboard) and around it the bar with Back (Indietro), Screenshot, Record the screen (Registra lo schermo) and the More commands (Altri comandi; ⋮) menu.

• The virtual display follows the window (6.5 “Resizing”).
• Portrait-only apps (the orientamento event): fixed-size 9:16 window, no maximizing and no draggable edges; in full screen the app sits in a column shaped like the phone.
• Connection lost or component failed: the last image stays, blurred, with “Reconnect now” and “Close” (Chiudi); the session restarts on its own when the connection returns and the app reappears where it was. With the phone locked only the subtitle changes.
• Protected screen: a message instead of the black image.
• When the window is closed, the app is removed from the phone's recents (ComandiVideo::chiudi(true)); if it was the one controlling playback (YouTube, Facebook), it is paused. When the last session closes, the panel turns back on (7.3 “The phone in hand”).

10.4 · Preferences

The drawer's Preferences page saves the user's choices in preferenze.toml (3.6 “Configuration and data on the PC”). Each item has its own value.

10.5 · The first connection

prepara.rs is “Add a phone” (Aggiungi un telefono) without a cable: the list of settings to enable on the phone (same Wi-Fi network, Developer options, any protections, Wireless debugging with “Pair device with pairing code”). For each item, the word to search for in Settings and “Ask Google ↗” (Chiedi a Google ↗), which opens Google's AI Mode with the question already written.

Items visible on the network tick themselves: Wireless debugging turned on (_adb-tls-connect) and the pairing code screen open (_adb-tls-pairing), which enables the 6-digit field. With the code, Phonestra pairs (adb::abbina), connects with adb_client, removes the expiry of the authorization (settings put global adb_allowed_connection_time 0) and saves the phone.

procedura.rs is the USB cable fallback, for Android 10 or earlier (it opens from “Android 10 or earlier? Connect with the cable” (Android 10 o precedente? Collega col cavo)). It advances on its own by checking the cable every second (usb.rs reads /sys/bus/usb/devices without opening the device) and recognizes these cases:

After the cable, telefono.rs retries 3 times with a 1 s pause (the error “got AUTH” means consent is still missing), sets adb_allowed_connection_time 0 and adb_wifi_enabled 1 and waits up to 30 s for the user's confirmation. After 20 s stuck at the first step, the “What the PC sees” (Cosa vede il PC) box appears with the list of USB devices, to photograph for whoever is helping remotely.

The per-brand instructions come from data/instructions.toml, embedded at build time. The families are chosen by searching for the words in marche in the manufacturer read from the cable; the last one, “Other phones” (Altri telefoni), has an empty marche and acts as the fallback. The paths are the phone's Settings names as they appear on the phone, in Italian here and in English in data/en/instructions.toml (the one used with the English interface); in the example: “Impostazioni › Informazioni sul telefono › Informazioni sul software” (Settings › About phone › Software information), “Numero build” (Build number), “Impostazioni › Opzioni sviluppatore” (Settings › Developer options) and “Impostazioni › Sicurezza e privacy › Blocco automatico” (Settings › Security and privacy › Auto Blocker).

[[famiglia]]
nome = "Samsung"
marche = ["samsung"]             # words searched in the manufacturer
verificata = true                # paths tested on a real phone
percorso_build = ["Impostazioni", "Informazioni sul telefono", "Informazioni sul software"]
voce_build = "Numero build"
percorso_debug = ["Impostazioni", "Opzioni sviluppatore"]
grigio = "…"                     # what to do if the USB debugging item is grayed out
sicurezza = "…"                  # extra step (Xiaomi: security settings)
[famiglia.prima]                 # a setting to change before anything else
percorso = ["Impostazioni", "Sicurezza e privacy", "Blocco automatico"]
voce = "Blocco automatico"

10.6 · Notifications and alerts

notifiche.rs reads dumpsys notification --noredact (title and text of private notifications too) in the connection's 3-second round, and battery (dumpsys battery, “charging” with status 2 or 5) and network (cmd wifi status) every 30 s. It discards ongoing notifications (ONGOING_EVENT, FOREGROUND_SERVICE), group summaries (GROUP_SUMMARY) and those with neither title nor text; it sorts them newest first.

avvisi.rs turns new notifications into system notifications with the D-Bus service org.freedesktop.Notifications (GNOME, KDE, Xfce): GTK notifications on GNOME work only for programs with a .desktop file, which Phonestra does not install. “Already seen” notifications are fixed at the first read; today, however, the first read happens with the drawer just opened, when the list is still empty, so at the first real read the notifications already on the phone raise an alert (ch. 18 “Appendix C — Known issues”). Clicking an alert opens the app. The preferences allow turning them off, showing only the app name (the text becomes “New notification”, Nuova notifica) and muting individual apps. The app icons for the alerts are written to ~/.config/Phonestra/icone/<pacchetto>.png.

11.1 · Installing and sending

azioni.rs uses only the Android shell: no app on the phone, no extra permissions.

• One transfer at a time: a second one is rejected with the alert “Wait for the current transfer to finish” (Aspetta la fine del trasferimento in corso). The transfer card shows the progress and is canceled with ×.
• After an installation or uninstallation, the app list is reread.

11.2 · Receiving files from the phone

ricevi.rs is the “Receive files…” (Ricevi file…) window (adw::Dialog): you browse the phone and choose the files to copy to the PC (SPECIFICATION §11.1, mockup receive-files.html).

• Clickable path and “up” button, up to Phone storage or SD card; search by name; sort by date, newest or oldest first; thumbnails or list.
• Folders are read with sync.rs (4.6 “Copying files: sync:”): they are read in full and shown 200 at a time (“Show N more”, Mostra altri N); hidden files (starting with a dot) do not appear.
• Checkmarks persist when changing folder; “Select all” / “Deselect all” (Scegli tutti / Togli tutti); a double click receives the file immediately.
• The thumbnails are made by the helper (miniature <lato> <percorsi in base64>, Miniature.java) in groups of 40, at 192 pixels: each launch costs about one second. Photos are downscaled by BitmapFactory and straightened using EXIF; videos give a frame with MediaMetadataRetriever through a MediaDataSource.

The copy is done by the drawer, with the same transfer card as sending: each file arrives with sync::ricevi in the folder of Preferenze::cartella_ricevuti (the Downloads (Scaricati) folder if not chosen), with a free name and the phone's modification date. At the end an alert says how many files arrived, with Open folder (Apri la cartella; with a single file, the folder opens with the file already highlighted).

12.1 · Tests on the PC

Two levels: the tests on the PC, which need no phone and run at every commit, and the tests on the real phone with phonestra-prova.

cargo test tests the pure parts: the formats of the chunked messages (commands, audio, video, input), the preamble, the ready line, CIAO, the heartbeat, shell,v2 packets, dispatching without a network, audio timing and margin, real AAC decoded and written to MP4, flow control against a fake adbd, mDNS, parsing of dumpsys, message numbers matching between Java and Rust, and these manuals (tests/manual.rs, 12.5 “The manuals and their checks”).

12.2 · The phonestra-prova tool

A separate executable, without a user interface, that uses the same code as the program. The component tests are run with the phone unlocked and Phonestra closed; each one cleans up after itself and checks that nothing is left behind on the phone.

$ ./target/debug/phonestra-prova servizio 10
$ ./target/debug/phonestra-prova video-componente app --secondi 15
$ PHONESTRA_DEBUG=1 ./target/debug/phonestra-prova input-componente tutte

12.3 · Rules for tests on the phone

Tests on the real phone follow a few rules: the phone must go back to how it was, and every measurement must stay on record.

• phonestra-prova first; the system adb only for diagnostics the tool cannot do (it uses a different key: the phone asks for a new authorization).
• At the end of a test: shut down any adb server that was started and any open sessions; do not leave phone settings changed.
• Before restarting Phonestra for a test, check all the mCallState lines (one per SIM): never during a call (7.4 “Calls”).
• Measurements and results go in notes/connection-tests.md, with the section number (§).

12.4 · Diagnostic variables

The PHONESTRA_* variables turn on diagnostics or change a parameter, for tests and measurements.

The log of Phonestra started from the AppImage is in the PC's journal: journalctl --user --since today | grep -i phonestra (7.6 “The change log”).

12.5 · The manuals and their checks

Both manuals are generated: the sources are in docs/sources/, one per chapter in technical/ and user/, and build.py assembles them into docs/Technical Manual.html and docs/User Manual.html, two self-contained files, readable even when downloaded on their own. Their style is the common style of the manuals of the seven projects, identical in all of them and embedded in each page: style.css and manual.js (the search box at the top of the sidebar and the Copy button on command blocks) are copied from it as they are, and build.py only adds the few rules for elements found only here. The cover shows the official logo (logos/phonestra-logo-horizontal-light.png, embedded in the page).

tests/manual.rs runs python3 docs/sources/build.py --controlla, which fails if:

• the published file does not match the sources (the manuals are not edited by hand);
• the page does not embed the common style.css and manual.js unchanged;
• a source file is missing from ch. 17 “Appendix B — File map” or the map lists a file that no longer exists;
• a cited Rust symbol (such as Collegamento::mantieni) does not exist in the sources, or a cited Java method (such as Servizio.comandi) is not in the class's file;
• a cited file does not exist in the repository;
• a PHONESTRA_* variable in the code is not documented, or the manuals cite one that does not exist;
• a command of phonestra-prova or of the helper is not documented;
• an internal link leads to a section that does not exist, or the version from Cargo.toml does not appear; or the running text of either manual contains Italian sentences (outside code, interface labels with the Italian label in parentheses after them, and program output).

13.1 · Required tools

Building Phonestra, its component and the manuals requires these tools. The reference system is Debian 13 “trixie”.

Testing requires a phone with Android 14 or later, Wireless debugging turned on and the PC on the same Wi-Fi network.

13.2 · Everyday commands

A few commands cover everyday work; cargo test also checks that the manuals are in step with the code.

$ export PATH=$HOME/.cargo/bin:$PATH
$ cargo build   # program and test tool
$ cargo test   # tests on the PC, without a phone; also checks the manuals
$ cargo clippy --all-targets   # no warnings allowed
$ cargo run --bin phonestra   # runs Phonestra from the sources
$ android/helper/build.sh   # rebuilds the phone component
$ python3 docs/sources/build.py   # regenerates the two manuals

13.3 · Building the component

The phone component is built outside cargo, with a script: javac, then D8. The resulting jar goes into the repository.

$ curl -L -o strumenti/r8.jar https://dl.google.com/android/maven2/com/android/tools/r8/9.4.26/r8-9.4.26.jar
$ android/helper/build.sh
creato android/phonestra-helper.jar

The script compiles with javac --release 11 the fake Android classes in stub/ (signatures only: they serve the compiler and do not end up in the jar; the phone has the real ones) and the sources in src/phonestra/, then D8 converts them to dex with --min-api 34 and --lib pointing at the JDK.

When you use a new public Android class, add its stub with only the methods used. Hidden APIs are called through reflection and usually have no stub; the exceptions are the hidden classes we extend, which the compiler must know: android.app.TaskStackListener (EventiApp.java) and android.content.IOnPrimaryClipChangedListener (Input.java).

13.4 · The AppImage container

A single file that starts on all common distributions: it is built on an old glibc and carries GTK, libadwaita and GStreamer with it, but uses the system's graphics drivers.

packaging/Containerfile starts from Ubuntu 22.04 (glibc 2.35), so the executable requires at most glibc 2.34 and starts even on 2022 systems. The GTK and libadwaita of Ubuntu 22.04 are too old: the container builds into /opt/phonestra wayland 1.22, wayland-protocols 1.36, glib 2.80, graphene 1.10, GTK 4.14 and libadwaita 1.5 (packaging/build.sh, meson), plus gst-plugin-gtk4 0.13.5 from gst-plugins-rs.

$ podman build -t phonestra-appimage packaging
$ podman run --rm -v .:/phonestra:Z phonestra-appimage sh -c 'CARGO_TARGET_DIR=target/appimage cargo build --release && packaging/collect.sh'

The result is target/appimage/Phonestra-<versione>-x86_64.AppImage; the version comes from Cargo.toml.

13.5 · What collect.sh does

collect.sh takes the executable built in the container and turns it into an AppImage, in five steps.

1. Copies the executable and, recursively with ldd, the libraries it uses, except those that must come from the system: glibc, libstdc++, libgcc_s, graphics drivers and the libraries that load them (GL, EGL, DRM, gbm, Vulkan), libX11 and libxcb, fontconfig, freetype, libexpat, PipeWire, ALSA, udev.
2. Copies the GStreamer plugins that are needed (coreelements, app, typefindfunctions, playback, videoparsersbad, videoconvert, videoscale, libav, opus, audioconvert, audioresample, autodetect, pulseaudio, isomp4, vaapi, va) and gtk4, with gst-plugin-scanner.
3. Copies the image loaders (PNG, JPEG, SVG), the GSettings schemas, the fallback Adwaita icons and the dconf GIO module: without it, GTK does not read the desktop settings (the window title bar was left with only the X). Then the licenses, in usr/share/doc/phonestra/: LICENSE.md, NOTICE.md and third-party/, with the Ubuntu copyright file of every package a copied file comes from, the license texts they point to, those of the libraries built in the container (saved by build.sh), the crates' ones (rust-licenses.py) and the AppImage runtime's.
4. Moves into usr/lib/riserva the libraries that the system's drivers also use (wayland, zlib, zstd, libxml2, libffi, libelf, libva, the libxcb-* ones…): they are used only if the system lacks them or has versions that are too old.
5. Fixes the paths with patchelf ($ORIGIN), adds AppRun, the icon (logos/icons/phonestra-256.png) and a .desktop file with NoDisplay=true (needed by appimagetool, not installed), and creates the AppImage with the static runtime (no libfuse2).

13.6 · AppRun

packaging/AppRun prepares the environment and launches usr/bin/phonestra: the system's libraries and the bundled ones must not mix.

13.7 · Testing on distributions

packaging/test-distributions.sh starts the AppImage in Ubuntu 22.04, Debian 12, Fedora 43 and Arch containers, connected to the PC's Wayland display and graphics card, with an empty configuration: Phonestra must open “Add a phone” (Aggiungi un telefono). With PHONESTRA_FOTO the window is saved as PNG and the script reports the errors in the log.

13.8 · Publishing a release

A new release is published in four steps, always in the same order.

1. Version in Cargo.toml (for release candidates: 1.0.0-rc.N), python3 docs/sources/build.py (the version appears in the manuals), commit and push.
2. AppImage from the container, startup and connection test, SHA-256 fingerprint.
3. Publication on https://phonestra.nicfio.it with site/publish.sh, which takes the AppImage just built or the published one (see the script's header; first --build alone, to look at site/public/; before publishing, the search-engine check: description, canonical, robots, icons, og.png, structured data, sitemap), then the annotated git tag v<versione>.
4. Copy of the AppImage into the user's home (~/Phonestra-<versione>-x86_64.AppImage): that is the one the user runs. Since 1.0.0 the site replaces the GitHub Releases (the repository is private).

14.1 · A new message on the command channel

A new message touches both sides: the Java class of the part and the Rust module that uses it. These are the steps, in order.

1. Choose the number in the part's range (video 0x40–0x4f, input 0x50–0x5f) or open a new range of 16 for a new part.
2. Phone: the constant in the part's class (static final int NOME = 0x47; in Video.java), the case in the switch of Servizio.comandi (or Input.nostro for input), the handler. If it is a request, respond with the same id and the RISPOSTA flag, or with ERRORE.
3. Rebuild the jar with android/helper/build.sh.
4. PC: the constant in componente::tipo (or input_nostro::tipo), the encoding of the content as a pure function, the method that uses it (Condiviso::domanda for a request, Mittente::manda for an event with no response).
5. Add the name to the list of the nessun_tipo_usato_da_due_moduli test: it checks that the number is unique, in the right range and the same in Java and in Rust.
6. An encoding test with the expected bytes, then a test with phonestra-prova.
7. Describe the message in the table of its chapter in docs/sources/technical/.

14.2 · A new channel type

A part with a stream of its own, like audio and video, needs its own channel, opened with the preamble.

1. Phone: a handler static void gestisci(LocalSocket s, String tipo) and its entry in Servizio.TIPI. The handler runs on its own thread: it catches all errors (including the Error of hidden APIs) and closes the socket with shutdownInput/shutdownOutput before close, otherwise a read in progress on another thread keeps the socket open.
2. PC: Condiviso::apritore().apri("tipo") gives a Canale with the preamble already sent.
3. If the part changes something on the phone, register the inverse action with the guardian.

14.3 · A new action for the guardian

Everything a part changes on the phone must have its inverse action registered with the service's guardian (5.6 “The two guardians”).

// When you change something on the phone:
Servizio.custode().imposta("mia-azione", 450, "settings put system qualcosa 1");
// When you have put it back yourself:
Servizio.custode().togli("mia-azione");

The command is a shell line run with sh -c after the service dies, without an Android context. Choose the order so that the actions happen in the right sequence (panel 400, refresh rate 410, task 500) and test it with kill -9 on the service (phonestra-prova shell 'kill -9 <pid>').

15.1 · Language and style

Phonestra's code reads like its project documents: in Italian, with the why next to the how. The two manuals are the exception: they are written in English.

• Italian everywhere else: names, comments, program messages (the English interface takes its texts from data/en/), the documents in the repository (README, SPECIFICATION, notes/). Only the text of the two manuals is in English: the pages in docs/ and the chapters they are generated from in docs/sources/. Plain words, short sentences. The manuals quote the interface labels as the English interface shows them, with the Italian label in parentheses.
• Comments explain the why and point to the source: SPECIFICATION §7.3, prove §49 (notes/connection-tests.md), notes/component.md.
• Rust: anyhow for errors, with context saying what was being done; no unwrap where a different phone might answer something else.
• Java: one class per piece, reflection only in Nascoste and in the pieces that use it, errors caught in the thread that produces them.
• Third-party code: never copied. scrcpy and AOSP are read as documentation.

15.2 · Before every commit

Every commit leaves the project built, tested and documented.

$ cargo build && cargo test && cargo clippy --all-targets

No clippy warnings. If you changed the component, the rebuilt jar goes into the same commit. If you changed a behavior, update the chapter that describes it in docs/sources/technical/ (and, if the user sees it, in docs/sources/user/) and regenerate the manuals (python3 docs/sources/build.py); if you added a source file, give it a row in the map (ch17_map.py, ch. 17 “Appendix B — File map”): cargo test requires it.

15.3 · Personal data

The repository is public: nothing that identifies people, phones or networks.

15.4 · Recording decisions

The project's why lives in notes/, one file per topic. Decisions are written there, together with their why.

Before proposing an alternative, check that it has not already been rejected (for example Flatpak, icons in the system menu, dark themes as a style, several phones active at the same time).

16.1 · Index of data structures

This appendix collects the central data structures of the PC program, with the file that defines them and the section that covers them in depth. They are the contracts that run through Phonestra; the Java classes of the component are listed in ch. 17 “Appendix B — File map”.

16.2 · Index of messages

All the command-channel messages in one table, by number. The format of each is described in the section indicated.

16.3 · Stream headers

Every byte stream in Phonestra starts with a fixed header. Here they are side by side.

17.1 · The project's files

Every source file with its line count, recounted each time the manual is generated. If a file is missing from the map, or the map lists a file that no longer exists, generation stops and cargo test fails.

18.1 · Open issues

Open as of version 1.0.0; the up-to-date status is in notes/issue-log.md.

19.1 · Terms A–L

Definitions of the technical terms used in the manual. The code of Phonestra is written in Italian, so terms that are also Italian names in the code are listed under the Italian word, followed by the English term this manual uses. The cross-references point to the section with the details.

adbd

The phone's ADB daemon: it accepts connections from the PC and starts the services (shell, sync:, localabstract:). See ch. 4 “The ADB client”.

Aiutante (helper)

The component's jar when used for short commands (app list, wallpaper, thumbnails, measurements). See 5.1 “What the component is”.

Annex B

The H.264/H.265 stream format with the start code 00 00 00 01 in front of every unit. See 6.3 “The video:<id> channel”.

app_process

The Android program that starts Java code outside an app; the shell uses it too. See 5.1 “What the component is”.

ART

Android Runtime: the virtual machine that runs the dex.

AudioPolicy

Hidden API for routing audio; with loopback it sends the apps' sound to a recorder instead of the loudspeaker. See 8.1 “The recipe”.

Battito (heartbeat)

The BATTITO message, sent every second in both directions: after 5 s of silence each side considers the other gone. See 5.5 “Heartbeat and exit codes”.

Canale (channel)

A logical connection inside the ADB connection, to a service on the phone; all channels share the same connection. See 4.4 “Channels and flow control”.

Collegamento (connection)

The active phone and its ADB connection (collegamento.rs), kept alive as long as Phonestra stays open. See 3.2 “Life of a connection”.

Componente (component)

Everything Phonestra runs on the phone: the jar phonestra-helper.jar. See ch. 5 “The on-phone component”.

Custode (guardian)

A shell process that puts the phone back in order when whatever it is tied to ends. See 5.6 “The two guardians”.

Delayed ack

ADB extension with more data in flight per channel and acknowledgements that carry the number of bytes received. See 4.4 “Channels and flow control”.

dex

The format of compiled Java code for Android (classes.dex), produced by D8. See 13.3 “Building the component”.

Drawer

Phonestra's main window with the phone's apps (cassetto.rs). See 10.2 “The drawer”.

Giro dei 3 s (3-second round)

The periodic check of the connection: lock, calls and notifications in a single command. See 3.3 “The 3-second round”.

In mano (in hand)

Panel state: the user is using the phone with their hands, so the panel stays on. See 7.3 “The phone in hand”.

Loopback

Capture of the audio coming out of the apps, while the phone itself stays silent. See 8.1 “The recipe”.

19.2 · Terms M–Z

mDNS

DNS on the local network without a server: this is how the phone announces Wireless debugging. See 4.8 “Network discovery: mDNS”.

Pannello (panel)

The phone's physical screen, turned off while the apps are used from the PC. See 7.1 “Turning the panel off”.

Preambolo (preamble)

The first bytes of every channel of the service: the secret and the channel type. See 5.3 “Channels and preamble”.

Schermo virtuale (virtual display)

An extra display, created by the component, where the app of a window runs. See 6.1 “Sessions: virtual display and mirror”.

Servizio (service)

The component's long-running process, one per connection (phonestra-servizio). See 5.2 “Starting the service”.

Sessione (session)

A virtual display or the mirror, with its video:<id> channel. See 6.1 “Sessions: virtual display and mirror”.

Specchio (mirror)

The copy of the phone's main screen, drawn in the drawer. See 6.1 “Sessions: virtual display and mirror”.

Surface

The graphics buffer the virtual display draws into and the encoder reads from. See 6.4 “Encoder and keyframe”.

uid 2000

The ADB shell user: its permissions are the component's permissions. See 5.8 “Service security”.

Wireless debugging (Debug wireless)

ADB over Wi-Fi in Android 11+, with TLS and pairing by code. See 4.3 “Wi-Fi connection and TLS”.