Skip to content

Never substitute invented motion for a missing sensor - #7

Merged
guilyx merged 3 commits into
mainfrom
feat/sleepy-carson-5qmnnj
Sep 14, 2026
Merged

guilyx merged 3 commits into
mainfrom
feat/sleepy-carson-5qmnnj

Conversation

@guilyx

@guilyx guilyx commented Sep 14, 2026 •

Copy link
Copy Markdown
Owner

What this changes

Three fixes, all found by using the thing rather than reading it.

  1. motion.source = "auto" no longer falls back to the synthetic demo source when the machine has no accelerometer.
  2. motionless stop could hang and leave the daemon running.
  3. The installer no longer prints a pip failure for a package that is simply not published yet.

1. Auto-detection must not invent motion

Found while answering a question about onboard sensors, on a laptop with no accelerometer.

demo replays a scripted drive. Auto-detection fell back to it whenever /sys/bus/iio had nothing — which is most laptops. In a moving vehicle those cues disagree with the motion the passenger actually feels: a worse sensory mismatch than no cues at all, and precisely the mismatch that causes motion sickness.

The failure mode is what makes it serious. Dots move, so it looks like it is working. Someone with no accelerometer would have started it in the car, seen exactly what the demo recording shows, and spent the journey being made sicker by the thing meant to help. Nothing in the overlay would have told them.

The original reasoning — "an overlay that visibly does something is easier to debug than one that silently does not" — was written for a first run at a desk. It is the wrong trade in the situation this program exists for.

Before After
Accelerometer present iio iio
No accelerometer demo, silently none — draws nothing, explains why
--source demo demo demo, unchanged

AUTO_ORDER is now (IioSource,) with the reasoning in a comment, so nobody helpfully adds demo back. NullSource parks until stopped and emits nothing, making "no sensor" a state the daemon and status report rather than one inferred from silence. doctor gains a row:

! Source: iio           no accelerometer found under /sys/bus/iio/devices
! Auto-detected source  none — no accelerometer on this machine, so no cues will appear
                        → stream from a phone: `motionless config set motion.source udp`

2. motionless stop could hang

The quit was scheduled with GLib.idle_add, which runs at PRIORITY_DEFAULT_IDLE (200). The overlay redraws on a GLib.timeout_add at PRIORITY_DEFAULT (0) — a higher priority. While drawing keeps the main loop busy, the idle callback below it never gets a turn: the daemon acknowledges quit and then runs forever.

It needs a machine slow enough that a frame takes most of the frame interval, which is why it had not surfaced — every previous run drew comfortably inside 16 ms. The CI runner on #5 did not: it took eleven seconds just to open the overlay, then ignored quit until the test killed it, failing with daemon did not stop on request.

A laptop on battery with the governor throttling is the same shape of machine. Quit is now scheduled at PRIORITY_HIGH, and a test pins the ordering by asserting the priority is above PRIORITY_DEFAULT rather than merely that something was scheduled.

This is also what is blocking #5, which is red through no fault of its own.

3. The installer's fake failure

A real install printed this, then succeeded:

Fatal error from pip prevented installation.
    ERROR: No matching distribution found for motionless-overlay
Error installing motionless-overlay.

That is pipx's wording for "this package does not exist". The git fallback worked, but it reads as a hard failure. The installer now asks the PyPI JSON API whether the package exists before handing the name to pip, and goes straight to the repository while it does not — switching to PyPI on its own once the first release lands, with no edit needed. MOTIONLESS_SOURCE now takes auto (default), pypi or git.

How it was tested

  • make check: ruff, ruff format, mypy strict, 345 tests.

  • New tests: auto returns NullSource rather than DemoSource when iio probes unavailable; DemoSource asserted absent from AUTO_ORDER; NullSource emits nothing and stops promptly; doctor surfaces the no-sensor case as a warning carrying the udp way out; quit is scheduled above PRIORITY_DEFAULT.

  • Two existing tests encoded the old fallback (detect() in AUTO_ORDER, and doctor's source list). Updated to the new contract rather than deleted.

  • Installer: pypi_has_package checked against a published package (requests → found) and ours (motionless-overlay → not found); shellcheck and bash -n clean.

  • The smoke job's shutdown timeout goes 10s → 45s and now says what a timeout means, so slow and stuck stop looking alike.

  • make check passes

  • Tested by hand on: Ubuntu 24.04 container with no accelerometer — the path fix 1 addresses

Checklist

  • New behaviour has tests
  • CHANGELOG.md updated under ## [Unreleased]
  • Documentation updated

Notes for review

  • Fix 1 is a behaviour change, listed under ### Changed: anyone relying on auto giving them the demo loop now gets nothing until they pass --source demo. That is the intent, and the README's own demo instructions already name the source explicitly.
  • Still no hardware coverage for iio — it is tested against a fake sysfs tree. Whether a real laptop accelerometer is found, and whether the default axis mapping suits it, is unverified.
  • iio only reads /sys/bus/iio. Some older laptops expose accelerometers through lis3lv02d or ThinkPad hdaps instead, which this would not find. Worth adding if a real machine turns out to need it.

`motion.source = "auto"` fell back to the synthetic `demo` source when no
accelerometer was found. That was written for a first run at a desk, where an
overlay that visibly does something beats one that silently does not. It is the
wrong behaviour in the situation this program exists for.

`demo` replays a scripted drive. In a moving vehicle those cues disagree with
the motion the passenger actually feels, which is a worse sensory mismatch than
no cues at all — precisely the mismatch that makes people ill. Worse, it is
invisible: dots move, so it looks like it is working, and the trip is spent
being made sicker by the thing meant to help.

Auto-detection now uses `iio` when the machine has an accelerometer and
otherwise selects an explicit null source that draws nothing. The daemon logs
why at startup, and `doctor` names the source it chose and points at the phone
route when there is none. `demo` stays available when asked for by name, which
is how the README and the capture scripts already use it.

Also: the installer asked pip for `motionless-overlay` before checking whether
it is published, so a real install printed pipx's "Fatal error from pip
prevented installation" and "Error installing motionless-overlay" before the
fallback quietly succeeded. It reads as a hard failure. It now asks the PyPI
JSON API first and goes straight to the repository while the package does not
exist, and starts using PyPI on its own once it does.
The quit was scheduled with GLib.idle_add, which runs at
PRIORITY_DEFAULT_IDLE. The overlay redraws on a GLib.timeout_add, which is
PRIORITY_DEFAULT — a higher priority. While drawing keeps the main loop busy,
the idle callback below it never gets a turn, so the daemon acknowledges the
quit and then carries on running forever.

It needs a machine slow enough for a frame to take most of the frame interval,
which is why it had not shown up: every previous run drew comfortably inside
16ms. A loaded CI runner did not. It took eleven seconds just to open the
overlay, and the daemon then ignored `quit` until the test killed it.

The quit is now scheduled at PRIORITY_HIGH, above the redraw, so it cannot be
starved. A test pins the ordering by asserting the scheduled priority is above
PRIORITY_DEFAULT rather than merely that something was scheduled.

The smoke job's shutdown timeout goes from 10s to 45s and says what it means
when it expires — the reply was sent, so a timeout means the loop did not act
on it. A slow shutdown and a stuck one should not look the same.
`motionless config set` triggers a reload, and reload tore down and rebuilt
every overlay window whether or not anything about the geometry had changed.
On a loaded machine that takes longer than the control socket's three-second
timeout, so the client raised while the daemon went on and applied the change
correctly. The user sees an error for something that worked.

The raised error also skipped whatever the caller meant to do next, which is
how this surfaced: CI's smoke test never reached its `quit`, the daemon kept
running, and the failure presented as a shutdown that hung. I chased that
first and fixed a real but unrelated priority-inversion in the quit path
before spotting the actual cause, which was two lines earlier.

Reload now restyles the windows that already exist and recomputes their
resting positions, and only tears anything down when the set of monitors to
cover changes. Commands that do real work get a longer client timeout as
defence in depth: giving up early is worse than waiting, because the work
happens anyway.

Reproduced by making reload take five seconds, which fails identically to CI;
both the reproduction and the real smoke script pass with this.

Also fixes the overlay connecting a pair of monitor-added/removed handlers on
every start and never disconnecting them, and rewrites CI's timeout message,
which asserted the reply had been sent when that was exactly what had not
happened.
@guilyx
guilyx marked this pull request as ready for review September 14, 2026 16:52
@guilyx
guilyx merged commit 2cbb0d8 into main Sep 14, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant