diff --git a/README.md b/README.md index de5a943..9be64e0 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # noah-mqtt ![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) -UNDER CONSTRUCTION! - `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. The application features Home Assistant auto-discovery, allowing your NOAH devices to be automatically recognized and integrated with Home Assistant via the MQTT integration. @@ -10,6 +8,8 @@ The application features Home Assistant auto-discovery, allowing your NOAH devic # ![HomeAssistant screenshot](/assets/ha-screenshot.png) +--- + # Run the application standalone ## Option 1: Running `noah-mqtt` with Docker @@ -90,9 +90,11 @@ To compile the binary yourself, ensure you have Go installed on your machine: Afterwards follow the instructions for running the application from option 2. +--- # Integration into HomeAssistant +## Run standalone (Home Assistant Container, Home Assistant Core) `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. ![Home Assistant Integration](./assets/noah-mqtt-ha-dark.drawio.png#gh-dark-mode-only) @@ -119,35 +121,15 @@ The following integration process for `noah-mqtt` with Home Assistant works for By 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. -# Configuration - -You can configure `noah-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 | 10 | -| `BATTERY_DETAILS_POLLING_INTERVAL` | Time in seconds between fetching battery details (per battery SoC & temperature). | 60 | -| `PARAMETER_POLLING_INTERVAL` | Time in seconds between fetching parameter data (system-output-power, charging limits). | 60 | -| `GROWATT_USERNAME` | Your Growatt account username (required) | - | -| `GROWATT_PASSWORD` | Your Growatt account password (required) | - | -| `MQTT_HOST` | Address of your MQTT broker (required) | - | -| `MQTT_PORT` | Port number of your MQTT broker | 1883 | -| `MQTT_CLIENT_ID` | Identifier for the MQTT client | noah-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 Noah-mqtt | noah2mqtt | -| `HOMEASSISTANT_TOPIC_PREFIX` | Prefix for topics used by Home Assistant | homeassistant | - -Adjust these settings to fit your environment and requirements. - - -# Run as Home Assistant add-on (Home Assistant OS, Home Assistant Supervised) +## 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 `noah-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 `noah-mqtt` directly on your Home Assistant instance. #### Steps to Use the Home Assistant Add-on +0. **Prerequisite:** + - Have the Mosquitto Add-on installed and running -or- have a separate MQTT running + - Home Assistant MQTT integration enabled 1. **Add the Repository:** - Open your Home Assistant web interface. @@ -163,10 +145,105 @@ This option leverages the add-on system to manage and run `noah-mqtt` directly o 3. **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 4. **Start the Add-on:** - Click **Start** to launch the `noah-mqtt` add-on. The 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. For more detailed information and updates, visit the [repository](https://github.com/mtrossbach/hassio-addons). + +--- + +# Configuration + +You can configure `noah-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 | 10 | +| `BATTERY_DETAILS_POLLING_INTERVAL` | Time in seconds between fetching battery details (per battery SoC & temperature). | 60 | +| `PARAMETER_POLLING_INTERVAL` | Time in seconds between fetching parameter data (system-output-power, charging limits). | 60 | +| `GROWATT_USERNAME` | Your Growatt account username (required) | - | +| `GROWATT_PASSWORD` | Your Growatt account password (required) | - | +| `MQTT_HOST` | Address of your MQTT broker (required) | - | +| `MQTT_PORT` | Port number of your MQTT broker | 1883 | +| `MQTT_CLIENT_ID` | Identifier for the MQTT client | noah-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 Noah-mqtt | noah2mqtt | +| `HOMEASSISTANT_TOPIC_PREFIX` | Prefix for topics used by Home Assistant | homeassistant | + +Adjust these settings to fit your environment and requirements. + +--- + +# Data provided by noah-mqtt + +## Published Topics + +The following MQTT topics are used by `noah-mqtt` to publish data: + +### 1. General Device Data +- **Topic:** `noah2mqtt/{DEVICE_SERIAL}` +- **Description:** This topic contains general data about the device. +- **Example:** `noah2mqtt/0ABC00AA15AA00AA` +- **Example Payload:** +```json +{ + "output_w": 398, // current output power in watts + "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 or battery_first + "status": "online" // connectivity status: online or offline +} +``` + +### 2. Battery Information +- **Topic:** `noah2mqtt/{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.). +- **Example:** `noah2mqtt/0ABC00AA15AA00AA/BAT0` +- **Example Payload:** +```json +{ + "serial": "0ABC00AA15AA00AA", // battery serial number + "soc": 42, // current state of charge of this battery + "temp": 26 // current temperatur of this battery +} +``` + +### 3. Device Configuration +- **Topic:** `noah2mqtt/{DEVICE_SERIAL}/parameters` +- **Description:** This topic contains the current configuration parameters of the device. +- **Example:** `noah2mqtt/0ABC00AA15AA00AA/parameters` +- **Example Payload:** +```json +{ + "charging_limit": 100, // battery charging limit in percent, between 70 and 100 + "discharge_limit": 9, // battery discharge limit in percent, between 0 and 30 + "output_power_w": 800 // system output power in watts, between 0 and 800 +} +``` + +## Setting Device Configuration + +You can update the device's configuration settings by posting a message to the following topic: + +- **Topic:** `noah2mqtt/{DEVICE_SERIAL}/parameters/set` +- **Description:** Send configuration settings to this topic to update the device's parameters. +- **Note:** If you want to change the charging limit you always have to set `charging_limit` and `discharge_limit`. +- **Example:** `noah2mqtt/1234567890/parameters/set` +- **Example Payload:** +```json +{ + "charging_limit": 100, // battery charging limit in percent, between 70 and 100 + "discharge_limit": 9, // battery discharge limit in percent, between 0 and 30 + "output_power_w": 800 // system output power in watts, between 0 and 800 +} +``` \ No newline at end of file diff --git a/assets/ha-screenshot.png b/assets/ha-screenshot.png index 60a3c4e..7c4526a 100644 Binary files a/assets/ha-screenshot.png and b/assets/ha-screenshot.png differ