Skip to content

Use the phone as the sensor, with nothing to install on the phone - #9

Merged
guilyx merged 1 commit into
mainfrom
feat/sleepy-carson-5qmnnj
Sep 15, 2026
Merged

guilyx merged 1 commit into
mainfrom
feat/sleepy-carson-5qmnnj

Conversation

@guilyx

@guilyx guilyx commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

What this changes

Adds motionless pair and a phone motion source. Your phone's accelerometer
becomes the overlay's sensor, and there is nothing to install on the phone —
it opens a page in its normal browser, and that page reads DeviceMotionEvent
and posts the readings back.

$ motionless pair
Paired over USB with R58M1234.

On the phone:
  1. open Chrome and go to  http://localhost:5577/
  2. tap "Start sending motion"
  3. wedge the phone somewhere fixed — a cradle or a cup holder

Why

Most laptops have no accelerometer. Since #7, motion.source = "auto" correctly
reports that there is nothing to follow and draws nothing rather than inventing
motion — which is right, but leaves the user with a working overlay and no
sensor.

The honest answer is not a worse sensor on the laptop. It is the good sensor
already in your pocket: a phone in the car's cradle is bolted to the vehicle,
where a laptop on your knees measures your knees.

Two routes, because of one browser rule

DeviceMotionEvent only fires in a secure context. That single constraint
produces the whole design, and pair picks the route for you:

Route Phones Setup Why it works
USB Android USB debugging, once adb reverse tcp:5577 tcp:5577 puts the laptop's port on the phone's own localhost, which browsers trust. No certificate, no network, no battery drain.
Wi-Fi iPhone and Android Accept a certificate warning, once A LAN address gets no such trust, so the page must be HTTPS. No CA will vouch for 192.168.x.x, so pair generates a self-signed certificate.

There is no USB route for iPhone, and this is not an omission: usbmuxd
forwards host-to-device only. iproxy lets the laptop reach a port on the
phone, not the reverse, and nothing in iOS forwards a phone-side port back to
the host without a jailbreak. Wi-Fi is the iPhone route.

Design notes

Batching. Phones report at ~60 Hz. Rather than a request per reading,
the page posts every 80 ms in groups of five. The resulting latency sits well
under motion.smoothing_tau (0.12 s), so it costs nothing visible — and no
WebSocket dependency.

Two clocks. The phone's clock is not ours and cannot be synchronised over a
link whose latency we do not measure. What is trustworthy is the spacing
between readings inside one batch, so a batch is anchored at its arrival time
and earlier readings are backdated by their own spacing. Timestamps that are
absent, out of order, or span implausibly long (a sender stamping in epoch
milliseconds) fall back to stamping on arrival.

What guards the Wi-Fi route, which binds to every interface:

  • a random pairing token required on every request — Config.validate() refuses
    a non-loopback bind without one;
  • HTTPS, so readings are not sent in clear;
  • posts must be Content-Type: application/json, and no CORS headers are ever
    sent. A hostile web page cannot quietly feed fake motion to a loopback-bound
    daemon, because that content type forces a preflight that is never answered.

iOS sign convention. iOS reports accelerationIncludingGravity with the
opposite sign to every other platform. The page flags its own platform and the
daemon applies the flip, with motion.phone.invert as the override. That
correction comes from the documented quirk and not from a test on real iPhone
hardware
— the README says so plainly and points at the override.

Two bugs found while testing, both older than this change

  • motionless restart could crash with Connection reset by peer instead
    of restarting. A daemon shutting down accepts the control connection and then
    dies before replying; is_running() raised on that rather than reading it as
    "not running", and restart polls is_running() against exactly that state
    while stopping its own predecessor. The phone source made it reproducible by
    taking fractionally longer to shut down; any source could have hit it.
  • The detached daemon wrote every log line twice. motionless start
    redirects the child's stderr into the log file, and the logger was also
    attaching a handler to that same file.

Also adds Config.update(), which applies several settings together and
validates once. Settings can constrain each other — a network bind needs a token
— so applying them one at a time rejected good combinations purely because of the
order they arrived in.

How it was tested

Beyond the suite, the parts that could not be unit-tested were driven for real:

The sender page's actual JavaScript, extracted and run against a stubbed DOM
under Node — not a reimplementation of it:

token baked in: true            devicemotion listener attached: true
flush timer interval (ms): 80   readings in one batch: 5
url: motion?t=demo0token        content-type: application/json
iOS inversion flagged: true     posts after a null reading: unchanged (dropped)

Its output through the Python parser, so the two halves agree rather than
each being independently plausible — the page's own batch JSON fed to
parse_report() / place_on_clock() gives back five samples with 16.7 ms
spacing preserved and the iOS flip applied.

The whole path against a live daemon on Xvfb + xcompmgr, over HTTPS with a
pair-generated certificate, posting the way the page posts:

source    phone          samples   185
motion    lat -3.17  long -3.51  vert +0.00 m/s²
phone     last reading 0.1s ago

10,786 pixels of the overlay differ between the still frame and the moving one.

restart under load, three times, with a phone streaming throughout — the
reproduction for the Connection reset by peer bug, green after the fix.

Both pair routes end to end with a stub adb: USB writes a loopback
config with no token and no certificate; Wi-Fi writes a token, 0.0.0.0 and a
real openssl certificate whose SANs cover the advertised address.

The page's layout at phone width — measured, not eyeballed:
scrollWidth=390 clientWidth=390 | overflowing: none.

  • make check passes (ruff, ruff format, mypy --strict, pytest, shellcheck)
  • Tested by hand on: not yet in a vehicle, and not yet on a real iPhone

Still unverified

No real phone has been paired, and nothing here has been tested in a moving
vehicle. The iOS sign flip in particular rests on a documented quirk rather
than on hardware.

Checklist

  • New behaviour has tests, or the PR explains why it cannot
  • CHANGELOG.md updated under ## [Unreleased]
  • Documentation updated if the change is user-visible

Most laptops have no accelerometer, so until now `motion.source = "auto"`
correctly reported that there was nothing to follow and drew nothing. The
honest answer to that is not a worse sensor on the laptop — it is the good
sensor already in your pocket. A phone in the car's cradle is bolted to the
vehicle; a laptop on your knees measures your knees.

`motionless pair` serves a small page that the phone opens in its normal
browser. The page reads DeviceMotionEvent and posts batches of readings back
over HTTP. No app, no store, no account.

One browser rule shapes the whole design: DeviceMotionEvent only fires in a
secure context. That gives two routes, and `pair` picks between them:

  USB (Android) — `adb reverse tcp:5577 tcp:5577` makes the laptop's port
  appear on the phone's own localhost, which browsers treat as trustworthy.
  No certificate, no network, no battery drain.

  Wi-Fi (iPhone, or Android without USB debugging) — a LAN address gets no
  such trust, so the page is served over HTTPS with a self-signed certificate
  generated on the machine. There is no USB route for iPhone: usbmuxd
  forwards host-to-device only, so nothing can point Safari back at the
  laptop over the cable without a jailbreak.

Batching, not one request per reading: phones report at ~60 Hz, so readings
are posted every 80 ms in groups of five. The resulting latency sits well
under motion.smoothing_tau, so it costs nothing visible, and the spacing
within a batch is preserved by anchoring the batch at its arrival time rather
than trying to synchronise two clocks over an unmeasured link.

What guards the Wi-Fi route, which binds to every interface: a random pairing
token required on every request (the config refuses a non-loopback bind
without one), HTTPS, and a required application/json content type with no
CORS headers ever sent — so a hostile web page cannot quietly feed fake
motion to the daemon, because the content type forces a preflight that is
never answered.

iOS reports accelerationIncludingGravity with the opposite sign to every
other platform. The page flags its own platform and the daemon applies the
flip, with motion.phone.invert as the override. That correction comes from
the documented quirk and not from a test on real hardware, which the README
says plainly.

Two bugs found while testing this, both older than it:

  `motionless restart` could crash with "Connection reset by peer" instead
  of restarting. A daemon shutting down accepts the control connection and
  then dies before replying; is_running() raised on that rather than reading
  it as "not running". The phone source made it reproducible by taking
  fractionally longer to shut down, but any source could have hit it.

  The detached daemon wrote every log line twice: `start` redirects the
  child's stderr into the log file and the logger also attached a handler to
  that same file.

Also adds Config.update(), which applies several settings together and
validates once. Settings can constrain each other — a network bind needs a
token — so applying them one at a time rejected good combinations purely
because of the order they arrived in.

Verified: the sender page's real JavaScript driven against a stub DOM
(iOS permission flow, batching, the iOS flag, null readings dropped), its
output fed through the Python parser, and the whole path run against a live
daemon over HTTPS — 10,786 pixels of the overlay move in response to
readings posted the way the page posts them.
@guilyx
guilyx marked this pull request as ready for review September 15, 2026 15:56
@guilyx
guilyx merged commit 85217cf into main Sep 15, 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