Driving a Treadmill From a PDF Specification

Share
A farmer in a conical hat working among pineapple plants at sunset, with tea rows, palm trees and a temple roof behind.

PacePrompt is an iPhone app I built for a Reebok FR30z treadmill that supports the Bluetooth Fitness Machine Service (FTMS) protocol. It is part of a loop in which an AI coach reads my recent exercise and trends, plans my sessions and writes each treadmill session in plain English. PacePrompt turns that description into a validated plan of segments with speeds and inclines, sets those targets on the treadmill over Bluetooth, and records what actually happened, including the cases where I override the plan using the app or the hardware controls on the treadmill. Apple Health is the source of truth for what was measured; my export app reads from it, and the coaches read that export rather than each other's notes.

The other half of the loop is that export app, which writes my Apple Health data to Google Drive each day for the AI coaches to read; the next posts cover it.

The daily loop: what I do, Apple Health, my export app, Google Drive and the AI coaches
The daily loop. PacePrompt feeds it from the treadmill; the next posts cover the rest.

PacePrompt itself is built for one device and one person, and written by coding agents end to end. That is the idea behind Apps for One: building apps for an audience of one, around one person's own needs, with coding agents doing the implementation. The first set follows the health apps I built for myself, and this post is the most self-contained of them, because the idea and the problem at hand were concrete. In this experiment, the key domain knowledge was not mine. It lived in the Bluetooth specification PDFs the agent implemented from. In an app like this, getting it wrong would mean a moving belt and potentially causing injuries rather than a wrong number on a screen.

For this project, the agent was Codex. All 155 non-bot pull requests (PRs) came from Codex branches, between the first commit on 2 September and the last on 5 October; Claude contributed four commits on 5 September, the prompt and test corpus for the workout import evaluation. The repository is public at syamaner/paceprompt-ios.

For similar projects, I would typically start with researching available packages that manage the hardware integration, because side projects rarely have the time to justify reinventing the wheel. With the latest agent harnesses and state-of-the-art models, we can now go down to protocol level and check whether an idea is feasible overnight. That is what happened with this project: within a day, a small read-only explorer had proven that the app could read the treadmill's own data.

Defining the principles first

The README states the core rule: AI may propose a plan, but deterministic local code validates it and controls the treadmill. It was in the first code commit on 2 September, with a short treadmill safety section in the agent instructions as follows:

  • The human operating the physical console and safety key is authoritative.
  • Nothing may be written to the treadmill's control point until a separately authorised slice of work allows it.
  • There is no automatic reconnection that could resume a programme.
  • No command is reported as successful until the protocol has acknowledged it and the treadmill's own reports show the change.

The more specific rules came later, from the treadmill itself. After characterising the console on 11 September, the design gained a profile in which the console owns belt motion: only its physical Start and Stop buttons start and stop the belt, and the app never sends the FTMS Start, Stop or Pause commands at all. These rules reached the agent instructions on 15 September, replacing the earlier blanket ban on writing to the control point.

PacePrompt can now send exactly three things:

  • Request Control.
  • Set Target Speed.
  • Set Target Inclination.

Only one class can write to the treadmill, and its encoder maps those three intents and nothing else.

Further rules handle the awkward cases:

  • "Begin workout" sends nothing and waits for me to press Start on the console.
  • The app asks for control only after the first fresh report of the belt moving.
  • When telemetry goes silent the app says it is checking the treadmill, and it never treats silence as zero speed.
  • Ending a workout sends no Stop.
  • Validation never clamps or rounds a target, so an invalid plan is rejected as it stands.
The workout check before a session. Begin workout sends nothing; the belt starts from the console.
The workout check before a session. Begin workout sends nothing; the belt starts from the console.

Reading the specification one piece at a time

The work started from the Bluetooth Special Interest Group (SIG) documents, which the design documents cite by section and table; the agent's FTMS skill requires each change to record the specification revision it was checked against. Each step proved one thing before the next was allowed:

  1. A capability explorer (2 September) that reads the treadmill's features and its supported speed and incline ranges, decoded by parsers tested against synthetic bytes.
  2. Read-only telemetry (2 to 3 September) that keeps the specification's "unavailable" values as unknown instead of turning them into numbers, while I ran the belt from the console and the app only listened.
  3. A written handshake (3 September) with the exact bytes for each command, and levels of evidence running from the write being accepted up to the machine's observed state changing. The document's phrase for this is that evidence is a ladder, not one boolean.
  4. A transport for a single procedure at a time (9 September), then proofs of Request Control on the real treadmill, accepted on 10 September.
  5. Characterising the console (11 September), which produced the console-owns-the-belt profile, followed by the workout logic, preflight checks and exercise screen, all tested with synthetic data.
  6. A supervised workout proof (13 September) under fixed conservative ceilings, below 1 km/h and at 1% incline.

Every physical step was a separate session that I authorised explicitly, with the console and safety key within reach. The agent instructions are explicit about why: simulator results cannot be considered as evidence of physical Bluetooth behaviour.

A real session: Codex has prepared Request Control and waits for me to confirm the physical state, with the phone mirrored beside it
From a real session, device name blurred. Codex has everything ready for the first Request Control, and nothing is written until I confirm the treadmill is in a safe state.
The exercise screen mid-workout. The footer says it plainly: Start and Stop remain on the physical treadmill console.
The exercise screen mid-workout. The footer says it plainly: Start and Stop remain on the physical treadmill console.
The levels of evidence on screen: the Bluetooth write delivered, the setting accepted, and then waiting for the treadmill to report the new value.
The levels of evidence on screen: the Bluetooth write delivered, the setting accepted, and then waiting for the treadmill to report the new value.
A change for this step only, shown against the plan and against what the treadmill reports.
A change for this step only, shown against the plan and against what the treadmill reports.

Treadmill's behaviour did not match the spec

Testing surfaced gaps between the documents and the machine, and the FTMS specification warns about none of the treadmill's quirks.

Start and Stop. The FTMS Start command returned success without starting the countdown or the belt, and Stop sometimes succeeded and sometimes reported "operation failed". That is the main reason the production app sends no Start, Stop or Pause: the console does those, and the app only adjusts targets while the belt is moving.

Silence after a stop. Control survived Stop and Start on the console, but a quick restart sent no zero-speed report at all, and a stop did not always produce one either. An app that inferred "stopped" from missing packets would have been wrong in both directions.

Callbacks out of order. CoreBluetooth sometimes delivered the treadmill's confirmation before the callback saying the write had completed. The transport refused to call that a success, and it now holds an early confirmation as provisional until the write callback arrives.

Speeds that did not compare. A scaled speed decoded through floating point failed an exact comparison with the target, so values are now canonicalised first; and during the start ramp the belt legitimately reports speeds below its advertised minimum, which the first workout logic had rejected.

Most of these were found by trial and error in a supervised session, turned into an issue and fixed with a test. The workout proof on 13 September took several tries before it was accepted, and each failure left the treadmill in a safe state.

Natural language exercise plan: plain English in, a validated plan out

The second half of the app is the import functionality, which turns a session the coach writes in plain language, such as a warm-up, intervals and a cool-down, into a structured plan the app can use.

A sample of the exercise coach's board on a treadmill day, ending with a line written for PacePrompt
On treadmill days the coach's plan ends with a line written for PacePrompt: paste it, review the plan, then press Start on the console. Sample content.
Plain English in: a session written the way a coach would write it.
Plain English in: a session written the way a coach would write it.
A validated plan out: exact ordered steps, saved only by a separate confirmation.
A validated plan out: exact ordered steps, saved only by a separate confirmation.
The review shown before every request: where the text goes, what is sent and what never leaves the phone.
The review shown before every request: where the text goes, what is sent and what never leaves the phone.

Before choosing a model, the agent wrote a provider-neutral contract: every model output is an untrusted proposal, kept as a separate type from a real workout plan, and validated locally before I see a preview or can save it. A fixed test measured the candidates and I chose the model: GPT-5.6 Sol at first, and GPT-6 Sol after a re-test.

What shipped on 6 September was a consent-gated OpenRouter import: a fresh disclosure and consent for every request, the key in a device-only keychain item, the route pinned to one provider with no fallback, and no prompt or response history kept.

How the model was chosen: the evaluation in full

I asked early on whether we could use Apple's on-device inference, since my phone supports it, and the agent built a developer-only evaluation target with two adapters, Apple Foundation Models with guided generation and OpenRouter with a strict schema, both scored deterministically against an answer key with no model acting as judge.

The on-device half was never run. It was parked within a few days and closed on 15 September, and the repository is careful to record it as deferred, not evaluated or shown to have failed.

The comparison that did run used a host harness through OpenRouter, with a synthetic test set written with Claude and checked by me: 79 cases, each tried three times. Three models completed the full run:

Model Valid responses Composite score Cost of the run Qualified
GPT-5.6 Sol 237 of 237 99.4% $1.05 Yes, chosen
Gemini 3.7 Flash 233 of 237 98.1% $1.13 No
GPT-5.6 Luna 228 of 237 91.3% $0.13 No

A later round tried nine open-weight routes. None qualified, but 789 of their 2,133 scheduled attempts never started after rate-limit pauses, so that comparison was incomplete and I would not read a ranking into it.

These are results for my task on my test set, not a ranking of the models, and the report lists its own caveats: a synthetic test set, repetitions that are not independent samples and no confidence intervals. I chose the model; the harness only measured.

The way the test was built mattered more than the headline. Most of the 79 cases, 67 of them, were not plans at all but requests the app should turn down or question, such as an unsafe speed, a medical question or an attempt to override the instructions.

A model had to clear three checks before its composite score counted at all:

  • every response valid against the schema;
  • every refusal exactly right, including the reason;
  • a minimum score in every category, so strength in one area could not hide weakness in another.

That is why Gemini 3.7 Flash, at 98.1%, still did not qualify, and why Luna, at an eighth of Sol's price, could not make up for its failures.

Each stage was written down and ratified before it ran, with a spending cap, no retries and no fallback, and the test cases had never been used as prompt examples. They were still my own cases, written with Claude, so they test the plans I thought of rather than the ones my coach actually writes.

On 22 September a re-evaluation compared it with GPT-6 Sol, using the same prompt and the same cases:

GPT-5.6 Sol GPT-6 Sol
Exactly right, all 109 cases 102 105
Original held-out set (79 cases) 73 75
Newer acceptance set (30 cases) 29 30
Slowest 5% of responses, held-out set 4.5 s or more 3.9 s or more
Cost of the run $0.92 $0.92

GPT-6 Sol gained three cases and lost none, at the same cost and a little faster, so I moved the app to it. It was one repetition, neither model passed every gate, and three cases in about a hundred is within the noise, so I read it as no worse rather than better, and the switch as my choice rather than a gate pass.

Testing on the phone, and releases from a tag

The supervised sessions needed the real phone, and from 10 September I let Codex drive it through iPhone Mirroring, which shows and controls an iPhone from a Mac, while I stayed at the console with the safety key. Over three weeks it checked builds before supervised attempts and tested what happens when the app is left, the phone is locked or the treadmill disconnects.

Mirroring hides the phone's controls from accessibility, so every tap was followed by a screenshot, and it disconnects whenever the phone is used directly. On 13 September that ended a workout proof: the app left the foreground, the safety rules invalidated the workout, and the attempt became a record of the app failing safely.

A supervised proof through iPhone Mirroring: the exercise screen beside Codex's running commentary
A supervised proof through iPhone Mirroring. The treadmill confirms each target, and Codex keeps me at the console while it waits for the next segment.
Codex testing PacePrompt on my phone through iPhone Mirroring: tap, look, check, next step
Every tap followed by a look, and the one time the loop broke on purpose.

Codex also automated releases. A tag such as testflight/1.0.1-b26 starts a GitHub Actions workflow that checks it points at a tested commit on main, builds, and signs and uploads only after I approve the run. Codex never reran a tag with an unclear outcome and used a new build number instead; 19 of 25 tags produced internal TestFlight builds.

The release line from a tag to TestFlight, with my approval before signing
From a tag to TestFlight, with one human gate. 19 of 25 tags became internal builds.

Adding the Watch

Heart rate was the missing piece. The plan, written down in mid-September, was one Apple Health workout per session that combines the Watch's heart rate and energy with the treadmill's intervals, and the contract merged at midnight between 27 and 28 September settles who saves it: only one device ever does. Once a session belongs to the Watch, the iPhone's own Health save is switched off, and a save whose outcome is uncertain is never retried or replaced. The Watch app landed later that morning, and the first single Health workout confirmed on my own devices came on 3 October, under a week and eight build numbers later.

That week, and the few days after it, were mostly about timing. The first real workout with the Watch showed heart rate and energy and then ended with "Save result uncertain"; that evening the Watch timed out before the start and the app got stuck. Two devices, a mirrored workout session and HealthKit's own saving all move at their own pace, and the defects were races:

  • a fresh start colliding with a discard still in progress;
  • a Start ignored while the previous workout was still closing;
  • intervals added after collection had already ended;
  • distance going wrong across pauses.

The pattern was the same each time. I reported what I saw on my wrist and phone, and Codex reproduced it before fixing it: on freshly paired iPhone and Watch simulators where it could, and otherwise with a regression test written to fail first or by watching the real phone through Mirroring. Six of my reports went through that report, reproduce, fix cycle and turned up nine defects between them; three of those six reproductions used simulators.

The experience changed along the way. Ending a workout went from Stop and a confirmation on the Watch to one tap on the phone, with the Watch saving on its own, and recovering on the Watch went from four taps to two. One rule did not change: no Watch or Health event can produce a treadmill command. The contract says so in plain words, and a build check fails if the Watch's code so much as references the treadmill's Bluetooth layer.

Adding the Watch: I report, Codex reproduces, Codex fixes, a new build reaches my wrist
Under a week and eight build numbers from the contract to the first single Health workout, with one rule that never moved.

Closing the loop with the coach

PacePrompt records each session as planned against executed segments: the prescribed targets, the effective ones after any manual change on the console, the settled values the treadmill reported, times, and distance with its provenance. The repository describes the JavaScript Object Notation (JSON) export of that history as an agent-readable fixture.

A finished session: the original plan beside what was recorded.
A finished session: the original plan beside what was recorded.

Heart rate comes by a different route. From late September the Apple Watch owns the single Health recording for a session. WeeklyHealthReport, which exports my Apple Health data to Google Drive, then carries each executed interval, with its heart rate summary and PacePrompt segment identity, into the daily file the coach reads. The next posts are about WeeklyHealthReport and the coaches that read its export.

What carried over, and what was different

Most of the emerging method here is also shared with WeeklyHealthReport, which I built alongside it: unknown is never zero, evaluations are frozen before they run, and every change comes with a line in a usage ledger.

The difference was where correctness came from. In WeeklyHealthReport, as the next post describes, I could write the domain rules down myself. Here I could only write the principles. The specific rules had to be read out of a specification and then learned from a machine that did not always follow it, in supervised sessions that those principles made safe to run. The rule that now defines how the app drives the treadmill, that the console owns the belt, came out of a session on 11 September, not from anything I wrote on 2 September.

That is also why the agent could move quickly. The parts that could hurt someone sat behind one-session approvals and, later, a build check, so everything else could change as fast as Codex could test it.

Two things are still open:

  • acceptance testing of the Watch companion on my own devices;
  • making sure the coach actually uses the per-interval detail the daily export can now carry. The export was paused from mid-October until early November, so that part of the loop has only just started running again.

Illustrations made with Claude Design; screenshots taken in the iOS Simulator with sample data.