Allows you to access your APsystems Energy Communication Unit (ECU) data by MQTT. This MQTT bridge queries the ECU directly at regular interval for new data, parse the returned data and publish them over MQTT.
In this way you can integrate your APsystems devices with whatever smart home infrastructure you are using.
This work is based on the awesome homeassistant-apsystems_ecur (v1.2.30). This couldn't have been done without their hardwork.
- A compatible APSystems ECU
- ECU-B
- ECU-R
- ECU-C
- Some inverters
- YC1000/QT2
- YC600/DS3/DS3-H/DS3-L/DS3D
- QS1/QS1A
Your ECU needs to be fully configured by the EMA Manager and should have a fixed IP address. APS2MQTT should run on a machine in the same network (or in an accessible one) as the ECU.
ECU-C and modern ECU-R (ID starting with 2162) can be automatically restarted in case of connection error. For older ECU-R and for ECU-B, the restart need to be done manually.
You can test the connection between APS2MQTT and the ECU using Netcat. From your terminal, run the following command (assuming your ECU IP address is 192.168.1.42) to open the connection
nc -v 192.168.1.42 8899ECU should response with an "open" message
192.168.1.42 (192.168.1.42:8899) openConnection is now established, the ECU is ready to receive commands
APS1100160001ENDIf this command return with an APS message, you are ready to start APS2MQTT. If not, rebbot your ECU and try again.
Binaries are available in the release asset or on PyPI. Using a virtual env is recommended for better insulation.
# with PyPI
pip3 install aps2mqtt
# manually
pip3 install aps2mqtt-[version]-py3-none-any.whlStart it
python3 -m aps2mqtt -hUsing systemd, APS2MQTT can be started automatically
[Unit]
Description=APS2MQTT
After=multi-user.target
[Service]
Type=simple
User=user
Restart=on-failure
ExecStart=/path-to-your-venv/python3 -m aps2mqtt -c config.yaml
[Install]
WantedBy=multi-user.targetAPS2MQTT configuration can be provided by a yaml config file or by environment variables (in a container context for example).
| Key | Description | Example | Default value |
|---|---|---|---|
| MQTT_BROKER_HOST | Host of the MQTT broker | "192.168.1.1", "broker.hivemq.com" | "127.0.0.1" |
| MQTT_BROKER_PORT | Port of the MQTT broker | 1883 | 1883 |
| MQTT_BROKER_USER | User login of the MQTT broker | "john-doe" | "" |
| MQTT_BROKER_PASSWD | User password of the MQTT broker | "itsasecret" | "" |
| MQTT_CLIENT_ID | Client ID if the MQTT client | "MyAwesomeClient" | "APS2MQTT" |
| MQTT_TOPIC_PREFIX | Topic prefix for publishing | "my-personal-topic" | "" |
| MQTT_BROKER_SECURED_CONNECTION | Use secure connection to MQTT broker | True | False |
| MQTT_BROKER_CACERTS_PATH | Path to the cacerts file | "/User/johndoe/.ssl/cacerts" | None |
| Key | Description | Example | Default value |
|---|---|---|---|
| APS_ECU_IP | IP of the ECU | "192.168.1.42" | None, this field id mandatory |
| APS_ECU_PORT | Communication port of the ECU | 8899 | 8899 |
| APS_ECU_TIMEZONE | Timezone of the ECU | 'Europe/Paris' | None (use system timezone) |
| APS_ECU_AUTO_RESTART | Automatically restart ECU in case of error | True | False |
| APS_ECU_WIFI_SSID | SSID of the ECU Wifi ℹ️ Only used if automatic restart is enabled |
"My Wifi" | "" |
| APS_ECU_WIFI_PASSWD | Password of the ECU Wifi ℹ️ Only used if automatic restart is enabled |
"secret-key" | "" |
| APS_ECU_STOP_AT_NIGHT | Stop ECU query during the night | True | False |
| APS_ECU_POSITION_LAT | Latitude of the ECU, used to retrieve sunset and sunrise ℹ️ Only used if stop at night is enabled |
51.49819 | 48.864716 (Paris) |
| APS_ECU_POSITION_LNG | Longitude of the ECU, used to retrieve sunset and sunrise ℹ️ Only used if stop at night is enabled |
-0.13087 | 2.349014 (Paris) |
Without any specific configuration, aps2mqtt use your system's timezone as a reference.
-
If you use aps2mqtt as a python application, setting the ECU timezone is recommended by setting the configuration variable 'APS_ECU_TIMEZONE' for better processing.
-
If you are using aps2mqtt as a Docker image, you can configure the timezone for the whole container using the environement variable 'TZ'
ecu:
APS_ECU_IP: '192.168.1.42'
APS_ECU_TIMEZONE: 'Europe/Paris'
APS_ECU_STOP_AT_NIGHT: True
APS_ECU_POSITION_LAT: 47.206
APS_ECU_POSITION_LNG: -1.5645
mqtt:
MQTT_BROKER_HOST: '192.168.1.12'
MQTT_BROKER_PORT: 1883
MQTT_BROKER_USER: 'johndoe'
MQTT_BROKER_PASSWD: 'itsasecret'ecu:
APS_ECU_IP: '192.168.1.42'
APS_ECU_TIMEZONE: 'Europe/Paris'
APS_ECU_STOP_AT_NIGHT: True
APS_ECU_POSITION_LAT: 47.206
APS_ECU_POSITION_LNG: -1.5645
mqtt:
MQTT_BROKER_HOST: 'broker.hivemq.com'
MQTT_BROKER_PORT: 8883
MQTT_BROKER_SECURED_CONNECTION: True
services:
aps2mqtt:
image: fligneul/aps2mqtt:latest
restart: always
environment:
- TZ=Europe/Paris
- DEBUG=True
- APS_ECU_IP=192.168.1.42
- APS_ECU_STOP_AT_NIGHT=True
- APS_ECU_POSITION_LAT=47.206
- APS_ECU_POSITION_LNG=-1.5645
- MQTT_BROKER_HOST=broker.hivemq.com
- MQTT_BROKER_PORT=8883
- MQTT_BROKER_USER=johndoe
- MQTT_BROKER_PASSWD=itsasecret
- MQTT_BROKER_SECURED_CONNECTION=TrueThe aps2mqtt retrieve from the whole PV array as a whole as well as each individual inverter in detail.
- aps/[ECU_ID]/power - total amount of power (in W) being generated right now
- aps/[ECU_ID]/energy/today - total amount of energy (in kWh) generated today
- aps/[ECU_ID]/energy/lifetime - total amount of energy (in kWh) generated from the lifetime of the array
- aps/[ECU_ID]/[INVERTER_ID]/online - True is the inverter is communicating with the ECU, False otherwise
- aps/[ECU_ID]/[INVERTER_ID]/signal - the signal strength of the zigbee connection
- aps/[ECU_ID]/[INVERTER_ID]/temperature - the temperature of the inverter in your local unit (C or F)
- aps/[ECU_ID]/[INVERTER_ID]/frequency - the AC power frequency (in Hz)
- aps/[ECU_ID]/[INVERTER_ID]/power - the current power generation (in W), sum of all panel power
- aps/[ECU_ID]/[INVERTER_ID]/voltage - the AC voltage (in V)
- aps/[ECU_ID]/[INVERTER_ID]/[PANEL_ID]/power - the current power generation (in W) of the selected panel