Skip to content
Open
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
9 changes: 9 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ _Avoid_: Fake iMotions
A second destination the **Relay** copies every packet to, so the Python side can read a flight while iMotions records it. The copy is best effort: packets are dropped if the mirror falls behind, and the iMotions stream is never held up for it (`docs/adr/0003`).
_Avoid_: Python stream, fan-out, secondary connection, sink

**Listener**:
The Python program that reads a **Flight**'s **Telemetry** from the **Relay**, through the **Mirror** or directly when there is no iMotions: the capture logger or live groups.
_Avoid_: Consumer, sink. "Sidecar" in `docs/adr/0004` means the live-groups listener only.

### Performance measurement

**Airspeed**:
Expand Down Expand Up @@ -98,6 +102,10 @@ _Avoid_: User, subject, participant
One continuous simulator session by one pilot.
_Avoid_: Session, run, trip

**Instructor**:
The person who gives the **Instructions** during a **Flight** and runs the software that records it.
_Avoid_: Host, operator, experimenter

**Pilot metadata**:
Facts about a pilot that are not telemetry: certification level, flight hours and pilot rating.
_Avoid_: Pilot profile, demographics
Expand Down Expand Up @@ -132,6 +140,7 @@ _Avoid_: Fake data, dummy data, mock data

- A **Pilot** flies many **Flights**; a **Flight** produces many **Samples**.
- A **Sample** has one value per telemetry field, and one **Deviation** per **Flight dynamics factor** once a **Target** exists.
- An **Instructor** gives a **Flight**'s **Instructions** in the order its **Brief** lists them.
- A **Flight** is divided into **Segments**, and is also flown as a sequence of **Legs**. A **Brief** lists its **Instructions** in order.
- An **Instruction** sets new **Targets** from the moment it is given. The targets it changes are not scored during its **Settle window**.
- A **Pilot** falls into exactly one **Performance group**, decided by their **Deviation features** alone. A pilot outside the **Reference cohort** is placed in the nearest group without changing the groups.
Expand Down
22 changes: 20 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,15 +109,16 @@ Then, in order:
- A literal IP address and port are required. A host name such as `localhost:5050` is rejected.
- Addresses that connect successfully are remembered in the `Saved IPs` dropdown (stored on Windows at `%APPDATA%\PilotDataSynchronization\relay_ips.json`).
4. Press `Connect TCP`.
5. Press `Check TCP Connection Status` to refresh the status line. It does not update by itself. This button is the only thing that changes it.
5. Press `Check TCP Connection Status` to refresh the status line. It is also updated when the connection is made or lost, but this button is the way to refresh it.
6. Start X-Plane. Flight data now flows automatically.

> The `Send Packet` button sends one test packet of zeros, for example `E;1;PilotDataSync;;;;;AltitudeSync;0;0`, and shows the time it was sent next to the button. The sample is the first dataref toggle that is enabled, so the packet always matches a `<Sample>` in the generated `iMotions.xml`. It is a connection check and needs TCP connected, not X-Plane. Avoid pressing it during a recording, since iMotions receives the zeros as a real sample. The live data stream is automatic and does not need this button.

Two more behaviors that catch people out:

- The eight dataref toggles do not affect what is sent over TCP. All eight values are always transmitted. The toggles control only which `<Sample>` entries appear in the generated `iMotions.xml`.
- Losing X-Plane also tears down the TCP connection. After restarting the simulator, press `Connect TCP` again.
- Losing X-Plane also tears down the TCP connection. After restarting the simulator, press `Connect TCP` again, unless the relay was started with `--tcp` (see below), which reconnects by itself.
- A TCP connection made by clicking now shows a drop too. If iMotions or the listener goes away, the event log says `TCP disconnected` and `Connect TCP` works again. Only outputs given on the command line are retried.

### Sending to iMotions and Python at the same time

Expand All @@ -137,6 +138,23 @@ With no iMotions to record to, skip the mirror and point `Connect TCP` straight

`Send Packet` goes to both destinations, which makes it a check of both links. It also means the logger writes a row of zeros, so avoid it mid-recording.

### Starting with the outputs already connected

Two optional options connect the relay's outputs when it starts, so nobody has to find the right box and button:

```bash
cd relay
cargo run -- --tcp <iMotions ip:port> --mirror 127.0.0.1:5001 # iMotions, and the Python side as the mirror
cargo run -- --tcp 127.0.0.1:5001 # no iMotions: straight to the Python listener
```

(With a built relay, the same options follow `relay`.) Addresses are a literal IP and port, as in the boxes. `--mirror` needs `--tcp`, because the mirror copies the TCP stream. `relay --help` prints the usage.

- Each output given is retried until it connects, and again after it drops, a connection that was up at once. A listener that starts late, or is restarted mid-Flight, is picked up with no clicks, and the relay window says it is waiting for the address and retrying. The relay itself keeps running, because the plugin cannot reconnect to a relay that has restarted (`docs/adr/0005`).
- While the mirror is down the iMotions stream is not held up, and the event log gets one line for the whole run of failed attempts, not one per attempt.
- `Disconnect TCP` stops the retrying, and the mirror's with it. `Disconnect mirror` stops only the mirror's. Pressing `Connect TCP` or `Connect mirror` yourself takes that output over: it is connected as the button always did, and is not retried to the command-line address afterwards.
- Without options nothing changes: the relay waits for you to click.

## 3. iMotions

With the relay running, generate the event-source definition that iMotions needs:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ What is guaranteed: the TCP thread never waits on the mirror. Connecting, writin

A mirror falling behind is reported once when it starts dropping and once when it catches up, not per packet, because the event log is capped at 200 entries and 160 packets a second would empty it.

The Python side has to read its socket continuously, on a thread of its own if it also does slow work. A clustering refit that stops reading for long enough will first lose copies and then, once the write timeout expires, lose the mirror, which does not reconnect by itself.
The Python side has to read its socket continuously, on a thread of its own if it also does slow work. A clustering refit that stops reading for long enough will first lose copies and then, once the write timeout expires, lose the mirror.

Nothing reconnects the mirror automatically. If Python restarts, press `Connect mirror` again.
A mirror connected by clicking is not reconnected: if Python restarts, press `Connect mirror` again. A mirror given with `--mirror` on the command line is retried until it connects and again after it drops (#276, docs/adr/0005).

`Send Packet` reaches both destinations, so it checks both links at once, and it writes a row of zeros to the logger as well as to iMotions.

Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0004-live-clustering-runs-in-a-python-sidecar.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,5 @@ To update **Performance groups** while a **Flight** is under way, the relay forw
- The sidecar reads the relay's **Mirror** (docs/adr/0003), so the relay already forwards to iMotions unchanged when the sidecar is absent or slow. The copy is best effort, so the sidecar must tolerate dropped samples and must keep reading its socket on a thread separate from the slower work, or it loses the mirror.
- The return channel (how the sidecar tells the relay a pilot's group) is not decided here.
- The groups are fitted once and the live pilot is assigned to the nearest one, rather than refitting with the live pilot included. A refit would renumber the groups between updates, and one live pilot cannot form groups alone (`candidate_ks` needs 6). Until real pilots have **Targets**, the reference cohort is **Synthetic pilots**, so the live group is a demonstration rather than a measurement.
- The client's **Targets** are not available (`docs/telemetry_schema.md` section 3). For our own X-Plane flights we are the instructor: we write a **Brief** of **Instructions**, and the operator marks each one live as it is spoken, so the sidecar knows when every target starts. The targets an instruction changes are not scored during its **Settle window**, so the turn or level-off is not scored, since **Synthetic pilots** fly only steady holds. Targets it leaves alone are scored throughout.
- The client's **Targets** are not available (`docs/telemetry_schema.md` section 3). For our own X-Plane flights we are the **Instructor**: we write a **Brief** of **Instructions** and mark each one live as it is spoken, so the sidecar knows when every target starts. The targets an instruction changes are not scored during its **Settle window**, so the turn or level-off is not scored, since **Synthetic pilots** fly only steady holds. Targets it leaves alone are scored throughout.
- If the sidecar is later judged too heavy to run beside the relay, this decision should be revisited, since porting to Rust then means re-validating the clustering against ADR 0002's evidence.
16 changes: 16 additions & 0 deletions docs/adr/0005-the-relay-outlives-the-listener.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# The relay outlives the listener and retries its outputs

Status: accepted. The relay's side is #276; the launchers and the listeners' resume are planned in #278 and #277.

The launchers start the **Relay** as its own process, apart from the Python listener (`data_logger` or `live_groups`). They leave it running when the listener stops, and reuse it if it is already running. Given `--tcp` or `--mirror`, the relay keeps retrying that address until it connects, and again after a drop, so a listener started again mid-**Flight** is picked up with no clicks. We chose this because the **Plugin** cannot reconnect to a relay that has restarted (#256, #255): a relay that closed with its listener would cost the **Instructor** an X-Plane restart mid-**Flight**. In the lab, closing the console window is how people stop a listener.

## Considered Options

- **One launch is one Flight** (the relay closes when the listener stops). Rejected. It is simpler and every Flight starts clean, but a listener that crashes or has its window closed takes the relay with it, and recovering then means restarting X-Plane or re-enabling the plugin in Plugin Admin.
- **Relay outlives the listener (chosen).** A restarted listener costs nothing in X-Plane. The relay is closed by hand, for example at the end of the day.

## Consequences

- A relay that is already running keeps the addresses it started with. The launcher does not ask for an iMotions address in that case; it says so, and changing the address means closing the relay.
- Restarting a listener mid-flight must keep the same `flight_id`, or one **Flight** splits into two. The launcher offers to resume when the last Flight did not end with `q`, and `live_groups` then continues the **Brief** from the last **Instruction** given.
- A crash of the relay itself still forces a plugin restart until #256 and #255 are fixed. Once they are, this decision still stands, since it avoids reconnecting at all.
6 changes: 3 additions & 3 deletions inference/pilot_inference/performance/live.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
"""
Deviation features for one flight while it is being flown (docs/adr/0004).

For flights we fly ourselves we are the instructor, so we know the targets: a
brief lists the instructions with the targets each one sets, and the operator
marks each one as it is spoken. Targets an instruction does not name carry
For flights we fly ourselves we are the Instructor, so we know the targets: a
brief lists the instructions with the targets each one sets, and we mark each
one as it is spoken. Targets an instruction does not name carry
over. LiveFlight attaches the targets in force to every sample, leaving the
ones an instruction changed blank for a settle window so the turn or level-off
is not scored, and summarises the scored samples with the same functions the
Expand Down
11 changes: 7 additions & 4 deletions inference/pilot_inference/performance/live_groups.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
Show a pilot's performance group while they fly (docs/adr/0004).

Listens for the relay's mirror (or Connect TCP), assembles samples the way the
capture logger does, attaches the brief's targets as the operator marks each
capture logger does, attaches the brief's targets as the Instructor marks each
instruction, and writes every sample to CSV. Every few seconds it prints the
pilot's deviation features and the nearest group of a reference cohort. The
cohort is synthetic until real pilots have targets, so the group demonstrates
Expand Down Expand Up @@ -184,15 +184,18 @@ def _serve(self) -> None:
pass
except (OSError, ValueError) as error:
# Garbled bytes or a socket error end this connection, not the
# listener: the mirror never reconnects by itself (docs/adr/0003),
# so the next Connect mirror must still find someone listening.
# listener: the relay may reconnect (with --mirror it does so by
# itself, docs/adr/0005), and must still find someone listening.
if not self._closed:
print(f"Relay connection failed: {error}")
with self._lock:
self._conn = None
if self._closed:
return
print("Relay disconnected. Press Connect mirror again to resume.")
print(
"Relay disconnected. A relay started with --mirror reconnects by itself; "
"otherwise press Connect mirror again."
)


def _cell(value) -> str:
Expand Down
Loading
Loading