Zwift Async - Home Assistant Integration

A fully async Home Assistant integration for Zwift that provides real-time sensor data for riders.

✨ Features

• 🚴 Real-time riding metrics: Heart rate, power, speed, cadence, altitude, and more
• 🔄 Fully async: No blocking I/O operations, minimal impact on Home Assistant
• ⚡ Performance optimized: Custom async API client using aiohttp
• 👥 Multiple riders: Track yourself and other riders simultaneously
• 🎨 UI Configuration: Easy setup through Home Assistant UI (no YAML required)
• 📊 Binary sensors: Online/offline status for each rider
• 🌍 World awareness: Knows which Zwift world the rider is in
• 📈 Progress tracking: Cycling and running level progress

📦 Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click on "Integrations"
3. Click the three dots in the top right corner
4. Select "Custom repositories"
5. Add this repository URL: https://github.com/xpenno255/zwift_async
6. Select category: "Integration"
7. Click "Add"
8. Find "Zwift Async" in HACS and install it
9. Restart Home Assistant

Manual Installation

1. Download the latest release from the releases page
2. Extract the zwift_async folder to your custom_components directory
3. Restart Home Assistant

🔧 Configuration

UI Configuration (Recommended)

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for "Zwift Async"
4. Enter your Zwift credentials
5. Choose whether to include your own rider
6. Optionally add other player IDs to track

YAML Configuration (Legacy)

sensor:
  - platform: zwift_async
    username: !secret zwift_username
    password: !secret zwift_password
    players:
      - 123456  # Friend's player ID
      - 789012  # Another friend's player ID
    include_self: true

📊 Sensors

For each tracked rider, the integration creates the following sensors:

Standard Sensors

• Online (binary_sensor): Whether the rider is currently riding
• Heart Rate (bpm): Current heart rate
• Power (W): Current power output
• Speed (mph/kmh): Current speed
• Cadence (rpm): Current pedaling cadence
• Altitude (ft/m): Current altitude
• Distance (miles/km): Distance covered in current ride
• Gradient (%): Current gradient

Progress Sensors

• Level: Current cycling level
• Run Level: Current running level
• Cycle Progress (%): Progress to next cycling level
• Run Progress (%): Progress to next running level

🌍 Supported Zwift Worlds

• Watopia
• Richmond
• London
• New York
• Innsbruck
• Bologna
• Yorkshire
• Crit City
• Makuri Islands
• France
• Paris

📝 Example Automations

Notify when friend starts riding

automation:
  - alias: "Notify when friend starts Zwift"
    trigger:
      - platform: state
        entity_id: binary_sensor.zwift_async_online_123456
        to: "on"
    action:
      - service: notify.mobile_app
        data:
          message: "Your friend just started riding on Zwift!"

Track personal records

automation:
  - alias: "New power PR"
    trigger:
      - platform: numeric_state
        entity_id: sensor.zwift_async_power_123456
        above: 350  # Your PR threshold
    condition:
      - condition: state
        entity_id: binary_sensor.zwift_async_online_123456
        state: "on"
    action:
      - service: notify.mobile_app
        data:
          message: "New power record: {{ states('sensor.zwift_async_power_123456') }}W!"

Dashboard card example

type: entities
title: Zwift Status
entities:
  - entity: binary_sensor.zwift_async_online_123456
    name: Riding
  - entity: sensor.zwift_async_heart_rate_123456
    name: Heart Rate
  - entity: sensor.zwift_async_power_123456
    name: Power
  - entity: sensor.zwift_async_speed_123456
    name: Speed
  - entity: sensor.zwift_async_cadence_123456
    name: Cadence

🔍 Finding Player IDs

You can find Zwift player IDs in several ways:

1. Zwift Companion App: Look in your profile or friends list
2. ZwiftPower: Your ID is in your profile URL: https://zwiftpower.com/profile.php?z=PLAYERID
3. Integration: After setup, your own player ID is shown in the options flow

⚡ Performance

This integration is fully async and uses:

• Custom async Zwift API client with aiohttp
• No blocking I/O operations
• Concurrent API calls for multiple riders
• Automatic token refresh
• Smart rate limiting

Performance comparison:

• Old (blocking): 100-500ms per update
• New (async): <10ms per update

🐛 Troubleshooting

Authentication Failed

• Verify your Zwift username and password are correct
• Check if Zwift service is online: https://status.zwift.com
• Try logging in directly on Zwift to ensure your account works

Rate Limiting (429 errors)

The integration automatically handles rate limiting by:

• Increasing update intervals when throttled
• Starting at 15s (offline) / 2s (online)
• Auto-adjusting in 0.25s increments

Enable Debug Logging

logger:
  default: info
  logs:
    custom_components.zwift_async: debug
    custom_components.zwift_async.async_zwift_client: debug

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

• Based on the original Zwift Home Assistant integration by @snicker
• Uses the unofficial Zwift API documented by the community
• Inspired by zwift-mobile-api

⚠️ Disclaimer

This is an unofficial integration and is not affiliated with, endorsed by, or connected to Zwift. Use at your own risk. Zwift does not provide an official public API, and this integration may break if Zwift makes changes to their unofficial API.

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Discussions

---

Enjoy your rides! 🚴‍♂️💨