Aether

- **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.

# 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<br/>(name it)"] --> B["② Add anchors<br/>(invite devices)"]

B --> C["③ Place them<br/>in the room"]

C --> D["④ Enter the layout<br/>(measure & type in)"]

D --> E["⑤ Calibrate<br/>→ 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<br/>nearby meshes"] --> B["② Join / request"]

B --> C["③ Get admitted<br/>(secure key)"]

C --> D["④ Your phone<br/>locates itself"]

D --> E["⑤ The 3-D scene<br/>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<br/>(point-at / zone)"] --> B["② Aim or place it"]

B --> C["③ Share to the mesh"]

C --> D["④ Everyone's device<br/>watches for it"]

D --> E["⑤ It fires ✓<br/>(you light up)"]

```

**Point at a person or place**

1. Open **Predicates**.

2. Choose *Point at a location* or *Point at <person>*.

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).*