Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 202 additions & 0 deletions device/tegu/TELEPHONY-APPS-PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
<!-- SPDX-License-Identifier: MIT -->
# Pixel 9a: connect Phone and Messages to sitd

Status (2026-11-03): Phone and Messages ran on the palmtop on 2026-11-02
through this path (results at the end). The optional
`omamobile-telephony-tegu` package installs mmd, the agent, an active-RIL
bridge policy and `omamobile-tegu-mmd-attach --check|--attach`, and enables
nothing. sitd's unit gets its modem dependency from a device-owned drop-in:
tegu uses Requisite on its already running starter, while cheetah and raven
keep Requires on their modem unit, and the virtual `omamobile-sitd-policy`
makes the drop-ins come along with a RIL upgrade. It builds on #363 (the
device modem policy). [Package/runbook](../../packages/omamobile-telephony-tegu/README.md).

Two ways start the bridge, each for its own case: at boot, #372's opt-in
`omamobile-tegu-modem-boot` starts the modem, sitd and mmd once the CP is
ONLINE (daily use); and `omamobile-tegu-mmd-attach --attach` attaches mmd
and the agent to a modem and sitd already started by hand (bring-up and
tests, where nothing should start the modem for you). The helper refuses
when sitd isn't running and never starts the modem itself.

Offline: the seven affected package suites pass, the attach package has 21
tests (including systemd verification of all three device policies), and
the architecture-independent package builds with makepkg. One bridge API
comparison skips when ModemManager's reference XML is missing.

The sections below are the investigation this started from, on `origin/main`
at `31fbcf9`, before #363 and the attach package. The owner then had texts
both ways and calls through `omamobile-sit`; this was the plan for the apps
on top.

The app protocol already exists. The immediate missing layer in the
recorded tegu setup is `omamobile-mmd`, installed and running. A normal
package install is blocked by the cheetah-only dependency still on main;
sitd's packaged modem-unit dependency also needs the tegu startup work.
Those are existing, separate changes. Do not duplicate them or install
with dependency checks disabled. The first app test can use an already
running, attended sitd; it need not wait for modem startup at boot.

## The existing path

```text
Phone / Messages
| session bus: org.omamobile.Phone1, org.omamobile.Messages1
omatel-agent (the logged-in user's service)
| system bus: org.freedesktop.ModemManager1
omamobile-mmd (root, ModemManager-compatible API)
| /run/omamobile-sit/socket: JSON requests and status subscription
omamobile-sitd (the only owner of the modem channels)
| SIT / AT
modem
```

| Layer | What the repository already supplies |
| --- | --- |
| Apps | `omamobile-apps` depends on `omaphone` and `omamessages`; both pull in `omatel-agent`. Contacts is supplied with Phone and does not need a modem. #361 puts all three packages in the image. |
| Agent | `packages/omatel` packages the agent, its user unit and both session-bus activation files. Its session-bus activation files are meant to start it when an app opens; on the palmtop that didn't happen (results below), and the user unit had to be started and enabled. The disabled user unit is intentional; no root agent and no generic enablement change are needed. |
| Bridge | `packages/omamobile-mmd` owns the system-bus name normally used by ModemManager, exports modem/call/SMS objects, and checks polkit for operations. It conflicts with the real `modemmanager`; installing both is not the solution. |
| Commands | `Voice.CreateCall` plus `Call.Start` maps to sitd `dial`; `Accept`, `Hangup` and `SendDtmf` map to sitd requests. `Messaging.Create` plus `Sms.Send` maps to `sms-send` with a durable request ID. |
| Incoming events | The bridge subscribes to sitd, exports calls, reads `sms-list`, and maps deletion to `sms-delete`. The agent stores SMS before deleting them from the bridge and handles notifications and call history. |
| Privileges | Apps and agent use D-Bus. Only the bridge needs sitd's private socket. Keep socket permissions and the current polkit policy; no wheel-group workaround is needed for app access. |

Sources: [app package](../../packages/omamobile-apps/PKGBUILD),
[agent packaging and activation](../../packages/omatel/README.md),
[bridge mappings](../../packages/omamobile-mmd/lib/bridge.py),
[socket subscription](../../packages/omamobile-mmd/lib/sitd_link.py), and
[the shared telephony plan](../../docs/TELEPHONY-APPS-PLAN.md), especially
sections 1.5 and 10.1b.

Contacts uses the shared local vCard address book; it does not need a modem
or an additional cellular service.

## What tegu is missing

1. **A dependency-correct install.** `omamobile-mmd` depends on
`omamobile-modem-sit`, which depends on `omamobile-modem`, which still
depends on `omamobile-device-cheetah`. That conflicts with tegu's device
package. #363 (merged) replaces that last dependency with the virtual
`omamobile-modem-policy` and adds tegu's provider.
2. **The bridge package and its start.** The common rootfs list deliberately
omits mmd and modem-sit. Tegu's `ROOTFS_PACKAGES` does not include them.
`omamobile-mmd.service` ships disabled, has no D-Bus activation file,
and its installer creates no wants link. Merely opening an app cannot
start it. The recorded SIM runbook says mmd was not installed; current
hardware state must be checked by the human rather than inferred here.
3. **The right modem service for later automatic integration.** The shipped
`omamobile-sitd.service` requires `omamobile-modem.service`; the recorded
tegu run uses its own starter and an `/etc` copy of sitd's unit that
removes this dependency. A bridge-only test must retain the already
qualified, running stack. Do not start or restart the stock sitd unit
to attach the bridge. Package tegu's starter/order separately before
making this an image default.
4. **The tested tegu RIL and release safety.** Main still carries the older
RIL; use the independently reviewed tegu SIM fixes and safe unconfirmed
call-release behavior. Do not replace a running test RIL as part of
installing the bridge. An unconfirmed hang-up must not stop the tegu
modem in place. Call audio remains its separate route/qualification.

There is no evidence that SMS needs an mmd APN, a tegu-specific socket
path, an extra bridge SMS transport, or a second modem daemon. The bridge
forwards SMS through sitd; sitd chooses the transport. Its modem state is
based on SIM/radio/registration and can be REGISTERED without a data bearer.
The hard-coded MM model string `Exynos Modem 5300` is misleading on tegu,
but is display metadata, not a routing selector or a reason to block SMS.

## The smallest durable changes after the prerequisites

- Keep `omamobile-apps` modem-independent, as #361 intends. Do not make all
images depend on the modem stack to get Phone or Contacts.
- After tegu's packaged modem start is qualified, add mmd and modem-sit to
tegu's board package list (and its packaged descriptor copy), with a
test that the descriptors agree and resolve against tegu's policy
provider without installing the cheetah device package.
- Enable only the bridge's existing relationship to sitd:
`systemctl enable omamobile-mmd.service` creates
`omamobile-sitd.service.wants/omamobile-mmd.service`. This follows a sitd
start without enabling sitd or starting the CP. Tegu's setup can do this
conditionally when mmd is installed; it need not use `--now`.
- Preserve mmd's one-way relationship: `After=omamobile-sitd.service`, no
`Requires=`, `Wants=` or activation path from the bridge to sitd or the
CP. An app opening or a bridge restart must never power the modem on.
- Test the conditional enablement with a fake systemctl, absent-package
handling, and a scratch unit root. Starting the bridge alone must not
request a CP start; starting qualified sitd must pull in the bridge.

For the already running palmtop, the manual steps below are enough once
package dependencies are correct. The durable boot/image changes are not
prerequisites for that test.

## Attended first test (ran on 2026-11-02)

Keep the existing modem sleep inhibitor throughout; suspend with the CP on
is not qualified by this work. Keep the existing once-per-boot start and
NV checks. No step below starts, stops or restarts the CP or sitd.
Run user commands in the existing graphical user's terminal, root commands
in the attended administrative session.

| Step / risk | Commands or action | Expect / pass | Stop condition | Rollback |
| --- | --- | --- | --- | --- |
| 1. Read-only / none | `uname -r`; `pacman -Q omaphone omamessages omatel-agent omamobile-mmd omamobile-modem-sit omamobile-modem`; `systemctl is-active omamobile-sitd omamobile-mmd ModemManager`; `systemctl cat omamobile-sitd`; `systemd-inhibit --list` | Record kernel/package versions, actual sitd unit, active inhibitor and existing running sitd. Missing bridge is expected initially. | No confirmed running sitd, wrong starter, competing ModemManager, or no inhibitor. | None; end this session without starting the modem. |
| 2. Install bridge / low | First review `pacman -Sp --print-format '%n %v' omamobile-mmd`. After the dependency fix is available, `pacman -S omamobile-mmd`, only if the transaction adds the bridge/dependencies without changing the running RIL, modem or device package. | No cheetah package, no tegu removal, no modem/RIL upgrade, and nothing starts the CP. | Resolver conflict or any unexpected upgrade/removal. Never use `-dd`. | Cancel before accepting the transaction; if installed, remove only the bridge after stopping it. |
| 3. Start bridge / low | Root: `systemctl start omamobile-mmd.service`; `busctl --system list --no-pager org.freedesktop.ModemManager1`; use `packages/omamobile-mmd/test/libmm-status.py` for states only. | Bus name owned by mmd, a modem object with SIM ready and expected registration; sitd/CP remain the same running instances. | Bridge cannot own the name/connect; sitd exits; hardware warning. | `systemctl stop omamobile-mmd.service`. Do not restart sitd or stop the modem. |
| 4. Agent and apps / low, screen changes | Announce first, then open Phone and Messages as the session user. `systemctl --user is-active omatel-agent`; `busctl --user list --no-pager org.omamobile.Phone1 org.omamobile.Messages1`. | Agent activates, apps see the modem instead of no-modem; Contacts opens without requiring a live modem. | Activation or authorization error. Do not weaken polkit/socket permissions. | Close apps; stop the user agent if it was started only for this test; stop mmd. |
| 5. SMS / carrier charge possible | Human sends one agreed test text in Messages, then sends one back from the other device; reopen the conversation. | One send, one received message, preserved after closing/reopening; no duplicate send on retry/reconnect. | Duplicate, uncertain delivery, or missing inbound text. Do not retry an uncertain send automatically. | Stop testing and stop the bridge; keep private message stores for diagnosis. |
| 6. Calls / medium, screen and sound | Only after the separate safe-release and call-audio checks: announce, place one ordinary agreed call from Phone, receive one, answer/decline and hang up. | UI state follows the call, release is confirmed, and the approved audio route behaves as qualified separately. | Unconfirmed release, unexpected audio level, CP/AoC/UFS fault. No emergency-number test. | Follow the attended safe-release runbook; no modem stop or second start. A reboot needs separate approval. |
| 7. Optional persistence / low | After passing, root: `systemctl enable omamobile-mmd.service` without `--now`. Inspect the resulting sitd wants link. | Bridge follows future *approved* sitd starts; sitd and modem remain disabled at boot. | Any change enabling the modem or sitd itself. | Disable only mmd if this step enabled it, then stop mmd if ending the test. |

SMS/call numbers, contents, operator identities and object dumps remain
private. Record only states, counts, errors and test outcomes in this plan.
The read-only libmm status helper deliberately prints states and counts.

A session that has never opened either app needs an additional activation
check before claiming always-on incoming notifications. The shell's call
watcher checks whether the agent owns its name and does not itself start
it. For this first test, open an app before arranging incoming traffic.
Keep #361's app-triggered activation policy until cold-session reception
has a separate test and an explicit decision about login activation.

App mute/speaker controls are also separate: the shared plan records that
the agent uses callaudiod for those, while sitd owns its own voice PCMs.
A successful dial through mmd does not prove those controls affect tegu's
route. MMS and mobile-data control through ModemManager are outside this
SMS/basic-call integration; keep the existing sitd data ownership.

## Offline evidence

`packages/omamobile-mmd/test/all` passed on this base with private D-Bus
and local simulator sockets. This covers API/bridge/libmm clients, the
real sitd-to-sit-sim call and SMS chain, and staged unit checks. One test
was skipped because ModemManager's reference introspection XML is absent.
The suite verifies that the bridge has no unit dependency that pulls in
the modem and no system-bus activation file.

`packages/omamobile-apps/test/all` also passed all 12 checks, including
Phone/Messages dependencies and the absence of a common modem dependency.

This does not run the packaged Rust agent or either GUI, does not test
tegu hardware or the current private carrier configuration, and does not
qualify polkit for the actual graphical session. The earlier full agent
chain result is recorded in the shared plan; it was not rerun here.

## Results on the palmtop, 2026-11-02

The daily kernel (`7.3.0-rc6-omamobile-tegu-s2mpg15-m1-g991042e2eff3-dirty`),
the modem started by hand and sitd running (built from this stack, 0.3.12
at the time), `omamobile-mmd` 0.1.0 started with `systemctl start`.

- Steps 1 to 3 passed: the bridge owned `org.freedesktop.ModemManager1`
and exported the modem with the SIM ready; sitd and the CP stayed the
same running instances.
- Step 4: opening Messages did *not* start the agent, and it showed
"service isn't running" until `systemctl --user enable --now
omatel-agent`. After that both apps saw the modem. Cold-session
activation stays open, as above.
- Step 5: texts both ways from Messages, with no duplicate.
- Step 6: calls out from Phone and in, with speakerphone audio (#367),
released cleanly.
- The status bar showed airplane mode until sitd mapped radio state 10 to
on (now on main with #381).

A `tools/phone-smoke` report from the palmtop is still to come, with the
next run.

5 changes: 3 additions & 2 deletions docs/TELEPHONY-APPS-PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ shell status / quick settings ────────────────
└─ AoC voice PCMs (EP5/EP4), rmnet0
```

- **Why a separate process.** `omamobile-sitd` holds the safety model: the allow-list, the do-not-send list, durable SMS sends that never repeat, and power-off when a hangup isn't confirmed. Keeping D-Bus out of it keeps that code small and keeps its tests (`tools/sit-sim`) as they are. A crash in the bridge can't drop a call, and the bridge can restart freely, which the RIL can't (a second start-up on the same CP isn't supported).
- **Why a separate process.** `omamobile-sitd` holds the safety model: the allow-list, the do-not-send list, durable SMS sends that never repeat, and radio-off recovery for unconfirmed call release. Keeping D-Bus out of it keeps that code small and keeps its tests (`tools/sit-sim`) as they are. A crash in the bridge can't drop a call, and the bridge can restart freely, which the RIL can't (a second start-up on the same CP isn't supported).
- **Why Python, with dbus-fast.** This differs from the apps, and it is Q3. The RIL is Python, and ofono2mm shows that Python with dbus-fast carries MM's whole API. The bridge is a translation layer with no performance load, and the same team reads both sides. Read Droidian's BSD-3-Clause original for structure (compatible with our MIT tree), and FuriLabs' GPL-2.0 fork for reference only. Rust with zbus is the alternative if the owner wants one language for everything new. It would add a toolchain to the system side, and the apps wouldn't share code with it anyway, since they use MM's public API.
- **Changes to `omamobile-sitd`'s socket API** (T0, offline, against `tools/sit-sim`):
- `subscribe`: a long-lived connection that receives one JSON event per change, with call, SMS, registration, signal and SIM events. The bridge then doesn't poll `state.json`.
Expand All @@ -143,7 +143,8 @@ shell status / quick settings ────────────────
- Received SMS handed over by ID: the bridge exports each one as an `Sms` object, and a client's `Messaging.Delete` deletes it in sitd's store. That is Chatty's pattern: it copies each message into its own database and deletes it from the modem.
- **Packaging, as built (T1, `packages/omamobile-mmd` 0.1.0; [MODEM-PLAN](../device/cheetah/MODEM-PLAN.md) "T0/T1: the ModemManager bridge"):**
- Its own package, `omamobile-mmd`, with `conflicts=(modemmanager)` and **no `provides=`**: nothing in Arch or Arch Linux ARM hard-depends on `modemmanager` (gnome-calls, chatty, networkmanager and geoclue need only libmm-glib; mmsd-tng is AUR-only and also needs only libmm-glib).
- It ships `omamobile-mmd.service`, not `ModemManager.service`, with no `dbus-org.freedesktop.ModemManager1.service` alias: `Type=dbus`, `BusName=org.freedesktop.ModemManager1`, `Conflicts=ModemManager.service`, `WantedBy=omamobile-sitd.service`, and not enabled by the package. It also ships the D-Bus bus policy (only root owns the name) and MM's polkit actions.
- It ships `omamobile-mmd.service`, not `ModemManager.service`, with no `dbus-org.freedesktop.ModemManager1.service` alias: `Type=dbus`, `BusName=org.freedesktop.ModemManager1`, `WantedBy=omamobile-sitd.service`, and not enabled by the package (up to mmd 0.1.2 it also had `Conflicts=ModemManager.service`). It also ships the D-Bus bus policy (only root owns the name) and MM's polkit actions.
- From mmd 0.1.3 (#371), the unit has no `Conflicts=ModemManager.service`: starting the bridge must not stop another modem daemon. Package conflicts and exclusive D-Bus name ownership still provide exclusion. The optional tegu integration adds Requisite on an already active sitd, a read-only service check, and an attended attachment helper; it enables neither modem nor RIL.
- **No D-Bus activation file**, so no client can start the bridge. Enabled, it starts with `omamobile-sitd`.
- No `mmcli` and no CLI of our own. Phone runbooks read the modem through libmm-glib with `test/libmm-status.py`; mmcli runs only in the conformance container (`test/conformance`).
- **Packaging, superseded (the design before T1, kept for history; not built):** a package named `omamobile-mm` with `provides=(modemmanager)` and `conflicts=(modemmanager)`, shipping `ModemManager.service` aliased `dbus-org.freedesktop.ModemManager1.service`, the bus policy, a D-Bus activation file, and `mmcli` or a small `omamobile-mm-cli`. T1 dropped `provides=` (no package needs it), the activation file (so no client can start the bridge) and the takeover of ModemManager's unit name.
Expand Down
2 changes: 1 addition & 1 deletion packages/omamobile-device-cheetah/PKGBUILD
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ url="https://github.com/derekross/omarchy-mobile"
license=(MIT Apache-2.0)
depends=(bash systemd util-linux omamobile-keyring i2c-tools)
# Keep CPIF and its link driver behind the modem's guarded startup.
provides=(omamobile-modem-policy)
provides=(omamobile-modem-policy omamobile-sitd-policy)
backup=(etc/pacman.d/omamobile-mirrorlist)
install=omamobile-device-cheetah.install
optdepends=('omamobile-boot-update: writes kernel package updates to slot B from the boot files this package ships')
Expand Down
Loading