chatter/README.md

# Chatter

A minimal, purpose-built writing interface for the **reMarkable Paper Pro Move**
(model RM03A), used as an **assistive-speech device**: the user writes, her
conversation partner reads. Chatter *augments* the stock reMarkable software; it
does not replace it.

**Start here.** This README is the entry point — it takes you from a clone to
Chatter running on a tablet, and everything else you might need is one of these
links. You should not need any information that isn't in this repository.

- **Install / test it on a tablet** → keep reading (**Quick install**, below).
- **What the user sees and how she uses it** →
  [`doc/Chatter_user_guide.md`](doc/Chatter_user_guide.md)
- **How it works, or to modify the code** →
  [`doc/Chatter_technical_reference.md`](doc/Chatter_technical_reference.md)
  — the complete master document; it links every other doc.
- **Project plan & history** →
  [`doc/Chatter_implementation.md`](doc/Chatter_implementation.md)

## Get the code

```
git clone git@git.andykopra.com:ack/chatter.git
cd chatter
```

Cloning needs an account on the Gitea server at `git.andykopra.com` with read
access to `ack/chatter`, and your SSH public key added to it (Gitea → Settings →
SSH Keys). HTTPS also works: `git clone https://git.andykopra.com/ack/chatter.git`.

The clone gives you the code only. Tablet access (root password, IPs) comes from
*your own* tablet's Copyright-and-licenses screen, not from this repo — see
**Quick install** step 1.

## Repository layout

```
dist/     Prebuilt tablet binaries (ready to install — see Quick install)
src/      C++ sources (ink engine, framebuffer capture, pen reader, …)
qml/      Qt Quick UI (the static Back/Clear bar + touch handling)
tools/    Standalone helpers (the return-to-Chatter launcher, probes)
scripts/  Build, deploy, and install scripts
doc/      Documentation (the technical reference has a full document map)
```

---

## Quick install (prebuilt binary — no build needed)

For installing/testing on a tablet, you do **not** need to build anything. The
repo ships ready-to-run aarch64 binaries in [`dist/`](dist/) (`dist/chatter`,
`dist/chatter-launcher`). You just need SSH access to the tablet.

### 1. One-time device setup

On the tablet (this **factory-resets** it — back up / sync first):

1. **Enable developer mode:** Hamburger menu → Settings → Software → Advanced →
   Developer mode → Accept. (Details: [`doc/developer_mode_screen.md`](doc/developer_mode_screen.md).)
2. Reconnect wifi (the reset wipes it).
3. Get the root credentials: Settings → Help → **Copyright and licenses** →
   under **GPLv3 Compliance** (root username, password, and the device IPs).
4. **Enable SSH over wifi** (off by default): connect over USB (`10.11.99.1`),
   SSH in, run `rm-ssh-over-wlan on`.
5. Add your workstation's SSH public key to the tablet's
   `/home/root/.ssh/authorized_keys`.

### 2. Point the `chatter` SSH alias at the tablet

In your `~/.ssh/config`:

```
Host chatter
    HostName 192.168.x.x          # the tablet's wifi IP (or 10.11.99.1 over USB)
    User root
    IdentityFile ~/.ssh/id_ed25519
```

> The tablet's wifi IP can change (DHCP), and it drops wifi when asleep. If
> `ssh chatter` stops connecting, wake the tablet and re-check the IP on the same
> **Copyright and licenses → GPLv3 Compliance** screen (a DHCP reservation on your
> router avoids this).

### 3. Install

```
scripts/deploy-and-run.sh      # copies dist/chatter and launches it on the panel
scripts/install-launcher.sh    # installs the persistent 4-finger return launcher
```

`scripts/restore-xochitl.sh` returns to the standard reMarkable GUI at any time.

> Each tablet has its **own** root password, IP, and MAC, shown on **its own**
> Copyright-and-licenses → GPLv3 Compliance screen (see step 1.3). Read them off
> *your* tablet — nothing about credentials comes from this repo or from anyone
> else. (`doc/tablet_access.md` is gitignored and is only a developer's private
> copy of their own tablet's screen.)

---

## Building from source

Only needed if you're **changing the code**. Chatter is a Qt 6 app
**cross-compiled** to the tablet's aarch64 CPU; you build on a host and copy the
binary over.

### Prerequisites

1. **A Linux host** (the reMarkable SDK is a Yocto toolchain — Linux only).
2. **The reMarkable "Chiappa" SDK** (cross-compiler + Qt 6.8.2 sysroot, ~486 MB),
   from developer.remarkable.com. Install it, e.g.:
   ```
   ./remarkable-…-chiappa-…-toolchain.sh -d ~/external/remarkable-sdk/chiappa-3.27.0.97
   ```
   The confirmed **x86_64-host** build is:
   `https://storage.googleapis.com/remarkable-codex-toolchain/3.27.0.97/chiappa/remarkable-production-image-5.7.119-chiappa-public-x86_64-toolchain.sh`
   An **aarch64-host** variant exists at the same path with `x86_64`→`aarch64`
   (confirm the exact link on developer.remarkable.com).

### Build & deploy

```
CHATTER_SDK=/path/to/chiappa-sdk scripts/build.sh   # -> build/chatter + tools/chatter-launcher
scripts/deploy-and-run.sh                            # prefers build/chatter when present
scripts/install-launcher.sh
```

### Building from macOS (Linux container)

There is **no macOS build of the reMarkable SDK**, so build inside a **Linux
container**. The cross-compiled output targets the tablet either way; only the
*host* running the SDK must be Linux.

1. Install a container runtime — **OrbStack** or **Docker Desktop**.
2. Start a Linux container matching your Mac's CPU and mount the repo:
   - **Apple Silicon Mac:** an **arm64** image (runs natively, no emulation):
     ```
     docker run -it --platform linux/arm64 -v "$PWD":/work ubuntu:24.04
     ```
     Inside it, install the **aarch64-host** Chiappa SDK.
   - **Intel Mac:** an **x86_64** image + the **x86_64** SDK.
3. In the container, install what the SDK/build need
   (`apt-get update && apt-get install -y build-essential cmake file which`),
   run the SDK self-extractor, then `cd /work && CHATTER_SDK=… scripts/build.sh`.
4. Deploy from the container (or from the Mac, if SSH to the tablet is set up
   there): `scripts/deploy-and-run.sh build/chatter`.

> This container route is the standard reMarkable cross-build approach but has
> not been verified end-to-end here — if you hit a missing-package error in the
> container, install that package and continue.

---

## Status

Working on hardware: stock-quality ink matching the selected pen, finger-wipe
erase, whole-page Clear, stylus eraser, bidirectional toggle with a persistent
return launcher, and vertical scrolling on a growable canvas. Open items (Save,
horizontal scroll/zoom, field tuning) are in the technical reference §10.