{"id":14963457,"url":"https://github.com/mtrossbach/noah-mqtt","last_synced_at":"2025-04-06T22:06:13.811Z","repository":{"id":250610520,"uuid":"834924691","full_name":"mtrossbach/noah-mqtt","owner":"mtrossbach","description":"A tool for integrating Growatt Noah 2000 home batteries with Home Assistant via MQTT, enabling monitoring and control of your energy storage system.","archived":false,"fork":false,"pushed_at":"2025-03-13T01:48:09.000Z","size":807,"stargazers_count":91,"open_issues_count":19,"forks_count":11,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-30T21:06:08.504Z","etag":null,"topics":["battery","docker","energy-monitor","go","golang","growatt","hassio","hassio-addon","home-assistant","homeassistant","iot","mqtt","mqtt-smarthome","noah","powerplant","solar","solar-energy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtrossbach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-28T18:17:58.000Z","updated_at":"2025-03-30T13:21:20.000Z","dependencies_parsed_at":"2024-09-13T19:16:40.191Z","dependency_job_id":"f1087d38-1b46-41ba-88e3-9b525bac871d","html_url":"https://github.com/mtrossbach/noah-mqtt","commit_stats":{"total_commits":63,"total_committers":3,"mean_commits":21.0,"dds":"0.15873015873015872","last_synced_commit":"410785d9f0004c3d5117aea5d9deb925b4729d57"},"previous_names":["mtrossbach/noah-mqtt"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtrossbach%2Fnoah-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtrossbach%2Fnoah-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtrossbach%2Fnoah-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtrossbach%2Fnoah-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtrossbach","download_url":"https://codeload.github.com/mtrossbach/noah-mqtt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["battery","docker","energy-monitor","go","golang","growatt","hassio","hassio-addon","home-assistant","homeassistant","iot","mqtt","mqtt-smarthome","noah","powerplant","solar","solar-energy"],"created_at":"2024-09-24T13:31:31.870Z","updated_at":"2025-04-06T22:06:13.772Z","avatar_url":"https://github.com/mtrossbach.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]  \n\u003e TLDR; 🎉 noah-mqtt has been updated to (hopefully!) mitigate Growatt IP bans for most users with v0.0.29!  A new `web` API mode using Growatt's website APIs is now available via the `GROWATT_API_MODE` configuration parameter. The default mode is `web+app` (web API for data, app API for parameters). The default fetch frequency has also been increased to 30 seconds. The default fetch frequency for detail data has been increased to 180 seconds.\n\n\u003e [!NOTE] \n\u003e Previously, noah-mqtt relied solely on Growatt's App APIs for data retrieval and parameter settings. Growatt has implemented IP blocking measures that significantly impact access to these App APIs.\n\u003e \n\u003e This update (v0.0.29) introduces the web API mode, which fetches data through Growatt's website APIs. While these Web APIs are currently less strictly affected by IP blocking, it's important to understand that this update DOES NOT directly unblock existing IP bans.\n\u003e \n\u003e Crucially, parameter settings (like changing output power and SoC limits) are still performed via the App APIs, as these functionalities are not supported by the Web APIs. Therefore, if your IP is currently blocked, this update will not enable parameter changes until your IP block is lifted.\n\u003e \n\u003e In summary, this update offers a workaround for data retrieval in the face of IP blocks, but parameter settings remain dependent on the App APIs and will only function when your IP is not blocked.\n\n# noah-mqtt\n![License](https://img.shields.io/github/license/mtrossbach/noah-mqtt) ![GitHub last commit](https://img.shields.io/github/last-commit/mtrossbach/noah-mqtt) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/mtrossbach/noah-mqtt)\n\n`noah-mqtt` is a standalone application designed to retrieve data and metrics from your Growatt NOAH 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.\n\nThe application features Home Assistant auto-discovery, allowing your NOAH devices to be automatically recognized and integrated with Home Assistant via the MQTT integration.\n\n# ![HomeAssistant screenshot](/assets/ha-screenshot.png)\n\n🌟 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!\n\n---\n\n# Configuration\n\n`noah-mqtt` supports three API modes:\n\n*   **`app`**: (previous default) 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.\n*   **`web`**: This mode uses the Growatt Website APIs. These APIs provide a more stable way to fetch data.  Setting parameters is not supported in this mode.\n*   **`web+app`**: (current default) This mode combines the best of both worlds. It uses the Growatt Website APIs for data fetching (for stability) and the App APIs for setting parameters.\n\n\nYou can configure `noah-mqtt` using the following environment variables:\n\n| Environment Variable               | Description                                                                             | Default                        |\n|:-----------------------------------|:----------------------------------------------------------------------------------------|:-------------------------------| \n| `LOG_LEVEL`                        | Sets the logging level of the application                                               | INFO                           |\n| `POLLING_INTERVAL`                 | Time in seconds between fetching new status data                                        | 30                             |\n| `BATTERY_DETAILS_POLLING_INTERVAL` | Time in seconds between fetching battery details (per battery SoC \u0026 temperature).       | 180                            |\n| `PARAMETER_POLLING_INTERVAL`       | Time in seconds between fetching parameter data (system-output-power, charging limits). | 180                            |\n| `GROWATT_API_MODE`                 | Growatt API mode, either `app`, `web`, `web+app`                                        | web+app                        |\n| `GROWATT_USERNAME`                 | Your Growatt account username (required)                                                | -                              |\n| `GROWATT_PASSWORD`                 | Your Growatt account password (required)                                                | -                              |\n| `GROWATT_SERVER_URL_WEB`           | Growatt server url for web apis                                                         | https://openapi.growatt.com    |\n| `GROWATT_SERVER_URL_APP`           | Growatt server url for app apis                                                         | https://server-api.growatt.com |\n| `MQTT_HOST`                        | Address of your MQTT broker (required)                                                  | -                              |\n| `MQTT_PORT`                        | Port number of your MQTT broker                                                         | 1883                           |\n| `MQTT_CLIENT_ID`                   | Identifier for the MQTT client                                                          | noah-mqtt                      |\n| `MQTT_USERNAME`                    | Username for connecting to your MQTT broker                                             | -                              |\n| `MQTT_PASSWORD`                    | Password for connecting to your MQTT broker                                             | -                              |\n| `MQTT_TOPIC_PREFIX`                | Prefix for MQTT topics used by Noah-mqtt                                                | noah2mqtt                      |\n| `HOMEASSISTANT_TOPIC_PREFIX`       | Prefix for topics used by Home Assistant                                                | homeassistant                  |\n\nAdjust these settings to fit your environment and requirements.\n\n---\n\n# Data provided by noah-mqtt\n\n## Published Topics\n\nThe following MQTT topics are used by `noah-mqtt` to publish data:\n\n### 1. General Device Data\n- **Topic:** `noah2mqtt/{DEVICE_SERIAL}`\n- **Description:** This topic contains general data about the device.\n- **Example:** `noah2mqtt/0ABC00AA15AA00AA`\n- **Example Payload:**\n```json\n{\n  \"output_w\": 398, // current output power in watts\n  \"solar_w\": 102, // current solar generation power in watts\n  \"soc\": 40, // current state of charge of the whole appliance\n  \"charge_w\": 0, // current charging power in watts\n  \"discharge_w\": 314, // current discharge power in watts\n  \"battery_num\": 2, // number of batteries\n  \"generation_total_kwh\": 319.8, // total energy generation\n  \"generation_today_kwh\": 3.1, // engery generation today\n  \"work_mode\": \"load_first\", // current work mode: load_first or battery_first\n  \"status\": \"online\" // connectivity status: online or offline\n}\n```\n\n### 2. Battery Information\n- **Topic:** `noah2mqtt/{DEVICE_SERIAL}/BAT{BAT_NR}`\n- **Description:** This topic contains information about the device's batteries. Replace `{BAT_NR}` with the battery number (e.g., BAT0, BAT1, BAT2, etc.).\n- **Example:** `noah2mqtt/0ABC00AA15AA00AA/BAT0`\n- **Example Payload:**\n```json\n{\n   \"serial\": \"0ABC00AA15AA00AA\", // battery serial number\n   \"soc\": 42, // current state of charge of this battery\n   \"temp\": 26 // current temperatur of this battery\n}\n```\n\n### 3. Device Configuration\n- **Topic:** `noah2mqtt/{DEVICE_SERIAL}/parameters`\n- **Description:** This topic contains the current configuration parameters of the device.\n- **Example:** `noah2mqtt/0ABC00AA15AA00AA/parameters`\n- **Example Payload:**\n```json\n{\n   \"charging_limit\": 100, // battery charging limit in percent, between 70 and 100\n   \"discharge_limit\": 9, // battery discharge limit in percent, between 0 and 30\n   \"output_power_w\": 800 // system output power in watts, between 0 and 800 \n}\n```\n\n## Setting Device Parameters\n\nYou can update the device's parameter settings by posting a message to the following topic:\n\n- **Topic:** `noah2mqtt/{DEVICE_SERIAL}/parameters/set`\n- **Description:** Send configuration settings to this topic to update the device's parameters.\n- **Example:** `noah2mqtt/1234567890/parameters/set`\n- **Example Payload:**\n```json\n{\n   \"charging_limit\": 100, // battery charging limit in percent, between 70 and 100\n   \"discharge_limit\": 9, // battery discharge limit in percent, between 0 and 30\n   \"output_power_w\": 800 // system output power in watts, between 0 and 800 \n}\n```\n\n\n---\n\n# Run the application standalone\n\n## Option 1: Running `noah-mqtt` with Docker\n\nTo run the latest version of `noah-mqtt` using Docker, follow these steps:\n\n1. **Install Docker**: Ensure Docker is installed on your system. You can download Docker Desktop from [Docker’s official website](https://www.docker.com/products/docker-desktop).\n\n2. **Open a Terminal**:\n   - **Windows**: Use Command Prompt or PowerShell.\n   - **Linux/macOS**: Use the Terminal.\n\n3. **Execute the Docker Command**: Run the following command, replacing the placeholders with your actual values:\n\n   ```\n   docker run --name noah-mqtt -e GROWATT_USERNAME=myusername -e GROWATT_PASSWORD=mypassword -e MQTT_HOST=localhost -e MQTT_PORT=1883 ghcr.io/mtrossbach/noah-mqtt:latest\n   ```\n   \n- Replace myusername with your Growatt username.\n- Replace mypassword with your Growatt password.\n- Replace localhost with the hostname or IP address of your MQTT broker.\n- Replace 1883 with the port number your MQTT broker uses (default is 1883).\n\nThe application will connect to your MQTT broker and retrieve all metrics and data for your NOAH devices.\n\n## Option 2: Downloading and running a prebuilt binary\n\nIf you prefer not to compile the binary yourself, you can download a prebuilt version:\n\n1. **Download the Binary**: Go to the [Releases](https://github.com/mtrossbach/noah-mqtt/releases) page of the repository and download the prebuilt binary for your operating system and system architecture.\n\n2. **Extract the Binary**: If the binary is compressed (e.g., in a zip or tar file), extract it to a directory of your choice.\n\n3. **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:\n\n   - **Windows** (Command Prompt):\n\n     ```sh\n     set GROWATT_USERNAME=myusername\n     set GROWATT_PASSWORD=mypassword\n     set MQTT_HOST=localhost\n     set MQTT_PORT=1883\n     noah-mqtt.exe\n     ```\n\n   - **Windows** (PowerShell):\n\n     ```sh\n     $env:GROWATT_USERNAME=„myusername“\n     $env:GROWATT_PASSWORD=„mypassword“\n     $env:MQTT_HOST=„localhost“\n     $env:MQTT_PORT=„1883“\n     .\\noah-mqtt.exe\n     ```\n\n   - **Linux/macOS**:\n\n     ```sh\n     GROWATT_USERNAME=myusername GROWATT_PASSWORD=mypassword MQTT_HOST=localhost MQTT_PORT=1883 ./noah-mqtt\n     ```\n\nAgain, replace `myusername`, `mypassword`, `localhost`, and `1883` with your actual Growatt account details and MQTT broker information.\n\n## Option 3: Compiling the binary yourself\n\nTo compile the binary yourself, ensure you have Go installed on your machine:\n\n1. **Install Go**: Download and install the latest version of Go from [the official Go website](https://golang.org/dl/).\n\n2. **Clone the Repository**: Open a terminal and run the following command to clone the repository:\n        \n        git clone https://github.com/mtrossbach/noah-mqtt.git\n        cd noah-mqtt\n\n3. **Build the application**:\n\n        go build -o noah-mqtt cmd/noah-mqtt/main.go\n\nAfterwards follow the instructions for running the application from option 2.\n\n---\n\n# Integration into HomeAssistant\n\n## Run standalone (Home Assistant Container, Home Assistant Core)\n`noah-mqtt` interacts with Home Assistant by publishing data from your Growatt NOAH 2000 home battery to an MQTT broker. This setup allows Home Assistant to subscribe to and integrate this data seamlessly into its ecosystem.\n\n![Home Assistant Integration](./assets/noah-mqtt-ha-dark.drawio.png#gh-dark-mode-only)\n![Home Assistant Integration](./assets/noah-mqtt-ha.drawio.png#gh-light-mode-only)\n\nIf 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 `noah-mqtt`.\n\nThe following integration process for `noah-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. \n\n1. **Set Up an MQTT Broker**:  \n   Ensure you have an MQTT broker running, such as [Mosquitto](https://mosquitto.org/), and that it’s accessible from both Noah-mqtt and Home Assistant.\n\n2. **Check MQTT Integration in Home Assistant**:  \n   - Navigate to **Settings** \u003e **Devices \u0026 Services** in Home Assistant.\n   - Click **Add Integration** and select „MQTT“.\n   - Enter your MQTT broker details (hostname, port, username, password).\n   - Test the connection to ensure it’s working correctly.\n\n3. **Run noah-mqtt**:  \n   Start `noah-mqtt` using the appropriate configuration for your MQTT broker.\n\n4. **Verify Device Discovery**:  \n   Check **Devices** and **Entities** under **Settings** \u003e **Devices \u0026 Services** in Home Assistant to confirm that your Noah devices are automatically discovered.\n\nBy following these steps, `noah-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.\n\n## Run as Home Assistant add-on (Home Assistant OS, Home Assistant Supervised)\n\nIf you are using Home Assistant OS or Home Assistant Supervised you can run `noah-mqtt` as a Home Assistant add-on, which provides seamless integration with your Home Assistant setup.\nThis option leverages the add-on system to manage and run `noah-mqtt` directly on your Home Assistant instance.\n\n#### Steps to Use the Home Assistant Add-on\n0. **Prerequisite:**\n   - Have the Mosquitto Add-on installed and running -or- have a separate MQTT running\n   - Home Assistant MQTT integration enabled\n\n1. **Add the Repository:**\n   - Open your Home Assistant web interface.\n   - Navigate to **Settings** \u003e **Add-ons** \u003e **Add-on Store**.\n   - Click on the three-dot menu in the top right corner and select **Repositories**.\n   - Add the following URL: `https://github.com/mtrossbach/hassio-addons`.\n\n[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmtrossbach%2Fhassio-addons)\n\n2. **Install the Add-on:**\n   - Search for the `noah-mqtt` add-on within the Add-on Store.\n   - Click on the add-on and select **Install**.\n\n3. **Configure the Add-on:**\n   - After installation, configure the add-on settings by providing your **Growatt username** and **Growatt password** and setup the other options as needed.\n   - If you do not use the Mosquitto Add-on, please also define your MQTT settings\n4. **Start the Add-on:**\n   - Click **Start** to launch the `noah-mqtt` add-on.\n\nThe Home Assistant add-on provides an easy and integrated way to run `noah-mqtt`, allowing you to manage it directly from the Home Assistant interface.\n\nFor more detailed information and updates, visit the [repository](https://github.com/mtrossbach/hassio-addons).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtrossbach%2Fnoah-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtrossbach%2Fnoah-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtrossbach%2Fnoah-mqtt/lists"}