Skip to content

yuyuki/hacs_marstek_venus_e

BranchesTags

Repository files navigation

Marstek Venus E

Marstek Venus E - Home Assistant Integration

hacs_badge License: MIT

A comprehensive Home Assistant custom integration for the Marstek Venus E battery energy storage system. This integration provides full local control and monitoring via the device's UDP JSON-RPC API.

1. Features

✅ Automatic Device Discovery

  • UDP broadcast discovery on local network
  • Automatic device detection during setup
  • Manual IP entry fallback option

✅ Complete Monitoring

  • Battery status (SOC, temperature, capacity, charge/discharge state)
  • Solar PV generation (power, voltage, current)
  • Grid power flow (import/export)
  • Energy totals (PV, grid, load)
  • CT clamp readings (3-phase power monitoring)
  • WiFi signal strength

✅ Full Control

  • UI Mode Selector: Change modes directly from Home Assistant UI
  • UI Schedule Configuration: Set up charging/discharging schedules through UI (no YAML needed)
  • Operating Modes: Auto (Self-Consuming), AI, Manual, Passive
  • Real-time mode changes
  • Up to 10 time-based schedules (slots 0-9)
  • Automation Support: Configure all 10 schedules via Home Assistant automations

✅ Home Assistant Integration

  • Native Energy Dashboard support
  • Service calls for automation
  • Select entity for easy mode switching
  • Options flow for schedule configuration
  • 5-minute polling interval (configurable via options)
  • Non-blocking async implementation
  • Comprehensive device information
  • Multi-language support (English, French)

2. Installation

2.1. HACS (Recommended)

  1. Open HACS in Home Assistant
  2. Click the three dots in the top right corner
  3. Select "Custom repositories"
  4. Add this repository URL: https://github.com/yuyuki/hacs_marstek_venus_e
  5. Category: Integration
  6. Click "Add"
  7. Find "Marstek Venus E" in HACS and click "Download"
  8. Restart Home Assistant

2.2. Manual Installation

  1. Copy the custom_components/marstek_venus_e folder to your Home Assistant's custom_components directory
  2. Restart Home Assistant

3. Configuration

3.1. Adding the Integration

  1. Go to Settings → Devices & Services
  2. Click + Add Integration
  3. Search for "Marstek Venus E"
  4. Automatic Discovery:
    • The integration scans your network for Marstek devices
    • Found devices are displayed in a list
    • Select your device and click Submit
  5. Manual Configuration (if no devices found):
    • Select "Enter IP manually"
    • Enter device IP address, port (30000), and optional BLE MAC
    • Click Submit

3.2. Configuring Manual Schedules

After adding the integration, you can configure charging/discharging schedules in two ways:

3.2.1. Method 1: Through the UI (Recommended for Single Slots)

  1. Go to Settings → Devices & Services
  2. Find Marstek Venus E integration
  3. Click Configure (gear icon)
  4. Select "Configure Manual Mode Schedule"
  5. Set up your schedule:
    • Time Slot: Choose 0-9 (you can create 10 different schedules)
    • Start/End Time: When the schedule runs
    • Active Days: Select days of the week
    • Power: Negative to charge (-1000W), positive to discharge (+1000W)
    • Enable: Toggle to activate
  6. Click Submit

3.2.2. Method 2: Through Automations (Recommended for Multiple Slots)

Configure all 10 schedule slots automatically when you switch to Manual mode using Home Assistant automations. This is the easiest way to set up complex schedules!

Quick Start:

  1. Copy the example automation from example_automation.yaml in this repository
  2. Paste it into your Home Assistant automations
  3. Adjust times, power levels, and days to match your needs
  4. Save and test by switching to Manual mode!

Benefits:

  • Configure all 10 slots in one action
  • Different schedules for weekdays vs weekends
  • Dynamic schedules based on battery level, weather, or electricity prices
  • Seasonal adjustments (winter vs summer patterns)

See the Manual Mode Automation Guide for detailed examples and best practices.

4. Entities

4.1. Sensors

4.1.1. Battery

  • sensor.marstek_venus_e_battery_state_of_charge - Battery SOC (%)
  • sensor.marstek_venus_e_battery_temperature - Battery temperature (°C)
  • sensor.marstek_venus_e_battery_capacity - Current battery capacity (Wh)
  • sensor.marstek_venus_e_battery_rated_capacity - Rated battery capacity (Wh)
  • sensor.marstek_venus_e_battery_power - Battery charging/discharging power (W)

4.1.2. Solar PV

  • sensor.marstek_venus_e_pv_power - Solar generation power (W)
  • sensor.marstek_venus_e_pv_voltage - PV voltage (V)
  • sensor.marstek_venus_e_pv_current - PV current (A)

4.1.3. Grid & Energy

  • sensor.marstek_venus_e_grid_power - Grid import/export power (W)
  • sensor.marstek_venus_e_offgrid_power - Off-grid power (W)
  • sensor.marstek_venus_e_total_pv_energy - Total PV energy generated (kWh)
  • sensor.marstek_venus_e_total_grid_export_energy - Total energy exported to grid (Wh)
  • sensor.marstek_venus_e_total_grid_import_energy - Total energy imported from grid (Wh)
  • sensor.marstek_venus_e_total_load_energy - Total load consumption (kWh)

4.1.4. CT Meter (if installed)

  • sensor.marstek_venus_e_phase_a_power - Phase A power (W)
  • sensor.marstek_venus_e_phase_b_power - Phase B power (W)
  • sensor.marstek_venus_e_phase_c_power - Phase C power (W)
  • sensor.marstek_venus_e_total_ct_power - Total CT power (W)

4.1.5. System

  • sensor.marstek_venus_e_wifi_signal_strength - WiFi RSSI (dBm)
  • sensor.marstek_venus_e_wifi_ssid - Connected WiFi network
  • sensor.marstek_venus_e_operating_mode - Current operating mode

4.2. Binary Sensors

  • binary_sensor.marstek_venus_e_battery_charging - Battery charging status
  • binary_sensor.marstek_venus_e_battery_discharging - Battery discharging status
  • binary_sensor.marstek_venus_e_ct_meter_connected - CT meter connection status

4.3. Select Entities

  • select.operating_mode - Change operating mode (Auto, AI, Manual, Passive)
    • Auto: Self-consumption optimization
    • AI: Intelligent mode based on usage patterns
    • Manual: Time-based schedules (configure via integration options)
    • Passive: Fixed power target mode

5. Services

5.1. marstek_venus_e.set_mode

Set the operating mode of your system.

Modes:

  • Auto - Automatic operation based on device algorithms
  • AI - AI-optimized operation
  • Manual - Time-based schedule control
  • Passive - Follow a specific power target
service: marstek_venus_e.set_mode
data:
  mode: "Auto"

5.2. marstek_venus_e.set_manual_schedule

Configure a manual charging/discharging schedule.

service: marstek_venus_e.set_manual_schedule
data:
  time_num: 0  # Time slot 0-9 (10 slots available!)
  start_time: "09:00"
  end_time: "17:00"  # MUST be greater than start_time
  week_set: 127  # All days (byte-based: 1=Mon, 2=Tue, 4=Wed, 8=Thu, 16=Fri, 32=Sat, 64=Sun)
  mode: "Charging"  # "Charging" or "Discharging"
  power: 500  # 100-2500W magnitude (always positive)
  enable: true

Important Constraints:

  • end_time must be greater than start_time
  • mode must be "Charging" (negative power) or "Discharging" (positive power)
  • power magnitude must be between 100 and 2500 watts (always positive)
  • week_set uses byte-based bitmask

Week Set Bitmask:

  • Monday: 1
  • Tuesday: 2
  • Wednesday: 4
  • Thursday: 8
  • Friday: 16
  • Saturday: 32
  • Sunday: 64
  • All days: 127 (sum of all)
  • Weekdays only: 31
  • Weekend only: 96

5.3. marstek_venus_e.set_passive_mode

Set passive mode with a power target.

service: marstek_venus_e.set_passive_mode
data:
  power: 2000  # Target power in watts
  cd_time: 3600  # Countdown in seconds (0 = indefinite)

6. Lovelace Dashboard Examples

6.1. Battery Status Card

type: vertical-stack
cards:
  - type: gauge
    entity: sensor.marstek_venus_e_battery_state_of_charge
    name: Battery Level
    min: 0
    max: 100
    needle: true
    severity:
      green: 60
      yellow: 30
      red: 0
  
  - type: entities
    entities:
      - entity: sensor.marstek_venus_e_battery_power
        name: Battery Power
      - entity: sensor.marstek_venus_e_battery_temperature
        name: Temperature
      - entity: binary_sensor.marstek_venus_e_battery_charging
        name: Charging
      - entity: binary_sensor.marstek_venus_e_battery_discharging
        name: Discharging
      - entity: sensor.marstek_venus_e_battery_capacity
        name: Current Capacity

6.2. Energy Flow Card

type: vertical-stack
cards:
  - type: horizontal-stack
    cards:
      - type: statistic
        entity: sensor.marstek_venus_e_pv_power
        name: Solar
        icon: mdi:solar-power
        stat_type: mean
        period:
          calendar:
            period: day
      
      - type: statistic
        entity: sensor.marstek_venus_e_grid_power
        name: Grid
        icon: mdi:transmission-tower
        stat_type: mean
        period:
          calendar:
            period: day
      
      - type: statistic
        entity: sensor.marstek_venus_e_battery_power
        name: Battery
        icon: mdi:battery
        stat_type: mean
        period:
          calendar:
            period: day
  
  - type: entities
    title: Energy Today
    entities:
      - entity: sensor.marstek_venus_e_total_pv_energy
        name: PV Generated
      - entity: sensor.marstek_venus_e_total_grid_import_energy
        name: Grid Import
      - entity: sensor.marstek_venus_e_total_grid_export_energy
        name: Grid Export
      - entity: sensor.marstek_venus_e_total_load_energy
        name: Total Consumption

6.3. Complete Dashboard

title: Marstek Venus E
type: vertical-stack
cards:
  # Header with mode
  - type: entities
    entities:
      - entity: sensor.marstek_venus_e_operating_mode
        name: Operating Mode
  
  # Battery gauge
  - type: gauge
    entity: sensor.marstek_venus_e_battery_state_of_charge
    name: Battery
    min: 0
    max: 100
    needle: true
    severity:
      green: 60
      yellow: 30
      red: 0
  
  # Power flow
  - type: horizontal-stack
    cards:
      - type: entity
        entity: sensor.marstek_venus_e_pv_power
        name: Solar
        icon: mdi:solar-power
      - type: entity
        entity: sensor.marstek_venus_e_grid_power
        name: Grid
        icon: mdi:transmission-tower
      - type: entity
        entity: sensor.marstek_venus_e_battery_power
        name: Battery
        icon: mdi:battery
  
  # Energy totals
  - type: entities
    title: Energy
    entities:
      - sensor.marstek_venus_e_total_pv_energy
      - sensor.marstek_venus_e_total_grid_import_energy
      - sensor.marstek_venus_e_total_grid_export_energy
      - sensor.marstek_venus_e_total_load_energy
  
  # Mode control buttons
  - type: horizontal-stack
    cards:
      - type: button
        name: Auto
        icon: mdi:autorenew
        tap_action:
          action: call-service
          service: marstek_venus_e.set_mode
          data:
            mode: "Auto"
      - type: button
        name: AI
        icon: mdi:brain
        tap_action:
          action: call-service
          service: marstek_venus_e.set_mode
          data:
            mode: "AI"
      - type: button
        name: Manual
        icon: mdi:clock-outline
        tap_action:
          action: call-service
          service: marstek_venus_e.set_mode
          data:
            mode: "Manual"

7. Energy Dashboard Configuration

Add your Marstek Venus E to Home Assistant's Energy Dashboard:

  1. Go to Settings → Dashboards → Energy
  2. Click Add Consumption:
    • Select sensor.marstek_venus_e_total_load_energy
  3. Click Add Solar Production:
    • Select sensor.marstek_venus_e_total_pv_energy
  4. Click Add Battery:
    • Energy in: sensor.marstek_venus_e_total_grid_import_energy
    • Energy out: sensor.marstek_venus_e_total_grid_export_energy
  5. Click Add Grid Consumption:
    • Grid import: sensor.marstek_venus_e_total_grid_import_energy
  6. Click Add Return to Grid:
    • Grid export: sensor.marstek_venus_e_total_grid_export_energy

8. Automation Examples

8.1. Auto-Configure All 10 Schedules When Switching to Manual Mode

The best way to use Manual mode is to automatically configure all 10 schedule slots when you switch to it:

automation:
  - alias: "Marstek - Auto-Configure on Manual Mode"
    trigger:
      - platform: state
        entity_id: select.operating_mode
        to: "Manual"
    action:
      # Slot 0: Night charging
      - service: marstek_venus_e.set_manual_schedule
        data:
          time_num: 0
          start_time: "01:00"
          end_time: "06:00"
          week_set: 127  # All days
          mode: "Charging"
          power: 2500  # Charge at 2500W (maximum)
          enable: true
      
      # Slot 1: Morning peak discharge (weekdays)
      - service: marstek_venus_e.set_manual_schedule
        data:
          time_num: 1
          start_time: "07:00"
          end_time: "09:00"
          week_set: 31  # Weekdays only
          mode: "Discharging"
          power: 700  # Discharge at 700W
          enable: true
      
      # Slot 2: Evening peak discharge
      - service: marstek_venus_e.set_manual_schedule
        data:
          time_num: 2
          start_time: "18:00"
          end_time: "22:00"
          week_set: 127  # All days
          mode: "Discharging"
          power: 750  # Discharge at 750W
          enable: true
      
      # ... configure remaining slots 3-9 as needed

📖 See the Manual Mode Automation Guide for:

  • Complete 10-slot configuration examples
  • Seasonal schedules (winter vs summer)
  • Dynamic schedules based on battery level
  • Price-based charging strategies
  • Weekend vs weekday patterns

8.2. Charge Battery During Cheap Hours (Single Slot)

automation:
  - alias: "Charge Battery at Night"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: marstek_venus_e.set_manual_schedule
        data:
          time_num: 0
          start_time: "01:00"
          end_time: "07:00"  # Must be > start_time
          week_set: 127  # Every day
          power: 2500  # Maximum (2500W)
          enable: true
      - service: marstek_venus_e.set_mode
        data:
          mode: "Manual"

8.3. Switch to Auto During Day

automation:
  - alias: "Auto Mode During Day"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: marstek_venus_e.set_mode
        data:
          mode: "Auto"

8.4. Low Battery Alert

automation:
  - alias: "Low Battery Warning"
    trigger:
      - platform: numeric_state
        entity_id: sensor.marstek_venus_e_battery_state_of_charge
        below: 20
    action:
      - service: notify.mobile_app
        data:
          title: "Low Battery"
          message: "Marstek battery is at {{ states('sensor.marstek_venus_e_battery_state_of_charge') }}%"

8.5. Maximize Self-Consumption

automation:
  - alias: "Store Excess Solar"
    trigger:
      - platform: numeric_state
        entity_id: sensor.marstek_venus_e_pv_power
        above: 2000
    condition:
      - condition: numeric_state
        entity_id: sensor.marstek_venus_e_battery_state_of_charge
        below: 95
    action:
      - service: marstek_venus_e.set_passive_mode
        data:
          power: -2000  # Charge battery
          cd_time: 0  # Until solar drops

9. Troubleshooting

9.1. Integration Not Appearing

  1. Ensure you've restarted Home Assistant after installation
  2. Check custom_components/marstek_venus_e/manifest.json exists
  3. Review Home Assistant logs for errors

9.2. Cannot Connect to Device

  1. Verify the device IP address is correct
  2. Ensure device and Home Assistant are on the same network
  3. Check if port 30000 (UDP) is accessible
  4. Try pinging the device: ping <device_ip>
  5. Verify the device is powered on and connected to WiFi

9.3. Missing Sensors

Some sensors depend on hardware configuration:

  • CT sensors require CT clamps to be installed
  • Check that the device firmware supports all API endpoints

9.4. Enable Debug Logging

Add to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.marstek_venus_e: debug

Then check logs at Settings → System → Logs

10. API Reference

This integration uses the Marstek Device Local API (UDP JSON-RPC). For complete API documentation, refer to the local API reference document in doc/MarstekDeviceOpenApi 2.0.pdf.

11. Support

12. Contribution

Contributions are welcome. This repository is a Home Assistant custom integration, so the best changes are usually small, focused, and easy to validate locally before opening a pull request.

12.1. Develop Locally

  1. Fork or clone the repository.
  2. Open the project in VS Code or your editor of choice.
  3. Make your changes under custom_components/marstek_venus_e/.
  4. Keep the code style consistent with the existing files.
  5. Update README.md, tests, or docs when behavior changes.

If you are adding or changing an entity, service, or config flow, check the corresponding file in custom_components/marstek_venus_e/ and keep the names, translations, and platform registration aligned.

12.2. Run Tests

This project uses pytest for automated tests. The test suite is split into individual scripts under tests/ so you can run either a single scenario or the whole suite.

Run all tests:

pytest tests

Run a specific test script:

python tests/test_api_functions.py
python tests/test_discovery.py
python tests/test_es_get_status.py --ip 192.168.0.225

If you want a more detailed guide for the available scripts, see tests/README_TESTS.md.

12.3. Run In A Container

For real device testing, you can run Home Assistant in a container and mount this integration into the container’s /config/custom_components directory.

When you mount a local Home Assistant config directory to /config, that mount replaces the /config directory from the image. If you want to use a persistent config directory and the local development version of this integration, mount both paths:

  1. Your Home Assistant config directory to /config.
  2. This repository's integration folder to /config/custom_components/hacs_marstek_venus_e.

The official image is:

homeassistant/home-assistant

To download it before you run the container, use:

docker pull homeassistant/home-assistant:stable

With Podman, the equivalent command is:

podman pull docker.io/homeassistant/home-assistant:stable
podman build -f docker/Dockerfile -t marstek-ha .

This pulls the stable tag from Docker Hub, which is the version most people use for local testing.

Generic Docker Example

podman run -d \
  --name homeassistant \
  --network=host \
  -e TZ=Europe/Brussels \
  -v /path/to/your/config:/config \
  -v /path/to/this/repo/custom_components/hacs_marstek_venus_e:/config/custom_components/hacs_marstek_venus_e \
  homeassistant/home-assistant:stable

Use --network=host when you need the container to discover your local Marstek device by UDP broadcast.

Windows + Podman Example

On Windows, Podman usually runs the container inside a Linux VM, so the simplest setup is to use a named volume or a bind mount from a directory that Podman can access.

podman machine init
podman machine start
podman run -d `
  --name homeassistant `
  --network=host `
  -e TZ=Europe/Brussels `
  -v C:\ha-config:/config `
  -v E:\Projets\hacs_marstek_venus_e\custom_components\hacs_marstek_venus_e:/config/custom_components/hacs_marstek_venus_e `
  homeassistant/home-assistant:stable

Notes for Windows:

  1. Use a path that Podman can share with the VM.
  2. If the bind mount is awkward, copy the integration folder into your Home Assistant config directory instead.
  3. If UDP discovery does not work in container mode, prefer a manual IP setup for the first test pass.

Suggested Test Flow

  1. Start Home Assistant in the container.
  2. Copy or mount the integration into custom_components/hacs_marstek_venus_e.
  3. Add the integration in Home Assistant.
  4. Validate discovery and status sensors.
  5. Use the service calls and manual schedule features to confirm write operations.

Contributions are usually easiest to review when they include:

  1. A clear description of the behavior change.
  2. A test case or test script update.
  3. Any README or documentation updates needed for new behavior.

13. License

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

14. Disclaimer

This is an unofficial integration. It is not affiliated with or endorsed by Marstek. Use at your own risk.

15. Credits

  • Integration developed for Home Assistant
  • Based on Marstek Device Open API documentation
  • Inspired by the Home Assistant community

Enjoy your Marstek Venus E integration! ⚡🔋

About

Home Assistant integration for Marstek Venus E solar inverter. Monitor real-time solar production, battery status, and energy metrics. Features binary/numeric sensors, custom services, UDP communication, and multi-language support (EN/FR).

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

3 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages