Automate Your Treadmill Intervals: Use Home Assistant, HACS, MCP and an AI to Run Workouts from a Screenshot

Table of Contents

1. Key Highlights
2. Introduction
3. How Home Assistant and HACS make your treadmill controllable
4. Model Context Protocol (MCP): letting AI act like a Home Assistant operator
5. Step-by-step: from workout screenshot to running treadmill script
6. What the AI-generated script looks like (structure and components)
7. Safety considerations and recommended protective measures
8. Extending the setup: sensors, dynamic adjustments, and logging
9. Troubleshooting common issues
10. Privacy, security and network considerations
11. Alternatives and other use cases
12. Practical example: a real-world run-through
13. Best practices for prompts and AI interaction
14. When to avoid automation
15. FAQ

Key Highlights

• Turn a Fitbit/Google Health workout screenshot into a Home Assistant script automatically: use HACS (hass-walkingpad), an MCP bridge (ha-mcp), and an AI client (e.g., Claude Code) to generate and run treadmill interval scripts with no YAML required.
• The system controls the treadmill over Bluetooth, handles timing and speed changes, and can include safety checks; review generated scripts and add presence or power sensors if you need automatic pause/stop behavior.
• This pattern works for any exercise device that Home Assistant can control; expect one-client Bluetooth limitations, authentication and network considerations, and a need to validate speeds/units before stepping onto the belt.

Introduction

Manual interval workouts on a treadmill quickly become a juggling act: tapping speed controls, watching a countdown, trying to match heart-rate targets while keeping an eye on the phone. Replace that choreography of button presses with a script that drives the treadmill exactly to your plan. By combining a reverse-engineered Bluetooth integration for common consumer treadmills, an MCP (Model Context Protocol) bridge that exposes Home Assistant to AI tools, and an AI assistant capable of reading workout screenshots, you can hand the routine to the machine and simply run.

The workflow is straightforward: capture your workout plan (a screenshot), give it to an AI that understands the plan, and let the AI create or update a Home Assistant script that controls the treadmill. No manual YAML editing. No learning integration APIs. The treadmill changes speed and stops on schedule. The remaining work is to check the script and run it — and to put safety measures in place.

The guide below explains the components, walks through exact steps and prompts, covers safety and troubleshooting, and suggests ways to extend the setup with sensors, heart-rate feedback, and smarter automations.

How Home Assistant and HACS make your treadmill controllable

Home Assistant becomes useful for fitness automation when the treadmill — or any exercise equipment — exposes control interfaces that Home Assistant can call. For many consumer compact treadmills (for example, Kingsmith WalkingPad models), members of the Home Assistant community have reverse-engineered the Bluetooth protocol and published integrations available through HACS (Home Assistant Community Store).

HACS is an unofficial add-on repository for Home Assistant. It hosts integrations not present in the official catalog and installs them through the Home Assistant UI. The hass-walkingpad integration, for example, acts like the treadmill’s official mobile app: it connects over Bluetooth, provides an on/off control for the belt, exposes speed controls, and surfaces sensors such as current speed, distance, steps and duration.

What that gives you inside Home Assistant:

• An entity to switch the treadmill belt on and off.
• A service or entity to set speed in km/h (or mph depending on the integration).
• Sensors that report current speed, total distance, elapsed time, and potentially power consumption.

Two practical points:

1. Because the integration mimics the official app, only one client can maintain the Bluetooth connection at a time. While Home Assistant holds the connection, the manufacturer’s app cannot connect concurrently.
2. Reverse-engineered integrations depend on the device firmware and the reverse-engineering effort. Updates to the treadmill firmware may break compatibility. Keep the integration’s repository bookmarked and the developer’s issue tracker handy.

Real-world example: a Kingsmith WalkingPad connected via hass-walkingpad shows as “Office Treadmill” in Home Assistant. When Home Assistant holds the Bluetooth connection, the treadmill accepts speed commands from automations and scripts, enabling timed intervals without pressing the treadmill buttons.

Model Context Protocol (MCP): letting AI act like a Home Assistant operator

MCP (Model Context Protocol) standardizes how AI assistants discover and call external tools. For smart homes, ha-mcp is the implementation that exposes Home Assistant as a set of callable tools for an AI: it lists entities, exposes services, allows creation and update of scripts, and triggers automations. The AI sees Home Assistant as a toolbox with items like "list entities", "call service switch.turn_on", or "create script".

Why MCP matters:

• It removes the need to encode Home Assistant API calls into text prompts manually. The AI uses structured tool calls to make changes.
• It enables an AI to generate or modify Home Assistant scripts and then execute them, rather than only suggesting code that a human must paste and run.
• It supports complex interactions: the AI can query current entity states, check whether devices are connected, and add safety checks into generated automations.

Set up typically involves:

1. Installing ha-mcp in Home Assistant and configuring authentication.
2. Choosing an AI client that supports MCP tool calls (Claude Code, for instance).
3. Authorizing the AI client to access the ha-mcp endpoint.

When configured, AI clients can list entities and services. In one setup, 77 Home Assistant tools were available to the AI — including script creation, service calls, entity state queries, and more. That breadth lets an AI assemble a runnable script that handles timing logic, speed changes, and safety checks.

Step-by-step: from workout screenshot to running treadmill script

The workflow below mirrors a working example where a Fitbit/Google Health interval plan was converted into a Home Assistant script using an AI.

Prerequisites

• A treadmill (or bike) that Home Assistant can control. Install an appropriate HACS integration (e.g., hass-walkingpad for KingSmith devices).
• An AI client connected to your Home Assistant via an MCP server like ha-mcp. Claude Code is an example of an AI tool that can read images and call MCP tools.
• A workout plan visible in your fitness app (Google Health/Fitbit) that can be screenshotted.

Exact steps

1. Capture the workout plan Open the workout in the Fitbit or Google Health app and take a screenshot. Interval workouts are ideal: they clearly show the durations and the sequence (warm-up, run/walk rounds, cool-down). Save the image to the device where your AI client runs.
2. Provide the screenshot to the AI Upload the screenshot to the AI client and supply a concise instruction. The AI should be told the target treadmill name in Home Assistant and the numeric speed values to use for each interval type. A sample prompt:

• Paste the screenshot into the chat.
• Tell the AI which treadmill entity to control (e.g., "Office Treadmill").
• Specify the speeds for “walk” and “run” (e.g., 6 km/h for walk, 9 km/h for run).
• Ask the AI to create or update a Home Assistant script named "Treadmill Interval Workout" to follow the workout plan.

Precise prompts produce the best results. Example prompt used successfully: [Paste Image Here] read this workout. Use homeassistant to create or update a script named "Treadmill Interval Workout" to follow this exercise. It needs to control my Office Treadmill. Set speed 6kmph for walk and 9kmph for run.

3. Let the AI parse and generate the script The AI reads the screenshot, translates the plan into a sequence of timed steps, and uses MCP to create a script. The generated script should:

• Include a safety check to confirm the treadmill entity is available/connected before starting.
• Turn the belt on or call the treadmill speed service to set initial speed.
• Use delays to implement interval durations and optional ramp-up pauses (e.g., 5 seconds to let the belt spin up).
• Loop over repeated rounds for run/walk cycles.
• Stop the treadmill at the end.

4. Review the generated script Open Home Assistant: Settings → Automations & Scenes → Scripts. Locate "Treadmill Interval Workout" and inspect the sequence. Verify:

• Speeds and units match expectations.
• Durations match the workout plan.
• There’s a final stop action.
• Safety checks are present (for example: abort if the treadmill entity is unavailable).

5. Run and monitor If satisfied, instruct the AI to run the script, or trigger it manually in the Home Assistant UI. Stand on the belt and let it control speed changes automatically. Keep your hands and eyes aware: the script will not replace a physical stop button or a personal decision to step off mid-interval.
6. Post-run logs and adjustments Check Home Assistant entity logs and the treadmill sensors to verify timing and achieved distances. Tweak speeds or durations if reality and the fitness plan diverge.

Practical tips:

• Always test scripts at low speeds without stepping on the belt to ensure the belt accelerates and stops correctly.
• If your treadmill reports speeds in mph, convert the km/h values in the prompt or specify units explicitly.
• Use descriptive script names to avoid confusion if you create multiple plans.

What the AI-generated script looks like (structure and components)

The AI usually creates a script that uses Home Assistant services and sequences rather than raw YAML typed by you. Conceptually, a generated script contains these components:

• Preconditions and safety checks:
  • Verify the treadmill entity exists (e.g., check entity state not unknown or unavailable).
  • Optionally check that the treadmill is not already in use.
• Initial setup:
  • Turn the device on, or call the service to start the belt.
  • Set the initial speed for warm-up.
  • Wait a short time (seconds) for the belt to ramp up.
• Interval loop:
  • For N rounds:
    • Set speed to "run" value.
    • Wait run duration.
    • Set speed to "walk" value.
    • Wait walk duration.
• Finalization:
  • Set speed to 0 or turn the belt off.
  • Optionally log a message or send a notification with distance/time summary.

Example pseudocode (not exact Home Assistant YAML but illustrates logic):

• Check treadmill entity 'switch.office_treadmill' is available.
• switch.turn_on: office_treadmill
• script: set speed to 6 km/h
• delay: 5:00 (warm-up)
• repeat 4 times:
  • set speed to 9 km/h
  • delay: 3:00
  • set speed to 6 km/h
  • delay: 2:00
• set speed to 0 km/h or switch.turn_off
• notify: "Workout complete"

The AI often adds a small safety wait before the belt engages and a check that aborts the script if the treadmill becomes unavailable during execution.

Safety considerations and recommended protective measures

Handing control of a moving machine to an automated script requires discipline and layered safeguards. Scripts may work perfectly in most runs, but a machine under your feet deserves extra attention.

Essential precautions

• Manual emergency stop: Know where the treadmill's physical stop button is and use it if something goes wrong. A script should never be the only fail-safe.
• Review before run: Always inspect the generated script for correct speeds, units and durations before executing it with a person on the belt.
• Initial dry-run at low speed: Test the script without stepping on the belt to confirm the treadmill accelerates and stops as expected.
• Add abort conditions: The AI can include checks such as "abort if treadmill entity unavailable" or "abort if distance sensor returns 0 after set time." Keep these in the script.
• Presence/power sensors for automatic pause: Use a pressure mat, weight sensor, or a current sensor on the treadmill’s plug. Add automations that pause or stop the treadmill if the presence sensor indicates the user stepped off or if the treadmill draws no current.

Example of presence safeguard

• Add a binary sensor that reports "user_on_belt" using a pressure mat or an inertial sensor.
• Script logic: before setting a run interval, check "user_on_belt == true". If false, pause and notify the user. During a run, if "user_on_belt" becomes false for more than X seconds, stop the treadmill.

Heart-rate awareness and fallbacks

• Home Assistant can read heart-rate data from connected wearables or health integrations. However, many fitness plans are pace-based rather than heart-rate-controlled.
• The AI-generated script will change speed according to timing, not heart rate. If you want heart-rate-responsive behavior (slow down if heart rate exceeds safe limits), that requires additional automations and safety logic, plus explicit medical considerations.

Liability and judgment

• Automating machine control does not remove personal responsibility. Use automation as a convenience, not a replacement for attention and safe operation.
• Ensure local safety regulations and warranty terms are not violated by third-party integrations.

Extending the setup: sensors, dynamic adjustments, and logging

Once you have a basic script generating and running setup, several practical extensions increase resilience and usefulness.

Presence and auto-pause

• Add a presence sensor that detects whether the user is standing on the treadmill. This could be a pressure pad, a weight sensor in the mat under the treadmill, a contact sensor that notices the belt is loaded, or Bluetooth-based detection of a paired smartwatch.
• Automate pause/resume logic: If the sensor indicates the user stepped off for more than a configurable threshold, pause or stop the script.

Power monitoring

• A smart plug that tracks current draw tells you if the treadmill is actually drawing power. If the belt is commanded on but the plug shows near-zero consumption, trigger a warning and abort.
• Power sensors also help detect stalls and motor problems early.

Heart-rate integration

• If you wear a smartwatch or chest strap that reports heart rate to Home Assistant, add automations that adjust pace or alert you when heart rate crosses thresholds. Example: if heart rate rises above a safe zone, reduce speed and notify.

Adaptive workouts

• Create a two-part system: a generator that reads a workout plan and creates a baseline script, and a runtime monitor that can make small adjustments (±0.5 km/h) based on heart rate or perceived exertion inputs.
• Note: dynamic adjustments complicate safety — ensure boundaries and rate-of-change limits to avoid sudden speed jumps.

Logging, metrics and progress tracking

• Have the AI-generated script log timestamps and speeds to a Home Assistant sensor or input_text entity.
• Visualize workout history using Home Assistant’s built-in graphs or external dashboards to see progress over time.

Scheduling and voice control

• Schedule generated scripts in Home Assistant for repeated routines.
• Expose a voice command (via Home Assistant’s voice assistant integrations) to start the latest generated workout, or to select between multiple scripts.

Create an "AI skill"

• If you create and refine this workflow often, set up an AI skill or shortcut that:
  • Accepts a screenshot,
  • Parses and creates a script with predefined options,
  • Saves common presets for your treadmill speeds,
  • Allows a one-click run operation.

Troubleshooting common issues

Bluetooth connection problems

• Single-client limitation: The reverse-engineered integration usually allows only one Bluetooth client at a time. If the official app can't connect, ensure Home Assistant disconnected cleanly.
• Intermittent disconnects: Keep the Home Assistant instance physically close to the treadmill, and avoid interference from other 2.4GHz devices. If issues persist, try restarting the Bluetooth service on the Home Assistant host.

Script errors and timing mismatches

• Unit mismatch: Confirm whether your treadmill integration expects speeds in km/h or mph. If the fitness app shows speeds in different units, convert them.
• Timing off by a few seconds: Home Assistant delays and script execution are not hard real-time; small timing inaccuracies (a second or two) are normal. For interval workouts, seconds differences rarely matter. If they do, build additional buffer waits into the script.
• Treadmill does not stop at end: Confirm there is a final service call to set speed to 0 or to call the treadmill's off service. If missing, add it and retest.

AI misread or parsing errors

• Poor-quality screenshots lead to misread durations or rounded numbers. Use clear, legible screenshots and specify any ambiguous values in the prompt.
• The AI may misinterpret "5 minute warm-up walk" as five separate one-minute steps. Inspect the script and correct grouping manually or prompt the AI for corrections.

Authentication and MCP issues

• Ensure ha-mcp is correctly configured and that the AI client has valid credentials.
• Network reachability: If the AI client runs externally (cloud-based), you must expose ha-mcp securely or run an AI client locally.

Safety sensor false positives

• Pressure mats and power sensors can produce false positives. Tune thresholds and introduce small grace periods (e.g., require 3 consecutive seconds of absence before auto-stopping).

Privacy, security and network considerations

An AI with write access to your Home Assistant instance is powerful. Address the following to maintain a secure posture.

Least privilege

• Use scoped credentials. Give the AI client only the permissions it needs: script creation, script execution and read-only access to the entities it needs to check.
• Rotate tokens regularly and revoke them when not needed.

Local vs cloud AI

• Running the AI client locally reduces the need to expose ha-mcp over the public internet. If the AI runs in the cloud, ensure TLS and authenticated access to the ha-mcp endpoint.
• If your AI tool stores copies of the screenshots or scripts on remote servers, consider whether that is acceptable for your privacy needs.

Audit logs

• Enable Home Assistant’s audit logs to track script creation and execution. Review logs periodically to spot unexpected modifications.

Network isolation

• Place Home Assistant on a VLAN or segment that prevents easy lateral movement from compromised devices.
• Keep Home Assistant and the treadmill firmware up to date to reduce attack surface.

Data retention

• Decide how long to retain workout screenshots and generated scripts. Remove or archive sensitive files if necessary.

Alternatives and other use cases

This approach is not limited to treadmills. Any device Home Assistant can control can be incorporated into a similar workflow.

Exercise bikes and rowers

• If the bike exposes Bluetooth controls or an API, an AI-generated script can shift resistance levels or power targets at timed intervals.
• For devices that accept virtual control (e.g., apps that adjust resistance), scripts can simulate user interactions.

Smart home training aids

• Combine treadmill scripts with environmental automations: adjust room lights, turn on a fan at a particular interval, or play a coaching playlist when sprints begin.

Rehabilitation and pacing for medical needs

• For controlled pace-based physical therapy, scripted treadmill sessions ensure repeatability. Coordinate with clinicians before automating medically-sensitive routines.

Group classes and staggered starts

• Use Home Assistant scripts to coordinate multiple devices: stagger start times for interval group training across several treadmills or control gym fans and timers.

Voice-driven start and hands-free control

• Use voice integration to select a saved script: "Start Tuesday intervals." The AI-generated script can be one of many options exposed to your voice assistant.

Practical example: a real-world run-through

A user with a Kingsmith WalkingPad wanted to automate a "Vigorous Treadmill Intervals" session from Fitbit. The plan: 5-minute warm-up walk (6 km/h), 4 rounds of 3-minute run (9 km/h) and 2-minute walk (6 km/h), and a 5-minute cool-down.

Flow used:

• HACS installed hass-walkingpad and configured the WalkingPad entity as switch.office_treadmill and a speed service.
• ha-mcp was installed and connected to Claude Code as the AI client, with scoped credentials granting script creation and entity read permissions.
• The user took a screenshot of the Fitbit workout and uploaded it to Claude Code with a short prompt: identify the sequence and create a script controlling Office Treadmill with a 6 km/h walk and 9 km/h run.
• Claude parsed the screenshot, created a script with safety checks and a 5-second ramp-up delay, and added loops for the four rounds.
• The user inspected the script, tested it at low speed, and then ran it with the treadmill belt on and standing on the belt.
• The treadmill executed the interval plan reliably. The user later added a pressure mat sensor to auto-pause when stepping off.

This example demonstrates that the pattern works with minimal setup and provides immediate convenience.

Best practices for prompts and AI interaction

Clear, minimal, and unambiguous prompts yield the most reliable results when asking an AI to generate automations.

Be explicit about:

• Target Home Assistant entity names (exact entity id or a human-readable name mapped in the prompt).
• Units (km/h vs mph).
• Exact names for created scripts (to avoid duplicates).
• Desired safety checks (abort when entity unavailable, small ramp-up delay, confirm final stop).
• Any special behavior (notifications, logging, heart-rate triggers).

Example prompt with extras: [Paste Image Here] Read this workout and create or update a Home Assistant script named "Treadmill Interval Workout (6/9 kmph)". Control entity: switch.office_treadmill. Set walk speed to 6 km/h and run speed to 9 km/h. Include a pre-check that aborts if the treadmill entity is unavailable. Add a 5-second belt spin-up delay after turning the treadmill on. At the end, ensure the belt is stopped and send a notification "Workout complete". If the AI misreads a number, correct it by updating the prompt with the correct duration or count.

Iterate:

• If the AI produces a script with small mistakes, ask it to modify the script explicitly: "Change the run duration in round 3 to 2:30" or "Add a 3-second grace period when pausing".

When to avoid automation

Automation is convenient but not always appropriate.

High-risk medical protocols

• If the workout is part of a clinician-managed rehabilitation plan, obtain explicit approval before automating. Human oversight may be required.

Devices without reliable remote control

• If your treadmill’s Bluetooth disconnects frequently or if the manufacturer forbids third-party control, avoid delegating control to an AI.

Environments with unpredictable hazards

• If others frequently pass near the treadmill, automated starts and stops could create hazards. Consider added warning lights or audible announcements before each change.

FAQ

Q: Which treadmills does this work with? A: It works with treadmills that Home Assistant can control via an integration. For compact consumer models like Kingsmith WalkingPad, community integrations such as hass-walkingpad provide Bluetooth control. Check HACS and the integration’s compatibility list for supported models.

Q: Do I need to write YAML? A: No. The AI uses MCP to create or update scripts via Home Assistant’s API. You should still review the generated script in Home Assistant’s UI before running it.

Q: Will this read my heart rate and adjust speed automatically? A: Not by default. The described workflow converts a timed workout to treadmill speed changes. You can extend it to use heart-rate sensors in Home Assistant, but that requires additional automations and safety boundaries. Heart-rate-driven control should be deployed cautiously.

Q: Is it safe to let an AI control my treadmill? A: The AI can create scripts, but safety depends on your configuration and vigilance. Always review scripts, test at low speed, and ensure you can physically stop the treadmill. Add presence or power sensors to automatically pause the belt if you step off or the treadmill’s power behavior is abnormal.

Q: What about the official treadmill app? A: Reverse-engineered integrations typically allow only one Bluetooth client at a time. When Home Assistant holds the connection, the official app cannot connect simultaneously. That is a trade-off: full automation vs. app access.

Q: How do I handle units (km/h vs mph)? A: Specify units in the prompt and verify how your integration expects speed values. If the fitness plan uses a different unit than your treadmill, convert values in the prompt or ask the AI to output speeds in the correct units.

Q: Can I schedule generated workouts? A: Yes. Once the AI creates scripts, schedule them within Home Assistant like any other script or automation. Add voice or dashboard controls to start them manually.

Q: What happens if the AI misreads the screenshot? A: Inspect the generated script and correct errors directly in Home Assistant or with a follow-up prompt to the AI. Use clear screenshots and explicit prompts to minimize misreads.

Q: Are cloud AI clients required? A: No. You can run an AI client locally if available; that reduces the need to expose your Home Assistant instance externally. Using cloud-based AI requires secure authentication and careful network setup.

Q: Can this be used for group training? A: Yes. Home Assistant scripts can coordinate multiple devices. For group intervals across multiple treadmills, ensure each device is individually addressable and tested.

Q: Where can I find the required software packages? A: Search the Home Assistant Community Store (HACS) for integrations like hass-walkingpad. For MCP, look for ha-mcp on the Home Assistant AI GitHub organization. Verify repository maturity and installation instructions in their documentation.

Q: What if my treadmill firmware updates break the integration? A: Follow the integration repository for issues and fixes. Keep backups of working configurations and be prepared to revert treadmill firmware if that becomes an option and if compatibility is critical. Community-driven integrations can sometimes lag behind manufacturer changes.

Q: Should I give the AI write access to all devices? A: No. Apply the least-privilege principle. Grant the AI only the access it needs to create scripts and interact with the treadmill entities. Limit access to unrelated devices.

Q: Can I have the AI generate different variations (easy/medium/hard)? A: Yes. Provide the AI with desired parameters (speeds, durations, number of rounds) and ask it to create multiple scripts or a parameterized script that accepts inputs when run.

Q: Is there any cost to using the AI? A: Costs depend on the AI client. Some local or open-source solutions run free; cloud AI services may bill usage. The Home Assistant components (HACS, integrations, ha-mcp) are typically free and community-maintained.

Q: What if I need to stop mid-run? A: Use the treadmill’s physical stop button as your first and fastest safety lever. Automations can provide supplemental stop/pause triggers via sensors, but a human-operated emergency stop remains essential.

Q: How do I learn to create my own prompts? A: Start simple. Describe the target entity, the name of the script, and explicit units and speeds. Iterate: examine the generated script and refine the prompt if any detail is wrong. Save effective prompts as templates.

Automating treadmill interval workouts by combining Home Assistant, community integrations and an AI that understands screenshots removes repetitive button presses and lets you focus on the run. The approach scales to other fitness devices and forms the basis for a richer, sensor-aware training environment. Carefully review generated scripts, add layers of safety, and treat automation as an aid that must be supervised when it controls moving equipment underfoot.