Belt Control

Control a WalkingPad from your browser. An independent web app that connects to a treadmill speaking the KingSmith / WalkingPad Bluetooth protocols over Web Bluetooth to start it, stop it, set speed, read live telemetry, and keep a private history of every walk — without the KS+Fit phone app, an account, or anything to install.

beltcontrol.com

Not affiliated with Beijing KingSmith Technology Co., Ltd. WalkingPad® and KingSmith® are their trademarks, referred to here only to identify which treadmills this app can talk to. See Trademarks and independence.

Everything runs in the browser. The BLE link is browser → treadmill over the local radio; the server only ships static files and never sees any telemetry. Session history lives in localStorage and is never uploaded — History exports it as a JSON backup you can import into another browser, or as a CSV for a spreadsheet.

Captured against the built-in simulator — hence "Simulated classic" on the status chip. A real pad reports its own name there. Regenerated by tools/screenshots.sh, not staged by hand — see Screenshots.

Will it work with my pad?

The app probes the GATT table on connect and picks a driver itself; it does not go by model name. What you get depends on which protocol your unit speaks:

Your pad speaks	Control	Pause	Distance	Steps	Calories
Classic fe00 — A1, C1, C2, P1, R1/R2, K12, T1, …	full	—	yes	yes	—
FTMS 1826 — Z1, Z3, P1E, MT1, W1, X21, G2, …	full	yes	yes	—	yes
KingSmith 0x1234 — KS-C2, G1, MX16, K12 Pro, …	full	yes	yes	yes	unverified
FitShow fff0 — some OEM units	detect only	—	—	—	—

Pause is a resumable stop. FTMS has a dedicated one — 08 02, resumed by the same op code that starts the belt; the button withdraws if the unit turns out to reject it. On the 0x1234 family a capture of KS+Fit finally settled it: pause is runState 0, the same bytes as stop, and what makes it a pause is that the pad keeps the session counters across it and picks the walk back up on the next start. The classic command set has none at all. Details in the protocol reference.

unverified means the pad sends a number that cannot be believed — usually because its scaling was never established, and in the 0x1234 calorie case because the pad computes it from distance at a flat rate rather than measuring it. Those are shown raw, flagged, and excluded from every total rather than quietly summed — see Field trust.

Browser support is the real constraint. Verified against MDN browser-compat-data for Bluetooth.requestDevice:

Browser	Supported
Chrome 56+ / Edge / Opera / Samsung Internet	yes
Chrome on Android	yes
Firefox (desktop and Android)	no — never implemented
Safari, including Safari on iOS	no — never implemented

There is no way around the Safari gap; an iPhone would need a third-party WebBLE browser. This is a browser limitation, not a hosting one. Phones and tablets get a dismissible "best on desktop" banner so nobody discovers it by tapping Connect and getting nothing.

Run it

./serve.sh              # → http://localhost:8080  (installs deps on first run)
# or
npm install && npm run dev

Open it in Chrome or Edge. http://localhost counts as a secure context, so no TLS is needed. Opening the built files as file:// will not work.

On macOS, Chrome needs Bluetooth permission under System Settings → Privacy & Security → Bluetooth, otherwise the device chooser comes up empty with no error.

Then hit Connect. The protocol the app settled on is shown in the connection sheet (tap the status chip at the top of the Now screen) and logged. If your unit exposes none of the four known services, the log says so explicitly, naming each one it looked for.

Telling us about it

Send feedback — in the footer of every screen, and beside the log in the connection sheet — writes a report to [email protected]: what you typed, plus the browser, the protocol, the belt state and the protocol log if you leave diagnostics ticked. The page sends nothing itself; it opens the mail in your own mail app, with the full text shown first, so you can read it, edit it or drop it. A log longer than a mail link can carry is trimmed to its newest lines and says so — Save report writes the whole thing to a file worth attaching. No session or history data is included, only a count of them. That is the fastest way to get an undecoded pad decoded: the log is the capture.

Without a treadmill in reach

In dev builds only, the console exposes a fake pad:

__wp.connectSimulated('classic')   // or 'ftms', 'ks1234', 'fitshow'
__wp.connectSimulated('ftms', { rejectPause: true })   // a unit that refuses to pause
__wp.connectSimulated('ks1234', { refuseStarts: 2 })   // a pad that takes three tries to start
__wp.disconnect()

import.meta.env.DEV is statically false in a production build, so the simulator and the console hook are dropped by the bundler.

Test and deploy

npm test                # vitest, both workspaces — no hardware or browser needed
npm run check           # tsc --noEmit over the app and the driver package
tools/screenshots.sh --check   # are the README images older than the UI they show?
npm run build           # → apps/web/dist/
npx vercel --prod

Details in Testing, Screenshots and Deploying.

Safety

The belt can start under software control with nobody on it. The app therefore:

• confirms before starting and before resuming, showing the target speed — it may not be the person who paused it standing on the belt now
• clamps speed to the unit's real range (FTMS 2ad4, or a conservative default) — and clamps that to an envelope of its own, so a pad reporting a nonsense limit widens nothing. The floor is 1.0 km/h (0.6 mph), where a walking pad moves off by itself, and it is also where the target starts
• limits each speed press to ≤0.5 km/h
• keeps Stop always enabled, and binds it to Esc — Pause never takes its place, its key, or more than a third of the bar
• reports a stop or a pause only once the belt itself reports zero, and a start or a resume only once the belt reports movement — a written command is not a moving belt, or a stopped one. All four say plainly when the belt never confirms, and none of them ever invents a reading of its own to stand in for one
• re-sends a start only when the pad has answered that it refused one — at most three times, only while the app is still saying "starting", and never after it has reported failure or once a stop, a pause or a disconnect has arrived. A belt that lurches into motion long after the app said it never moved, when whoever pressed the button has stepped off, is precisely the thing a retry must not become
• pins Stop from the moment a start goes out until the belt reports zero — above the tab bar on mobile, at the top of the rail on desktop — and keeps it on screen in ambient mode and inside every dialog, so it can never be scrolled out of reach or covered
• takes the belt's word for it when it stops itself — nobody stepped on inside its safety window, the key was pulled, its own panel was used — so Stop goes away and Start comes back rather than the app insisting on a walk that ended without it
• never reports a pause to a belt that is still moving: a unit that rejects the pause command gets stopped instead, and says so
• never auto-reconnects — silently reattaching to a possibly-moving belt with stale UI state is not a safe default
• warns before you navigate away while the belt is running

Closing the page does not stop the belt. Use the treadmill's own controls or remote as the real safety stop.

Those are engineering mitigations, and they reduce the risk rather than removing it — none of them can help once the Bluetooth link drops with the belt still moving. The safety terms a user actually sees are the footer line on every screen and the in-app Safety, terms & privacy page (#/legal, apps/web/src/routes/Legal.tsx), which also covers privacy and what is and is not collected.

Documentation

Doc	What's in it
The driver SDK	The package the app drives a treadmill with: the Driver contract, what each protocol can do, and the simulator and GATT fake it ships
Protocol reference	All four BLE protocols frame by frame, and how they were reverse engineered — including the previously undocumented KingSmith 0x1234 family
Interface and session design	Why the UI is shaped this way; session detection, counter resets, field trust
Testing	What the suite covers, the BLE mock, and what is deliberately left out
Screenshots	How the images at the top of this file are regenerated, and the month of fake walking they are taken against
Deploying	Hosting, the domain, and what every rule in vercel.json is for
Trademarks and independence	Nominative use, and what this project deliberately does not do

Layout

Two npm workspaces: the app, and the drivers it drives a treadmill with. The split is where it is because the drivers import nothing — they are handed a GATT server and report through callbacks — so everything above that seam is one side and everything below it is the other.

apps/web/
  index.html            Vite entry
  src/main.tsx          bootstrap, guards, service-worker registration
  src/app.tsx           shell (one column on mobile, rail + content on desktop), hash router
  src/routes/           Now · Today · History · Legal (safety, terms, privacy)
  src/components/       hero, speed control, tiles, stop bar, ambient mode, sheets
  src/charts/           hand-rolled inline SVG: column, area, heatmap
  src/state/            connection · telemetry · session · settings · backup · log
  src/lib/feedback.ts   the support report, and fitting one into a mailto: link
  src/lib/viewport.ts   the 64rem desktop breakpoint, shared by the shell and app.css
  src/lib/links.ts      outbound URLs used in more than one place
  src/styles/tokens.css the single source of truth for colour, type and spacing
  public/               manifest, icons, service worker, robots.txt, sitemap.xml
  public/content.css    the written pages' stylesheet — they never load the app bundle
  public/*/index.html   the written pages: compatibility, troubleshooting, the protocols
  test/                 the app's unit tests

packages/belt-drivers/  the SDK — see its own README
  src/drivers.ts        the four protocol drivers, and the contract they share
  src/bluetooth.ts      what to ask navigator.bluetooth.requestDevice for
  src/simulator.ts      fake pad, for driving the UI with no hardware in reach
  src/testing/          a fake GATT surface, exported so the app's tests use it too
  test/                 the protocol suites — the only stand-in for a treadmill

tools/og-image.html     source for the link-preview card in apps/web/public/og.png
tools/screenshots.sh    regenerates the two images above (--check for staleness)
tools/screenshots/      the month of fake walking they are taken against
docs/                   the documentation linked above
serve.sh                local dev server
vercel.json             hosting config
LICENSE                 Apache-2.0
NOTICE                  attribution, independence and safety notice carried by forks

Speeds are shown in mph. Everything on the wire stays metric — the protocols all speak km/h — so miles are a display concern only.

Related projects

Belt Control is not the only way to drive one of these pads without KS+Fit, and the others solve different halves of the problem. If you want a script, a local server, or just to check that your pad answers at all, start here:

• ph4r05/ph4-walkingpad — a Python controller for the classic fe00 protocol, and the reference this project's frame layout was cross-checked against.
• CodeJawn/walkingpad — a self-hosted web UI that drives the pad over BLE from a server on your own network, reachable from any device on it.
• Duttke's WalkingPad Bluetooth connection test — a single page for checking whether a pad responds over Web Bluetooth at all.

What is different here: no install, no server, and no Python — the browser is the client, so the only moving part is a tab. Sessions are recorded locally and never uploaded, and the 0x1234 family behind the KS-C2 is driven rather than merely detected. See the protocol reference for what that took.

Licence

Apache-2.0. Chosen over MIT for two things this project specifically wants: an explicit patent grant, and sections 7 and 8 — the "AS IS" warranty disclaimer and the limitation of liability — spelled out rather than compressed into one sentence. Software that commands a motorised belt should say plainly that it comes with no warranty.

Section 4(d) makes the NOTICE file a condition rather than a request, which is what carries the independence statement into forks. If you fork this, keep it, and keep apps/web/src/components/Disclaimer.tsx rendered — see Trademarks and independence.

Nothing here is legal advice.