Skip to content

README.md

Latest commit

 

History

History
258 lines (177 loc) · 7.25 KB

README.md

File metadata and controls

258 lines (177 loc) · 7.25 KB

APS2MQTT

Projet dérivé de fligneul/aps2mqtt - Version internalisée avec améliorations spécifiques

🌟 v2.1.0 - Modern architecture, comprehensive monitoring, ECU CONTROL, auto-discovery!

Access your APsystems Energy Communication Unit (ECU) data via MQTT. This bridge queries the ECU directly, parses data, and publishes it over MQTT with automatic Home Assistant integration.

✨ New in 2.1.0 (January 2026):

  • 🎛️ ECU Control for ECU-R-Pro (2162) & ECU-C (215)
    • 🔌 Switch ON/OFF all inverters remotely
    • 🔄 Reboot ECU button
  • 🚨 Intelligent alerts (offline, temperature, low production)
  • 📊 57+ entities for complete monitoring (1 ECU + 2 inverters)
  • 🏠 Auto-discovery for Home Assistant
  • 🔋 Per-panel monitoring (DC voltage, temperature, frequency)
  • 📈 Aggregate statistics (average temp, frequency)

ℹ️ Currently supports one ECU with unlimited inverters.

📚 Documentation

🚀 Quick Start

Docker Compose (Recommended)

# Download example configuration
wget https://raw.githubusercontent.com/fligneul/aps2mqtt/main/docker-compose.yml.example

# Edit with your settings
cp docker-compose.yml.example docker-compose.yml
nano docker-compose.yml

# Start container
docker-compose up -d

Docker

docker run -d \
  --name aps2mqtt \
  --restart unless-stopped \
  -e APS_ECU_IP=192.168.1.42 \
  -e MQTT_BROKER_HOST=192.168.1.50 \
  -e MQTT_BROKER_USER=mqtt_user \
  -e MQTT_BROKER_PASSWD=mqtt_password \
  fligneul/aps2mqtt:latest

🏠 Home Assistant Integration

Automatic Discovery - All entities are automatically created in Home Assistant!

Enable MQTT discovery in Home Assistant:

# configuration.yaml
mqtt:
  discovery: true

What you get:

  • ✅ 15 ECU entities (power, energy, firmware, statistics)
  • ✅ 9 entities per inverter (temperature, voltage, frequency, power)
  • ✅ 6 entities per panel (DC voltage, temperature, AC frequency, power)
  • ✅ Proper device classes and units
  • ✅ Beautiful icons and grouping

See ENTITIES.md for the complete list.

Acknowledgements

This work is based on the awesome homeassistant-apsystems_ecur (v1.2.30). This couldn't have been done without their hardwork.

Prerequisites

Compatible Hardware

  • ECU Models:

    • ECU-B
    • ECU-R (all versions, ID 2160xxx or 2162xxx)
    • ECU-C

  • Inverter Models:

    • YC1000 / QT2 (4 channels)
    • YC600 / DS3 / DS3-H / DS3-L / DS3D (2 channels)
    • QS1 / QS1A (4 channels)

Requirements

  • ECU with fixed IP address on your network
  • ECU configured via EMA Manager
  • MQTT broker (Mosquitto, HiveMQ, etc.)
  • Open port 8899 on ECU

📖 Full details: See Installation Guide

Test your connection

Verify ECU accessibility before installation:

# Test connection (replace with your ECU IP)
nc -v 192.168.1.42 8899

Expected response:

192.168.1.42 (192.168.1.42:8899) open

Send test command:

APS1100160001END

If you receive an APS response, you're ready! ✅

📖 Troubleshooting: See Installation Guide

Install

📖 Complete Installation Guide: INSTALL.md

Quick Options

Docker Compose (Recommended):

wget https://raw.githubusercontent.com/fligneul/aps2mqtt/main/docker-compose.yml.example
cp docker-compose.yml.example docker-compose.yml
# Edit docker-compose.yml with your settings
docker-compose up -d

Docker:

docker run -d \
  --name aps2mqtt \
  -e APS_ECU_IP=192.168.1.42 \
  -e MQTT_BROKER_HOST=192.168.1.50 \
  fligneul/aps2mqtt:latest

Python Package:

pip3 install aps2mqtt
python3 -m aps2mqtt -c config.yaml

Configuration Files

Configuration

📖 Complete Configuration Guide: INSTALL.md#configuration

Required Parameters

Parameter Description Example
APS_ECU_IP ECU IP address 192.168.1.42
MQTT_BROKER_HOST MQTT broker address 192.168.1.50

Key Optional Parameters

Parameter Description Default
APS_ECU_STOP_AT_NIGHT Stop querying at night False
APS_ECU_AUTO_RESTART Auto-restart ECU on error False
MQTT_BROKER_PORT MQTT port 1883
MQTT_TOPIC_PREFIX Topic prefix ""
TZ Timezone Europe/Paris

See INSTALL.md for all 20+ parameters

MQTT Topics

📖 Complete Entity List: ENTITIES.md

Overview

For a typical installation (1 ECU + 2 YC600 inverters):

  • 57 MQTT topics published
  • 15 ECU entities (power, energy, stats, firmware)
  • 21 entities per inverter (9 inverter + 12 panel metrics)

Topic Structure

{prefix}/aps/{ECU_ID}/...                          # ECU level
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/...            # Inverter level
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/...    # Panel level

Examples

ECU Topics:

aps/216200063835/power                    → 630 (W)
aps/216200063835/energy_today             → 25.8 (kWh)
aps/216200063835/firmware                 → ECU_R_2.1.5
aps/216200063835/average_temperature      → 46.5 (°C)

Inverter Topics:

aps/216200063835/123456789ABC/online      → on
aps/216200063835/123456789ABC/version     → INV_1.2.3
aps/216200063835/123456789ABC/temperature → 45 (°C)
aps/216200063835/123456789ABC/power       → 310 (W)

Panel Topics (per channel):

aps/216200063835/123456789ABC/1/power           → 150 (W)
aps/216200063835/123456789ABC/1/dc_voltage      → 38.5 (V)
aps/216200063835/123456789ABC/1/dc_temperature  → 42.5 (°C)
aps/216200063835/123456789ABC/2/current_power   → 159.2 (W)

See ENTITIES.md for the complete reference

📝 License

MIT License

🙏 Credits

Ce projet est basé sur le travail original de fligneul/aps2mqtt.

Merci également à :

  • @checking12 et @HAEdwin (Home Assistant forum) - Analyse du protocole APSystems
  • @12christiaan et @ViperRNMC - Solutions de redémarrage automatique ECU
  • Communauté Tweakers.net - Reverse engineering du protocole