🚀 APS2MQTT - Installation Guide

Complete guide to install and configure APS2MQTT to integrate your APSystems solar inverters with Home Assistant via MQTT.

📋 Table of Contents

Prerequisites
Installation Methods
Configuration
Home Assistant Integration
Troubleshooting

📦 Prerequisites

Hardware Requirements

Compatible APSystems ECU:
- ECU-B
- ECU-R (all versions)
- ECU-C
Compatible Inverters:
- YC1000 / QT2 (4 channels)
- YC600 / DS3 / DS3-H / DS3-L / DS3D (2 channels)
- QS1 / QS1A (4 channels)

Network Requirements

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

Test Your ECU Connection

Before installation, verify your ECU is accessible:

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

You should see:

192.168.1.42 (192.168.1.42:8899) open

Send test command:

APS1100160001END

If you receive an APS response, your ECU is ready! ✅

🐳 Installation Methods

Docker (Recommended)

Quick start with Docker:

docker run -d \
  --name aps2mqtt \
  --restart unless-stopped \
  -e TZ=Europe/Paris \
  -e APS_ECU_IP=192.168.1.42 \
  -e MQTT_BROKER_HOST=192.168.1.50 \
  -e MQTT_BROKER_PORT=1883 \
  -e MQTT_BROKER_USER=your_mqtt_user \
  -e MQTT_BROKER_PASSWD=your_mqtt_password \
  fligneul/aps2mqtt:latest

Docker Compose

Step 1: Download the configuration

# Create directory
mkdir aps2mqtt && cd aps2mqtt

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

Step 2: Configure your settings

Edit docker-compose.yml and set your values:

services:
  aps2mqtt:
    image: fligneul/aps2mqtt:latest
    container_name: aps2mqtt
    restart: unless-stopped
    
    environment:
      # Required settings
      - TZ=Europe/Paris
      - APS_ECU_IP=192.168.1.42          # Your ECU IP
      - MQTT_BROKER_HOST=192.168.1.50    # Your MQTT broker IP
      - MQTT_BROKER_PORT=1883
      - MQTT_BROKER_USER=mqtt_user       # Your MQTT username
      - MQTT_BROKER_PASSWD=mqtt_password # Your MQTT password
      
      # Optional: Night mode (stop querying at night)
      - APS_ECU_STOP_AT_NIGHT=True
      - APS_ECU_POSITION_LAT=48.864716   # Your latitude
      - APS_ECU_POSITION_LNG=2.349014    # Your longitude

Step 3: Start the container

docker-compose up -d

Step 4: Check logs

docker-compose logs -f aps2mqtt

Python Package

Step 1: Install via pip

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install package
pip install aps2mqtt

Step 2: Create configuration file

Create config.yaml:

ecu:
  APS_ECU_IP: '192.168.1.42'
  APS_ECU_TIMEZONE: 'Europe/Paris'
  APS_ECU_STOP_AT_NIGHT: True
  APS_ECU_POSITION_LAT: 48.864716
  APS_ECU_POSITION_LNG: 2.349014

mqtt:
  MQTT_BROKER_HOST: '192.168.1.50'
  MQTT_BROKER_PORT: 1883
  MQTT_BROKER_USER: 'mqtt_user'
  MQTT_BROKER_PASSWD: 'mqtt_password'

Step 3: Run the application

python3 -m aps2mqtt -c config.yaml

Optional: Run as systemd service

Create /etc/systemd/system/aps2mqtt.service:

[Unit]
Description=APS2MQTT
After=multi-user.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/home/your_user/aps2mqtt
ExecStart=/home/your_user/aps2mqtt/venv/bin/python3 -m aps2mqtt -c config.yaml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable aps2mqtt
sudo systemctl start aps2mqtt
sudo systemctl status aps2mqtt

⚙️ Configuration

Required Configuration

Parameter	Description	Example
`APS_ECU_IP`	IP address of your ECU	`192.168.1.42`
`MQTT_BROKER_HOST`	MQTT broker IP/hostname	`192.168.1.50`
`MQTT_BROKER_PORT`	MQTT broker port	`1883`

Optional Configuration

ECU Settings

Parameter	Description	Default
`APS_ECU_PORT`	ECU communication port	`8899`
`APS_ECU_TIMEZONE`	ECU timezone	System timezone
`APS_ECU_AUTO_RESTART`	Auto-restart ECU on error (ECU-C/modern ECU-R only)	`False`
`APS_ECU_WIFI_SSID`	WiFi SSID for auto-restart	-
`APS_ECU_WIFI_PASSWD`	WiFi password for auto-restart	-
`APS_ECU_STOP_AT_NIGHT`	Stop querying at night	`False`
`APS_ECU_POSITION_LAT`	Latitude for sunrise/sunset	`48.864716` (Paris)
`APS_ECU_POSITION_LNG`	Longitude for sunrise/sunset	`2.349014` (Paris)

MQTT Settings

Parameter	Description	Default
`MQTT_BROKER_USER`	MQTT username	-
`MQTT_BROKER_PASSWD`	MQTT password	-
`MQTT_CLIENT_ID`	MQTT client ID	`APS2MQTT`
`MQTT_TOPIC_PREFIX`	Topic prefix	-
`MQTT_BROKER_SECURED_CONNECTION`	Use TLS/SSL	`False`
`MQTT_BROKER_CACERTS_PATH`	Path to CA certificates	-

Other Settings

Parameter	Description	Default
`TZ`	Container timezone	`Europe/Paris`
`DEBUG`	Enable debug logging	`False`

Using .env File

Create a .env file in the same directory as docker-compose.yml:

TZ=Europe/Paris
DEBUG=False
APS_ECU_IP=192.168.1.42
APS_ECU_STOP_AT_NIGHT=True
APS_ECU_POSITION_LAT=48.864716
APS_ECU_POSITION_LNG=2.349014
MQTT_BROKER_HOST=192.168.1.50
MQTT_BROKER_PORT=1883
MQTT_BROKER_USER=mqtt_user
MQTT_BROKER_PASSWD=mqtt_password

Then simplify your docker-compose.yml:

services:
  aps2mqtt:
    image: fligneul/aps2mqtt:latest
    container_name: aps2mqtt
    restart: unless-stopped
    env_file: .env

🏠 Home Assistant Integration

MQTT Topics Published

APS2MQTT publishes comprehensive data about your solar installation:

ECU Level (15 entities)

{prefix}/aps/{ECU_ID}/power                    # Current power (W)
{prefix}/aps/{ECU_ID}/energy_today             # Today's energy (kWh)
{prefix}/aps/{ECU_ID}/energy_lifetime          # Lifetime energy (kWh)
{prefix}/aps/{ECU_ID}/firmware                 # ECU firmware version
{prefix}/aps/{ECU_ID}/timezone                 # ECU timezone
{prefix}/aps/{ECU_ID}/last_update              # Last update timestamp
{prefix}/aps/{ECU_ID}/inverters_qty            # Total inverters
{prefix}/aps/{ECU_ID}/online_inverters_qty     # Online inverters
{prefix}/aps/{ECU_ID}/offline_inverters_qty    # Offline inverters
{prefix}/aps/{ECU_ID}/average_temperature      # Average temperature
{prefix}/aps/{ECU_ID}/average_frequency        # Average AC frequency
{prefix}/aps/{ECU_ID}/querying                 # Query status
{prefix}/aps/{ECU_ID}/restart_ecu              # ECU restart status
{prefix}/aps/{ECU_ID}/restart_hard_ecu         # Hard restart status
{prefix}/aps/{ECU_ID}/status/bridge/device     # Connection status

Per Inverter (9 entities)

{prefix}/aps/{ECU_ID}/{INVERTER_ID}/online            # Online status
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/version           # Software version
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/model             # Inverter model
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/signal            # WiFi signal (dB)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/temperature       # Temperature (°C)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/frequency         # AC frequency (Hz)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/ac_voltage        # AC voltage (V)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/power             # Total power (W)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/channel_qty       # Number of panels

Per Panel (6 entities per channel)

{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/power           # Panel power (W)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/current_power   # Instantaneous power (W)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/ac_voltage      # AC voltage (V)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/ac_frequency    # AC frequency (Hz)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/dc_voltage      # DC voltage (V)
{prefix}/aps/{ECU_ID}/{INVERTER_ID}/{PANEL}/dc_temperature  # DC temperature (°C)

Auto-Discovery

APS2MQTT supports Home Assistant MQTT Discovery! All entities are automatically created with:

✅ Proper device classes (power, energy, temperature, etc.)
✅ Correct units of measurement
✅ Appropriate icons
✅ Logical device grouping (ECU + Inverters)

Configuration required in Home Assistant:

# configuration.yaml
mqtt:
  discovery: true
  discovery_prefix: homeassistant

After starting APS2MQTT, all devices will appear automatically in Home Assistant! 🎉

Manual MQTT Sensors (if not using discovery)

# configuration.yaml
mqtt:
  sensor:
    # ECU Total Power
    - name: "Solar Power"
      state_topic: "aps/216200063835/power"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement
      
    # Today's Energy
    - name: "Solar Energy Today"
      state_topic: "aps/216200063835/energy_today"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      
    # Inverter Temperature
    - name: "Inverter 1 Temperature"
      state_topic: "aps/216200063835/123456789ABC/temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement

🔧 Troubleshooting

Connection Issues

Problem: Cannot connect to ECU

# Verify ECU is reachable
ping 192.168.1.42

# Test ECU port
nc -v 192.168.1.42 8899

# Check Docker logs
docker-compose logs -f aps2mqtt

Solution:

Ensure ECU has a fixed IP address
Check firewall rules
Verify ECU is powered on and configured

MQTT Issues

Problem: Not receiving MQTT messages

# Test MQTT connection
mosquitto_sub -h 192.168.1.50 -p 1883 -u mqtt_user -P mqtt_password -t 'aps/#' -v

# Check MQTT broker logs
docker logs mosquitto

Solution:

Verify MQTT broker credentials
Check MQTT broker is running
Verify network connectivity

Debug Mode

Enable debug logging for detailed information:

environment:
  - DEBUG=True

Then check logs:

docker-compose logs -f aps2mqtt

Common Issues

Issue	Cause	Solution
ECU timeout	ECU not responding	Power cycle ECU, check network
Invalid data	Communication error	Enable auto-restart (if supported)
Night mode active	Sun has set	Normal behavior, will resume at sunrise
No MQTT messages	Wrong credentials	Check MQTT user/password
Entities not appearing in HA	Discovery disabled	Enable MQTT discovery in HA

📊 Example Dashboard

For an example installation with 1 ECU + 2 YC600 inverters (4 panels total):

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

All automatically available in Home Assistant! 🌟

🆘 Support

Issues: GitHub Issues
Documentation: ENTITIES.md for complete entity list
Refactoring Guide: REFACTORING.md for developers

📄 License

This project is licensed under the MIT License.

Made with ❤️ for the Home Assistant community

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 APS2MQTT - Installation Guide

📋 Table of Contents

📦 Prerequisites

Hardware Requirements

Network Requirements

Test Your ECU Connection

🐳 Installation Methods

Docker (Recommended)

Docker Compose

Python Package

⚙️ Configuration

Required Configuration

Optional Configuration

ECU Settings

MQTT Settings

Other Settings

Using .env File

🏠 Home Assistant Integration

MQTT Topics Published

ECU Level (15 entities)

Per Inverter (9 entities)

Per Panel (6 entities per channel)

Auto-Discovery

Manual MQTT Sensors (if not using discovery)

🔧 Troubleshooting

Connection Issues

MQTT Issues

Debug Mode

Common Issues

📊 Example Dashboard

🆘 Support

📄 License

FilesExpand file tree

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

🚀 APS2MQTT - Installation Guide

📋 Table of Contents

📦 Prerequisites

Hardware Requirements

Network Requirements

Test Your ECU Connection

🐳 Installation Methods

Docker (Recommended)

Docker Compose

Python Package

⚙️ Configuration

Required Configuration

Optional Configuration

ECU Settings

MQTT Settings

Other Settings

Using .env File

🏠 Home Assistant Integration

MQTT Topics Published

ECU Level (15 entities)

Per Inverter (9 entities)

Per Panel (6 entities per channel)

Auto-Discovery

Manual MQTT Sensors (if not using discovery)

🔧 Troubleshooting

Connection Issues

MQTT Issues

Debug Mode

Common Issues

📊 Example Dashboard

🆘 Support

📄 License