nexa-mqtt

nexa-mqtt is a standalone application designed to retrieve data and metrics from your Growatt NEXA 2000 home battery used in balcony power plants. It publishes this information to an MQTT broker, making it easily accessible for Home Assistant or other applications. It is a fork of https://github.com/mtrossbach/noah-mqtt.

The application features Home Assistant auto-discovery, allowing your NEXA devices to be automatically recognized and integrated with Home Assistant via the MQTT integration.

🌟 If you find my project helpful, please consider giving me a star on GitHub! Your support motivates me to improve and delve deeper into enhancing the project. Thank you!

Configuration

nexa-mqtt supports three API modes:

app: This mode utilizes the Shine App APIs. These APIs offer faster data updates and support setting parameters. However, they are the least stable, as they are prone to change with new app updates. They are also subject to strict rate limits, which may result in IP bans.
web: (default) This mode uses the Growatt Website APIs. These APIs provide a more stable way to fetch data. This mode also supports setting parameters.
web+app: (deprecated) This mode uses the Growatt Website APIs for data fetching (for stability) and the App APIs for setting parameters. This was necessary before the Growatt Website API supported setting of parameters.

You can configure nexa-mqtt using the following environment variables:

Environment Variable	Description	Default
`LOG_LEVEL`	Sets the logging level of the application	INFO
`POLLING_INTERVAL`	Time in seconds between fetching new status data	30
`BATTERY_DETAILS_POLLING_INTERVAL`	See below	180
`PARAMETER_POLLING_INTERVAL`	Time in seconds between fetching parameter data (system-output-power, charging limits).	180
`GROWATT_API_MODE`	Growatt API mode, either `app`, `web`, `web+app`	web+app
`GROWATT_USERNAME`	Your Growatt account username (required)	-
`GROWATT_PASSWORD`	Your Growatt account password (required)	-
`GROWATT_SERVER_URL_WEB`	Growatt server url for web apis	https://openapi.growatt.com
`GROWATT_SERVER_URL_APP`	Growatt server url for app apis	https://server-api.growatt.com
`GROWATT_TZ`	IANA time zone the NEXA is running in, e.g. "Europe/Berlin", "America/New_York", ... This is probably set by the country in the app configuration. If not given, the host's time zone is used. Note: when using the Home Assistant Docker container the host time zone is always UTC! The Alpine base image does not support time zones so be sure to use this setting!	-
`MQTT_BROKER_URL`	Full URL of the MQTT Broker e.g. tls://x.eu.hivemq.cloud. If empty, the URL is created as `tcp://{MQTT_HOST}:{MQTT_PORT}`	-
`MQTT_HOST`	Address of your MQTT broker (required if `MQTT_BROKER_URL` is empty)	-
`MQTT_PORT`	Port number of your MQTT broker	1883
`MQTT_CLIENT_ID`	Identifier for the MQTT client	nexa-mqtt
`MQTT_USERNAME`	Username for connecting to your MQTT broker	-
`MQTT_PASSWORD`	Password for connecting to your MQTT broker	-
`MQTT_TOPIC_PREFIX`	Prefix for MQTT topics used by nexa-mqtt	nexa2mqtt
`HOMEASSISTANT_TOPIC_PREFIX`	Prefix for topics used by Home Assistant	homeassistant
`HOMEASSISTANT_SWITCH_AS_SELECT`	Publish 'switch' entities as 'select'. Set to 'True' for OpenHAB, see below	false

Adjust these settings to fit your environment and requirements.

Battery details and PV input data are fetched from historical, not real-time data. nexa-mqtt tries to fetch data that is at most 5 seconds old. If that fails it retries after 5 seconds, if that still fails it retries after BATTERY_DETAILS_POLLING_INTERVAL seconds.

In app mode the PV input data is not available and battery details may not be available.

Data provided by nexa-mqtt

Published Topics

The following MQTT topics are used by nexa-mqtt to publish data:

1. General Device Data

Topic: nexa2mqtt/{DEVICE_SERIAL}
Description: This topic contains general data about the device.
Example: nexa2mqtt/0ABC00AA15AA00AA
Example Payload:

{
  "ac_w": -398, // current AC power in watts
                // is negative when solar or battery power is delivered to the grid
                // is positive when battery is charged from grid
  "solar_w": 102, // current solar generation power in watts
  "soc": 40, // current state of charge of the whole appliance
  "charge_w": 0, // current charging power in watts
  "discharge_w": 314, // current discharge power in watts
  "battery_num": 2, // number of batteries
  "generation_total_kwh": 319.8, // total energy generation
  "generation_today_kwh": 3.1, // engery generation today
  "work_mode": "load_first", // current work mode: load_first, battery_first or smart_self_use
  "status": "on_grid" // connectivity status: offline, smart_self_use, fault, on_grid or off_grid
}

2. Battery Information

Topic: nexa2mqtt/{DEVICE_SERIAL}/BAT{BAT_NR}
Description: This topic contains information about the device's batteries. Replace {BAT_NR} with the battery number (e.g., BAT0, BAT1, BAT2, etc.). Battery information is updated about every 3 minutes.
Example: nexa2mqtt/0ABC00AA15AA00AA/BAT0
Example Payload:

{
   "time": "2025-05-21T10:54:51+02:00", // timestamp
   "serial": "0ABC00AA15AA00AA", // battery serial number
   "soc": 42, // current state of charge of this battery
   "temp": 26 // current temperature of this battery
}

3. PV Input Information

Topic: nexa2mqtt/{DEVICE_SERIAL}/PV{0..3}
Description: This topic contains information about the 4 PV inputs. PV input data is updated about every 3 minutes. PV input data is only available in API modes web and web+app
Example: nexa2mqtt/0ABC00AA15AA00AA/PV1
Example Payload:

{
   "time": "2025-05-21T10:54:51+02:00", // timestamp
   "voltage": 33.25,
   "current": 1.72,
   "temp": 26
}

4. Device Configuration

Topic: nexa2mqtt/{DEVICE_SERIAL}/parameters
Description: This topic contains the current configuration parameters of the device.
Example: nexa2mqtt/0ABC00AA15AA00AA/parameters
Example Payload:

{
   "charging_limit": 100, // battery charging limit in percent, between 70 and 100
   "discharge_limit": 10, // battery discharge limit in percent, between 0 and 30
   "default_output_w": 150, // desired system AC output power in watts, between 0 and 1000 in steps of 10
   "default_mode": "load_first", // load_first, battery_first or smart_self_use
   "allow_grid_charging": "OFF", // ON when battery may be charged from grid
   "grid_connection_control": "OFF", // ON for off-grid mode
   "ac_couple_power_control": "OFF", // ON for 1000W max. AC output. (Power+ Function)
                                     // Note: this may be forbidden when connected to
                                     // public grid!
   "light_load_enable": "OFF", // ON allows the device to discharge at low power for
                               // extended periods. (AC Always On)
   "never_power_off": "OFF", // When ON the device remains powered on and never shuts down
                             // while connected to the grid. (Always On)
                             // "allow_grid_charging" should be ON for this function
   "anti_backflow_enable": "OFF", //When ON export to grid is limited in smart_self_use mode
   "anti_backflow_power_percentage": 20 // Seems to be max. allowed backflow in percent
                                        // of maximum output (800/1000W)
}

Setting Device Parameters

You can update the device's parameter settings by posting a message to the following topic:

Topic: nexa2mqtt/{DEVICE_SERIAL}/parameters/set
Description: Send configuration settings to this topic to update the device's parameters.
Example: nexa2mqtt/1234567890/parameters/set
Example Payload:

{
   "charging_limit": 100, // battery charging limit in percent, between 70 and 100
   "discharge_limit": 9, // battery discharge limit in percent, between 0 and 30
   "default_output_w": 800, // desired system AC output power in watts, between 0 and 1000 in steps of 10 
   "default_mode": "load_first", // load_first, battery_first or smart_self_use
   "allow_grid_charging": "OFF", // ON when battery may be charged from grid
   "grid_connection_control": "OFF", // ON for off-grid mode
   "ac_couple_power_control": "OFF", // ON for 1000W max. AC output. (Power+ Function)
                                     // Note: this may be forbidden when connected to
                                     // public grid!
   "light_load_enable": "OFF", // ON allows the device to discharge at low power for
                               // extended periods. (AC Always On)
   "never_power_off": "OFF", // When ON the device remains powered on and never shuts down
                             // while connected to the grid. (Always On)
                             // "allow_grid_charging" should be ON for this function
   "anti_backflow_enable": "OFF", // When ON, export to grid is limited. This requires a smart meter
   "anti_backflow_power_percentage": 20 // Seems to be max. allowed backflow in percent
                                        // of maximum output (800/1000W)
   "ac_couple_enable": "OFF" // When ON, the NEXA2000 can be charged using excess energy from 
                             // third-party inverters in the home. This requires one or two smart 
                             // meters. Ensure the allow_grid_charging is also ON.
}

You can set a property individually or any combination of properties. The value pairs charging_limit, discharge_limit and default_output_w, default_mode are set together. If one of them is missing in the payload the cached previous value is used. A debounce timer of 500 ms is used to combine payloads with individual properties to a combined payload. That means that any setting of a value is executed after a delay of 500 ms.

API Health

Topic: nexa2mqtt/{DEVICE_SERIAL}/health
Description: State of API calls to app or web interface.
Example: nexa2mqtt/1234567890/health
Example Payload:

{
   "status":"error", // ok or error
   "last_success":"2026-05-21T03:43:29+02:00", // time of last successful api call
   "message":"Post \"https://openapi.growatt.com/panel/noah/getNoahStatusData?plantId=37665926\": read: connection reset by peer"
}

This topic is updated for every failed api call and once for the first successful api call after an error.

Availability

Topic: nexa2mqtt/availability
Description: Shows if nexa-mqtt is running (online) or not (offline)
Example: nexa2mqtt/1234567890/health
Example Payload:

online

This value of this topic is stored permanently in the MQTT broker after the first run of nexa-mqtt. Home Assistant Entities are unavailable when this topic is offline.

Run the application standalone

Option 1: Running `nexa-mqtt` with Docker

To run the latest version of nexa-mqtt using Docker, follow these steps:

Install Docker: Ensure Docker is installed on your system. You can download Docker Desktop from Docker’s official website.
Open a Terminal:
- Windows: Use Command Prompt or PowerShell.
- Linux/macOS: Use the Terminal.

Execute the Docker Command: Run the following command, replacing the placeholders with your actual values:

docker run --name nexa-mqtt -e GROWATT_USERNAME=myusername -e GROWATT_PASSWORD=mypassword -e MQTT_HOST=localhost -e MQTT_PORT=1883 ghcr.io/mgerczuk/nexa-mqtt:latest

Replace myusername with your Growatt username.
Replace mypassword with your Growatt password.
Replace localhost with the hostname or IP address of your MQTT broker.
Replace 1883 with the port number your MQTT broker uses (default is 1883).

The application will connect to your MQTT broker and retrieve all metrics and data for your NEXA devices.

Option 2: Downloading and running a Debian package

Download the deb package file: Go to the Releases page of the repository and download the .deb file for your operating system and system architecture.
Install the package
```
sudo apt install -f <deb-file>
```

When there is an update simply download the new deb package file and install with the same install command.

nexa-mqtt is started and will be started automatically after a reboot. Check with journalctl -t nexa-mqtt if there are any problems, e.g. user name or password errors.

You can modify the environment variables by executing

sudo systemctl edit nexa-mqtt
sudo systemctl daemon-reload
sudo systemctl restart nexa-mqtt

To uninstall the package execute sudo apt remove nexa-mqtt.

Option 3: Downloading and running a prebuilt binary

If you prefer not to compile the binary yourself, you can download a prebuilt version:

Download the Binary: Go to the Releases page of the repository and download the prebuilt binary for your operating system and system architecture.
Extract the Binary: If the binary is compressed (e.g., in a zip or tar file), extract it to a directory of your choice.

Run the Application: Open a terminal in the directory containing the binary and run it using the appropriate command for your OS, setting the necessary environment variables:

Windows (Command Prompt):

set GROWATT_USERNAME=myusername
set GROWATT_PASSWORD=mypassword
set MQTT_HOST=localhost
set MQTT_PORT=1883
nexa-mqtt.exe

Windows (PowerShell):

$env:GROWATT_USERNAME=„myusername“
$env:GROWATT_PASSWORD=„mypassword“
$env:MQTT_HOST=„localhost“
$env:MQTT_PORT=„1883“
.\nexa-mqtt.exe

Linux/macOS:

GROWATT_USERNAME=myusername GROWATT_PASSWORD=mypassword MQTT_HOST=localhost MQTT_PORT=1883 ./nexa-mqtt

Again, replace myusername, mypassword, localhost, and 1883 with your actual Growatt account details and MQTT broker information.

Option 4: Compiling the binary yourself

To compile the binary yourself, ensure you have Go installed on your machine:

Install Go: Download and install the latest version of Go from the official Go website.
Clone the Repository: Open a terminal and run the following command to clone the repository:
```
 git clone https://github.com/mgerczuk/nexa-mqtt.git
 cd nexa-mqtt
```

Build the application:

 go build -o nexa-mqtt cmd/nexa-mqtt/main.go

Afterwards follow the instructions for running the application from option 2.

Integration into HomeAssistant

Run standalone (Home Assistant Container, Home Assistant Core)

nexa-mqtt interacts with Home Assistant by publishing data from your Growatt NEXA 2000 home battery to an MQTT broker. This setup allows Home Assistant to subscribe to and integrate this data seamlessly into its ecosystem.

If you’re already using MQTT with other integrations like zigbee2mqtt or AhoyDTU, you already have the MQTT integration configured and active. In this case, you can skip step 1 and 2 as your existing setup should work with nexa-mqtt.

The following integration process for nexa-mqtt with Home Assistant works for all installation methods, regardless of how Home Assistant is installed—whether it’s through Home Assistant OS, Home Assistant Supervised, or Home Assistant Container.

Set Up an MQTT Broker:
Ensure you have an MQTT broker running, such as Mosquitto, and that it’s accessible from both nexa-mqtt and Home Assistant.
Check MQTT Integration in Home Assistant:
- Navigate to Settings > Devices & Services in Home Assistant.
- Click Add Integration and select „MQTT“.
- Enter your MQTT broker details (hostname, port, username, password).
- Test the connection to ensure it’s working correctly.
Run nexa-mqtt:
Start nexa-mqtt using the appropriate configuration for your MQTT broker.
Verify Device Discovery:
Check Devices and Entities under Settings > Devices & Services in Home Assistant to confirm that your Noah devices are automatically discovered.

By following these steps, nexa-mqtt will communicate with Home Assistant via your MQTT broker, also supporting automatic device discovery. If you already have MQTT set up, it should integrate seamlessly with your existing configuration.

Run as Home Assistant add-on (Home Assistant OS, Home Assistant Supervised)

If you are using Home Assistant OS or Home Assistant Supervised you can run nexa-mqtt as a Home Assistant add-on, which provides seamless integration with your Home Assistant setup. This option leverages the add-on system to manage and run nexa-mqtt directly on your Home Assistant instance.

Steps to Use the Home Assistant Add-on

Prerequisite:
- Have the Mosquitto Add-on installed and running -or- have a separate MQTT running
- Home Assistant MQTT integration enabled
Add the Repository:
- Open your Home Assistant web interface.
- Navigate to Settings > Add-ons > Add-on Store.
- Click on the three-dot menu in the top right corner and select Repositories.
- Add the following URL: https://github.com/mgerczuk/hassio-addons.

Install the Add-on:
- Search for the nexa-mqtt add-on within the Add-on Store.
- Click on the add-on and select Install.
Configure the Add-on:
- After installation, configure the add-on settings by providing your Growatt username and Growatt password and setup the other options as needed.
- If you do not use the Mosquitto Add-on, please also define your MQTT settings
Start the Add-on:
- Click Start to launch the nexa-mqtt add-on.

The Home Assistant add-on provides an easy and integrated way to run nexa-mqtt, allowing you to manage it directly from the Home Assistant interface.

For more detailed information and updates, visit the repository.

Integration into OpenHAB

nexa-mqtt interacts with OpenHAB by publishing data from your Growatt NEXA 2000 home battery to an MQTT broker. This setup allows OpenHAB to subscribe to and integrate this data seamlessly into its ecosystem.

nexa-mqtt uses Home Assistant auto-discover. OpenHAB has some problems with this, especially you cannot properly set a 'Switch' channel data imported from HA auto-discovery. Be sure to set the environment variable HOMEASSISTANT_SWITCH_AS_SELECT to True when you use OpenHAB. The 'switch' entities will then be imported as String channels.

Set Up an MQTT Broker:
Ensure you have an MQTT broker running, such as Mosquitto, and that it’s accessible from both nexa-mqtt and OpenHAB.
Check MQTT Integration in OpenHAB: If not already done install the MQTT Binding from the Add-on Store
Run nexa-mqtt:
Start nexa-mqtt using the appropriate configuration for your MQTT broker and the environment variable HOMEASSISTANT_SWITCH_AS_SELECT to True.
Device Discovery:
OpenHAB should now show a new thing in the inbox on the Settings/Things page. Click on the inbox, select the entry an chose Add as Thing. Enter a name for the new thing. The thing should now be online and you can start linking items to the channels.

In case the thing does not go online first check the MQTT broker and the MQTT binding. If that is Ok, try to disable/enable the thing and/or restart nexa-mqtt.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
assets		assets
cmd/nexa-mqtt		cmd/nexa-mqtt
internal		internal
package		package
pkg/models		pkg/models
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.goreleaser.yaml		.goreleaser.yaml
CODEOWNERS		CODEOWNERS
Dockerfile		Dockerfile
Dockerfile_goreleaser		Dockerfile_goreleaser
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
passwd		passwd
renovate.json		renovate.json

Navigation Menu

Repository files navigation

nexa-mqtt

Configuration

Data provided by nexa-mqtt

Published Topics

1. General Device Data

2. Battery Information

3. PV Input Information

4. Device Configuration

Setting Device Parameters

API Health

Availability

Run the application standalone

Option 1: Running `nexa-mqtt` with Docker

Option 2: Downloading and running a Debian package

Option 3: Downloading and running a prebuilt binary

Option 4: Compiling the binary yourself

Integration into HomeAssistant

Run standalone (Home Assistant Container, Home Assistant Core)

Run as Home Assistant add-on (Home Assistant OS, Home Assistant Supervised)

Steps to Use the Home Assistant Add-on

Integration into OpenHAB

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

nexa-mqtt

Configuration

Data provided by nexa-mqtt

Published Topics

1. General Device Data

2. Battery Information

3. PV Input Information

4. Device Configuration

Setting Device Parameters

API Health

Availability

Run the application standalone

Option 1: Running nexa-mqtt with Docker

Option 2: Downloading and running a Debian package

Option 3: Downloading and running a prebuilt binary

Option 4: Compiling the binary yourself

Integration into HomeAssistant

Run standalone (Home Assistant Container, Home Assistant Core)

Run as Home Assistant add-on (Home Assistant OS, Home Assistant Supervised)

Steps to Use the Home Assistant Add-on

Integration into OpenHAB

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Option 1: Running `nexa-mqtt` with Docker