From 2edd86e4fdbd5a369028ab1106f052d6ae2b5870 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 4 Aug 2026 19:41:49 +0000 Subject: [PATCH 2/2] docs: layperson User Guide (mesh setup / join / predicate authoring) An end-user-facing guide advertising the three core workflows in plain language, committed alongside the developer docs so it is durable + referenceable + editable (not an ephemeral artifact). Cross-linked from the architecture manifest; mirrors the technical sequences in docs/architecture/09-workflows.md. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01WppuiKZt4CuQxX4N7k6SVR --- docs/architecture/README.md | 5 +- docs/user-guide.md | 157 ++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 2 deletions(-) create mode 100644 docs/user-guide.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 974a06a..a5366f8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -12,8 +12,9 @@ [06](06-server-and-telemetry.md) → [07](07-client-app-and-rendering.md) → [08](08-contributing.md) → [09](09-workflows.md). - **Touching a file?** Find it in the **Source-of-truth map** below → open that doc first. -- **Want the user's-eye view?** The workflows in [09](09-workflows.md) mirror the - layperson guide (mesh setup, client join, predicate authoring). +- **Want the user's-eye view?** The end-user [User Guide](../user-guide.md) advertises the + same three workflows (mesh setup, client join, predicate authoring) in plain language; + [09](09-workflows.md) is their technical-sequence counterpart. ## The doc set diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..5e949fc --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,157 @@ +# Aether — User Guide + +*Turn a room and a handful of phones into a shared, centimetre-accurate map of who's +where — and let people point at things to make them happen.* + +Aether is an indoor positioning system. Where GPS gives you a blue dot on a street, +Aether gives you a **precise 3-D position indoors** — good to a few centimetres — for every +device in a "mesh." Your phone measures tiny radio time-of-flight distances to nearby +**anchors** and peers over Ultra-Wideband (the same tech that finds a lost tag), blends +that with its motion sensors, and everyone agrees on one shared coordinate frame. Then the +app shows a live 3-D / first-person view of the space and lets you **point at people or +places** to trigger events. + +- **No internet required to run.** A mesh forms device-to-device over local Wi-Fi/UWB. + The cloud is optional (for accounts, dashboards, and shared trust). +- **Private by design.** Positions are computed on your devices. The optional cloud link + sends health metrics, not your live location, unless you opt into full traces. +- **Roles that make sense.** *Anchors* are the fixed reference points that build the map; + *clients* are the people moving through it. + +--- + +## Three things you can do + +| I want to… | Go to | +|------------|-------| +| Build a new space (place anchors, calibrate) | [Set up a mesh](#1-set-up-a-mesh) | +| Walk into someone else's space and appear on the map | [Join a mesh](#2-join-a-mesh) | +| Make "point at that" or "enter this zone" trigger things | [Author a predicate](#3-author-a-predicate) | + +--- + +## 1 · Set up a mesh + +*You're the host. You'll place a few anchor devices around the room and teach the app where +they are, until the map "locks."* + +```mermaid +flowchart LR + A["① Create the mesh
(name it)"] --> B["② Add anchors
(invite devices)"] + B --> C["③ Place them
in the room"] + C --> D["④ Enter the layout
(measure & type in)"] + D --> E["⑤ Calibrate
→ map LOCKS ✓"] +``` + +1. **Create the mesh.** Open **Meshes ▸ +**, give it a name, pick who can see it (public, + protected, invisible, private). Your device becomes the **root anchor** — the origin of + the map. No account needed. +2. **Add anchors.** Anchors are devices that stay put and form the reference frame. Have + other devices [join](#2-join-a-mesh), then in **Requests** tap *invite as anchor*; they + accept. +3. **Place them.** Put the anchors around the space — spread out, not in a straight line, + ideally with one raised up. Good spread = an accurate map. +4. **Enter the layout.** Open **Diagnostics ▸ Layout** and type in each anchor's real + position (e.g. corner-to-corner distances). This "ground truth" is what makes Aether + *accurate* rather than merely consistent. A live fit score tells you when it's right. +5. **Calibrate to a lock.** The app measures the anchors against each other and locks the + frame. You'll pass through **Calibrating → Pre-quorum → Quorum**; at **Quorum** (3+ + anchors) the map is trustworthy and self-heals if an anchor is bumped or leaves. + +> As the host you land on the **Diagnostics** screen by default — it shows the mesh building +> in real time (link strengths, geometry quality, calibration), which is exactly what you +> want while setting up. + +--- + +## 2 · Join a mesh + +*You're a guest. You'll find the space, join it, and appear on the map once your phone +figures out where it is.* + +```mermaid +flowchart LR + A["① Discover
nearby meshes"] --> B["② Join / request"] + B --> C["③ Get admitted
(secure key)"] + C --> D["④ Your phone
locates itself"] + D --> E["⑤ The 3-D scene
appears ✓"] +``` + +1. **Discover.** Open **Meshes ▸ Discover**. Nearby meshes appear automatically (they + announce themselves over the local network). +2. **Join or request.** Public meshes join instantly; protected ones send a request the + host approves. +3. **Get admitted securely.** On approval you receive an encrypted key so your traffic is + private to the mesh. (To go online with an account, the app also fetches and pins the + mesh's security certificate — automatic.) +4. **Your phone locates itself.** As you range the anchors, the mesh computes your position + and your phone "self-seeds" from it, then smooths it with your motion sensors. +5. **The scene appears.** Until your phone is confident where it is, you'll see a friendly + *"Acquiring mesh… / Locating this device…"* hold screen — **not** a wrong map. The moment + it's ready, the live **3-D and first-person** view opens: anchors, people, and any shared + objects, all in their real places. + +> That hold screen is deliberate. A guest is never shown a jittery, wrong position that +> *looks* real — you either see the correct scene or an honest "getting ready." + +--- + +## 3 · Author a predicate + +*Predicates are the "if this, then that" of space. Two kinds: **point at** something, or +**enter a zone**.* + +```mermaid +flowchart LR + A["① Pick a predicate
(point-at / zone)"] --> B["② Aim or place it"] + B --> C["③ Share to the mesh"] + C --> D["④ Everyone's device
watches for it"] + D --> E["⑤ It fires ✓
(you light up)"] +``` + +**Point at a person or place** + +1. Open **Predicates**. +2. Choose *Point at a location* or *Point at *. +3. **Aim your phone** — the back of the phone is the "wand." Hold steady on the target for a + moment. +4. The predicate is shared mesh-wide, and **every device watches for it**. When your aim + lands within the target for the dwell time, it **fires** — you light up as the one + pointing (the *actor*), and the person you pointed at lights up as the *target*. + +**Create a zone (region)** + +1. Define a shape — a **sphere, box, or line** — somewhere in the space. +2. Share it to the mesh. Now whenever anyone **enters or exits** that zone, an event fires. +3. Behind the scenes the mesh's leader double-checks each event against its own precise + history and confirms it, so a brief glitch never triggers a false alarm. + +> Predicates are how Aether becomes *interactive*: proximity greetings, "you've entered the +> lab" reminders, point-to-select, spatial games — all built on the same shared frame. + +--- + +## What "good" looks like + +- **Anchors** spread around the room, one raised, real positions entered → an accurate, + **locked** map that survives a bump. +- **Clients** that walk in, briefly see "locating…", then a smooth, correct 3-D/first-person + view that tracks as they move. +- **Predicates** that fire crisply when you point or cross a zone, and not otherwise. + +## Frequently asked + +- **Do I need special hardware?** A phone with Ultra-Wideband (UWB). Anchors are just phones + that stay put; dedicated UWB anchors work too. +- **Does it work without internet?** Yes — a mesh forms locally. Online adds accounts, + shared trust, and dashboards. +- **Is my location uploaded?** No — positions are computed on your devices. Only health + metrics go to the optional cloud, unless you turn on detailed traces. +- **Why is the guest screen "holding"?** Your phone hasn't finished locating itself yet. + It's protecting you from a wrong map; it clears in seconds once the anchors have you. + +--- + +*Developers: the systems behind each step are documented in +[`docs/architecture/`](architecture/README.md) — the same three workflows appear there as +technical sequences in [09-workflows](architecture/09-workflows.md).* -- 2.43.0