Repository navigation
Use the phone as the sensor, with nothing to install on the phone - #9
Merged
Merged
Conversation
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
marked this pull request as ready for review
September 15, 2026 15:56
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Adds
motionless pairand aphonemotion source. Your phone's accelerometerbecomes 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
DeviceMotionEventand posts the readings back.
Why
Most laptops have no accelerometer. Since #7,
motion.source = "auto"correctlyreports 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
DeviceMotionEventonly fires in a secure context. That single constraintproduces the whole design, and
pairpicks the route for you:adb reverse tcp:5577 tcp:5577puts the laptop's port on the phone's ownlocalhost, which browsers trust. No certificate, no network, no battery drain.192.168.x.x, sopairgenerates a self-signed certificate.There is no USB route for iPhone, and this is not an omission:
usbmuxdforwards host-to-device only.
iproxylets the laptop reach a port on thephone, 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 noWebSocket 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:
Config.validate()refusesa non-loopback bind without one;
Content-Type: application/json, and no CORS headers are eversent. 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
accelerationIncludingGravitywith theopposite sign to every other platform. The page flags its own platform and the
daemon applies the flip, with
motion.phone.invertas the override. Thatcorrection 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 restartcould crash withConnection reset by peerinsteadof 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
restartpollsis_running()against exactly that statewhile stopping its own predecessor. The phone source made it reproducible by
taking fractionally longer to shut down; any source could have hit it.
motionless startredirects 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 andvalidates 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:
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 msspacing 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:10,786 pixels of the overlay differ between the still frame and the moving one.
restartunder load, three times, with a phone streaming throughout — thereproduction for the
Connection reset by peerbug, green after the fix.Both
pairroutes end to end with a stubadb: USB writes a loopbackconfig with no token and no certificate; Wi-Fi writes a token,
0.0.0.0and areal 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 checkpasses (ruff,ruff format,mypy --strict,pytest,shellcheck)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
CHANGELOG.mdupdated under## [Unreleased]