Skip to content

Home

Jump to bottom
d0n0van edited this page Oct 29, 2025 · 2 revisions

Marstek Cloud Battery Integration Wiki

Welcome to the Marstek Cloud Battery integration wiki! This page provides comprehensive documentation, troubleshooting guides, and tips for using this Home Assistant integration.

📚 Table of Contents

Quick Start Guide

The fastest way to get started:

  1. Install via HACS (recommended) or manually
  2. Restart Home Assistant
  3. Go to Settings → Devices & Services → Add Integration
  4. Search for "Marstek Cloud Battery"
  5. Enter your Marstek cloud credentials
  6. Configure scan interval (default: 60 seconds)
  7. Set battery capacities if needed

Once configured, your battery sensors will appear in Home Assistant!

Installation

HACS Installation (Recommended)

  1. Install HACS if you haven't already
  2. In HACS, go to Integrations
  3. Click the three dots menu (⋮) and select Custom repositories
  4. Add repository: https://github.com/d0n0van/marstek_cloud
  5. Select Integration as the category
  6. Click Add then Install
  7. Restart Home Assistant

Manual Installation

  1. Download the latest release from the Releases page
  2. Extract the marstek_cloud folder
  3. Copy it to your Home Assistant custom_components directory:
    • Home Assistant OS/Supervised: /config/custom_components/
    • Home Assistant Container: /config/custom_components/
    • Home Assistant Core: Your config directory's custom_components/
  4. Restart Home Assistant

Configuration

Initial Setup

During setup, you'll be asked for:

  • Email: Your Marstek cloud account email
  • Password: Your Marstek cloud account password
  • Scan Interval: How often to poll the API (10-3600 seconds, default: 60)
  • Default Battery Capacity: Default capacity for all batteries in kWh (default: 5.12)

Updating Configuration

After initial setup, you can update settings via:

  1. Go to Settings → Devices & Services
  2. Find Marstek Cloud Battery integration
  3. Click Configure (or the three dots menu)
  4. Update scan interval or battery capacities

Battery Capacity Configuration

Each battery can have its own capacity setting:

  • Set during initial setup for all batteries
  • Update individual battery capacities via the Options menu
  • Capacity is used to calculate total_charge (soc × capacity)

Troubleshooting

Integration Not Appearing

Problem: Can't find "Marstek Cloud Battery" in the integration search.

Solutions:

  • Ensure the integration is properly installed in custom_components/marstek_cloud/
  • Check that manifest.json exists in the integration folder
  • Restart Home Assistant
  • Clear browser cache

Authentication Errors

Problem: "Authentication failed" or "Login failed" errors.

Solutions:

  • Verify your email and password are correct
  • Check your Marstek cloud account status
  • Ensure your account has API access
  • Check Home Assistant logs for detailed error messages

No Data / Sensors Not Updating

Problem: Sensors show as "unavailable" or don't update.

Solutions:

  • Check the connection_status diagnostic sensor
  • Review api_latency diagnostic sensor for slow responses
  • Verify your scan interval is appropriate (not too frequent)
  • Check Home Assistant logs for API errors
  • Verify your devices are online in the Marstek cloud portal

Rate Limiting

Problem: Getting rate limit errors in logs.

Solutions:

  • Increase your scan interval (reduce API call frequency)
  • Recommended minimum: 60 seconds
  • The integration automatically handles rate limits with retries

API Latency Issues

Problem: High latency reported in diagnostic sensor.

Solutions:

  • High latency usually indicates network or API server issues
  • Check your internet connection
  • Marstek API servers may be experiencing high load
  • Consider increasing scan interval to reduce load

Energy Dashboard Setup

This integration provides native Energy Dashboard support!

Option 1: Use Native kWh Sensors (Recommended)

  1. Go to Settings → Energy
  2. In the Battery section, click Add battery storage
  3. Select your battery's charge_power_kwh sensor
  4. Select your battery's discharge_power_kwh intermittent sensor
  5. Repeat for each battery if you have multiple

Option 2: Manual Template Sensors

If you prefer custom sensor names, you can create template sensors:

template:
  - sensor:
      - name: "Marstek Charge"
        unit_of_measurement: "kWh"
        state: "{{ (states('sensor.mst_vnse3_a4c2_charge_power') | float(0) / 1000) | round(2) }}"
        state_class: total
        device_class: energy
      - name: "Marstek Discharge"
        unit_of_measurement: "kWh"
        state: "{{ (states('sensor.mst_vnse3_a4c2_discharge_power') | float烟雾(0) / 1000) | round(2) }}"
        state_class: total
        device_class: energy

Note: Replace mst_vnse3_a4c2 with your actual device ID (found in Settings → Devices & Services → Entities).

Advanced Configuration

Scan Interval Optimization

The scan interval affects:

  • API load: More frequent = higher load
  • Data freshness: More frequent = more up-to-date data
  • Battery usage: More frequent = more battery usage (for mobile installations)

Recommendations:

  • Default: 60 seconds (good balance)
  • Low power/rate limit concerns: 300-600 seconds
  • Maximum freshness: 10-30 seconds (use with caution)

Multiple Battery Systems

If you have multiple Marstek battery systems:

  • Each system requires its own integration instance
  • Use different scan intervals if needed
  • Sensors will have unique names per instance

Total Charge Calculation

The total_charge sensor calculates: (soc / 100) × capacity_kwh

  • Ensure your battery capacity is correctly set
  • Update capacity via Options menu if incorrect
  • Capacity can be set per device

API Information

Endpoints Used

  • Login: POST https://eu.hamedata.com/app/Solar/v2_get_device.php
  • Get Devices: GET https://eu.hamedata.com/ems/api/v1/getDeviceList

Authentication

  • Uses MD5 hashed passwords (required by Marstek API)
  • Tokens automatically refresh when expired
  • Handles authentication errors gracefully

Security

  • Passwords are encrypted at rest by Home Assistant
  • Sensitive data is never logged
  • All API communication uses HTTPS

Frequently Asked Questions

Q: Why MD5 for password hashing?

A: The Marstek cloud API requires client-side MD5 hashing. This is an API requirement, not a choice by this integration. Passwords are properly secured in Home Assistant's encrypted storage and never logged.

Q: Can I use this integration with multiple Marstek accounts?

A: Yes! Add multiple integration instances, each with different credentials.

Q: How often should I poll the API?

A: 60 seconds is recommended for most users. Reduce frequency if experiencing rate limits, increase if you need more frequent updates (but be mindful of API load).

Q: My battery capacity is wrong. How do I fix it?

A: Go to Settings → Devices & Services → Marstek Cloud Battery → Configure (or Options) and update the capacity for the specific battery.

Q: Can I see historical data?

A: Yes! Home Assistant automatically stores sensor history. You can view it in the sensor history panel or create graphs in Lovelace.

Q: Does this work with Home Assistant Energy Dashboard?

A: Yes! The integration provides native kWh sensors specifically designed for the Energy Dashboard. See the Energy Dashboard Setup section above.

Q: Will this work if I'm not in Europe?

A: The API endpoints point to eu.hamedata.com. If you're outside Europe, you may experience higher latency. Contact Marstek support if you need region-specific endpoints.

Development & Contributing

Running Tests

# Activate development environment
source activate_env.sh

# Run unit tests
python -m pytest tests/test_coordinator.py -v

# Run all tests (excluding integration tests)
python run_tests.py

# Run integration tests (requires real credentials)
python run_integration_test.py

Code Quality

  • Uses black for code formatting
  • Uses flake8 for linting
  • Uses mypy for type checking
  • Pre-commit hooks available

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Ensure all tests pass
  6. Submit a pull request

See the README for more development details.

Additional Resources

Version History

  • v0.6.9 - Security improvements: Password redaction, security documentation
  • v0.6.8 - Previous stable release
  • See Releases for full changelog

Note: This is a community-maintained integration. For official Marstek support, contact Marstek directly.

Clone this wiki locally