Files
bubble/android/README.md
T
trav 96c368dfd1 v0.5.0: bubble for Android 0.5.0 — text from the Rabbit's SIM on the desktop, and chat names and read status sync, through jai
A relay on jai (server/bubble_relay.py, stdlib + SQLite, tailscale address
only, bearer token) carries sealed blobs between the desktop and the Rabbit:
AES-256-GCM with a key the desktop makes and hands over USB (Sync to Rabbit),
so jai can neither read nor forge anything. It deletes what's been picked up,
and anything after 14 days.

- Desktop (src/main/relay.ts): "Rabbit SIM" is a number to text from, groups
  included; the SIM's history and new texts arrive; older photos are fetched
  when shown; names and read/unread/archived go both ways. Settings → Rabbit
  relay connects it.
- Rabbit (Relay.java, RelayJob): no timer of its own for the battery; it rides
  along with the background checks, plus one network job after a text, a send
  or a swipe. Each send from the desktop goes out at most once and not after a
  day. Plain http only to jai and localhost (network_security_config).
- scripts/deploy-jai.sh; tests: server unit tests, an end-to-end relay test,
  and DEVICE=1 relay.device.test.ts against the dev app.
2026-11-06 17:35:00 -08:00

103 lines
5.6 KiB
Markdown

# bubble for Android (Rabbit R1)
The desktop app's companion: the same conversations, both numbers (voip.ms
and Google Voice), group chats, photos, and chat names, on a Rabbit R1. Plain
Java with no libraries and no Gradle, built like andTunes
(`~/Documents/lintunes/andtunes`, whose README and DEVICE.md cover the
toolchain and the R1's screen quirks: everything here is about double a
stock size).
## Getting it onto the Rabbit
Use the desktop app: **Settings → Rabbit → Install to Rabbit**. It installs
the APK bundled with the desktop app, exempts it from Doze (so background
checks keep their interval), and copies into the app's private storage:
- `files/config.json`: voip.ms API login, Google Voice number and sign-in
cookies, the voip.ms numbers to use, the default number
- `files/messages.db`: the desktop's history (same schema, minus the FTS5
search index Android's SQLite can't open)
- `files/media/`: cached photos and attachments
- `files/state-in.json`: chat names and read/unread/archived, merged both ways (newest change wins; the app keeps its side in `files/state.json`)
**Sync to Rabbit** copies the accounts again and merges names and read state without touching the
history. Everything goes in through `adb shell -T "run-as …"`, which is why
the APK is debuggable.
## Building
```sh
python3 android/build.py # -> android/build/release/VoipMessages.apk
python3 android/build.py --ship # ... + copy into resources/android/ (npm run android)
```
`npm run install-desktop` ships it before building the AppImage.
## Testing without real messages
A separate **dev** app (`me.teafry.voipmessages.dev`, "bubble (dev)" on the
launcher) has its own data, so it never touches the real one:
```sh
python3 android/build.py --dev --install
python3 android/tools/push_sandbox.py # made-up conversations; never goes online
```
Or run the desktop in its sandbox (`VOIPMS_SANDBOX=/tmp/x npm run dev`): its
Install/Sync buttons then target the dev app with the sandbox's made-up data.
## How it works
- `Store`: the desktop's SQLite schema; `Sync`: checks voip.ms (last day) and
Google Voice (thread list) like the desktop's polling; `Sender`: the
desktop's send-and-retry rules.
- `GVoice`/`Pb`/`Waa`: the desktop's Google Voice client ported to Java
(message ids hash identically, so copied history and new messages line up).
- Background: `Alarms` (AlarmManager, interval from Settings, "Never" = pull
to refresh only) → `PollJob` → notifications for new incoming messages.
- The launcher icon is `bubble.jpg` cut to just the bubble (transparent outside
an ellipse fitted to the rim's outer edge, pixels inside untouched), at 192 px
in `res/drawable-nodpi/ic_launcher.png`. The desktop's `resources/icon.png`
keeps the full square photo.
- 📎: press it and Camera / Photo / Voice note bubble out of it
(`AttachBubble`); drag onto one and let go, or tap the clip and then tap one. Camera
shots go through the Rabbit's camera app into MediaStore and are deleted
from the gallery once they're in the tray.
- Voice notes (📎 → Voice note): `VoiceActivity` records AAC `.m4a` (32 kbit/s,
3 min cap, under `Media.BUDGET`) and sends it as an MMS. voip.ms numbers
only: Google Voice's sendsms takes image types and nothing else, so a Google
Voice chat's bubble has no microphone.
- Search: pull the chat list down past its top for the search box (it hides
again on Back). Matches what a chat is called (your name for it, the
person, a number), then group chats with a matching member; archived too.
- Swipes (`SwipeActions`): left to right archives (blue band), right to left
marks unread or read (magenta band).
- Opening a chat shows its newest 60 messages first, then the full history;
marking it read (and telling Google Voice) waits until it's on screen.
- SIM card (`Sim`, `Pdu`): the third source, while bubble is Android's default
texting app (Settings → SIM card asks for that). Chats are did `sim` ("via
SIM"). Android's shared message store (`content://sms`, `content://mms`) stays
the record, as a default SMS app must keep it: `SmsReceiver`/`MmsReceiver`
write incoming messages there and sends are written there too, then `Sim.sync`
copies whatever is new into `Store` (ids `2^51 + _id` for SMS, `2^51 + 2^49 +
_id` for MMS). The phone's existing texts come over the first time, and an
Install to Rabbit that replaces messages.db just copies them in again. MMS
photos are read from the store when first shown (`mmspart:` refs). `Pdu`
reads/writes the MMS wire format (no libraries); `SmsManager` does the carrier
side, through `MmsFiles`. Long texts go as multipart SMS; photos, voice notes
and group chats as MMS (needs mobile data on). The dev app's sandbox never
uses the SIM.
- Relay (`Relay`, `RelayJob`): the desktop's link through jai (its
`src/main/relay.ts`, server `server/bubble_relay.py`). config.json's `relay`
(address, token, AES-256-GCM key) comes from Sync to Rabbit. The SIM's
messages go to the desktop, sends typed there go out here (each one at most
once, and not after a day), chat names and read status go both ways, and
older photos are sent when the desktop asks. For the battery it has no timer
of its own: it rides along with `PollJob`'s checks, plus one network job a few
seconds after something happens here (a text in, a send done, a swipe or
rename), and a catch-up when the app is opened (at most once a minute). Plain
http is allowed only to jai's tailscale address and localhost
(`res/xml/network_security_config.xml`).
- The scroll wheel is left alone: it stays the volume control (and volume
down + the side button still takes a screenshot).