pax_global_header00006660000000000000000000000064151446734420014524gustar00rootroot0000000000000052 comment=0258b4e69a13c5e9389749ff70bebf8139a6c042 indykoning-PyPi_GrowattServer-0258b4e/000077500000000000000000000000001514467344200200055ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/.github/000077500000000000000000000000001514467344200213455ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/.github/FUNDING.yml000066400000000000000000000001021514467344200231530ustar00rootroot00000000000000github: [indykoning] custom: ["https://www.paypal.me/indykoning"] indykoning-PyPi_GrowattServer-0258b4e/.github/ISSUE_TEMPLATE/000077500000000000000000000000001514467344200235305ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/.github/ISSUE_TEMPLATE/1-bug.yml000066400000000000000000000035651514467344200251770ustar00rootroot00000000000000name: Bug Report description: File a bug report. title: "[🐛]: " labels: ["bug"] body: - type: markdown attributes: value: | Thanks for participating in this project! Please fill out the following sections to help us understand the issue you're experiencing. In any case, - make sure you are using the latest version of the package; - do at least one search in current issues or questions (Including closed), your question might already be answered; - please include as many details as possible; - type: textarea id: current-behavior attributes: label: What is the current behavior? validations: required: true - type: textarea id: expected-behavior attributes: label: What is the expected behavior? validations: required: true - type: textarea id: steps-to-reproduce attributes: label: How can we reproduce the issue? - type: textarea id: proposed-solution attributes: label: What is the proposed solution? - type: textarea id: additional-information attributes: label: do you have any additional information for us? description: Please include any additional information that may be helpful in resolving the issue. Like logs, screenshots, or any other relevant details. - type: checkboxes attributes: label: Is there an existing issue for this? description: Please search to see if an issue already exists for the bug you encountered. options: - label: I have searched the existing issues required: true - type: checkboxes attributes: label: Are you willing to create a pull request for this? description: Thank you so much for your willingness to help us out! We really appreciate it. options: - label: If i have a fix i would be willing to create a pull request indykoning-PyPi_GrowattServer-0258b4e/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000010411514467344200255140ustar00rootroot00000000000000blank_issues_enabled: true contact_links: - name: Feature Requests and Ideas url: https://github.com/indykoning/PyPi_GrowattServer/discussions/categories/ideas about: Unfortunately i've implemented eveything i have access to. But with help of the community we can add more features. Please add your ideas here. - name: Support, Questions & Other url: https://github.com/indykoning/PyPi_GrowattServer/discussions/categories/q-a about: If you have questions or need help, take a look here. You can also ask your question here.indykoning-PyPi_GrowattServer-0258b4e/.github/PULL_REQUEST_TEMPLATE.md000066400000000000000000000011421514467344200251440ustar00rootroot00000000000000 **Summary** **Checklist** - [ ] I've made sure the PR does small incremental changes. (new code additions are dificult to review when e.g. the entire repository got improved codestyle in the same PR.) - [ ] I've added/updated the relevant docs for code changes i've made. indykoning-PyPi_GrowattServer-0258b4e/.github/workflows/000077500000000000000000000000001514467344200234025ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/.github/workflows/release.yml000077500000000000000000000017671514467344200255630ustar00rootroot00000000000000name: Release on: release: types: - published jobs: release: name: Build & Deploy to PyPI runs-on: ubuntu-latest steps: - name: Clone repo uses: actions/checkout@v2 # - name: Ensure latest tag is in setup.py if i forgot # run: | # sed -i "s/version=\"[0-9\.]*\"/version=\"$(git describe --tags)\"/g" setup.py # git config user.name github-actions # git config user.email github-actions@github.com # git add setup.py # git commit -m "Ensure setup.py contains the latest tag" # git push - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.9 - name: Install dependencies run: pip install wheel - name: Build package run: python setup.py sdist bdist_wheel - name: Upload package uses: pypa/gh-action-pypi-publish@release/v1 with: user: __token__ password: ${{ secrets.PYPI_API_TOKEN }} indykoning-PyPi_GrowattServer-0258b4e/.github/workflows/ruff.yml000066400000000000000000000003261514467344200250700ustar00rootroot00000000000000name: Ruff on: - push - pull_request jobs: ruff: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/ruff-action@v3 with: src: "./growattServer"indykoning-PyPi_GrowattServer-0258b4e/.gitignore000066400000000000000000000005271514467344200220010ustar00rootroot00000000000000### Python ### # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class image.jpg # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # Symlink examples/growattServer indykoning-PyPi_GrowattServer-0258b4e/.ruff.toml000066400000000000000000000016331514467344200217250ustar00rootroot00000000000000# The contents of this file is based on https://github.com/home-assistant/core/blob/dev/pyproject.toml target-version = "py313" [lint] select = [ "ALL", ] ignore = [ "ANN401", # Dynamically typed expressions (typing.Any) are disallowed "ANN001", "ANN201", "ANN202", "D203", # no-blank-line-before-class (incompatible with formatter) "D212", # multi-line-summary-first-line (incompatible with formatter) "COM812", # incompatible with formatter "ISC001", # incompatible with formatter "E501", # Line length is not important "EM101", "TRY003", # Allow exception messages to be used directly "ERA001", # Commented out code is allowed for examples "T201", # Prints are allowed in examples "PLR0913", "FBT002", "N999", ] [lint.flake8-pytest-style] fixture-parentheses = false [lint.pyupgrade] keep-runtime-typing = true [lint.mccabe] max-complexity = 25indykoning-PyPi_GrowattServer-0258b4e/LICENSE000066400000000000000000000021001514467344200210030ustar00rootroot00000000000000MIT License Copyright (c) 2018 Sjoerd Langkemper & Indy Koning Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. indykoning-PyPi_GrowattServer-0258b4e/README.md000077500000000000000000000043151514467344200212720ustar00rootroot00000000000000# Growatt Server [![Version](https://img.shields.io/pypi/v/GrowattServer?style=flat-square) ](https://pypi.org/project/growattServer/) [![Total Downloads](https://img.shields.io/pepy/dt/GrowattServer?style=flat-square)](https://pypi.org/project/growattServer/) Package to retrieve PV information from the growatt server. Special thanks to [Sjoerd Langkemper](https://github.com/Sjord) who has provided a strong base to start off from https://github.com/Sjord/growatt_api_client That project has since ben archived. This library supports both the classic password-based API and the token-based V1 API, officially supported by Growatt. Currently, the V1 API implementation supports MIN and SPH devices, where MIN broadly corresponds to classic TLX and SPH to classic MIX. If your inverter supports the V1 API, it is encouraged to use this over the classic API, as it offers better security, more features, and more relaxed rate limiting. ## Usage ### Legacy API Please refer to the [docs](./docs/README.md) for [ShinePhone/legacy](./docs/shinephone.md) for it's usage and available methods. ### V1 API Please refer to the [docs](./docs/README.md) for [OpenAPI V1](./docs/openapiv1.md) for it's usage and available methods. ## Examples The `examples` directory contains example usage for the library. You are required to have the library installed to use them `pip install growattServer`. However, if you are contributing to the library and want to use the latest version from the git repository, simply create a symlink to the growattServer directory inside the `examples` directory. ## Disclaimer The developers & maintainers of this library accept no responsibility for any damage, problems or issues that arise with your Growatt systems as a result of its use. The library contains functions that allow you to modify the configuration of your plant & inverter which carries the ability to set values outside of normal operating parameters, therefore, settings should only be modified if you understand the consequences. To the best of our knowledge only the `settings` functions perform modifications to your system and all other operations are read only. Regardless of the operation: ***The library is used entirely at your own risk.***indykoning-PyPi_GrowattServer-0258b4e/docs/000077500000000000000000000000001514467344200207355ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/docs/README.md000066400000000000000000000035641514467344200222240ustar00rootroot00000000000000# Growatt Server Docs Welcome to the docs for the [GrowattServer Python package](https://pypi.org/project/growattServer/) Package to retrieve PV information from the growatt server. This package uses the Growatt Cloud in order to retrieve information from your "Power Plant"/home, Inverters, Battery banks and more! It can also be used to update Settings on your Plant, Inverters and Battery banks made by Growatt. ### Legacy API This is the original way this package has started, at the time of writing it is still the most used. Please refer to the docs for [ShinePhone/legacy](./shinephone.md) for it's usage and available methods. ### V1 API This follows Growatt's OpenAPI V1. Please refer to the docs for [OpenAPI V1](./openapiv1.md) for it's usage and available methods. ## Note This is based on the endpoints used on the mobile app and could be changed without notice. ## Examples The `examples` directory contains example usage for the library. You are required to have the library installed to use them `pip install growattServer`. However, if you are contributing to the library and want to use the latest version from the git repository, simply create a symlink to the growattServer directory inside the `examples` directory. ## Disclaimer The developers & maintainers of this library accept no responsibility for any damage, problems or issues that arise with your Growatt systems as a result of its use. The library contains functions that allow you to modify the configuration of your plant & inverter which carries the ability to set values outside of normal operating parameters, therefore, settings should only be modified if you understand the consequences. To the best of our knowledge only the `settings` functions perform modifications to your system and all other operations are read only. Regardless of the operation: ***The library is used entirely at your own risk.***indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1.md000066400000000000000000000172531514467344200231710ustar00rootroot00000000000000# OpenAPI V1 This version of the API follows the newer [OpenAPI V1 API](https://www.showdoc.com.cn/262556420217021/0) Growatt has made available. It extends our ["Legacy" ShinePhone](./shinephone.md) so methods from [there](./shinephone.md#methods) should be available, but it's safer to rely on the methods described in this file where possible. ## Usage The public v1 API requires token-based authentication ```python import growattServer api = growattServer.OpenApiV1(token="YOUR_API_TOKEN") # Get a list of growatt plants. plants = api.plant_list_v1() print(plants) ``` ## Methods and Variables ### Methods #### Generic Methods Methods that work across all device types. | Method | Arguments | Description | |:---|:---|:---| | `api.plant_list()` | None | Get a list of plants registered to your account. | | `api.plant_details(plant_id)` | plant_id: String | Get detailed information about a power station. | | `api.plant_energy_overview(plant_id)` | plant_id: String | Get energy overview data for a plant. | | `api.plant_energy_history(plant_id, start_date, end_date, time_unit, page, perpage)` | plant_id: String, start_date: Date, end_date: Date, time_unit: String, page: Int, perpage: Int | Get historical energy data for a plant for multiple days/months/years. | | `api.device_list(plant_id)` | plant_id: String | Get a list of devices in specified plant. | #### Devices Devices offer a generic way to interact with your device using the V1 API without needing to provide your S/N every time. And can be used instead of the more specific device methods in the API class. ```python import growattServer from growattServer.open_api_v1.devices import Sph, Min api = growattServer.OpenApiV1(token="YOUR_API_TOKEN") my_inverter = Sph(api, 'YOUR_DEVICE_SERIAL_NUMBER') # or Min(api, 'YOUR_DEVICE_SERIAL_NUMBER') my_inverter.detail() my_inverter.energy() my_inverter.energy_history() my_inverter.read_parameter() my_inverter.write_parameter() ``` | Method | Arguments | Description | |:---|:---|:---| | `device.energy()` | None | Get current energy data for any inverter, including power and energy values. | | `device.detail()` | None | Get detailed data for any inverter. | | `device.energy_history(start_date=None, end_date=None, timezone=None, page=None, limit=None)` | start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for any inverter (7-day max range). | | `device.read_parameter(parameter_id, start_address=None, end_address=None)` | parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for any inverter. | | `device.write_parameter(parameter_id, parameter_values)` | parameter_id: String, parameter_values: Dict/Array | Set parameters on any inverter. Parameter values can be a single value, a list, or a dictionary. | For more details see: [OpenApiV1 Devices](./openapiv1/devices.md) The remaining methods below all actually use these device methods. #### MIN Methods Methods for MIN devices (type 7). | Method | Arguments | Description | |:---|:---|:---| | `api.min_energy(device_sn)` | device_sn: String | Get current energy data for a min inverter, including power and energy values. | | `api.min_detail(device_sn)` | device_sn: String | Get detailed data for a min inverter. | | `api.min_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None)` | device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for a min inverter (7-day max range). | | `api.min_settings(device_sn)` | device_sn: String | Get all settings for a min inverter. | | `api.min_read_parameter(device_sn, parameter_id, start_address=None, end_address=None)` | device_sn: String, parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for a min inverter. see: [details](./openapiv1/min_tlx_settings.md) | | `api.min_write_parameter(device_sn, parameter_id, parameter_values)` | device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on a min inverter. Parameter values can be a single value, a list, or a dictionary. see: [details](./openapiv1/min_tlx_settings.md) | | `api.min_write_time_segment(device_sn, segment_id, batt_mode, start_time, end_time, enabled=True)` | device_sn: String, segment_id: Int, batt_mode: Int <0=load priority, 1=battery priority, 2=grid priority>, start_time: datetime.time, end_time: datetime.time, enabled: Bool | Update a specific time segment for a min inverter. see: [details](./openapiv1/min_tlx_settings.md) | | `api.min_read_time_segments(device_sn, settings_data=None)` | device_sn: String, settings_data: Dict | Read all time segments from a MIN inverter. Optionally pass settings_data to avoid redundant API calls. see: [details](./openapiv1/min_tlx_settings.md) | #### SPH Methods Methods for SPH devices (type 5). | Method | Arguments | Description | |:---|:---|:---| | `api.sph_detail(device_sn)` | device_sn: String | Get detailed data and settings for an SPH hybrid inverter. see: [details](./openapiv1/sph_settings.md) | | `api.sph_energy(device_sn)` | device_sn: String | Get current energy data for an SPH inverter, including power and energy values. | | `api.sph_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None)` | device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for an SPH inverter (7-day max range). | | `api.sph_read_parameter(device_sn, parameter_id=None, start_address=None, end_address=None)` | device_sn: String, parameter_id: String (optional), start_address: Int (optional), end_address: Int (optional) | Read a specific parameter (only pv_on_off supported). see: [details](./openapiv1/sph_settings.md) | | `api.sph_write_parameter(device_sn, parameter_id, parameter_values)` | device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on an SPH inverter. see: [details](./openapiv1/sph_settings.md) | #### SPH Helper Methods Convenience methods that wrap the core SPH methods above for common use cases. | Method | Arguments | Description | |:---|:---|:---| | `api.sph_write_ac_charge_times(...)` | device_sn, charge_power, charge_stop_soc, mains_enabled, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_charge_time_period`. see: [details](./openapiv1/sph_settings.md) | | `api.sph_write_ac_discharge_times(...)` | device_sn, discharge_power, discharge_stop_soc, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_discharge_time_period`. see: [details](./openapiv1/sph_settings.md) | | `api.sph_read_ac_charge_times(...)` | device_sn, settings_data (optional) | Helper: parses charge config from `sph_detail()` response. see: [details](./openapiv1/sph_settings.md) | | `api.sph_read_ac_discharge_times(...)` | device_sn, settings_data (optional) | Helper: parses discharge config from `sph_detail()` response. see: [details](./openapiv1/sph_settings.md) | #### Classic methods Methods from [classic API](./shinephone.md#methods) should be available, but it's safer to rely on the methods described in this section where possible. There is no guarantee that the classic API methods will work, or remain stable through updates. ### Variables Some variables you may want to set. `api.server_url` The growatt server URL, default: 'https://openapi.growatt.com/v1/' You may need a different URL depending on where your account is registered: 'https://openapi-cn.growatt.com/v1/' (Chinese server) 'https://openapi-us.growatt.com/v1/' (North American server) 'https://openapi.growatt.com/v1/' (Other regional server: e.g. Europe) ### Initialisation ```python api = growattServer.GrowattApiV1(token="YOUR_API_TOKEN") # Initialize with your API token ```indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/000077500000000000000000000000001514467344200226375ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/devices.md000066400000000000000000000037741514467344200246160ustar00rootroot00000000000000# OpenAPI V1 - Devices Devices offer a generic way to interact with your device using the V1 API without needing to provide your S/N every time. And can be used instead of the more specific device functions in the API class. ```python import growattServer from growattServer.open_api_v1.devices import Sph, Min api = growattServer.OpenApiV1(token="YOUR_API_TOKEN") device = Sph(api, 'YOUR_DEVICE_SERIAL_NUMBER') # or Min(api, 'YOUR_DEVICE_SERIAL_NUMBER') device.detail() device.energy() device.energy_history() device.read_parameter() device.write_parameter() ``` If you do not know your devices type, but do have their type id this method will provide you with the correct device class to use ``` import growattServer api = growattServer.OpenApiV1(token="YOUR_API_TOKEN") device = api.get_device(device_sn, device_type) if device is not None: device.detail() device.energy() device.energy_history() device.read_parameter() device.write_parameter() ``` The basic methods are described here | Method | Arguments | Description | |:---|:---|:---| | `device.energy()` | None | Get current energy data for any inverter, including power and energy values. | | `device.detail()` | None | Get detailed data for any inverter. | | `device.energy_history(start_date=None, end_date=None, timezone=None, page=None, limit=None)` | start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for any inverter (7-day max range). | | `device.read_parameter(parameter_id, start_address=None, end_address=None)` | parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for any inverter. | | `device.write_parameter(parameter_id, parameter_values)` | parameter_id: String, parameter_values: Dict/Array | Set parameters on any inverter. Parameter values can be a single value, a list, or a dictionary. | However some device classes harbor more methods, which will be described in their respective readmes: - [SPH/MIX](./devices/sph.md) - [Min/TLX](./devices/min.md)indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/devices/000077500000000000000000000000001514467344200242615ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/devices/min.md000066400000000000000000000032061514467344200253670ustar00rootroot00000000000000# OpenAPI V1 - Min/TLX Device (device type 7) The Min device offers the following methods | Method | Arguments | Description | |:---|:---|:---| | `device.energy()` | None | Get current energy data for a min inverter, including power and energy values. | | `device.detail()` | None | Get detailed data for a min inverter. | | `device.energy_history(start_date=None, end_date=None, timezone=None, page=None, limit=None)` | start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for a min inverter (7-day max range). | | `device.settings()` | None | Get all settings for a min inverter. | | `device.read_parameter(parameter_id, start_address=None, end_address=None)` | parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for a min inverter. see: [details](../min_tlx_settings.md) | | `device.write_parameter(parameter_id, parameter_values)` | parameter_id: String, parameter_values: Dict/Array | Set parameters on a min inverter. Parameter values can be a single value, a list, or a dictionary. see: [details](../min_tlx_settings.md) | | `device.write_time_segment(segment_id, batt_mode, start_time, end_time, enabled=True)` | segment_id: Int, batt_mode: Int <0=load priority, 1=battery priority, 2=grid priority>, start_time: datetime.time, end_time: datetime.time, enabled: Bool | Update a specific time segment for a min inverter. see: [details](../min_tlx_settings.md) | | `device.read_time_segments(settings_data=None)` | settings_data: Dict | Read all time segments from a MIN inverter. Optionally pass settings_data to avoid redundant API calls. see: [details](../min_tlx_settings.md) |indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/devices/sph.md000066400000000000000000000040011514467344200253700ustar00rootroot00000000000000# OpenAPI V1 - SPH/MIX Device (device type 5) The SPH device offers the following methods | Method | Arguments | Description | |:---|:---|:---| | `device.detail()` | None | Get detailed data and settings for an SPH hybrid inverter. see: [details](../sph_settings.md) | | `device.energy()` | None | Get current energy data for an SPH inverter, including power and energy values. | | `device.energy_history(start_date=None, end_date=None, timezone=None, page=None, limit=None)` | start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for an SPH inverter (7-day max range). | | `device.read_parameter(parameter_id=None, start_address=None, end_address=None)` | parameter_id: String (optional), start_address: Int (optional), end_address: Int (optional) | Read a specific parameter (only pv_on_off supported). see: [details](../sph_settings.md) | | `device.write_parameter(parameter_id, parameter_values)` | parameter_id: String, parameter_values: Dict/Array | Set parameters on an SPH inverter. see: [details](../sph_settings.md) | #### SPH Helper Methods Convenience methods that wrap the core SPH methods above for common use cases. | Method | Arguments | Description | |:---|:---|:---| | `device.write_ac_charge_times(...)` | device_sn, charge_power, charge_stop_soc, mains_enabled, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_charge_time_period`. see: [details](../sph_settings.md) | | `device.write_ac_discharge_times(...)` | device_sn, discharge_power, discharge_stop_soc, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_discharge_time_period`. see: [details](../sph_settings.md) | | `device.read_ac_charge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses charge config from `sph_detail()` response. see: [details](../sph_settings.md) | | `device.read_ac_discharge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses discharge config from `sph_detail()` response. see: [details](../sph_settings.md) |indykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/min_tlx_settings.md000066400000000000000000000024641514467344200265610ustar00rootroot00000000000000# MIN/TLX Inverter Settings This is part of the [OpenAPI V1 doc](../openapiv1.md). For MIN/TLX systems, the public V1 API provides a more robust way to read and write inverter settings: * **Read Parameter** * function: `api.min_read_parameter` * parameters: * `device_sn`: The device serial number * `parameter_id`: Parameter ID to read (e.g., "discharge_power") * `start_address`, `end_address`: Optional, for reading registers by address * **Write Parameter** * function: `api.min_write_parameter` * parameters: * `device_sn`: The device serial number * `parameter_id`: Parameter ID to write (e.g., "ac_charge") * `parameter_values`: Value to set (single value, list, or dictionary) * **Time Segments** * function: `api.min_write_time_segment` * parameters: * `device_sn`: The device serial number * `segment_id`: Segment number (1-9) * `batt_mode`: Battery mode (0=Load First, 1=Battery First, 2=Grid First) * `start_time`: Datetime.time object for segment start * `end_time`: Datetime.time object for segment end * `enabled`: Boolean to enable/disable segment * **Read Time Segments** * function: `api.min_read_time_segments` * parameters: * `device_sn`: The device serial number * `settings_data`: Optional settings data to avoid redundant API callsindykoning-PyPi_GrowattServer-0258b4e/docs/openapiv1/sph_settings.md000066400000000000000000000232321514467344200256750ustar00rootroot00000000000000# SPH Inverter Settings This is part of the [OpenAPI V1 doc](../openapiv1.md). For SPH (hybrid inverter) systems, the public V1 API provides methods to read and write inverter settings. **Source:** [Official Growatt API Documentation](https://www.showdoc.com.cn/262556420217021/6129763571291058) ## Read All Settings * function: `api.sph_detail` * parameters: * `device_sn`: The device serial number * returns: Dict containing all device data and settings **Return parameter description:** | Field | Type | Description | |-------|------|-------------| | serialNum | String | Serial Number | | portName | String | Communication port information Communication port type and address | | dataLogSn | String | DataLog serial number | | groupId | int | Inverter group | | alias | String | Alias | | location | String | Location | | addr | int | Inverter address | | fwVersion | String | Firmware version | | model | long | Model | | innerVersion | String | Internal version number | | lost | boolean | Whether communication is lost | | status | int | Mix Status 0: waiting mode, 1: self-check mode, 3: failure mode, 4: upgrading, 5, 6, 7, 8: normal mode | | tcpServerIp | String | TCP server IP address | | lastUpdateTime | Date | Last update time | | sysTime | Calendar | System Time | | deviceType | int | 0: Mix6k, 1: Mix4-10k | | communicationVersion | String | Communication version number | | onOff | int | Switch machine | | pmax | int | Rated power | | vnormal | float | Rated PV voltage | | lcdLanguage | int | LCD language | | countrySelected | int | Country selection | | wselectBaudrate | int | Baud rate selection | | comAddress | int | Mailing address | | manufacturer | String | Manufacturer Code | | dtc | int | Device code | | modbusVersion | int | MODBUS version | | floatChargeCurrentLimit | float | Float charge current limit | | vbatWarning | float | Low battery voltage alarm point | | vbatWarnClr | float | Low battery voltage recovery point | | vbatStopForDischarge | float | Battery discharge stop voltage | | vbatStopForCharge | float | Battery charging stop voltage | | vbatStartForDischarge | float | Lower limit of battery discharge voltage | | vbatStartforCharge | float | Battery charging upper limit voltage | | batTempLowerLimitD | float | Lower limit of battery discharge temperature | | batTempUpperLimitD | float | Upper limit of battery discharge temperature | | batTempLowerLimitC | float | Lower limit of battery charging temperature | | batTempUpperLimitC | float | Upper limit of battery charging temperature | | forcedDischargeTimeStart1 | String | Discharge 1 start time | | forcedDischargeTimeStart2 | String | Discharge 2 start time | | forcedDischargeTimeStart3 | String | Discharge 3 start time | | forcedDischargeTimeStop1 | String | Discharge 1 stop time | | forcedDischargeTimeStop2 | String | Discharge 2 stop time | | forcedDischargeTimeStop3 | String | Discharge 3 stop time | | forcedChargeTimeStart1 | String | Charge 1 start time | | forcedChargeTimeStart2 | String | Charge 2 start time | | forcedChargeTimeStart3 | String | Charge 3 start time | | forcedChargeTimeStop1 | String | Charge 1 stop time | | forcedChargeTimeStop2 | String | Charge 2 stop time | | forcedChargeTimeStop3 | String | Charge 3 stop time | | bctMode | int | Sensor type (2:METER;1:cWirelessCT;0:cWiredCT) | | bctAdjust | int | Sensor adjustment enable | | wdisChargeSOCLowLimit1 | int | Discharge in load priority mode | | wdisChargeSOCLowLimit2 | int | Grid priority mode discharge | | wchargeSOCLowLimit1 | int | Load priority mode charging | | wchargeSOCLowLimit2 | int | Battery priority mode charging | | acChargeEnable | int | AC charging enable | | priorityChoose | int | Energy priority selection | | chargePowerCommand | int | Charging power setting | | disChargePowerCommand | int | Discharge power setting | | bagingTestStep | int | Battery self-test | | batteryType | int | Battery type selection | | epsFunEn | int | Emergency power enable | | epsVoltSet | int | Emergency power supply voltage | | epsFreqSet | int | Emergency power frequency | | forcedDischargeStopSwitch1 | int | Discharge 1 enable bit | | forcedDischargeStopSwitch2 | int | Discharge 2 enable bit | | forcedDischargeStopSwitch3 | int | Discharge 3 enable bit | | forcedChargeStopSwitch1 | int | Charge 1 enable bit | | forcedChargeStopSwitch2 | int | Charge 2 enable bit | | forcedChargeStopSwitch3 | int | Charge 3 enable bit | | voltageHighLimit | float | Mains voltage upper limit | | voltageLowLimit | float | Mains voltage lower limit | | buckUpsFunEn | int | Off-grid enable | | uspFreqSet | int | Off-grid frequency | | buckUPSVoltSet | int | Off-grid voltage | | pvPfCmdMemoryState | int | Does the inverter store the following commands | | activeRate | int | Active power | | reactiveRate | int | Reactive power | | underExcited | int | Capacitive or Perceptual | | exportLimit | int | Backflow prevention enable | | exportLimitPowerRate | float | Backflow prevention | | powerFactor | float | PF value | | pv_on_off | String | Switch | | pf_sys_year | String | Set time | | pv_grid_voltage_high | String | Mains voltage upper limit | | pv_grid_voltage_low | String | Mains voltage lower limit | | mix_off_grid_enable | String | Off-grid enable | | mix_ac_discharge_frequency | String | Off-grid frequency | | mix_ac_discharge_voltage | String | Off-grid voltage | | pv_pf_cmd_memory_state | String | Set whether to store the following PF commands | | pv_active_p_rate | String | Set active power | | pv_reactive_p_rate | String | Set reactive power | | pv_reactive_p_rate_two | String | No power capacity/inductive | | backflow_setting | String | Backflow prevention setting | | pv_power_factor | String | Set PF value | | batSeriesNum | int | Number of cells in series | | batParallelNum | int | Number of parallel cells | | error_code | string | 0: normal return, 10001: system error | | error_msg | string | Error message prompt | ## Read Parameter * function: `api.sph_read_parameter` * parameters: * `device_sn`: The device serial number * `parameter_id`: Parameter ID to read (optional) * `start_address`, `end_address`: Optional, for reading registers by address **Supported parameter types for reading:** | parameter_id | Description | Return value | |--------------|-------------|--------------| | `pv_on_off` | Switch | 0 (off), 1 (on) | ## Write Parameter * function: `api.sph_write_parameter` * parameters: * `device_sn`: The device serial number * `parameter_id`: Parameter ID to write * `parameter_values`: Value to set (single value, list, or dictionary) **Supported parameter types for writing:** | parameter_id | Description | Values | |--------------|-------------|--------| | **Device Control** ||| | `pv_on_off` | Switch | "0" (off), "1" (on) | | `pf_sys_year` | Set time | hour:min format | | **Charge Settings** ||| | `mix_ac_charge_time_period` | Charge time periods | charge power, stop SOC, mains enable, time periods... | | **Discharge Settings** ||| | `mix_ac_discharge_time_period` | Discharge time periods | discharge power, stop SOC, time periods... | | **Grid Settings** ||| | `pv_grid_voltage_high` | Mains voltage upper limit | e.g. "270" | | `pv_grid_voltage_low` | Mains voltage lower limit | e.g. "180" | | `pv_active_p_rate` | Set active power | 0-100 | | `pv_reactive_p_rate` | Set reactive power | value | | `pv_reactive_p_rate_two` | No power capacity/inductive | value | | `pv_pf_cmd_memory_state` | Set whether to store PF commands | "0" (no), "1" (yes) | | `pv_power_factor` | Set PF value | 0-100 | | `backflow_setting` | Backflow prevention setting | "1" (on), "0" (off), power % | | **Off-Grid/EPS Settings** ||| | `mix_off_grid_enable` | Off-grid enable | "1" (enabled), "0" (disabled) | | `mix_ac_discharge_frequency` | Off-grid frequency | "0" (50Hz), "1" (60Hz) | | `mix_ac_discharge_voltage` | Off-grid voltage | "0" (230V), "1" (208V), "2" (240V) | > **Note:** For time period settings, it's recommended to use the dedicated helper functions `sph_write_ac_charge_times()` and `sph_write_ac_discharge_times()` instead of calling `sph_write_parameter()` directly. ## AC Charge Time Periods ### Write: `api.sph_write_ac_charge_times` * parameters: * `device_sn`: The device serial number * `charge_power`: Charging power percentage (0-100) * `charge_stop_soc`: Stop charging at this SOC percentage (0-100) * `mains_enabled`: Boolean to enable/disable grid charging * `periods`: List of 3 period dicts, each with: * `start_time`: datetime.time object for period start * `end_time`: datetime.time object for period end * `enabled`: Boolean to enable/disable period ### Read: `api.sph_read_ac_charge_times` * parameters: * `device_sn`: The device serial number * `settings_data`: Settings data from sph_detail() (not used if device_sn is provided) * note: Either `device_sn` or `settings_data` must be provided * returns: Dict with `charge_power`, `charge_stop_soc`, `mains_enabled`, and `periods` list ## AC Discharge Time Periods ### Write: `api.sph_write_ac_discharge_times` * parameters: * `device_sn`: The device serial number * `discharge_power`: Discharge power percentage (0-100) * `discharge_stop_soc`: Stop discharging at this SOC percentage (0-100) * `periods`: List of 3 period dicts, each with: * `start_time`: datetime.time object for period start * `end_time`: datetime.time object for period end * `enabled`: Boolean to enable/disable period ### Read: `api.sph_read_ac_discharge_times` * parameters: * `device_sn`: The device serial number (not used if settings_data is provided) * `settings_data`: Settings data from sph_detail() (not used if device_sn is provided) * note: Either `device_sn` or `settings_data` must be provided * returns: Dict with `discharge_power`, `discharge_stop_soc`, and `periods` list indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone.md000066400000000000000000000214601514467344200234220ustar00rootroot00000000000000# ShinePhone reverse engineered api (legacy) This is where the project was born, when no consumer facing api was available. We reverse-engineered the ShinePhone app. Currently Growatt does seem to support consumers using their [OpenApi](./openapiv1.md). At the time of writing this "Legacy API" is still the most used method. ## Getting started Using username/password basic authentication ```python import growattServer api = growattServer.GrowattApi() login_response = api.login(, ) # Get a list of growatt plants. print(api.plant_list(login_response['user']['id'])) ``` ## Methods and Variables ### Methods Any methods that may be useful. |method|arguments|description| |:---|:---:|:---| | `api.login(username, password)` | username: String, password: String | Log into the growatt API. This must be done beforemaking any request. After this you will be logged in. You will want to capture the response to get the `userId` variable. Should not be used for public v1 APIs. | | `api.plant_list(user_id)` | user_id: String | Get a list of plants registered to your account. | | `api.plant_info(plant_id)` | plant_id: String | Get info for specified plant. | | `api.plant_settings(plant_id)` | plant_id: String | Get the current settings for the specified plant. see: [details](./shinephone/plant_settings.md) | | `api.plant_detail(plant_id, timespan, date)` | plant_id: String, timespan: Int (1=day, 2=month), date: String | Get details of a specific plant. | | `api.plant_energy_data(plant_id)` | plant_id: String | Get energy data for the specified plant. | | `api.device_list(plant_id)` | plant_id: String | Get a list of devices in specified plant. | | `api.dashboard_data(plant_id, timespan, date)` | plant_id: String, timespan: Int (0=hour, 1=day, 2=month), date: String | Get dashboard values for a timespan. NOTE: Many values are incorrect for 'Mix' systems but still provide some accurate data unavailable elsewhere. | | `api.inverter_list(plant_id)` | plant_id: String | Get a list of inverters in specified plant. (May be deprecated in the future, use `device_list` instead). | | `api.inverter_data(inverter_id, date)` | inverter_id: String, date: String | Get some basic data of a specific date for the inverter. | | `api.inverter_detail(inverter_id)` | inverter_id: String | Get detailed data on inverter. | | `api.tlx_system_status(plant_id, tlx_id)` | plant_id: String, tlx_id: String | Get system status. | | `api.tlx_energy_overview(plant_id, tlx_id)` | plant_id: String, tlx_id: String | Get energy overview of the system. | | `api.tlx_energy_prod_cons(plant_id, tlx_id)` | plant_id: String, tlx_id: String | Get energy production and consumption for the system. | | `api.tlx_data(tlx_id, date)` | tlx_id: String, date: String | Get some basic data of a specific date for the tlx type inverter. | | `api.tlx_detail(tlx_id)` | tlx_id: String | Get detailed data on a tlx type inverter. | | `api.tlx_params(tlx_id)` | tlx_id: String | Get parameters for the tlx type inverter. | | `api.tlx_get_all_settings(tlx_id)` | tlx_id: String | Get all possible settings for the tlx type inverter. | | `api.tlx_get_enabled_settings(tlx_id)` | tlx_id: String | Get all enabled settings for the tlx type inverter. | | `api.tlx_battery_info(serial_num)` | serial_num: String | Get battery info for tlx systems. | | `api.tlx_battery_info_detailed(serial_num)` | serial_num: String | Get detailed battery info. | | `api.mix_info(mix_id, plant_id=None)` | mix_id: String, plant_id: String (optional) | Get high-level information about the Mix system, including daily and overall totals. | | `api.mix_totals(mix_id, plant_id)` | mix_id: String, plant_id: String | Get daily and overall total information for the Mix system (duplicates some of the information from `mix_info`). | | `api.mix_system_status(mix_id, plant_id)` | mix_id: String, plant_id: String | Get instantaneous values for Mix system, e.g., current import/export, generation, charging rates, etc. | | `api.mix_detail(mix_id, plant_id, timespan, date)` | mix_id: String, plant_id: String, timespan: Int <0=hour, 1=day, 2=month>, date: String | Get detailed values for a timespan. The API call also returns totals data for the same values in this time window. | | `api.storage_detail(storage_id)` | storage_id: String | Get detailed data on storage (battery). | | `api.storage_params(storage_id)` | storage_id: String | Get extensive information on storage (more info, more convoluted). | | `api.storage_energy_overview(plant_id, storage_id)` | plant_id: String, storage_id: String | Get the information you see in the "Generation overview". | | `api.is_plant_noah_system(plant_id)` | plant_id: String | Get information if Noah devices are configured for the specified plant. | | `api.noah_system_status(serial_number)` | serial_number: String | Get the current status for the specified Noah device, e.g., workMode, soc, chargePower, disChargePower, current import/export, etc. | | `api.noah_info(serial_number)` | serial_number: String | Get all information for the specified Noah device, e.g., configured operation modes, battery management settings, firmware version, etc. | | `api.update_plant_settings(plant_id, changed_settings, current_settings)` | plant_id: String, changed_settings: Dict, current_settings: Dict (optional) | Update the settings for a plant to the values specified in the dictionary. If `current_settings` are not provided, it will look them up automatically using the `get_plant_settings` function. | | `api.update_tlx_inverter_setting(serial_number, setting_type, parameter)` | serial_number: String, setting_type: String, parameter: Any | Apply the provided parameter for the specified setting on the specified tlx inverter. see: [details](./shinephone/inverter_settings.md) | | `api.update_tlx_inverter_time_segment(serial_number, segment_id, batt_mode, start_time, end_time, enabled)` | serial_number: String, segment_id: Int, batt_mode: String, start_time: String, end_time: String, enabled: Bool | Update one of the 9 time segments with the specified battery mode (load, battery, grid first). see: [details](./shinephone/inverter_settings.md) | | `api.update_mix_inverter_setting(serial_number, setting_type, parameters)` | serial_number: String, setting_type: String, parameters: Dict/Array | Apply the provided parameters for the specified setting on the specified Mix inverter. see: [details](./shinephone/inverter_settings.md) | | `api.update_ac_inverter_setting(serial_number, setting_type, parameters)` | serial_number: String, setting_type: String, parameters: Dict/Array | Apply the provided parameters for the specified setting on the specified AC-coupled inverter. see: [details](./shinephone/inverter_settings.md) | | `api.update_noah_settings(serial_number, setting_type, parameters)` | serial_number: String, setting_type: String, parameters: Dict/Array | Apply the provided parameters for the specified setting on the specified Noah device. see: [details](./shinephone/noah_settings.md) | | `api.update_classic_inverter_setting(default_parameters, parameters)` | default_parameters: Dict, parameters: Dict/Array | Applies settings for specified system based on serial number. This function is only going to work for classic inverters. | ### Variables Some variables you may want to set. `api.server_url` The growatt server URL, default: 'https://openapi.growatt.com/' You may need a different URL depending on where your account is registered: 'https://openapi-cn.growatt.com/' (Chinese server) 'https://openapi-us.growatt.com/' (North American server) 'https://openapi.growatt.com/' (Other regional server: e.g. Europe) ## Initialisation The library can be initialised to introduce randomness into the User Agent field that is used when communicating with the servers. This has been added since the Growatt servers started checking for the presence of a `User-Agent` field in the headers that are sent. By default the library will use a pre-set `User-Agent` value which identifies this library while also appearing like an Android device. However, it is also possible to pass in parameters to the intialisation of the library to override this entirely, or just add a random ID to the value. e.g. ```python api = growattServer.GrowattApi() # The default way to initialise api = growattServer.GrowattApi(True) # Adds a randomly generated User ID to the default User-Agent api = growattServer.GrowattApi(False, "my_user_agent_value") # Overrides the default and uses "my_user_agent_value" in the User-Agent header ``` ## Note This is based on the endpoints used on the mobile app and could be changed without notice. ## Settings Discovery The settings for the Plant and Inverter have been reverse engineered by using the ShinePhone Android App and the NetCapture SSL application together to inspect the API calls that are made by the application and the parameters that are provided with it. See: [Reverse Engineered](./shinephone/reverse_engineering.md)indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone/000077500000000000000000000000001514467344200230755ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone/inverter_settings.md000066400000000000000000000132201514467344200271730ustar00rootroot00000000000000# Inverter Settings This is part of the [ShinePhone/Legacy doc](../shinephone.md). NOTE: The inverter settings function appears to only work with 'mix' and 'tlx' systems based on the API call that it makes being specific to those inverter types The inverter settings function(s) allow you to change individual values on your inverter e.g. time, charging period etc. From what has been reverse engineered from the api, each setting has a `setting_type` and a set of `parameters` that are relevant to it. Known working settings & parameters are as follows (all parameter values are strings): * **Time/Date** * type: `pf_sys_year` * params: * `param1`: datetime in format: `YYYY-MM-DD HH:MM:SS` * **Hybrid inverter AC charge times** * function: `api.update_mix_inverter_setting` * setting type: `mix_ac_charge_time_period` * params: * `param1`: Charging power % (value between 0 and 100) * `param2`: Stop charging Statement of Charge % (value between 0 and 100) * `param3`: Allow AC charging (0 = Disabled, 1 = Enabled) * `param4`: Schedule 1 - Start time - Hour e.g. "01" (1am) * `param5`: Schedule 1 - Start time - Minute e.g. "00" (0 minutes) * `param6`: Schedule 1 - End time - Hour e.g. "02" (2am) * `param7`: Schedule 1 - End time - Minute e.g. "00" (0 minutes) * `param8`: Schedule 1 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * `param9`: Schedule 2 - Start time - Hour e.g. "01" (1am) * `param10`: Schedule 2 - Start time - Minute e.g. "00" (0 minutes) * `param11`: Schedule 2 - End time - Hour e.g. "02" (2am) * `param12`: Schedule 2 - End time - Minute e.g. "00" (0 minutes) * `param13`: Schedule 2 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * `param14`: Schedule 3 - Start time - Hour e.g. "01" (1am) * `param15`: Schedule 3 - Start time - Minute e.g. "00" (0 minutes) * `param16`: Schedule 3 - End time - Hour e.g. "02" (2am) * `param17`: Schedule 3 - End time - Minute e.g. "00" (0 minutes) * `param18`: Schedule 3 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * **AC-coupled inverter AC charge times** * function: `api.update_ac_inverter_setting` * setting type: `spa_ac_charge_time_period` * params: * `param1`: Charging power % (value between 0 and 100) * `param2`: Stop charging Statement of Charge % (value between 0 and 100) * `param3`: Schedule 1 - Start time - Hour e.g. "01" (1am) * `param4`: Schedule 1 - Start time - Minute e.g. "00" (0 minutes) * `param5`: Schedule 1 - End time - Hour e.g. "02" (2am) * `param6`: Schedule 1 - End time - Minute e.g. "00" (0 minutes) * `param7`: Schedule 1 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * `param8`: Schedule 2 - Start time - Hour e.g. "01" (1am) * `param9`: Schedule 2 - Start time - Minute e.g. "00" (0 minutes) * `param10`: Schedule 2 - End time - Hour e.g. "02" (2am) * `param11`: Schedule 2 - End time - Minute e.g. "00" (0 minutes) * `param12`: Schedule 2 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * `param13`: Schedule 3 - Start time - Hour e.g. "01" (1am) * `param14`: Schedule 3 - Start time - Minute e.g. "00" (0 minutes) * `param15`: Schedule 3 - End time - Hour e.g. "02" (2am) * `param16`: Schedule 3 - End time - Minute e.g. "00" (0 minutes) * `param17`: Schedule 3 - Enabled/Disabled (0 = Disabled, 1 = Enabled) * **TLX inverter settings** * function: `api.update_tlx_inverter_setting` * type: `charge_power` * param1: Charging power % (value between 0 and 100) * type: `charge_stop_soc` * param1: Charge Stop SOC * type: `discharge_power` * param1: Discharging power % (value between 0 and 100) * type: `on_grid_discharge_stop_soc` * param1: On-grid discharge Stop SOC * type: `discharge_stop_soc` * param1: Off-grid discharge Stop SOC * type: `ac_charge` * param1: Allow AC (grid) charging (0 = Disabled, 1 = Enabled) * type: `pf_sys_year` * param1: datetime in format: `YYYY-MM-DD HH:MM:SS` * function: `api.update_tlx_inverter_time_segment` * segment_id: The segment to update (1-9) * batt_mode: Battery Mode for the segment: 0=Load First(Self-Consumption), 1=Battery First, 2=Grid First * start_time: timedate object with start time of segment with format HH:MM * end_time: timedate object with end time of segment with format HH:MM * enabled: time segment enabled, boolean: True (Enabled), False (Disabled) * **Classic inverter settings** * function: `api.update_classic_inverter_setting` * description: Applies settings for specified system based on serial number. This function is only going to work for classic inverters. * params: * `param1`: First parameter (specific to the setting type) * `param2`: Second parameter (specific to the setting type) * Additional parameters can be passed as needed. The four functions `update_tlx_inverter_setting`, `update_mix_inverter_setting`, `update_ac_inverter_setting`, and `update_inverter_setting` take either a dictionary or an array. If an array is passed it will automatically generate the `paramN` key based on array index since all params for settings seem to used the same numbering scheme. Only the settings described above have been tested with `update_tlx_inverter_setting` and they all take only one single parameter. It is very likely that the function works with all settings returned by `tlx_get_enabled_settings`, but this has not been tested. A helper function `update_tlx_inverter_time_segment` is provided for the settings that require more than one parameter. The `api.get_mix_inverter_settings` method can be used to get the current inverter settings for the specified serial number including charge/discharge schedule for hybrid systems.indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone/noah_settings.md000066400000000000000000000000001514467344200262520ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone/plant_settings.md000066400000000000000000000027141514467344200264610ustar00rootroot00000000000000# Plant Settings This is part of the [ShinePhone/Legacy doc](../shinephone.md). The plant settings function(s) allow you to re-configure the settings for a specified plant. The following settings are required (and are therefore pre-populated based on the existing values for these settings) * `plantCoal` - The formula used to calculate equivalent coal usage * `plantSo2` - The formula used to calculate So2 generation/saving * `accountName` - The username that the system is assigned to * `plantID` - The ID of the plant * `plantFirm` - The 'firm' of the plant (unknown what this relates to - hardcoded to '0') * `plantCountry` - The Country that the plant resides in * `plantType` - The 'type' of plant (numerical value - mapped to an Enum) * `plantIncome` - The formula used to calculate money per kwh * `plantAddress` - The address of the plant * `plantTimezone` - The timezone of the plant (relative to UTC) * `plantLng` - The longitude of the plant's location * `plantCity` - The city that the plant is located in * `plantCo2` - The formula used to calculate Co2 saving/reduction * `plantMoney` - The local currency e.g. gbp * `plantPower` - The capacity/size of the plant in W e.g. 6400 (6.4kw) * `plantLat` - The latitude of the plant's location * `plantDate` - The date that the plant was installed * `plantName` - The name of the plant The function `update_plant_settings` allows you to provide a python dictionary of any/all of the above settings and change their value.indykoning-PyPi_GrowattServer-0258b4e/docs/shinephone/reverse_engineering.md000066400000000000000000000013221514467344200274420ustar00rootroot00000000000000# Reverse Engineering The [ShinePhone/Legacy](../shinephone.md) part of this library has been reverse engineered from the [ShinePhone](https://play.google.com/store/apps/details?id=com.growatt.shinephones) app. There are many ways to achieve this. One of the ways is using. [The ShinePhone Android App](https://play.google.com/store/apps/details?id=com.growatt.shinephones)and the [NetCapture SSL application](https://play.google.com/store/apps/details?id=com.minhui.networkcapture) together to inspect the API calls that are made by the application and the parameters that are provided with it. More details on how this was done can be foud [here](https://indykoning.nl/adding-growatt-solar-pannels-to-home-assistant/)indykoning-PyPi_GrowattServer-0258b4e/examples/000077500000000000000000000000001514467344200216235ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/examples/min_example.py000066400000000000000000000070641514467344200245020ustar00rootroot00000000000000import json import requests import growattServer """ # Example script controlling a MID/TLX Growatt (MID-30KTL3-XH + APX battery) system using the public growatt API # You can obtain an API token from the Growatt API documentation or developer portal. """ # Get the API token from user input or environment variable # api_token = os.environ.get("GROWATT_API_TOKEN") or input("Enter your Growatt API token: ") # test token from official API docs https://www.showdoc.com.cn/262556420217021/1494053950115877 api_token = "6eb6f069523055a339d71e5b1f6c88cc" # gitleaks:allow try: # Initialize the API with token instead of using login api = growattServer.OpenApiV1(token=api_token) # Plant info plants = api.plant_list() print(f"Plants: Found {plants['count']} plants") plant_id = plants["plants"][0]["plant_id"] # Devices devices = api.device_list(plant_id) for device in devices["devices"]: if device["type"] == 7: # (MIN/TLX) inverter_sn = device["device_sn"] print(f"Processing inverter: {inverter_sn}") # Get device details inverter_data = api.min_detail(inverter_sn) print("Saving inverter data to inverter_data.json") with open("inverter_data.json", "w") as f: json.dump(inverter_data, f, indent=4, sort_keys=True) # Get energy data energy_data = api.min_energy(device_sn=inverter_sn) print("Saving energy data to energy_data.json") with open("energy_data.json", "w") as f: json.dump(energy_data, f, indent=4, sort_keys=True) # Get energy history energy_history_data = api.min_energy_history(inverter_sn) print("Saving energy history data to energy_history.json") with open("energy_history.json", "w") as f: json.dump(energy_history_data["datas"], f, indent=4, sort_keys=True) # Get settings settings_data = api.min_settings(device_sn=inverter_sn) print("Saving settings data to settings_data.json") with open("settings_data.json", "w") as f: json.dump(settings_data, f, indent=4, sort_keys=True) # Read time segments tou = api.min_read_time_segments(inverter_sn, settings_data) print(json.dumps(tou, indent=4)) # Read discharge power discharge_power = api.min_read_parameter( inverter_sn, "discharge_power") print("Current discharge power:", discharge_power, "%") # Settings parameters - Uncomment to test # Turn on AC charging # api.min_write_parameter(inverter_sn, 'ac_charge', 1) # print("AC charging enabled successfully") # Enable Load First between 00:00 and 11:59 using time segment 1 # api.min_write_time_segment( # device_sn=inverter_sn, # segment_id=1, # batt_mode=growattServer.BATT_MODE_BATTERY_FIRST, # start_time=datetime.time(0, 0), # end_time=datetime.time(00, 59), # enabled=True # ) # print("Time segment updated successfully") except growattServer.GrowattV1ApiError as e: print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})") except growattServer.GrowattParameterError as e: print(f"Parameter Error: {e}") except requests.exceptions.RequestException as e: print(f"Network Error: {e}") except Exception as e: print(f"Unexpected error: {e}") indykoning-PyPi_GrowattServer-0258b4e/examples/min_example_dashboard.py000066400000000000000000000115451514467344200265100ustar00rootroot00000000000000import json import requests import growattServer """ Example script fetching key power and today+total energy metrics from a Growatt MID-30KTL3-XH (TLX) + APX battery hybrid system using the V1 API with token-based authentication. """ # Get the API token from user input or environment variable # api_token = os.environ.get("GROWATT_API_TOKEN") or input("Enter your Growatt API token: ") # test token from official API docs https://www.showdoc.com.cn/262556420217021/1494053950115877 api_token = "6eb6f069523055a339d71e5b1f6c88cc" # gitleaks:allow try: # Initialize the API with token api = growattServer.OpenApiV1(token=api_token) # Get plant list using V1 API plants = api.plant_list() plant_id = plants["plants"][0]["plant_id"] # Get devices in plant devices = api.device_list(plant_id) # Iterate over all devices energy_data = None for device in devices["devices"]: if device["type"] == 7: # (MIN/TLX) inverter_sn = device["device_sn"] # Get energy data energy_data = api.min_energy(device_sn=inverter_sn) with open("energy_data.json", "w") as f: json.dump(energy_data, f, indent=4, sort_keys=True) # energy data does not contain epvToday for some reason, so we need to calculate it epv_today = energy_data["epv1Today"] + energy_data["epv2Today"] solar_production = f'{float(epv_today):.1f}/{float(energy_data["epvTotal"]):.1f}' solar_production_pv1 = f'{float(energy_data["epv1Today"]):.1f}/{float(energy_data["epv1Total"]):.1f}' solar_production_pv2 = f'{float(energy_data["epv2Today"]):.1f}/{float(energy_data["epv2Total"]):.1f}' energy_output = f'{float(energy_data["eacToday"]):.1f}/{float(energy_data["eacTotal"]):.1f}' system_production = f'{float(energy_data["esystemToday"]):.1f}/{float(energy_data["esystemTotal"]):.1f}' battery_charged = f'{float(energy_data["echargeToday"]):.1f}/{float(energy_data["echargeTotal"]):.1f}' battery_grid_charge = f'{float(energy_data["eacChargeToday"]):.1f}/{float(energy_data["eacChargeTotal"]):.1f}' battery_discharged = f'{float(energy_data["edischargeToday"]):.1f}/{float(energy_data["edischargeTotal"]):.1f}' exported_to_grid = f'{float(energy_data["etoGridToday"]):.1f}/{float(energy_data["etoGridTotal"]):.1f}' imported_from_grid = f'{float(energy_data["etoUserToday"]):.1f}/{float(energy_data["etoUserTotal"]):.1f}' load_consumption = f'{float(energy_data["elocalLoadToday"]):.1f}/{float(energy_data["elocalLoadTotal"]):.1f}' self_consumption = f'{float(energy_data["eselfToday"]):.1f}/{float(energy_data["eselfTotal"]):.1f}' battery_charged = f'{float(energy_data["echargeToday"]):.1f}/{float(energy_data["echargeTotal"]):.1f}' # Output the dashboard print("\nGeneration overview Today/Total(kWh)") print(f"Solar production {solar_production:>22}") print(f" Solar production, PV1 {solar_production_pv1:>22}") print(f" Solar production, PV2 {solar_production_pv2:>22}") print(f"Energy Output {energy_output:>22}") print(f"System production {system_production:>22}") print(f"Self consumption {self_consumption:>22}") print(f"Load consumption {load_consumption:>22}") print(f"Battery Charged {battery_charged:>22}") print(f" Charged from grid {battery_grid_charge:>22}") print(f"Battery Discharged {battery_discharged:>22}") print(f"Import from grid {imported_from_grid:>22}") print(f"Export to grid {exported_to_grid:>22}") print("\nPower overview (Watts)") print(f'AC Power {float(energy_data["pac"]):>22.1f}') print(f'Self power {float(energy_data["pself"]):>22.1f}') print( f'Export power {float(energy_data["pacToGridTotal"]):>22.1f}') print( f'Import power {float(energy_data["pacToUserTotal"]):>22.1f}') print( f'Local load power {float(energy_data["pacToLocalLoad"]):>22.1f}') print(f'PV power {float(energy_data["ppv"]):>22.1f}') print(f'PV #1 power {float(energy_data["ppv1"]):>22.1f}') print(f'PV #2 power {float(energy_data["ppv2"]):>22.1f}') print( f'Battery charge power {float(energy_data["bdc1ChargePower"]):>22.1f}') print( f'Battery discharge power {float(energy_data["bdc1DischargePower"]):>22.1f}') print(f'Battery SOC {int(energy_data["bdc1Soc"]):>21}%') except growattServer.GrowattV1ApiError as e: print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})") except growattServer.GrowattParameterError as e: print(f"Parameter Error: {e}") except requests.exceptions.RequestException as e: print(f"Network Error: {e}") except Exception as e: print(f"Unexpected error: {e}") indykoning-PyPi_GrowattServer-0258b4e/examples/mix_example.py000077500000000000000000000255041514467344200245160ustar00rootroot00000000000000import getpass import pprint import growattServer """ This is a very trivial script that logs into a user's account and prints out useful data for a "Mix" system (Hybrid). The first half of the logic is applicable to all types of system. There is a clear point (marked in the script) where we specifically make calls to the "mix" WebAPI calls, at this point other types of systems will no longer work. This has been tested against my personal system (muppet3000) which is a hybrid inverter system. Throughout the script there are points where 'pp.pprint' has been commented out. If you wish to see all the data that is returned from those specific library calls, just uncomment them and they will appear as part of the output. NOTE - For some reason (not sure if this is just specific to my system or not) the "export to grid" daily total and overall total values don't seem to be populating. As such they are untested. This has been causing problems on my WebUI and mobile app too, it is not a bug in this library, the output from this script has been updated to reflect it's inaccuracy. """ pp = pprint.PrettyPrinter(indent=4) """ A really hacky function to allow me to print out things with an indent in-front """ def indent_print(to_output, indent) -> None: indent_string = "" for _x in range(indent): indent_string += " " print(indent_string + to_output) #Prompt user for username username=input("Enter username:") #Prompt user to input password user_pass=getpass.getpass("Enter password:") api = growattServer.GrowattApi() login_response = api.login(username, user_pass) plant_list = api.plant_list(login_response["user"]["id"]) #pp.pprint(plant_list) print("***Totals for all plants***") pp.pprint(plant_list["totalData"]) print() print("***List of plants***") for plant in plant_list["data"]: indent_print("ID: {}, Name: {}".format(plant["plantId"], plant["plantName"]), 2) print() for plant in plant_list["data"]: plant_id = plant["plantId"] plant_name = plant["plantName"] plant_info=api.plant_info(plant_id) #pp.pprint(plant_info) print(f"***Info for Plant {plant_id} - {plant_name}***") #There are more values in plant_info, but these are some of the useful/interesting ones indent_print("CO2 Reducion: {}".format(plant_info["Co2Reduction"]),2) indent_print("Nominal Power (w): {}".format(plant_info["nominal_Power"]),2) indent_print("Solar Energy Today (kw): {}".format(plant_info["todayEnergy"]),2) indent_print("Solar Energy Total (kw): {}".format(plant_info["totalEnergy"]),2) print() indent_print("Devices in plant:",2) for device in plant_info["deviceList"]: device_sn = device["deviceSn"] device_type = device["deviceType"] indent_print(f"- Device - SN: {device_sn}, Type: {device_type}",4) print() for device in plant_info["deviceList"]: device_sn = device["deviceSn"] device_type = device["deviceType"] indent_print(f"**Device - SN: {device_sn}, Type: {device_type}**",2) #NOTE - This is the bit where we specifically only handle information on Mix devices - this won't work for non-mix devices #These two API calls return lots of duplicated information, but each also holds unique information as well mix_info = api.mix_info(device_sn, plant_id) pp.pprint(mix_info) mix_totals = api.mix_totals(device_sn, plant_id) #pp.pprint(mix_totals) indent_print("*TOTAL VALUES*", 4) indent_print("==Today Totals==", 4) indent_print("Battery Charge (kwh): {}".format(mix_info["eBatChargeToday"]),6) indent_print("Battery Discharge (kwh): {}".format(mix_info["eBatDisChargeToday"]),6) indent_print("Solar Generation (kwh): {}".format(mix_info["epvToday"]),6) indent_print("Local Load (kwh): {}".format(mix_totals["elocalLoadToday"]),6) indent_print("Export to Grid (kwh): {}".format(mix_totals["etoGridToday"]),6) indent_print("==Overall Totals==",4) indent_print("Battery Charge: {}".format(mix_info["eBatChargeTotal"]),6) indent_print("Battery Discharge (kwh): {}".format(mix_info["eBatDisChargeTotal"]),6) indent_print("Solar Generation (kwh): {}".format(mix_info["epvTotal"]),6) indent_print("Local Load (kwh): {}".format(mix_totals["elocalLoadTotal"]),6) indent_print("Export to Grid (kwh): {}".format(mix_totals["etogridTotal"]),6) print() mix_detail = api.mix_detail(device_sn, plant_id) #pp.pprint(mix_detail) #Some of the 'totals' values that are returned by this function do not align to what we would expect, however the graph data always seems to be accurate. #Therefore, here we take a moment to calculate the same values provided elsewhere but based on the graph data instead #The particular stats that we question are 'load consumption' (elocalLoad) and 'import from grid' (etouser) which seem to be calculated from one-another #It would appear that 'etouser' is calculated on the backend incorrectly for systems that use AC battery charged (e.g. during cheap nighttime rates) pacToGridToday = 0.0 pacToUserToday = 0.0 pdischargeToday = 0.0 ppvToday = 0.0 sysOutToday = 0.0 chartData = mix_detail["chartData"] for data_points in chartData.values(): #For each time entry convert it's wattage into kWh, this assumes that the wattage value is #the same for the whole 5 minute window (it's the only assumption we can make) #We Multiply the wattage by 5/60 (the number of minutes of the time window divided by the number of minutes in an hour) #to give us the equivalent kWh reading for that 5 minute window pacToGridToday += float(data_points["pacToGrid"]) * (5/60) pacToUserToday += float(data_points["pacToUser"]) * (5/60) pdischargeToday += float(data_points["pdischarge"]) * (5/60) ppvToday += float(data_points["ppv"]) * (5/60) sysOutToday += float(data_points["sysOut"]) * (5/60) mix_detail["calculatedPacToGridTodayKwh"] = round(pacToGridToday,2) mix_detail["calculatedPacToUserTodayKwh"] = round(pacToUserToday,2) mix_detail["calculatedPdischargeTodayKwh"] = round(pdischargeToday,2) mix_detail["calculatedPpvTodayKwh"] = round(ppvToday,2) mix_detail["calculatedSysOutTodayKwh"] = round(sysOutToday,2) #Option to print mix_detail again now we've made the additions #pp.pprint(mix_detail) dashboard_data = api.dashboard_data(plant_id) #pp.pprint(dashboard_data) indent_print("*TODAY TOTALS BREAKDOWN*", 4) indent_print("Self generation total (batteries & solar - from API) (kwh): {}".format(mix_detail["eCharge"]),6) indent_print("Load consumed from solar (kwh): {}".format(mix_detail["eChargeToday"]),6) indent_print("Load consumed from batteries (kwh): {}".format(mix_detail["echarge1"]),6) indent_print("Self consumption total (batteries & solar - from API) (kwh): {}".format(mix_detail["eChargeToday1"]),6) indent_print("Load consumed from grid (kwh): {}".format(mix_detail["etouser"]),6) indent_print("Total imported from grid (Load + AC charging) (kwh): {}".format(dashboard_data["etouser"].replace("kWh","")),6) calculated_consumption = float(mix_detail["eChargeToday"]) + float(mix_detail["echarge1"]) + float(mix_detail["etouser"]) indent_print(f"Load consumption (calculated) (kwh): {round(calculated_consumption,2)}",6) indent_print("Load consumption (API) (kwh): {}".format(mix_detail["elocalLoad"]),6) indent_print("Exported (kwh): {}".format(mix_detail["eAcCharge"]), 6) solar_to_battery = round(float(mix_info["epvToday"]) - float(mix_detail["eAcCharge"]) - float(mix_detail["eChargeToday"]),2) indent_print(f"Solar battery charge (calculated) (kwh): {solar_to_battery}", 6) ac_to_battery = round(float(mix_info["eBatChargeToday"]) - solar_to_battery,2) indent_print(f"AC battery charge (calculated) (kwh): {ac_to_battery}", 6) print() indent_print("*TODAY TOTALS COMPARISONS*", 4) indent_print("Export to Grid (kwh) - TRUSTED:", 6) indent_print("mix_totals['etoGridToday']: {}".format(mix_totals["etoGridToday"]), 8) indent_print("mix_detail['eAcCharge']: {}".format(mix_detail["eAcCharge"]), 8) indent_print("mix_detail['calculatedPacToGridTodayKwh']: {}".format(mix_detail["calculatedPacToGridTodayKwh"]), 8) print() indent_print("Imported from Grid (kwh) - TRUSTED:", 6) indent_print("dashboard_data['etouser']: {}".format(dashboard_data["etouser"].replace("kWh","")), 8) indent_print("mix_detail['calculatedPacToUserTodayKwh']: {}".format(mix_detail["calculatedPacToUserTodayKwh"]), 8) print() indent_print("Battery discharge (kwh) - TRUSTED:", 6) indent_print("mix_info['eBatDisChargeToday']: {}".format(mix_info["eBatDisChargeToday"]), 8) indent_print("mix_totals['edischarge1Today']: {}".format(mix_totals["edischarge1Today"]), 8) indent_print("mix_detail['echarge1']: {}".format(mix_detail["echarge1"]), 8) indent_print("mix_detail['calculatedPdischargeTodayKwh']: {}".format(mix_detail["calculatedPdischargeTodayKwh"]), 8) print() indent_print("Solar generation (kwh) - TRUSTED:", 6) indent_print("mix_info['epvToday']: {}".format(mix_info["epvToday"]), 8) indent_print("mix_totals['epvToday']: {}".format(mix_totals["epvToday"]), 8) indent_print("mix_detail['calculatedPpvTodayKwh']: {}".format(mix_detail["calculatedPpvTodayKwh"]), 8) print() indent_print("Load Consumption (kwh) - TRUSTED:", 6) indent_print("mix_totals['elocalLoadToday']: {}".format(mix_totals["elocalLoadToday"]), 8) indent_print("mix_detail['elocalLoad']: {}".format(mix_detail["elocalLoad"]), 8) indent_print("mix_detail['calculatedSysOutTodayKwh']: {}".format(mix_detail["calculatedSysOutTodayKwh"]), 8) print() #This call gets all of the instantaneous values from the system e.g. current load, generation etc. mix_status = api.mix_system_status(device_sn, plant_id) #pp.pprint(mix_status) #NOTE - There are some other values available in mix_status, however these are the most useful ones indent_print("*CURRENT VALUES*",4) indent_print("==Batteries==",4) indent_print("Charging Batteries at (kw): {}".format(mix_status["chargePower"]),6) indent_print("Discharging Batteries at (kw): {}".format(mix_status["pdisCharge1"]),6) indent_print("Batteries %: {}".format(mix_status["SOC"]),6) indent_print("==PVs==",4) indent_print("PV1 wattage: {}".format(mix_status["pPv1"]),6) indent_print("PV2 wattage: {}".format(mix_status["pPv2"]),6) calc_pv_total = (float(mix_status["pPv1"]) + float(mix_status["pPv2"]))/1000 indent_print(f"PV total wattage (calculated) - KW: {round(calc_pv_total,2)}",6) indent_print("PV total wattage (API) - KW: {}".format(mix_status["ppv"]),6) indent_print("==Consumption==",4) indent_print("Local load/consumption - KW: {}".format(mix_status["pLocalLoad"]),6) indent_print("==Import/Export==",4) indent_print("Importing from Grid - KW: {}".format(mix_status["pactouser"]),6) indent_print("Exporting to Grid - KW: {}".format(mix_status["pactogrid"]),6) indykoning-PyPi_GrowattServer-0258b4e/examples/noah_example.py000066400000000000000000000060111514467344200246330ustar00rootroot00000000000000import getpass import pprint import growattServer """ This is a very trivial script that logs into a user's account and prints out useful data for a "NOAH" system. This has been tested against my personal system (NOAH2000) which is a 2kW Balcony Storage system. Throughout the script there are points where 'pp.pprint' has been commented out. If you wish to see all the data that is returned from those specific library calls, just uncomment them and they will appear as part of the output. """ pp = pprint.PrettyPrinter(indent=4) """ A really hacky function to allow me to print out things with an indent in-front """ def indent_print(to_output, indent) -> None: indent_string = "" for _x in range(indent): indent_string += " " print(indent_string + to_output) #Prompt user for username username=input("Enter username:") #Prompt user to input password user_pass=getpass.getpass("Enter password:") api = growattServer.GrowattApi() login_response = api.login(username, user_pass) plant_list = api.plant_list(login_response["user"]["id"]) #pp.pprint(plant_list) print("***Totals for all plants***") pp.pprint(plant_list["totalData"]) print() print("***List of plants***") for plant in plant_list["data"]: indent_print("ID: {}, Name: {}".format(plant["plantId"], plant["plantName"]), 2) print() for plant in plant_list["data"]: plant_id = plant["plantId"] plant_name = plant["plantName"] plant_info=api.plant_info(plant_id) #pp.pprint(plant_info) print(f"***Info for Plant {plant_id} - {plant_name}***") #There are more values in plant_info, but these are some of the useful/interesting ones indent_print("CO2 Reducion: {}".format(plant_info["Co2Reduction"]),2) indent_print("Nominal Power (w): {}".format(plant_info["nominal_Power"]),2) indent_print("Solar Energy Today (kw): {}".format(plant_info["todayEnergy"]),2) indent_print("Solar Energy Total (kw): {}".format(plant_info["totalEnergy"]),2) print() indent_print("Devices in plant:",2) for device in plant_info["deviceList"]: device_sn = device["deviceSn"] device_type = device["deviceType"] indent_print(f"- Device - SN: {device_sn}, Type: {device_type}",4) is_noah = api.is_plant_noah_system(plant["plantId"]) if is_noah["result"] == 1 and (is_noah["obj"]["isPlantNoahSystem"] or is_noah["obj"]["isPlantHaveNoah"]): device_sn = is_noah["obj"]["deviceSn"] indent_print(f"**NOAH - SN: {device_sn}**",2) noah_system = api.noah_system_status(is_noah["obj"]["deviceSn"]) pp.pprint(noah_system["obj"]) print() noah_infos = api.noah_info(is_noah["obj"]["deviceSn"]) pp.pprint(noah_infos["obj"]["noah"]) print() indent_print("Remaining battery (" + "%" + "): {}".format(noah_system["obj"]["soc"]),2) indent_print("Solar Power (w): {}".format(noah_system["obj"]["ppv"]),2) indent_print("Charge Power (w): {}".format(noah_system["obj"]["chargePower"]),2) indent_print("Discharge Power (w): {}".format(noah_system["obj"]["disChargePower"]),2) indent_print("Output Power (w): {}".format(noah_system["obj"]["pac"]),2) indykoning-PyPi_GrowattServer-0258b4e/examples/settings_example.py000077500000000000000000000064041514467344200255570ustar00rootroot00000000000000import datetime import getpass import pprint import growattServer """ This is a very trivial script to show how to interface with the configuration settings of a plant and it's inverters This has been tested against my personal system (muppet3000) which is a hybrid (aka 'mix') inverter system. Throughout the script there are points where 'pp.pprint' has been commented out. If you wish to see all the data that is returned from those specific library calls, just uncomment them and they will appear as part of the output. """ pp = pprint.PrettyPrinter(indent=4) #Prompt user for username username=input("Enter username:") #Prompt user to input password user_pass=getpass.getpass("Enter password:") api = growattServer.GrowattApi() login_response = api.login(username, user_pass) plant_list = api.plant_list(login_response["user"]["id"]) #Simple logic to just get the first inverter from the first plant #Expand this using a for-loop to perform for more systems (see mix_example for more detail) plant = plant_list["data"][0] #This is an array - we just take the first - would need a for-loop for more systems plant_id = plant["plantId"] plant_name = plant["plantName"] plant_info=api.plant_info(plant_id) device = plant_info["deviceList"][0] #This is an array - we just take the first - would need a for-loop for more systems device_sn = device["deviceSn"] device_type = device["deviceType"] #Get plant settings - This is performed for us inside 'update_plant_settings' but you can get ALL of the settings using this current_settings = api.get_plant_settings(plant_id) #pp.pprint(current_settings) #Get mix inverter settings inverter_settings = api.get_mix_inverter_settings(device_sn) pp.pprint(inverter_settings) #Change the timezone of the plant plant_settings_changes = { "plantTimezone": "0" } print("Changing the following plant setting(s):") pp.pprint(plant_settings_changes) response = api.update_plant_settings(plant_id, plant_settings_changes) print(response) print() #Set inverter time now = datetime.datetime.now() dt_string = now.strftime("%Y-%m-%d %H:%M:%S") time_settings={ "param1": dt_string } print(f"Setting inverter time to: {dt_string}") response = api.update_mix_inverter_setting(device_sn, "pf_sys_year", time_settings) print(response) print() #Set inverter schedule (Uses the 'array' method which assumes all parameters are named param1....paramN) schedule_settings = ["100", #Charging power % "100", #Stop charging SoC % "1", #Allow AC charging (1 = Enabled) "00", "40", #Schedule 1 - Start time "04", "20", #Schedule 1 - End time "1", #Schedule 1 - Enabled/Disabled (1 = Enabled) "00", "00", #Schedule 2 - Start time "00", "00", #Schedule 2 - End time "0", #Schedule 2 - Enabled/Disabled (0 = Disabled) "00", "00", #Schedule 3 - Start time "00", "00", #Schedule 3 - End time "0"] #Schedule 3 - Enabled/Disabled (0 = Disabled) print("Setting the inverter charging schedule to:") pp.pprint(schedule_settings) response = api.update_mix_inverter_setting(device_sn, "mix_ac_charge_time_period", schedule_settings) print(response) indykoning-PyPi_GrowattServer-0258b4e/examples/settings_example_AC.py000066400000000000000000000043241514467344200261160ustar00rootroot00000000000000import json import sys import growattServer """ Sample script to set AC battery charging Takes commandline arguments for terminal SOC, start time, end time, and whether to run, with default arguments if none are given Tested on an SPA3000 """ # check for SOC percent and whether to run if len(sys.argv) != 7: SOC = "40" startH = "0" startM = "40" endH = "04" endM = "30" run = "1" else: SOC = str(sys.argv[1]) startH = f"{int(sys.argv[2]):02.0f}" startM = f"{int(sys.argv[3]):02.0f}" endH = f"{int(sys.argv[4]):02.0f}" endM = f"{int(sys.argv[5]):02.0f}" run = str(sys.argv[6]) api = growattServer.GrowattApi() # This part needs to be adapted by the user login_response = api.login("USERNAME_AS_STRING", "PASSWORD_AS_STRING") if login_response["success"]: # Get a list of growatt plants. plant_list = api.plant_list(login_response["user"]["id"]) plant = plant_list["data"][0] plant_id = plant["plantId"] plant_info = api.plant_info(plant_id) device = plant_info["deviceList"][0] device_sn = device["deviceSn"] # All parameters need to be given, including zeros # All parameters must be strings schedule_settings = ["100", # Charging power % SOC, # Stop charging at SoC % startH, startM, # Schedule 1 - Start time endH, endM, # Schedule 1 - End time run, # Schedule 1 - Enabled/Disabled (1 = Enabled) "00","00", # Schedule 2 - Start time "00","00", # Schedule 2 - End time "0", # Schedule 2 - Enabled/Disabled (1 = Enabled) "00","00", # Schedule 3 - Start time "00","00", # Schedule 3 - End time "0"] # Schedule 3 - Enabled/Disabled (1 = Enabled) response = api.update_ac_inverter_setting(device_sn, "spa_ac_charge_time_period", schedule_settings) else: response = login_response print(json.dumps(response)) indykoning-PyPi_GrowattServer-0258b4e/examples/settings_example_classic.py000066400000000000000000000030741514467344200272550ustar00rootroot00000000000000import getpass import pprint import growattServer """ This script demonstrates how to interface with the configuration settings of a plant and its classic inverters. It uses the `update_classic_inverter_setting` function to apply settings to a classic inverter. """ pp = pprint.PrettyPrinter(indent=4) # Prompt user for username username = input("Enter username:") # Prompt user to input password user_pass = getpass.getpass("Enter password:") api = growattServer.GrowattApi(True, username) login_response = api.login(username, user_pass) plant_list = api.plant_list(login_response["user"]["id"]) # Simple logic to just get the first inverter from the first plant # Expand this using a for-loop to perform for more systems plant = plant_list["data"][0] # This is an array - we just take the first - would need a for-loop for more systems plant_id = plant["plantId"] plant_name = plant["plantName"] plant_info = api.plant_info(plant_id) devices = api.device_list(plant_id) device = devices[0] # This is an array - we just take the first - would need a for-loop for more systems device_sn = device["deviceSn"] device_type = device["deviceType"] # Turn inverter on print(f"Turning on inverter: {device_sn}") # Set up the default parameters default_parameters = { "action": "inverterSet", "serialNum": device_sn, } parameters = { "paramId": "pv_on_off", "command_1": "0001", # 0001 to turn on, 0000 to turn off "command_2": "", # Empty string for command_2 as not used } response = api.update_classic_inverter_setting(default_parameters, parameters) print(response) indykoning-PyPi_GrowattServer-0258b4e/examples/simple.py000077500000000000000000000002751514467344200234750ustar00rootroot00000000000000import growattServer api = growattServer.GrowattApi() login_response = api.login(, ) #Get a list of growatt plants. print(api.plant_list(login_response['user']['id'])) indykoning-PyPi_GrowattServer-0258b4e/examples/sph_example.py000066400000000000000000000151621514467344200245070ustar00rootroot00000000000000""" Example script for SPH devices using the OpenAPI V1. This script demonstrates controlling SPH interface devices (device type 5) such as hybrid inverter systems. You can obtain an API token from the Growatt API documentation or developer portal. """ import json import os import requests import growattServer # Get the API token from environment variable or use test token api_token = os.environ.get("GROWATT_API_TOKEN") if not api_token: # test token from official API docs https://www.showdoc.com.cn/262556420217021/1494053950115877 api_token = "6eb6f069523055a339d71e5b1f6c88cc" # noqa: S105 try: # Initialize the API with token instead of using login api = growattServer.OpenApiV1(token=api_token) # Plant info plants = api.plant_list() print(f"Plants: Found {plants['count']} plants") plant_id = plants["plants"][0]["plant_id"] # Devices devices = api.device_list(plant_id) for device in devices["devices"]: print(device) if device["type"] == growattServer.DeviceType.SPH.value: inverter_sn = device["device_sn"] print(f"Processing SPH device: {inverter_sn}") # Get energy data energy_data = api.sph_energy( device_sn=inverter_sn, ) print("Saving energy data to energy_data.json") with open("energy_data.json", "w") as f: json.dump(energy_data, f, indent=4, sort_keys=True) # Get energy history energy_history_data = api.sph_energy_history( device_sn=inverter_sn, ) print("Saving energy history data to energy_history.json") with open("energy_history.json", "w") as f: json.dump( energy_history_data.get("datas", []), f, indent=4, sort_keys=True, ) # Get device details inverter_data = api.sph_detail( device_sn=inverter_sn, ) print("Saving inverter data to inverter_data.json") with open("inverter_data.json", "w") as f: json.dump(inverter_data, f, indent=4, sort_keys=True) # Read some settings directly from inverter_data (from sph_detail) # See docs/openapiv1/sph_settings.md for all available fields print("Device Settings:") print(f" Device status: {inverter_data.get('status', 'N/A')}") print(f" Battery type: {inverter_data.get('batteryType', 'N/A')}") print(f" EPS enabled: {inverter_data.get('epsFunEn', 'N/A')}") print(f" Export limit: {inverter_data.get('exportLimitPowerRate', 'N/A')}%") # Read AC charge time periods using helper function and inverter_data to avoid rate limiting charge_config = api.sph_read_ac_charge_times( device_sn=inverter_sn, settings_data=inverter_data, ) print("AC Charge Configuration:") print(f" Charge Power: {charge_config['charge_power']}%") print(f" Stop SOC: {charge_config['charge_stop_soc']}%") print(f" Mains Enabled: {charge_config['mains_enabled']}") print(f" Periods: {json.dumps(charge_config['periods'], indent=4)}") # Read AC discharge time periods using helper function and inverter_data to avoid rate limiting discharge_config = api.sph_read_ac_discharge_times( device_sn=inverter_sn, settings_data=inverter_data, ) print("AC Discharge Configuration:") print(f" Discharge Power: {discharge_config['discharge_power']}%") print(f" Stop SOC: {discharge_config['discharge_stop_soc']}%") print(f" Periods: {json.dumps(discharge_config['periods'], indent=4)}") # Write examples - Uncomment to test # Example 1: Set AC charge time periods # Charge at 50% power, stop at 95% SOC, grid charging enabled # api.sph_write_ac_charge_times( # device_sn=inverter_sn, # charge_power=50, # charge_stop_soc=95, # mains_enabled=True, # periods=[ # {"start_time": datetime.time(0, 0), "end_time": datetime.time(6, 0), "enabled": True}, # {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False}, # {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False}, # ] # ) # print("AC charge periods updated successfully") # Example 2: Set AC discharge time periods # Discharge at 100% power, stop at 20% SOC # api.sph_write_ac_discharge_times( # device_sn=inverter_sn, # discharge_power=100, # discharge_stop_soc=20, # periods=[ # {"start_time": datetime.time(17, 0), "end_time": datetime.time(22, 0), "enabled": True}, # {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False}, # {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False}, # ] # ) # print("AC discharge periods updated successfully") # Example 3: Turn device on/off # api.sph_write_parameter(inverter_sn, "pv_on_off", "1") # Turn on # api.sph_write_parameter(inverter_sn, "pv_on_off", "0") # Turn off # Example 4: Set grid voltage limits # api.sph_write_parameter(inverter_sn, "pv_grid_voltage_high", "270") # api.sph_write_parameter(inverter_sn, "pv_grid_voltage_low", "180") # Example 5: Configure off-grid/EPS settings # api.sph_write_parameter(inverter_sn, "mix_off_grid_enable", "1") # Enable # api.sph_write_parameter(inverter_sn, "mix_ac_discharge_frequency", "0") # 50Hz # api.sph_write_parameter(inverter_sn, "mix_ac_discharge_voltage", "0") # 230V # Example 6: Set anti-backflow (export limit) # api.sph_write_parameter(inverter_sn, "backflow_setting", ["1", "50"]) # On, 50% except growattServer.GrowattV1ApiError as e: print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})") except growattServer.GrowattParameterError as e: print(f"Parameter Error: {e}") except requests.exceptions.RequestException as e: print(f"Network Error: {e}") except Exception as e: # noqa: BLE001 print(f"Unexpected error: {e}") indykoning-PyPi_GrowattServer-0258b4e/examples/tlx_example.py000066400000000000000000000115231514467344200245210ustar00rootroot00000000000000import datetime import getpass import json import growattServer """ # Example script controlling a Growatt MID-30KTL3-XH + APX battery hybrid system by emulating the ShinePhone iOS app. # The same API calls are used by the ShinePhone Android app as well. Traffic intercepted using HTTP Toolkit. # # The plant / energy / device APIs seem to be generic for all Growatt systems, while the inverter and battery APIs use the TLX APIs. # # The available settings under the 'Control' tab in ShinePhone are created by combining the results from two function calls: # tlx_get_all_settings() seem to returns the sum of all settings for all systems while tlx_get_enabled_settings() tells # which of these settings are valid for the TLX system. # # Settings that takes a single parameter can be set using update_tlx_inverter_setting(). A helper function, update_tlx_inverter_time_segment() # is provided for updating time segments which take several parameters. The inverter is picky and time intervals can't be overlapping, # even if they are disabled. # # The set functions are commented out in the example, uncomment to test, and use at your own risk. Most likely all settings returned in # tlx_get_enabled_settings() can be set using update_tlx_inverter_setting(), but has not been tested. # """ # Prompt user for username username=input("Enter username:") # Prompt user to input password user_pass=getpass.getpass("Enter password:") user_agent = "ShinePhone/8.1.17 (iPhone; iOS 15.6.1; Scale/2.00)" api = growattServer.GrowattApi(agent_identifier=user_agent) login_response = api.login(username, user_pass) user_id = login_response["user"]["id"] print("Login successful, user_id:", user_id) # Plant info plant_list = api.plant_list_two() plant_id = plant_list[0]["id"] plant_info = api.plant_info(plant_id) print("Plant info:", json.dumps(plant_info, indent=4, sort_keys=True)) # Energy data (used in the 'Plant' Tab) energy_data = api.plant_energy_data(plant_id) print("Plant Energy data", json.dumps(energy_data, indent=4, sort_keys=True)) # Devices devices = api.device_list(plant_id) print("Devices:", json.dumps(devices, indent=4, sort_keys=True)) for device in devices: if device["deviceType"] == "tlx": # Inverter info (used in inverter view) inverter_sn = device["deviceSn"] inverter_info = api.tlx_params(inverter_sn) print("Inverter info:", json.dumps(inverter_info, indent=4, sort_keys=True)) # PV production data data = api.tlx_data(inverter_sn, datetime.datetime.now()) print("PV production data:", json.dumps(data, indent=4, sort_keys=True)) # System settings all_settings = api.tlx_all_settings(inverter_sn) enabled_settings = api.tlx_enabled_settings(inverter_sn) # 'on_grid_discharge_stop_soc' is present in web UI, but for some reason not # returned in enabled settings so we enable it manually here instead enabled_settings["enable"]["on_grid_discharge_stop_soc"] = "1" enabled_keys = enabled_settings["enable"].keys() available_settings = {k: v for k, v in all_settings.items() if k in enabled_keys} print("System settings:", json.dumps(available_settings, indent=4, sort_keys=True)) # System status data = api.tlx_system_status(plant_id, inverter_sn) print("System status:", json.dumps(data, indent=4, sort_keys=True)) # Energy overview data = api.tlx_energy_overview(plant_id, inverter_sn) print("Energy overview:", json.dumps(data, indent=4, sort_keys=True)) # Energy production & consumption data = api.tlx_energy_prod_cons(plant_id, inverter_sn) print("Energy production & consumption:", json.dumps(data, indent=4, sort_keys=True)) elif device["deviceType"] == "bat": # Battery info batt_info = api.tlx_battery_info(device["deviceSn"]) print("Battery info:", json.dumps(batt_info, indent=4, sort_keys=True)) batt_info_detailed = api.tlx_battery_info_detailed(plant_id, device["deviceSn"]) print("Battery info: detailed", json.dumps(batt_info_detailed, indent=4, sort_keys=True)) # Examples of updating settings, uncomment to use # Set charging power to 95% #res = api.update_tlx_inverter_setting(inverter_sn, 'charge_power', 95) #print(res) # Turn on AC charging #res = api.update_tlx_inverter_setting(inverter_sn, 'ac_charge', 1) #print(res) # Enable Load First between 00:01 and 11:59 using time segment 1 #res = api.update_tlx_inverter_time_segment(serial_number = inverter_sn, # segment_id = 1, # batt_mode = growattServer.BATT_MODE_LOAD_FIRST, # start_time = datetime.time(00, 1), # end_time = datetime.time(11, 59), # enabled=True) #print(res) indykoning-PyPi_GrowattServer-0258b4e/examples/tlx_example_dashboard.py000066400000000000000000000150701514467344200265310ustar00rootroot00000000000000 import getpass import sys import growattServer # Example script fetching key power and today+total energy metrics from a Growatt MID-30KTL3-XH (TLX) + APX battery hybrid system # # There is a lot of overlap in what the various Growatt APIs returns. # tlx_detail() contains the bulk of the needed data, but some info is missing and is fetched from # tlx_system_status(), tlx_energy_overview() and tlx_battery_info_detailed() instead # Prompt user for username username=input("Enter username:") # Prompt user to input password user_pass=getpass.getpass("Enter password:") # Login, emulating the Growatt app user_agent = "ShinePhone/8.1.17 (iPhone; iOS 15.6.1; Scale/2.00)" api = growattServer.GrowattApi(agent_identifier=user_agent) login_response = api.login(username, user_pass) if not login_response["success"]: print(f"Failed to log in, msg: {login_response['msg']}, error: {login_response['error']}") sys.exit() # Get plant(s) plant_list = api.plant_list_two() plant_id = plant_list[0]["id"] # Get devices in plant devices = api.device_list(plant_id) # Iterate over all devices. Here we are interested in data from 'tlx' inverters and 'bat' devices batteries_info = [] for device in devices: if device["deviceType"] == "tlx": inverter_sn = device["deviceSn"] # Inverter detail, contains the bulk of energy and power values inverter_detail = api.tlx_detail(inverter_sn).get("data") # Energy overview is used to retrieve "epvToday" which is not present in tlx_detail() for some reason energy_overview = api.tlx_energy_overview(plant_id, inverter_sn) # System status, contains power values, not available in inverter_detail() system_status = api.tlx_system_status(plant_id, inverter_sn) if device["deviceType"] == "bat": batt_info = api.tlx_battery_info(device["deviceSn"]) if batt_info.get("lost"): # Disconnected batteries are listed with 'old' power/energy/SOC data # Therefore we check it it's 'lost' and skip it in that case. print("'Lost' battery found, skipping") continue # Battery info batt_info = api.tlx_battery_info_detailed(plant_id, device["deviceSn"]).get("data") if float(batt_info["chargeOrDisPower"]) > 0: bdcChargePower = float(batt_info["chargeOrDisPower"]) bdcDischargePower = 0 else: bdcChargePower = 0 bdcDischargePower = float(batt_info["chargeOrDisPower"]) bdcDischargePower = -bdcDischargePower battery_data = { "serialNum": device["deviceSn"], "bdcChargePower": bdcChargePower, "bdcDischargePower": bdcDischargePower, "dischargeTotal": batt_info["dischargeTotal"], "soc": batt_info["soc"] } batteries_info.append(battery_data) solar_production = f'{float(energy_overview["epvToday"]):.1f}/{float(energy_overview["epvTotal"]):.1f}' solar_production_pv1 = f'{float(inverter_detail["epv1Today"]):.1f}/{float(inverter_detail["epv1Total"]):.1f}' solar_production_pv2 = f'{float(inverter_detail["epv2Today"]):.1f}/{float(inverter_detail["epv2Total"]):.1f}' energy_output = f'{float(inverter_detail["eacToday"]):.1f}/{float(inverter_detail["eacTotal"]):.1f}' system_production = f'{float(inverter_detail["esystemToday"]):.1f}/{float(inverter_detail["esystemTotal"]):.1f}' battery_charged = f'{float(inverter_detail["echargeToday"]):.1f}/{float(inverter_detail["echargeTotal"]):.1f}' battery_grid_charge = f'{float(inverter_detail["eacChargeToday"]):.1f}/{float(inverter_detail["eacChargeTotal"]):.1f}' battery_discharged = f'{float(inverter_detail["edischargeToday"]):.1f}/{float(inverter_detail["edischargeTotal"]):.1f}' exported_to_grid = f'{float(inverter_detail["etoGridToday"]):.1f}/{float(inverter_detail["etoGridTotal"]):.1f}' imported_from_grid = f'{float(inverter_detail["etoUserToday"]):.1f}/{float(inverter_detail["etoUserTotal"]):.1f}' load_consumption = f'{float(inverter_detail["elocalLoadToday"]):.1f}/{float(inverter_detail["elocalLoadTotal"]):.1f}' self_consumption = f'{float(inverter_detail["eselfToday"]):.1f}/{float(inverter_detail["eselfTotal"]):.1f}' battery_charged = f'{float(inverter_detail["echargeToday"]):.1f}/{float(inverter_detail["echargeTotal"]):.1f}' print("\nGeneration overview Today/Total(kWh)") print(f"Solar production {solar_production:>22}") print(f" Solar production, PV1 {solar_production_pv1:>22}") print(f" Solar production, PV2 {solar_production_pv2:>22}") print(f"Energy Output {energy_output:>22}") print(f"System production {system_production:>22}") print(f"Self consumption {self_consumption:>22}") print(f"Load consumption {load_consumption:>22}") print(f"Battery Charged {battery_charged:>22}") print(f" Charged from grid {battery_grid_charge:>22}") print(f"Battery Discharged {battery_discharged:>22}") print(f"Import from grid {imported_from_grid:>22}") print(f"Export to grid {exported_to_grid:>22}") print("\nPower overview (Watts)") print(f'AC Power {float(inverter_detail["pac"]):>22.1f}') print(f'Self power {float(inverter_detail["pself"]):>22.1f}') print(f'Export power {float(inverter_detail["pacToGridTotal"]):>22.1f}') print(f'Import power {float(inverter_detail["pacToUserTotal"]):>22.1f}') print(f'Local load power {float(inverter_detail["pacToLocalLoad"]):>22.1f}') print(f'PV power {float(inverter_detail["ppv"]):>22.1f}') print(f'PV #1 power {float(inverter_detail["ppv1"]):>22.1f}') print(f'PV #2 power {float(inverter_detail["ppv2"]):>22.1f}') print(f'Battery charge power {float(system_status["chargePower"])*1000:>22.1f}') if len(batteries_info) > 0: print(f'Batt #1 charge power {float(batteries_info[0]["bdcChargePower"]):>22.1f}') if len(batteries_info) > 1: print(f'Batt #2 charge power {float(batteries_info[1]["bdcChargePower"]):>22.1f}') print(f'Battery discharge power {float(system_status["pdisCharge"])*1000:>18.1f}') if len(batteries_info) > 0: print(f'Batt #1 discharge power {float(batteries_info[0]["bdcDischargePower"]):>22.1f}') if len(batteries_info) > 1: print(f'Batt #2 discharge power {float(batteries_info[1]["bdcDischargePower"]):>22.1f}') if len(batteries_info) > 0: print(f'Batt #1 SOC {int(batteries_info[0]["soc"]):>21}%') if len(batteries_info) > 1: print(f'Batt #2 SOC {int(batteries_info[1]["soc"]):>21}%') indykoning-PyPi_GrowattServer-0258b4e/examples/user_agent_options.py000077500000000000000000000035211514467344200261100ustar00rootroot00000000000000import getpass import growattServer """ This is a simple script that demonstrates the various ways to initialise the library to set a User Agent """ #Prompt user for username username=input("Enter username:") #Prompt user to input password user_pass=getpass.getpass("Enter password:") api = growattServer.GrowattApi() login_response = api.login(username, user_pass) print("Default initialisation") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() api = growattServer.GrowattApi(True) login_response = api.login(username, user_pass) print("Add random ID to default User-Agent") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() api = growattServer.GrowattApi(False, "my-user-id") login_response = api.login(username, user_pass) print("Override default User-Agent") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() api = growattServer.GrowattApi(True, "my-user-id") login_response = api.login(username, user_pass) print("Override default User-Agent and add random ID") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() api = growattServer.GrowattApi(False, growattServer.GrowattApi.agent_identifier + " - my-user-id") login_response = api.login(username, user_pass) print("Extend default User-Agent") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() api = growattServer.GrowattApi(True, growattServer.GrowattApi.agent_identifier + " - my-user-id") login_response = api.login(username, user_pass) print("Extend default User-Agent and add random ID") print("User-Agent: {}\nLogged in User id: {}".format(api.agent_identifier, login_response["userId"])) print() indykoning-PyPi_GrowattServer-0258b4e/growattServer/000077500000000000000000000000001514467344200226635ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/growattServer/__init__.py000077500000000000000000000007171514467344200250040ustar00rootroot00000000000000#!/usr/bin/env python3 """growattServer package exports.""" from .base_api import GrowattApi, Timespan, hash_password from .exceptions import GrowattError, GrowattParameterError, GrowattV1ApiError from .open_api_v1 import DeviceType, OpenApiV1 # Package name name = "growattServer" __all__ = [ "DeviceType", "GrowattApi", "GrowattError", "GrowattParameterError", "GrowattV1ApiError", "OpenApiV1", "Timespan", "hash_password", ] indykoning-PyPi_GrowattServer-0258b4e/growattServer/base_api.py000066400000000000000000001340611514467344200250050ustar00rootroot00000000000000"""Core Growatt API client and helpers.""" # ruff: noqa: S324 import datetime import hashlib import secrets import warnings from enum import IntEnum import requests from .exceptions import GrowattV1ApiError name = "growattServer" BATT_MODE_LOAD_FIRST = 0 BATT_MODE_BATTERY_FIRST = 1 BATT_MODE_GRID_FIRST = 2 def hash_password(password): """ Return a modified MD5-like hex digest with 'c' substitutions. The algorithm computes an MD5 hex digest and replaces bytes with a '0' nibble by the character 'c' at every other position. """ password_md5 = hashlib.md5(password.encode("utf-8")).hexdigest() # nosec for i in range(0, len(password_md5), 2): if password_md5[i] == "0": password_md5 = password_md5[0:i] + "c" + password_md5[i + 1:] return password_md5 class Timespan(IntEnum): """Enumeration of supported timespans.""" hour = 0 day = 1 month = 2 class GrowattApi: """Base client for Growatt API endpoints.""" server_url = "https://openapi.growatt.com/" agent_identifier = "Dalvik/2.1.0 (Linux; U; Android 12; https://github.com/indykoning/PyPi_GrowattServer)" def __init__(self, add_random_user_id=False, agent_identifier=None) -> None: """ Initialize the Growatt API client. Args: add_random_user_id: Append a short random suffix to the user-agent. agent_identifier: Optional override for the user-agent string. """ if agent_identifier is not None: self.agent_identifier = agent_identifier # If a random user id is required, generate a 5 digit number and add it to the user agent if add_random_user_id: random_number = "".join(str(secrets.randbelow(10)) for _ in range(5)) self.agent_identifier += " - " + random_number self.session = requests.Session() def _raise_for_status(response, *args: object, **kwargs: object) -> None: _ = args _ = kwargs response.raise_for_status() self.session.hooks = {"response": _raise_for_status} headers = {"User-Agent": self.agent_identifier} self.session.headers.update(headers) def __get_date_string(self, timespan=None, date=None): if timespan is not None and not isinstance(timespan, Timespan): raise ValueError("timespan must be a Timespan enum value") if date is None: date = datetime.datetime.now(datetime.UTC) date_str = "" if timespan == Timespan.month: date_str = date.strftime("%Y-%m") else: date_str = date.strftime("%Y-%m-%d") return date_str def get_url(self, page): """Return the page URL.""" return self.server_url + page def login(self, username, password, is_password_hashed=False): """ Log the user in. Returns ------- 'data' -- A List containing Objects containing the folowing 'plantName' -- Friendly name of the plant 'plantId' -- The ID of the plant 'service' 'quality' 'isOpenSmartFamily' 'totalData' -- An Object 'success' -- True or False 'msg' 'app_code' 'user' -- An Object containing a lot of user information 'uid' 'userLanguage' 'inverterGroup' -- A List 'timeZone' -- A Number 'lat' 'lng' 'dataAcqList' -- A List 'type' 'accountName' -- The username 'password' -- The password hash of the user 'isValiPhone' 'kind' 'mailNotice' -- True or False 'id' 'lasLoginIp' 'lastLoginTime' 'userDeviceType' 'phoneNum' 'approved' -- True or False 'area' -- Continent of the user 'smsNotice' -- True or False 'isAgent' 'token' 'nickName' 'parentUserId' 'customerCode' 'country' 'isPhoneNumReg' 'createDate' 'rightlevel' 'appType' 'serverUrl' 'roleId' 'enabled' -- True or False 'agentCode' 'inverterList' -- A list 'email' 'company' 'activeName' 'codeIndex' 'appAlias' 'isBigCustomer' 'noticeType' """ if not is_password_hashed: password = hash_password(password) response = self.session.post(self.get_url("newTwoLoginAPI.do"), data={ "userName": username, "password": password }) data = response.json()["back"] if data["success"]: data.update({ "userId": data["user"]["id"], "userLevel": data["user"]["rightlevel"] }) return data def plant_list(self, user_id): """ Get a list of plants connected to this account. Args: user_id (str): The ID of the user. Returns: list: A list of plants connected to the account. Raises: Exception: If the request to the server fails. """ response = self.session.get( self.get_url("PlantListAPI.do"), params={"userId": user_id}, allow_redirects=False ) return response.json().get("back", []) def plant_detail(self, plant_id, timespan, date=None): """ Get plant details for specified timespan. Args: plant_id (str): The ID of the plant. timespan (Timespan): The ENUM value conforming to the time window you want e.g. hours from today, days, or months. date (datetime, optional): The date you are interested in. Defaults to datetime.datetime.now(). Returns: dict: A dictionary containing the plant details. Raises: Exception: If the request to the server fails. """ date_str = self.__get_date_string(timespan, date) response = self.session.get(self.get_url("PlantDetailAPI.do"), params={ "plantId": plant_id, "type": timespan.value, "date": date_str }) return response.json().get("back", {}) def plant_list_two(self): """ Get a list of all plants with detailed information. Returns: list: A list of plants with detailed information. """ response = self.session.post( self.get_url("newTwoPlantAPI.do"), params={"op": "getAllPlantListTwo"}, data={ "language": "1", "nominalPower": "", "order": "1", "pageSize": "15", "plantName": "", "plantStatus": "", "toPageNum": "1" } ) return response.json().get("PlantList", []) def inverter_data(self, inverter_id, date=None): """ Get inverter data for specified date or today. Args: inverter_id (str): The ID of the inverter. date (datetime, optional): The date you are interested in. Defaults to datetime.datetime.now(). Returns: dict: A dictionary containing the inverter data. Raises: Exception: If the request to the server fails. """ date_str = self.__get_date_string(date=date) response = self.session.get(self.get_url("newInverterAPI.do"), params={ "op": "getInverterData", "id": inverter_id, "type": 1, "date": date_str }) return response.json() def inverter_detail(self, inverter_id): """ Get detailed data from PV inverter. Args: inverter_id (str): The ID of the inverter. Returns: dict: A dictionary containing the inverter details. Raises: Exception: If the request to the server fails. """ response = self.session.get(self.get_url("newInverterAPI.do"), params={ "op": "getInverterDetailData", "inverterId": inverter_id }) return response.json() def inverter_detail_two(self, inverter_id): """ Get detailed data from PV inverter (alternative endpoint). Args: inverter_id (str): The ID of the inverter. Returns: dict: A dictionary containing the inverter details. Raises: Exception: If the request to the server fails. """ response = self.session.get(self.get_url("newInverterAPI.do"), params={ "op": "getInverterDetailData_two", "inverterId": inverter_id }) return response.json() def tlx_system_status(self, plant_id, tlx_id): """ Get status of the system. Args: plant_id (str): The ID of the plant. tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing system status. Raises: Exception: If the request to the server fails. """ response = self.session.post( self.get_url("newTlxApi.do"), params={"op": "getSystemStatus_KW"}, data={"plantId": plant_id, "id": tlx_id} ) return response.json().get("obj", {}) def tlx_energy_overview(self, plant_id, tlx_id): """ Get energy overview. Args: plant_id (str): The ID of the plant. tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing energy data. Raises: Exception: If the request to the server fails. """ response = self.session.post( self.get_url("newTlxApi.do"), params={"op": "getEnergyOverview"}, data={"plantId": plant_id, "id": tlx_id} ) return response.json().get("obj", {}) def tlx_energy_prod_cons(self, plant_id, tlx_id, timespan=Timespan.hour, date=None): """ Get energy production and consumption (kW). Args: plant_id: The plant identifier. tlx_id: The ID of the TLX inverter. timespan: Timespan enum for the requested range. date: Date of interest. Returns: dict: A dictionary containing energy data. Raises: Exception: If the request to the server fails. """ date_str = self.__get_date_string(timespan, date) response = self.session.post( self.get_url("newTlxApi.do"), params={"op": "getEnergyProdAndCons_KW"}, data={"date": date_str, "plantId": plant_id, "language": "1", "id": tlx_id, "type": timespan.value} ) return response.json().get("obj", {}) def tlx_data(self, tlx_id, date=None): """ Get TLX inverter data for specified date or today. Args: tlx_id (str): The ID of the TLX inverter. date (datetime, optional): The date you are interested in. Defaults to datetime.datetime.now(). Returns: dict: A dictionary containing the TLX inverter data. Raises: Exception: If the request to the server fails. """ date_str = self.__get_date_string(date=date) response = self.session.get(self.get_url("newTlxApi.do"), params={ "op": "getTlxData", "id": tlx_id, "type": 1, "date": date_str }) return response.json() def tlx_detail(self, tlx_id): """ Get detailed data from TLX inverter. Args: tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing the detailed TLX inverter data. Raises: Exception: If the request to the server fails. """ response = self.session.get(self.get_url("newTlxApi.do"), params={ "op": "getTlxDetailData", "id": tlx_id }) return response.json() def tlx_params(self, tlx_id): """ Get parameters for TLX inverter. Args: tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing the TLX inverter parameters. Raises: Exception: If the request to the server fails. """ response = self.session.get(self.get_url("newTlxApi.do"), params={ "op": "getTlxParams", "id": tlx_id }) return response.json() def tlx_all_settings(self, tlx_id): """ Get all possible settings from TLX inverter. Args: tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing all possible settings for the TLX inverter. Raises: Exception: If the request to the server fails. """ response = self.session.post(self.get_url("newTlxApi.do"), params={ "op": "getTlxSetData" }, data={ "serialNum": tlx_id }) return response.json().get("obj", {}).get("tlxSetBean") def tlx_enabled_settings(self, tlx_id): """ Get "Enabled settings" from TLX inverter. Args: tlx_id (str): The ID of the TLX inverter. Returns: dict: A dictionary containing the enabled settings. Raises: Exception: If the request to the server fails. """ string_time = datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%d") response = self.session.post( self.get_url("newLoginAPI.do"), params={"op": "getSetPass"}, data={"deviceSn": tlx_id, "stringTime": string_time, "type": "5"} ) return response.json().get("obj", {}) def tlx_battery_info(self, serial_num): """ Get battery information. Args: serial_num (str): The serial number of the battery. Returns: dict: A dictionary containing the battery information. Raises: Exception: If the request to the server fails. """ response = self.session.post( self.get_url("newTlxApi.do"), params={"op": "getBatInfo"}, data={"lan": 1, "serialNum": serial_num} ) return response.json().get("obj", {}) def tlx_battery_info_detailed(self, plant_id, serial_num): """ Get detailed battery information. Args: plant_id (str): The ID of the plant. serial_num (str): The serial number of the battery. Returns: dict: A dictionary containing the detailed battery information. Raises: Exception: If the request to the server fails. """ response = self.session.post( self.get_url("newTlxApi.do"), params={"op": "getBatDetailData"}, data={"lan": 1, "plantId": plant_id, "id": serial_num} ) return response.json() def mix_info(self, mix_id, plant_id=None): """ Get high-level values from a Mix device. Args: mix_id: The device serial number. plant_id: Optional plant identifier. Returns: dict: 'acChargeEnergyToday' -- ??? 2.7 'acChargeEnergyTotal' -- ??? 25.3 'acChargePower' -- ??? 0 'capacity': '45' -- The current remaining capacity of the batteries (same as soc but without the % sign) 'eBatChargeToday' -- Battery charged today in kWh 'eBatChargeTotal' -- Battery charged total (all time) in kWh 'eBatDisChargeToday' -- Battery discharged today in kWh 'eBatDisChargeTotal' -- Battery discharged total (all time) in kWh 'epvToday' -- Energy generated from PVs today in kWh 'epvTotal' -- Energy generated from PVs total (all time) in kWh 'isCharge'-- ??? 0 - Possible a 0/1 based on whether or not the battery is charging 'pCharge1' -- ??? 0 'pDischarge1' -- Battery discharging rate in W 'soc' -- Statement of charge including % symbol 'upsPac1' -- ??? 0 'upsPac2' -- ??? 0 'upsPac3' -- ??? 0 'vbat' -- Battery Voltage 'vbatdsp' -- ??? 51.8 'vpv1' -- Voltage PV1 'vpv2' -- Voltage PV2 """ request_params = { "op": "getMixInfo", "mixId": mix_id } if (plant_id): request_params["plantId"] = plant_id response = self.session.get(self.get_url( "newMixApi.do"), params=request_params) return response.json().get("obj", {}) def mix_totals(self, mix_id, plant_id): """ Get totals values from a Mix device. Args: mix_id: The device serial number. plant_id: Plant identifier. Returns: dict: Totals response object. 'echargetoday' -- Battery charged today in kWh (same as eBatChargeToday from mix_info) 'echargetotal' -- Battery charged total (all time) in kWh (same as eBatChargeTotal from mix_info) 'edischarge1Today' -- Battery discharged today in kWh (same as eBatDisChargeToday from mix_info) 'edischarge1Total' -- Battery discharged total (all time) in kWh (same as eBatDisChargeTotal from mix_info) 'elocalLoadToday' -- Load consumption today in kWh 'elocalLoadTotal' -- Load consumption total (all time) in kWh 'epvToday' -- Energy generated from PVs today in kWh (same as epvToday from mix_info) 'epvTotal' -- Energy generated from PVs total (all time) in kWh (same as epvTotal from mix_info) 'etoGridToday' -- Energy exported to the grid today in kWh 'etogridTotal' -- Energy exported to the grid total (all time) in kWh 'photovoltaicRevenueToday' -- Revenue earned from PV today in 'unit' currency 'photovoltaicRevenueTotal' -- Revenue earned from PV total (all time) in 'unit' currency 'unit' -- Unit of currency for 'Revenue' """ response = self.session.post(self.get_url("newMixApi.do"), params={ "op": "getEnergyOverview", "mixId": mix_id, "plantId": plant_id }) return response.json().get("obj", {}) def mix_system_status(self, mix_id, plant_id): """ Get current status from a Mix device. Args: mix_id: The device serial number. plant_id: Plant identifier. Returns: dict: Status response object. 'SOC' -- Statement of charge (remaining battery %) 'chargePower' -- Battery charging rate in kw 'fAc' -- Frequency (Hz) 'lost' -- System status e.g. 'mix.status.normal' 'pLocalLoad' -- Load conumption in kW 'pPv1' -- PV1 Wattage in W 'pPv2' -- PV2 Wattage in W 'pactogrid' -- Export to grid rate in kW 'pactouser' -- Import from grid rate in kW 'pdisCharge1' -- Discharging batteries rate in kW 'pmax' -- ??? 6 ??? PV Maximum kW ?? 'ppv' -- PV combined Wattage in kW 'priorityChoose' -- Priority setting - 0=Local load 'status' -- System statue - ENUM - Unknown values 'unit' -- Unit of measurement e.g. 'kW' 'upsFac' -- ??? 0 'upsVac1' -- ??? 0 'uwSysWorkMode' -- ??? 6 'vAc1' -- Grid voltage in V 'vBat' -- Battery voltage in V 'vPv1' -- PV1 voltage in V 'vPv2' -- PV2 voltage in V 'vac1' -- Grid voltage in V (same as vAc1) 'wBatteryType' -- ??? 1 """ response = self.session.post(self.get_url("newMixApi.do"), params={ "op": "getSystemStatus_KW", "mixId": mix_id, "plantId": plant_id }) return response.json().get("obj", {}) def mix_detail(self, mix_id, plant_id, timespan=Timespan.hour, date=None): """ Get Mix details for the given timespan. Args: mix_id: Serial number (device_sn) of the inverter. plant_id: Plant identifier. timespan: Timespan enum for the requested range. date: Date of interest (defaults to now). Returns: dict: The response object containing mix details. A chartData object where each entry is for a specific 5 minute window e.g. 00:05 and 00:10 respectively (below) 'chartData': { '00:05': { 'pacToGrid' -- Export rate to grid in kW 'pacToUser' -- Import rate from grid in kW 'pdischarge' -- Battery discharge in kW 'ppv' -- Solar generation in kW 'sysOut' -- Load consumption in kW }, '00:10': { 'pacToGrid': '0', 'pacToUser': '0.93', 'pdischarge': '0', 'ppv': '0', 'sysOut': '0.93'}, ...... } 'eAcCharge' -- Exported to grid in kWh 'eCharge' -- System production in kWh = Self-consumption + Exported to Grid 'eChargeToday' -- Load consumption from solar in kWh 'eChargeToday1' -- Self-consumption in kWh 'eChargeToday2' -- Self-consumption in kWh (eChargeToday + echarge1) 'echarge1' -- Load consumption from battery in kWh 'echargeToat' -- Total battery discharged (all time) in kWh 'elocalLoad' -- Load consumption in kW (battery + solar + imported) 'etouser' -- Load consumption imported from grid in kWh 'photovoltaic' -- Load consumption from solar in kWh (same as eChargeToday) 'ratio1' -- % of system production that is self-consumed 'ratio2' -- % of system production that is exported 'ratio3' -- % of Load consumption that is "self consumption" 'ratio4' -- % of Load consumption that is "imported from grid" 'ratio5' -- % of Self consumption that is directly from Solar 'ratio6' -- % of Self consumption that is from batteries 'unit' -- Unit of measurement e.g kWh 'unit2' -- Unit of measurement e.g kW NOTE - It is possible to calculate the PV generation that went into charging the batteries by performing the following calculation: Solar to Battery = Solar Generation - Export to Grid - Load consumption from solar epvToday (from mix_info) - eAcCharge - eChargeToday """ date_str = self.__get_date_string(timespan, date) response = self.session.post( self.get_url("newMixApi.do"), params={ "op": "getEnergyProdAndCons_KW", "plantId": plant_id, "mixId": mix_id, "type": timespan.value, "date": date_str, }, ) return response.json().get("obj", {}) def get_mix_inverter_settings(self, serial_number): """ Get the inverter settings related to battery modes. Args: serial_number: -- The serial number (device_sn) of the inverter. Returns: dict: A dictionary of settings. """ default_params = { "op": "getMixSetParams", "serialNum": serial_number, "kind": 0 } response = self.session.get(self.get_url("newMixApi.do"), params=default_params) return response.json() def dashboard_data(self, plant_id, timespan=Timespan.hour, date=None): """ Get dashboard data for a plant over a timespan. Args: plant_id: Plant identifier. timespan: Timespan enum for the requested range. date: Date of interest (defaults to now). Returns: dict: Dashboard chart and summary data. A chartData object where each entry is for a specific 5 minute window e.g. 00:05 and 00:10 respectively (below) NOTE: The keys are interpreted differently, the examples below describe what they are used for in a 'Mix' system 'chartData': { '00:05': { 'pacToUser' -- Power from battery in kW 'ppv' -- Solar generation in kW 'sysOut' -- Load consumption in kW 'userLoad' -- Export in kW }, '00:10': { 'pacToUser': '0', 'ppv': '0', 'sysOut': '0.7', 'userLoad': '0'}, ...... } 'chartDataUnit' -- Unit of measurement e.g. 'kW', 'eAcCharge' -- Energy exported to the grid in kWh e.g. '20.5kWh' (not accurate for Mix systems) 'eCharge' -- System production in kWh = Self-consumption + Exported to Grid e.g '23.1kWh' (not accurate for Mix systems - actually showing the total 'load consumption' 'eChargeToday1' -- Self-consumption of PPV (possibly including excess diverted to batteries) in kWh e.g. '2.6kWh' (not accurate for Mix systems) 'eChargeToday2' -- Total self-consumption (PPV consumption(eChargeToday2Echarge1) + Battery Consumption(echarge1)) e.g. '10.1kWh' (not accurate for Mix systems) 'eChargeToday2Echarge1' -- Self-consumption of PPV only e.g. '0.8kWh' (not accurate for Mix systems) 'echarge1' -- Self-consumption from Battery only e.g. '9.3kWh' 'echargeToat' -- Not used on Dashboard view, likely to be total battery discharged e.g. '152.1kWh' 'elocalLoad' -- Total load consumption (etouser + eChargeToday2) e.g. '20.3kWh', (not accurate for Mix systems) 'etouser'-- Energy imported from grid today (includes both directly used by load and AC battery charging e.g. '10.2kWh' 'keyNames' -- Keys to be used for the graph data e.g. ['Solar', 'Load Consumption', 'Export To Grid', 'From Battery'] 'photovoltaic' -- Same as eChargeToday2Echarge1 e.g. '0.8kWh' 'ratio1' -- % of 'Solar production' that is self-consumed e.g. '11.3%' (not accurate for Mix systems) 'ratio2' -- % of 'Solar production' that is exported e.g. '88.7%' (not accurate for Mix systems) 'ratio3' -- % of 'Load consumption' that is self consumption e.g. '49.8%' (not accurate for Mix systems) 'ratio4' -- % of 'Load consumption' that is imported from the grid e.g '50.2%' (not accurate for Mix systems) 'ratio5' -- % of Self consumption that is from batteries e.g. '92.1%' (not accurate for Mix systems) 'ratio6' -- % of Self consumption that is directly from Solar e.g. '7.9%' (not accurate for Mix systems) NOTE: Does not return any data for a tlx system. Use plant_energy_data() instead. """ date_str = self.__get_date_string(timespan, date) response = self.session.post(self.get_url("newPlantAPI.do"), params={ "action": "getEnergyStorageData", "date": date_str, "type": timespan.value, "plantId": plant_id, }) return response.json() def plant_settings(self, plant_id): """ Get a dictionary containing the settings for the specified plant. Args: plant_id: The id of the plant you want the settings of Returns: dict: A python dictionary containing the settings for the specified plant. """ response = self.session.get(self.get_url("newPlantAPI.do"), params={ "op": "getPlant", "plantId": plant_id }) return response.json() def storage_detail(self, storage_id): """Get "All parameters" from battery storage.""" response = self.session.get(self.get_url("newStorageAPI.do"), params={ "op": "getStorageInfo_sacolar", "storageId": storage_id }) return response.json() def storage_params(self, storage_id): """Get much more detail from battery storage.""" response = self.session.get(self.get_url("newStorageAPI.do"), params={ "op": "getStorageParams_sacolar", "storageId": storage_id }) return response.json() def storage_energy_overview(self, plant_id, storage_id): """Get some energy/generation overview data.""" response = self.session.post(self.get_url("newStorageAPI.do?op=getEnergyOverviewData_sacolar"), params={ "plantId": plant_id, "storageSn": storage_id }) return response.json().get("obj", {}) def inverter_list(self, plant_id): """Use device_list, it's more descriptive since the list contains more than inverters.""" warnings.warn( "This function may be deprecated in the future because naming is not correct, use device_list instead", DeprecationWarning, stacklevel=2) return self.device_list(plant_id) def __get_all_devices(self, plant_id): """Get basic plant information with device list.""" response = self.session.get(self.get_url("newTwoPlantAPI.do"), params={"op": "getAllDeviceList", "plantId": plant_id, "language": 1}) return response.json().get("deviceList", {}) def device_list(self, plant_id): """Get a list of all devices connected to plant.""" device_list = self.plant_info(plant_id).get("deviceList", []) if not device_list: # for tlx systems, the device_list in plant is empty, so use __get_all_devices() instead device_list = self.__get_all_devices(plant_id) return device_list def plant_info(self, plant_id): """Get basic plant information with device list.""" response = self.session.get(self.get_url("newTwoPlantAPI.do"), params={ "op": "getAllDeviceListTwo", "plantId": plant_id, "pageNum": 1, "pageSize": 1 }) return response.json() def plant_energy_data(self, plant_id): """Get the energy data used in the 'Plant' tab in the phone.""" response = self.session.post(self.get_url("newTwoPlantAPI.do"), params={ "op": "getUserCenterEnertyDataByPlantid"}, data={"language": 1, "plantId": plant_id}) return response.json() def is_plant_noah_system(self, plant_id): """ Check whether a plant is a Noah system. Args: plant_id: The id of the plant. Returns: dict: API response indicating Noah configuration. 'msg' 'result' -- True or False 'obj' -- An Object containing if noah devices are configured 'isPlantNoahSystem' -- Is the specified plant a noah system (True or False) 'plantId' -- The ID of the plant 'isPlantHaveNoah' -- Are noah devices configured in the specified plant (True or False) 'deviceSn' -- Serial number of the configured noah device 'plantName' -- Friendly name of the plant """ response = self.session.post(self.get_url("noahDeviceApi/noah/isPlantNoahSystem"), data={ "plantId": plant_id }) return response.json() def noah_system_status(self, serial_number): """ Get the Noah device status. Args: serial_number: Noah device serial number. Returns: dict: Status response object. 'msg' 'result' -- True or False 'obj' -- An Object containing the noah device status 'chargePower' -- Battery charging rate in watt e.g. '200Watt' 'workMode' -- Workingmode of the battery (0 = Load First, 1 = Battery First) 'soc' -- Statement of charge (remaining battery %) 'associatedInvSn' -- ??? 'batteryNum' -- Numbers of batterys 'profitToday' -- Today generated profit through noah device 'plantId' -- The ID of the plant 'disChargePower' -- Battery discharging rate in watt e.g. '200Watt' 'eacTotal' -- Total energy exported to the grid in kWh e.g. '20.5kWh' 'eacToday' -- Today energy exported to the grid in kWh e.g. '20.5kWh' 'pac' -- Export to grid rate in watt e.g. '200Watt' 'ppv' -- Solar generation in watt e.g. '200Watt' 'alias' -- Friendly name of the noah device 'profitTotal' -- Total generated profit through noah device 'moneyUnit' -- Unit of currency e.g. '€' 'status' -- Is the noah device online (True or False) """ response = self.session.post(self.get_url("noahDeviceApi/noah/getSystemStatus"), data={ "deviceSn": serial_number }) return response.json() def noah_info(self, serial_number): """ Get detailed Noah device information. Args: serial_number: Noah device serial number. Returns: dict: Detailed Noah device info. 'msg' 'result' -- True or False 'obj' -- An Object containing the noah device informations 'neoList' -- A List containing Objects 'unitList' -- A Object containing currency units e.g. "Euro": "euro", "DOLLAR": "dollar" 'noah' -- A Object containing the folowing 'time_segment' -- A List containing Objects with configured "Operation Mode" NOTE: The keys are generated numerical, the values are generated with folowing syntax "[workingmode (0 = Load First, 1 = Battery First)]_[starttime]_[endtime]_[output power]" 'time_segment': { 'time_segment1': "0_0:0_8:0_150", ([Load First]_[00:00]_[08:00]_[150 watt]) 'time_segment2': "1_8:0_18:0_0", ([Battery First]_[08:00]_[18:00]_[0 watt]) .... } 'batSns' -- A List containing all battery Serial Numbers 'associatedInvSn' -- ??? 'plantId' -- The ID of the plant 'chargingSocHighLimit' -- Configured "Battery Management" charging upper limit 'chargingSocLowLimit' -- Configured "Battery Management" charging lower limit 'defaultPower' -- Configured "System Default Output Power" 'version' -- The Firmware Version of the noah device 'deviceSn' -- The Serial number of the noah device 'formulaMoney' -- Configured "Select Currency" energy cost per kWh e.g. '0.22' 'alias' -- Friendly name of the noah device 'model' -- Model Name of the noah device 'plantName' -- Friendly name of the plant 'tempType' -- ??? 'moneyUnitText' -- Configured "Select Currency" (Value from the unitList) e.G. "euro" 'plantList' -- A List containing Objects containing the folowing 'plantId' -- The ID of the plant 'plantImgName' -- Friendly name of the plant Image 'plantName' -- Friendly name of the plant """ response = self.session.post(self.get_url("noahDeviceApi/noah/getNoahInfoBySn"), data={ "deviceSn": serial_number }) return response.json() def update_plant_settings(self, plant_id, changed_settings, current_settings=None): """ Update plant settings. Args: plant_id: Plant identifier. changed_settings: Dict of settings to change. current_settings: Current settings dict or None. Returns: dict: Server response indicating success or failure. """ # If no existing settings have been provided then get them from the growatt server if current_settings is None: current_settings = self.plant_settings(plant_id) # These are the parameters that the form requires, without these an error is thrown. Pre-populate their values with the current values form_settings = { "plantCoal": (None, str(current_settings["formulaCoal"])), "plantSo2": (None, str(current_settings["formulaSo2"])), "accountName": (None, str(current_settings["userAccount"])), "plantID": (None, str(current_settings["id"])), # Hardcoded to 0 as I can't work out what value it should have "plantFirm": (None, "0"), "plantCountry": (None, str(current_settings["country"])), "plantType": (None, str(current_settings["plantType"])), "plantIncome": (None, str(current_settings["formulaMoneyStr"])), "plantAddress": (None, str(current_settings["plantAddress"])), "plantTimezone": (None, str(current_settings["timezone"])), "plantLng": (None, str(current_settings["plant_lng"])), "plantCity": (None, str(current_settings["city"])), "plantCo2": (None, str(current_settings["formulaCo2"])), "plantMoney": (None, str(current_settings["formulaMoneyUnitId"])), "plantPower": (None, str(current_settings["nominalPower"])), "plantLat": (None, str(current_settings["plant_lat"])), "plantDate": (None, str(current_settings["createDateText"])), "plantName": (None, str(current_settings["plantName"])), } # Overwrite the current value of the setting with the new value for setting, value in changed_settings.items(): form_settings[setting] = (None, str(value)) response = self.session.post(self.get_url( "newTwoPlantAPI.do?op=updatePlant"), files=form_settings) return response.json() def update_inverter_setting(self, serial_number, setting_type, default_parameters, parameters): """ Apply inverter settings. Args: serial_number: Serial number of the inverter. setting_type: Type of setting to configure. default_parameters: Default parameter mapping for the request. parameters: Parameters to send (dict or list). Returns: dict: Server response JSON. """ # Ensure declared but unused args are referenced to satisfy linters _ = serial_number _ = setting_type settings_parameters = parameters # If we've been passed an array then convert it into a dictionary if isinstance(parameters, list): settings_parameters = {} for index, param in enumerate(parameters, start=1): settings_parameters["param" + str(index)] = param settings_parameters = {**default_parameters, **settings_parameters} response = self.session.post(self.get_url("newTcpsetAPI.do"), params=settings_parameters) return response.json() def update_mix_inverter_setting(self, serial_number, setting_type, parameters): """ Set inverter parameters for a Mix inverter. Args: serial_number: Inverter serial number. setting_type: Setting type. parameters: Parameters to send. Returns: dict: Server response JSON. """ default_parameters = { "op": "mixSetApiNew", "serialNum": serial_number, "type": setting_type } return self.update_inverter_setting(serial_number, setting_type, default_parameters, parameters) def update_ac_inverter_setting(self, serial_number, setting_type, parameters): """ Set inverter parameters for an AC-coupled inverter. Args: serial_number: Inverter serial number. setting_type: Setting type. parameters: Parameters to send. Returns: dict: Server response JSON. """ default_parameters = { "op": "spaSetApi", "serialNum": serial_number, "type": setting_type } return self.update_inverter_setting(serial_number, setting_type, default_parameters, parameters) def update_tlx_inverter_time_segment(self, serial_number, segment_id, batt_mode, start_time, end_time, enabled): """ Update a TLX inverter time segment. Args: serial_number: Inverter serial number. segment_id: ID of the time segment. batt_mode: Battery mode. start_time: Segment start time (datetime.time). end_time: Segment end time (datetime.time). enabled: Whether the segment is enabled. Returns: dict: Server JSON response. """ params = { "op": "tlxSet" } data = { "serialNum": serial_number, "type": f"time_segment{segment_id}", "param1": batt_mode, "param2": start_time.strftime("%H"), "param3": start_time.strftime("%M"), "param4": end_time.strftime("%H"), "param5": end_time.strftime("%M"), "param6": "1" if enabled else "0" } response = self.session.post(self.get_url( "newTcpsetAPI.do"), params=params, data=data) result = response.json() if not result.get("success", False): msg = f"Failed to update TLX inverter time segment: {result.get('msg', 'Unknown error')}" raise GrowattV1ApiError(msg) return result def update_tlx_inverter_setting(self, serial_number, setting_type, parameter): """ Set parameters on a TLX inverter. Args: serial_number: Inverter serial number. setting_type: Setting type to configure. parameter: Parameter(s) to send (dict, list or single value). Returns: dict: Server JSON response. """ default_parameters = { "op": "tlxSet", "serialNum": serial_number, "type": setting_type } # If parameter is a single value, convert it to a dictionary if not isinstance(parameter, (dict, list)): parameter = {"param1": parameter} elif isinstance(parameter, list): parameter = {f"param{index+1}": param for index, param in enumerate(parameter)} return self.update_inverter_setting(serial_number, setting_type, default_parameters, parameter) def update_noah_settings(self, serial_number, setting_type, parameters): """ Apply settings for a Noah device. Args: serial_number: Noah device serial number. setting_type: Setting to be configured. parameters: Parameters to send (dict or list). Returns: dict: Server JSON response. """ default_parameters = { "serialNum": serial_number, "type": setting_type } settings_parameters = parameters # If we've been passed an array then convert it into a dictionary if isinstance(parameters, list): settings_parameters = {} for index, param in enumerate(parameters, start=1): settings_parameters["param" + str(index)] = param settings_parameters = {**default_parameters, **settings_parameters} response = self.session.post(self.get_url("noahDeviceApi/noah/set"), data=settings_parameters) return response.json() def update_classic_inverter_setting(self, default_parameters, parameters): """ Apply classic inverter settings. Args: default_parameters: Default parameters dict. parameters: Parameters to send (dict or list). Returns: dict: Server JSON response. """ settings_parameters = parameters # If we've been passed an array then convert it into a dictionary if isinstance(parameters, list): settings_parameters = {} for index, param in enumerate(parameters, start=1): settings_parameters["param" + str(index)] = param settings_parameters = {**default_parameters, **settings_parameters} response = self.session.post(self.get_url("tcpSet.do"), params=settings_parameters) return response.json() indykoning-PyPi_GrowattServer-0258b4e/growattServer/exceptions.py000066400000000000000000000027061514467344200254230ustar00rootroot00000000000000""" Exception classes for the growattServer library. Note that in addition to these custom exceptions, methods may also raise exceptions from the underlying requests library (requests.exceptions.RequestException and its subclasses) when network or HTTP errors occur. These are not wrapped and are passed through directly to the caller. Common requests exceptions to handle: - requests.exceptions.HTTPError: For HTTP error responses (4XX, 5XX) - requests.exceptions.ConnectionError: For network connection issues - requests.exceptions.Timeout: For request timeouts - requests.exceptions.RequestException: The base exception for all requests exceptions """ class GrowattError(Exception): """Base exception class for all Growatt API related errors.""" class GrowattParameterError(GrowattError): """Raised when invalid parameters are provided to API methods.""" class GrowattV1ApiError(GrowattError): """Raised when a Growatt V1 API request fails or returns an error.""" def __init__(self, message: str, error_code: int | None = None, error_msg: str | None = None) -> None: """ Initialize the GrowattV1ApiError. Args: message: Human readable error message. error_code: Optional numeric error code returned by the API. error_msg: Optional detailed error message from the API. """ super().__init__(message) self.error_code = error_code self.error_msg = error_msg indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/000077500000000000000000000000001514467344200250635ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/__init__.py000066400000000000000000000724261514467344200272070ustar00rootroot00000000000000"""OpenApi V1 extensions for Growatt API client.""" import platform import warnings from datetime import UTC, date, datetime from enum import Enum from growattServer import GrowattApi from growattServer.exceptions import GrowattV1ApiError from .devices import AbstractDevice, Min, Sph class DeviceType(Enum): """Enumeration of Growatt device types.""" INVERTER = 1 STORAGE = 2 OTHER = 3 MAX = 4 SPH = Sph.DEVICE_TYPE_ID # (MIX) SPA = 6 MIN = Min.DEVICE_TYPE_ID PCS = 8 HPS = 9 PBD = 10 class OpenApiV1(GrowattApi): """ Extended Growatt API client with V1 API support. This class extends the base GrowattApi class with methods for MIN and SPH devices using the public V1 API described here: https://www.showdoc.com.cn/262556420217021/0. """ def _create_user_agent(self) -> str: python_version = platform.python_version() system = platform.system() release = platform.release() machine = platform.machine() return f"Python/{python_version} ({system} {release}; {machine})" def __init__(self, token) -> None: """ Initialize the Growatt API client with V1 API support. Args: token (str): API token for authentication (required for V1 API access). """ # Initialize the base class super().__init__(agent_identifier=self._create_user_agent()) # Add V1 API specific properties self.api_url = f"{self.server_url}v1/" # Set up authentication for V1 API using the provided token self.session.headers.update({"token": token}) def process_response(self, response, operation_name="API operation"): """ Process API response and handle errors. Args: response (dict): The JSON response from the API operation_name (str): Name of the operation for error messages Returns: dict: The 'data' field from the response Raises: GrowattV1ApiError: If the API returns an error response """ if response.get("error_code", 1) != 0: msg = f"Error during {operation_name}" raise GrowattV1ApiError( msg, error_code=response.get("error_code"), error_msg=response.get("error_msg", "Unknown error") ) return response.get("data") def get_url(self, page): """Return the page URL for the v1 API.""" return self.api_url + page def plant_list(self): """ Get a list of all plants with detailed information. Returns: dict: A dictionary containing plants information with 'count' and 'plants' keys. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # Prepare request data request_data = { "page": "", "perpage": "", "search_type": "", "search_keyword": "" } # Make the request response = self.session.get( url=self.get_url("plant/list"), data=request_data ) return self.process_response(response.json(), "getting plant list") def plant_details(self, plant_id): """ Get basic information about a power station. Args: plant_id (int): Power Station ID Returns: dict: A dictionary containing the plant details. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ response = self.session.get( self.get_url("plant/details"), params={"plant_id": plant_id} ) return self.process_response(response.json(), "getting plant details") def plant_energy_overview(self, plant_id): """ Get an overview of a plant's energy data. Args: plant_id (int): Power Station ID Returns: dict: A dictionary containing the plant energy overview. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ response = self.session.get( self.get_url("plant/data"), params={"plant_id": plant_id} ) return self.process_response(response.json(), "getting plant energy overview") def plant_power_overview(self, plant_id: int, day: str | date | None = None) -> dict: """ Obtain power data of a certain power station. Get the frequency once every 5 minutes Args: plant_id (int): Power Station ID day (date): Date - defaults to today Returns: dict: A dictionary containing the plants power data. .. code-block:: python { 'count': int, # Total number of records 'powers': list[dict], # List of power data entries # Each entry in 'powers' is a dictionary with: # 'time': str, # Time of the power reading # 'power': float | None # Power value in Watts (can be None) }. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. API-Doc: https://www.showdoc.com.cn/262556420217021/1494062656174173 """ if day is None: day = datetime.now(UTC).date() response = self.session.get( self.get_url("plant/power"), params={ "plant_id": plant_id, "date": day, } ) return self.process_response(response.json(), "getting plant power overview") def plant_energy_history(self, plant_id, start_date=None, end_date=None, time_unit="day", page=None, perpage=None): """ Retrieve plant energy data for multiple days/months/years. Args: plant_id (int): Power Station ID start_date (date, optional): Start Date - defaults to today end_date (date, optional): End Date - defaults to today time_unit (str, optional): Time unit ('day', 'month', 'year') - defaults to 'day' page (int, optional): Page number - defaults to 1 perpage (int, optional): Number of items per page - defaults to 20, max 100 Returns: dict: A dictionary containing the plant energy history. Notes: - When time_unit is 'day', date interval cannot exceed 7 days - When time_unit is 'month', start date must be within same or previous year - When time_unit is 'year', date interval must not exceed 20 years Raises: GrowattParameterError: If date parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ max_day_interval = 7 max_year_interval = 20 if start_date is None and end_date is None: start_date = datetime.now(UTC).date() end_date = datetime.now(UTC).date() elif start_date is None: start_date = end_date elif end_date is None: end_date = start_date # Validate date ranges based on time_unit if time_unit == "day" and (end_date - start_date).days > max_day_interval: warnings.warn( "Date interval must not exceed 7 days in 'day' mode.", RuntimeWarning, stacklevel=2) elif time_unit == "month" and (end_date.year - start_date.year > 1): warnings.warn( "Start date must be within same or previous year in 'month' mode.", RuntimeWarning, stacklevel=2) elif time_unit == "year" and (end_date.year - start_date.year > max_year_interval): warnings.warn( "Date interval must not exceed 20 years in 'year' mode.", RuntimeWarning, stacklevel=2) response = self.session.get( self.get_url("plant/energy"), params={ "plant_id": plant_id, "start_date": start_date.strftime("%Y-%m-%d"), "end_date": end_date.strftime("%Y-%m-%d"), "time_unit": time_unit, "page": page, "perpage": perpage } ) return self.process_response(response.json(), "getting plant energy history") def device_list(self, plant_id): """ Get devices associated with plant. Note: returned "device_type" mappings: 1: inverter (including MAX) 2: storage 3: other 4: max (single MAX) 5: sph 6: spa 7: min (including TLX) 8: pcs 9: hps 10: pbd Args: plant_id (int): Power Station ID Returns: DeviceList e.g. { "data": { "count": 3, "devices": [ { "device_sn": "ZT00100001", "last_update_time": "2018-12-13 11:03:52", "model": "A0B0D0T0PFU1M3S4", "lost": True, "status": 0, "manufacturer": "Growatt", "device_id": 116, "datalogger_sn": "CRAZT00001", "type": 1 }, ] }, "error_code": 0, "error_msg": "" } """ response = self.session.get( url=self.get_url("device/list"), params={ "plant_id": plant_id, "page": "", "perpage": "", }, ) return self.process_response(response.json(), "getting device list") def get_device(self, device_sn: str, device_type: int) -> AbstractDevice|None: """Get the device class by serial number and device_type id.""" match device_type: case Sph.DEVICE_TYPE_ID: return Sph(self, device_sn) case Min.DEVICE_TYPE_ID: return Min(self, device_sn) case _: warnings.warn(f"Device for type id: {device_type} has not been implemented yet.", stacklevel=2) return None def min_detail(self, device_sn): """ Get detailed data for a MIN inverter. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter details. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).detail() def min_energy(self, device_sn): """ Get energy data for a MIN inverter. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter energy data. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).energy() def min_energy_history(self, device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None): """ Get MIN inverter data history. Args: device_sn (str): The ID of the MIN inverter. start_date (date, optional): Start date. Defaults to today. end_date (date, optional): End date. Defaults to today. timezone (str, optional): Timezone ID. page (int, optional): Page number. limit (int, optional): Results per page. Returns: dict: A dictionary containing the MIN inverter history data. Raises: GrowattParameterError: If date interval is invalid (exceeds 7 days). GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).energy_history(start_date, end_date, timezone, page, limit) def min_settings(self, device_sn): """ Get settings for a MIN inverter. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter settings. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).settings(device_sn) def min_read_parameter(self, device_sn, parameter_id, start_address=None, end_address=None): """ Read setting from MIN inverter. Args: device_sn (str): The ID of the TLX inverter. parameter_id (str): Parameter ID to read. Don't use start_address and end_address if this is set. start_address (int, optional): Register start address (for set_any_reg). Don't use parameter_id if this is set. end_address (int, optional): Register end address (for set_any_reg). Don't use parameter_id if this is set. Returns: dict: A dictionary containing the setting value. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).read_parameter(parameter_id, start_address, end_address) def min_write_parameter(self, device_sn, parameter_id, parameter_values=None): """ Set parameters on a MIN inverter. Args: device_sn (str): Serial number of the inverter parameter_id (str): Setting type to be configured parameter_values: Parameter values to be sent to the system. Can be a single string (for param1 only), a list of strings (for sequential params), or a dictionary mapping param positions to values Returns: dict: JSON response from the server Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).write_parameter(parameter_id, parameter_values) def min_write_time_segment(self, device_sn, segment_id, batt_mode, start_time, end_time, enabled=True): """ Set a time segment for a MIN inverter. Args: device_sn (str): The serial number of the inverter. segment_id (int): Time segment ID (1-9). batt_mode (int): 0=load priority, 1=battery priority, 2=grid priority. start_time (datetime.time): Start time for the segment. end_time (datetime.time): End time for the segment. enabled (bool): Whether this segment is enabled. Returns: dict: The server response. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).write_time_segment(segment_id, batt_mode, start_time, end_time, enabled) def min_read_time_segments(self, device_sn, settings_data=None): """ Read Time-of-Use (TOU) settings from a Growatt MIN/TLX inverter. Retrieves all 9 time segments from a Growatt MIN/TLX inverter and parses them into a structured format. Note that this function uses min_settings() internally to get the settings data, To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from min_settings(). Args: device_sn (str): The device serial number of the inverter settings_data (dict, optional): Settings data from min_settings call to avoid repeated API calls. Can be either the complete response or just the data portion. Returns: list: A list of dictionaries, each containing details for one time segment: - segment_id (int): The segment number (1-9) - batt_mode (int): 0=Load First, 1=Battery First, 2=Grid First - mode_name (str): String representation of the mode - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the segment is enabled Example: # Option 1: Make a single call tou_settings = api.min_read_time_segments("DEVICE_SERIAL_NUMBER") # Option 2: Reuse existing settings data settings_response = api.min_settings("DEVICE_SERIAL_NUMBER") tou_settings = api.min_read_time_segments("DEVICE_SERIAL_NUMBER", settings_response) Raises: GrowattV1ApiError: If the API request fails requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Min(self, device_sn).read_time_segments(settings_data) # SPH Device Methods (Device Type 5) def sph_detail(self, device_sn): """ Get detailed data for an SPH inverter. Args: device_sn (str): The serial number of the SPH inverter. Returns: dict: A dictionary containing the SPH inverter details. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).detail() def sph_energy(self, device_sn): """ Get energy data for an SPH inverter. Args: device_sn (str): The serial number of the SPH inverter. Returns: dict: A dictionary containing the SPH inverter energy data. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).energy() def sph_energy_history(self, device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None): """ Get SPH inverter data history. Args: device_sn (str): The ID of the SPH inverter. start_date (date, optional): Start date. Defaults to today. end_date (date, optional): End date. Defaults to today. timezone (str, optional): Timezone ID. page (int, optional): Page number. limit (int, optional): Results per page. Returns: dict: A dictionary containing the SPH inverter history data. Raises: GrowattParameterError: If date interval is invalid (exceeds 7 days). GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).energy_history(start_date, end_date, timezone, page, limit) def sph_read_parameter(self, device_sn, parameter_id=None, start_address=None, end_address=None): """ Read setting from SPH inverter. Args: device_sn (str): The ID of the SPH inverter. parameter_id (str, optional): Parameter ID to read. Don't use start_address and end_address if this is set. start_address (int, optional): Register start address (for set_any_reg). Don't use parameter_id if this is set. end_address (int, optional): Register end address (for set_any_reg). Don't use parameter_id if this is set. Returns: dict: A dictionary containing the setting value. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).read_parameter(parameter_id, start_address, end_address) def sph_write_parameter(self, device_sn, parameter_id, parameter_values=None): """ Set parameters on an SPH inverter. Args: device_sn (str): Serial number of the inverter parameter_id (str): Setting type to be configured parameter_values: Parameter values to be sent to the system. Can be a single string (for param1 only), a list of strings (for sequential params), or a dictionary mapping param positions to values Returns: dict: JSON response from the server Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).write_parameter(parameter_id, parameter_values) def sph_write_ac_charge_times(self, device_sn, charge_power, charge_stop_soc, mains_enabled, periods): """ Set AC charge time periods for an SPH inverter. Args: device_sn (str): The serial number of the inverter. charge_power (int): Charging power percentage (0-100). charge_stop_soc (int): Stop charging at this SOC percentage (0-100). mains_enabled (bool): Enable grid charging. periods (list): List of 3 period dicts, each with keys: - start_time (datetime.time): Start time for the period - end_time (datetime.time): End time for the period - enabled (bool): Whether this period is enabled Returns: dict: The server response. Example: from datetime import time api.sph_write_ac_charge_times( device_sn="ABC123", charge_power=100, charge_stop_soc=100, mains_enabled=True, periods=[ {"start_time": time(1, 0), "end_time": time(5, 0), "enabled": True}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, ] ) Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).write_ac_charge_times(charge_power, charge_stop_soc, mains_enabled, periods) def sph_write_ac_discharge_times(self, device_sn, discharge_power, discharge_stop_soc, periods): """ Set AC discharge time periods for an SPH inverter. Args: device_sn (str): The serial number of the inverter. discharge_power (int): Discharging power percentage (0-100). discharge_stop_soc (int): Stop discharging at this SOC percentage (0-100). periods (list): List of 3 period dicts, each with keys: - start_time (datetime.time): Start time for the period - end_time (datetime.time): End time for the period - enabled (bool): Whether this period is enabled Returns: dict: The server response. Example: from datetime import time api.sph_write_ac_discharge_times( device_sn="ABC123", discharge_power=100, discharge_stop_soc=10, periods=[ {"start_time": time(17, 0), "end_time": time(21, 0), "enabled": True}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, ] ) Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).write_ac_discharge_times(discharge_power, discharge_stop_soc, periods) def sph_read_ac_charge_times(self, device_sn, settings_data=None): """ Read AC charge time periods and settings from an SPH inverter. Retrieves all 3 AC charge time periods plus global charge settings (power, stop SOC, mains enabled) from an SPH inverter. Note that this function uses sph_detail() internally to get the settings data. To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from sph_detail(). Args: device_sn (str): The device serial number of the inverter. settings_data (dict, optional): Settings data from sph_detail call to avoid repeated API calls. Returns: dict: A dictionary containing: - charge_power (int): Charging power percentage (0-100) - charge_stop_soc (int): Stop charging at this SOC percentage (0-100) - mains_enabled (bool): Whether grid/mains charging is enabled - periods (list): List of 3 period dicts, each with: - period_id (int): The period number (1-3) - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the period is enabled Example: # Option 1: Fetch settings automatically charge_config = api.sph_read_ac_charge_times(device_sn="DEVICE_SERIAL_NUMBER") print(f"Charge power: {charge_config['charge_power']}%") print(f"Periods: {charge_config['periods']}") # Option 2: Reuse existing settings data settings_response = api.sph_detail("DEVICE_SERIAL_NUMBER") charge_config = api.sph_read_ac_charge_times(device_sn="DEVICE_SERIAL_NUMBER", settings_data=settings_response) Raises: GrowattParameterError: If neither device_sn nor settings_data is provided. GrowattV1ApiError: If the API request fails. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).read_ac_charge_times(settings_data) def sph_read_ac_discharge_times(self, device_sn, settings_data=None): """ Read AC discharge time periods and settings from an SPH inverter. Retrieves all 3 AC discharge time periods plus global discharge settings (power, stop SOC) from an SPH inverter. Note that this function uses sph_detail() internally to get the settings data. To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from sph_detail(). Args: device_sn (str, optional): The device serial number of the inverter. settings_data (dict, optional): Settings data from sph_detail call to avoid repeated API calls. Returns: dict: A dictionary containing: - discharge_power (int): Discharging power percentage (0-100) - discharge_stop_soc (int): Stop discharging at this SOC percentage (0-100) - periods (list): List of 3 period dicts, each with: - period_id (int): The period number (1-3) - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the period is enabled Example: # Option 1: Fetch settings automatically discharge_config = api.sph_read_ac_discharge_times(device_sn="DEVICE_SERIAL_NUMBER") print(f"Discharge power: {discharge_config['discharge_power']}%") print(f"Stop SOC: {discharge_config['discharge_stop_soc']}%") # Option 2: Reuse existing settings data settings_response = api.sph_detail("DEVICE_SERIAL_NUMBER") discharge_config = api.sph_read_ac_discharge_times(device_sn="DEVICE_SERIAL_NUMBER", settings_data=settings_response) Raises: GrowattParameterError: If neither device_sn nor settings_data is provided. GrowattV1ApiError: If the API request fails. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ return Sph(self, device_sn).read_ac_discharge_times(settings_data) indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/devices/000077500000000000000000000000001514467344200265055ustar00rootroot00000000000000indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/devices/__init__.py000066400000000000000000000002151514467344200306140ustar00rootroot00000000000000# noqa: D104 from .abstract_device import AbstractDevice # noqa: F401 from .min import Min # noqa: F401 from .sph import Sph # noqa: F401 indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/devices/abstract_device.py000066400000000000000000000035611514467344200322060ustar00rootroot00000000000000"""Abstract device file for centralising shared device logic.""" from typing import TYPE_CHECKING, TypedDict from growattServer.exceptions import GrowattParameterError if TYPE_CHECKING: from growattServer.open_api_v1 import OpenApiV1 class ReadParamResponse(TypedDict): """Response type for ReadParam endpoints.""" data: str error_code: str error_msg: str class AbstractDevice: """Abstract device type. Must not be used directly.""" def __init__(self, api: "OpenApiV1", device_sn: str) -> None: """ Initialize the device with the bare minimum being the device_sn. Args: api (OpenApiV1): API used for all API calls. device_sn (str): Device serial number used for all API calls. """ self.api = api self.device_sn = device_sn def validate_read_parameter_input(self, parameter_id: str | None, start_address: int | None, end_address: int | None): # noqa: ARG002 """ Validate read parameter input and throws an error if it is invalid. Args: parameter_id (str): Parameter ID to read. Don't use start_address and end_address if this is set. start_address (int, optional): Register start address (for set_any_reg). Don't use parameter_id if this is set. end_address (int, optional): Register end address (for set_any_reg). Don't use parameter_id if this is set. Raises: GrowattParameterError: If parameters are invalid. """ if parameter_id is None and start_address is None: raise GrowattParameterError( "specify either parameter_id or start_address/end_address") if parameter_id is not None and start_address is not None: raise GrowattParameterError( "specify either parameter_id or start_address/end_address - not both." ) indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/devices/min.py000066400000000000000000000360601514467344200276470ustar00rootroot00000000000000"""Min/TLX device file.""" from datetime import UTC, datetime, timedelta from typing import Any from growattServer.exceptions import GrowattParameterError from .abstract_device import AbstractDevice class Min(AbstractDevice): """Min/TLX device type.""" DEVICE_TYPE_ID = 7 def detail(self) -> dict: """ Get detailed data for a MIN inverter. See the API doc: https://www.showdoc.com.cn/262556420217021/6129816412127075. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter details. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ response = self.api.session.get( self.api.get_url("device/tlx/tlx_data_info"), params={ "device_sn": self.device_sn } ) return self.api.process_response(response.json(), "getting MIN inverter details") def energy(self) -> dict: """ Get energy data for a MIN inverter. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter energy data. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ response = self.api.session.post( url=self.api.get_url("device/tlx/tlx_last_data"), data={ "tlx_sn": self.device_sn, }, ) return self.api.process_response(response.json(), "getting MIN inverter energy data") def energy_history(self, start_date=None, end_date=None, timezone=None, page=None, limit=None) -> dict: """ Get MIN inverter data history. Args: device_sn (str): The ID of the MIN inverter. start_date (date, optional): Start date. Defaults to today. end_date (date, optional): End date. Defaults to today. timezone (str, optional): Timezone ID. page (int, optional): Page number. limit (int, optional): Results per page. Returns: dict: A dictionary containing the MIN inverter history data. Raises: GrowattParameterError: If date interval is invalid (exceeds 7 days). GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if start_date is None and end_date is None: start_date = datetime.now(UTC).date() end_date = datetime.now(UTC).date() elif start_date is None: start_date = end_date elif end_date is None: end_date = start_date # check interval validity if end_date - start_date > timedelta(days=7): raise GrowattParameterError("date interval must not exceed 7 days") response = self.api.session.post( url=self.api.get_url("device/tlx/tlx_data"), data={ "tlx_sn": self.device_sn, "start_date": start_date.strftime("%Y-%m-%d"), "end_date": end_date.strftime("%Y-%m-%d"), "timezone_id": timezone, "page": page, "perpage": limit, } ) return self.api.process_response(response.json(), "getting MIN inverter energy history") def settings(self) -> dict: """ Get settings for a MIN inverter. Args: device_sn (str): The serial number of the MIN inverter. Returns: dict: A dictionary containing the MIN inverter settings. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ response = self.api.session.get( self.api.get_url("device/tlx/tlx_set_info"), params={ "device_sn": self.device_sn } ) return self.api.process_response(response.json(), "getting MIN inverter settings") def read_parameter(self, parameter_id, start_address=None, end_address=None) -> dict: """ Read setting from MIN inverter. Args: device_sn (str): The ID of the TLX inverter. parameter_id (str): Parameter ID to read. Don't use start_address and end_address if this is set. start_address (int, optional): Register start address (for set_any_reg). Don't use parameter_id if this is set. end_address (int, optional): Register end address (for set_any_reg). Don't use parameter_id if this is set. Returns: dict: A dictionary containing the setting value. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ self.validate_read_parameter_input(parameter_id, start_address, end_address) if parameter_id is not None: # named parameter start_address = 0 end_address = 0 else: # using register-number mode parameter_id = "set_any_reg" if start_address is None: start_address = end_address if end_address is None: end_address = start_address response = self.api.session.post( self.api.get_url("readMinParam"), data={ "device_sn": self.device_sn, "paramId": parameter_id, "startAddr": start_address, "endAddr": end_address, } ) return self.api.process_response(response.json(), f"reading parameter {parameter_id}") def write_parameter(self, parameter_id, parameter_values=None) -> dict: """ Set parameters on a MIN inverter. Args: device_sn (str): Serial number of the inverter parameter_id (str): Setting type to be configured parameter_values: Parameter values to be sent to the system. Can be a single string (for param1 only), a list of strings (for sequential params), or a dictionary mapping param positions to values Returns: dict: JSON response from the server Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # Initialize all parameters as empty strings max_min_params = 19 parameters = dict.fromkeys(range(1, max_min_params + 1), "") # Process parameter values based on type if parameter_values is not None: if isinstance(parameter_values, (str, int, float, bool)): # Single value goes to param1 parameters[1] = str(parameter_values) elif isinstance(parameter_values, list): # List of values go to sequential params for i, value in enumerate(parameter_values, 1): if i <= max_min_params: # Only use up to max_min_params parameters parameters[i] = str(value) elif isinstance(parameter_values, dict): # Dict maps param positions to values for pos_raw, value in parameter_values.items(): pos = int(pos_raw) if not isinstance(pos_raw, int) else pos_raw if 1 <= pos <= max_min_params: # Validate parameter positions parameters[pos] = str(value) # IMPORTANT: Create a data dictionary with ALL parameters explicitly included request_data = { "tlx_sn": self.device_sn, "type": parameter_id } # Add all MIN parameters to the request for i in range(1, max_min_params + 1): request_data[f"param{i}"] = str(parameters[i]) # Send the request response = self.api.session.post( self.api.get_url("tlxSet"), data=request_data ) return self.api.process_response(response.json(), f"writing parameter {parameter_id}") def write_time_segment(self, segment_id, batt_mode, start_time, end_time, enabled=True) -> dict: """ Set a time segment for a MIN inverter. Args: device_sn (str): The serial number of the inverter. segment_id (int): Time segment ID (1-9). batt_mode (int): 0=load priority, 1=battery priority, 2=grid priority. start_time (datetime.time): Start time for the segment. end_time (datetime.time): End time for the segment. enabled (bool): Whether this segment is enabled. Returns: dict: The server response. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ max_min_params = 19 max_min_segments = 9 max_batt_mode = 2 if not 1 <= segment_id <= max_min_segments: msg = f"segment_id must be between 1 and {max_min_segments}" raise GrowattParameterError(msg) if not 0 <= batt_mode <= max_batt_mode: msg = f"batt_mode must be between 0 and {max_batt_mode}" raise GrowattParameterError(msg) # Initialize ALL 19 parameters as empty strings, not just the ones we need all_params = { "tlx_sn": self.device_sn, "type": f"time_segment{segment_id}" } # Add param1 through param19, setting the values we need all_params["param1"] = str(batt_mode) all_params["param2"] = str(start_time.hour) all_params["param3"] = str(start_time.minute) all_params["param4"] = str(end_time.hour) all_params["param5"] = str(end_time.minute) all_params["param6"] = "1" if enabled else "0" # Add empty strings for all unused parameters for i in range(7, max_min_params + 1): all_params[f"param{i}"] = "" # Send the request response = self.api.session.post( self.api.get_url("tlxSet"), data=all_params ) return self.api.process_response(response.json(), f"writing time segment {segment_id}") def read_time_segments(self, settings_data=None) -> list[dict[str, Any]]: """ Read Time-of-Use (TOU) settings from a Growatt MIN/TLX inverter. Retrieves all 9 time segments from a Growatt MIN/TLX inverter and parses them into a structured format. Note that this function uses min_settings() internally to get the settings data, To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from min_settings(). Args: device_sn (str): The device serial number of the inverter settings_data (dict, optional): Settings data from min_settings call to avoid repeated API calls. Can be either the complete response or just the data portion. Returns: list: A list of dictionaries, each containing details for one time segment: - segment_id (int): The segment number (1-9) - batt_mode (int): 0=Load First, 1=Battery First, 2=Grid First - mode_name (str): String representation of the mode - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the segment is enabled Example: # Option 1: Make a single call tou_settings = api.min_read_time_segments("DEVICE_SERIAL_NUMBER") # Option 2: Reuse existing settings data settings_response = api.min_settings("DEVICE_SERIAL_NUMBER") tou_settings = api.min_read_time_segments("DEVICE_SERIAL_NUMBER", settings_response) Raises: GrowattV1ApiError: If the API request fails requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # Process the settings data if settings_data is None: # Fetch settings if not provided settings_data = self.settings() # Define mode names mode_names = { 0: "Load First", 1: "Battery First", 2: "Grid First" } segments = [] # Process each time segment for i in range(1, 10): # Segments 1-9 # Get raw time values start_time_raw = settings_data.get(f"forcedTimeStart{i}", "0:0") end_time_raw = settings_data.get(f"forcedTimeStop{i}", "0:0") # Handle 'null' string values if start_time_raw == "null" or not start_time_raw: start_time_raw = "0:0" if end_time_raw == "null" or not end_time_raw: end_time_raw = "0:0" # Format times with leading zeros (HH:MM) try: start_parts = start_time_raw.split(":") start_hour = int(start_parts[0]) start_min = int(start_parts[1]) start_time = f"{start_hour:02d}:{start_min:02d}" except (ValueError, IndexError): start_time = "00:00" try: end_parts = end_time_raw.split(":") end_hour = int(end_parts[0]) end_min = int(end_parts[1]) end_time = f"{end_hour:02d}:{end_min:02d}" except (ValueError, IndexError): end_time = "00:00" # Get the mode value safely mode_raw = settings_data.get(f"time{i}Mode") if mode_raw == "null" or mode_raw is None: batt_mode = None else: try: batt_mode = int(mode_raw) except (ValueError, TypeError): batt_mode = None # Get the enabled status safely enabled_raw = settings_data.get(f"forcedStopSwitch{i}", 0) if enabled_raw == "null" or enabled_raw is None: enabled = False else: try: enabled = int(enabled_raw) == 1 except (ValueError, TypeError): enabled = False segment = { "segment_id": i, "batt_mode": batt_mode, "mode_name": mode_names.get(batt_mode, "Unknown"), "start_time": start_time, "end_time": end_time, "enabled": enabled } segments.append(segment) return segments indykoning-PyPi_GrowattServer-0258b4e/growattServer/open_api_v1/devices/sph.py000066400000000000000000000550561514467344200276640ustar00rootroot00000000000000"""SPH/MIX device file.""" from datetime import UTC, datetime, timedelta from growattServer.exceptions import GrowattParameterError from .abstract_device import AbstractDevice class Sph(AbstractDevice): """SPH/MIX device type.""" DEVICE_TYPE_ID = 5 def detail(self): """ Get detailed data for an SPH inverter. Args: device_sn (str): The serial number of the SPH inverter. Returns: dict: A dictionary containing the SPH inverter details. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # API: https://www.showdoc.com.cn/262556420217021/6129763571291058 response = self.api.session.get( self.api.get_url("device/mix/mix_data_info"), params={ "device_sn": self.device_sn } ) return self.api.process_response(response.json(), "getting SPH inverter details") def energy(self): """ Get energy data for an SPH inverter. Args: device_sn (str): The serial number of the SPH inverter. Returns: dict: A dictionary containing the SPH inverter energy data. Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # API: https://www.showdoc.com.cn/262556420217021/6129764475556048 response = self.api.session.post( url=self.api.get_url("device/mix/mix_last_data"), data={ "mix_sn": self.device_sn, }, ) return self.api.process_response(response.json(), "getting SPH inverter energy data") def energy_history(self, start_date=None, end_date=None, timezone=None, page=None, limit=None): """ Get SPH inverter data history. Args: device_sn (str): The ID of the SPH inverter. start_date (date, optional): Start date. Defaults to today. end_date (date, optional): End date. Defaults to today. timezone (str, optional): Timezone ID. page (int, optional): Page number. limit (int, optional): Results per page. Returns: dict: A dictionary containing the SPH inverter history data. Raises: GrowattParameterError: If date interval is invalid (exceeds 7 days). GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if start_date is None and end_date is None: start_date = datetime.now(UTC).date() end_date = datetime.now(UTC).date() elif start_date is None: start_date = end_date elif end_date is None: end_date = start_date # check interval validity if end_date - start_date > timedelta(days=7): raise GrowattParameterError("date interval must not exceed 7 days") # API: https://www.showdoc.com.cn/262556420217021/6129765461123058 response = self.api.session.post( url=self.api.get_url("device/mix/mix_data"), data={ "mix_sn": self.device_sn, "start_date": start_date.strftime("%Y-%m-%d"), "end_date": end_date.strftime("%Y-%m-%d"), "timezone_id": timezone, "page": page, "perpage": limit, } ) return self.api.process_response(response.json(), "getting SPH inverter energy history") def read_parameter(self, parameter_id=None, start_address=None, end_address=None): """ Read setting from SPH inverter. Args: device_sn (str): The ID of the SPH inverter. parameter_id (str, optional): Parameter ID to read. Don't use start_address and end_address if this is set. start_address (int, optional): Register start address (for set_any_reg). Don't use parameter_id if this is set. end_address (int, optional): Register end address (for set_any_reg). Don't use parameter_id if this is set. Returns: dict: A dictionary containing the setting value. Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if parameter_id is None and start_address is None: raise GrowattParameterError( "specify either parameter_id or start_address/end_address") if parameter_id is not None and start_address is not None: raise GrowattParameterError( "specify either parameter_id or start_address/end_address - not both." ) if parameter_id is not None: # named parameter start_address = 0 end_address = 0 else: # address range parameter_id = "set_any_reg" # API: https://www.showdoc.com.cn/262556420217021/6129766954561259 response = self.api.session.post( self.api.get_url("readMixParam"), data={ "device_sn": self.device_sn, "paramId": parameter_id, "startAddr": start_address, "endAddr": end_address } ) return self.api.process_response(response.json(), f"reading parameter {parameter_id}") def write_parameter(self, parameter_id, parameter_values=None): """ Set parameters on an SPH inverter. Args: device_sn (str): Serial number of the inverter parameter_id (str): Setting type to be configured parameter_values: Parameter values to be sent to the system. Can be a single string (for param1 only), a list of strings (for sequential params), or a dictionary mapping param positions to values Returns: dict: JSON response from the server Raises: GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ # Initialize all parameters as empty strings (API uses param1-param18) max_sph_params = 18 parameters = dict.fromkeys(range(1, max_sph_params + 1), "") # Process parameter values based on type if parameter_values is not None: if isinstance(parameter_values, (str, int, float, bool)): # Single value goes to param1 parameters[1] = str(parameter_values) elif isinstance(parameter_values, list): # List of values go to sequential params for i, value in enumerate(parameter_values, 1): if i <= max_sph_params: # Only use up to max_sph_params parameters parameters[i] = str(value) elif isinstance(parameter_values, dict): # Dict maps param positions to values for pos_raw, value in parameter_values.items(): pos = int(pos_raw) if not isinstance(pos_raw, int) else pos_raw if 1 <= pos <= max_sph_params: # Validate parameter positions parameters[pos] = str(value) # Create a data dictionary with ALL parameters explicitly included request_data = { "mix_sn": self.device_sn, "type": parameter_id } # Add all SPH parameters to the request for i in range(1, max_sph_params + 1): request_data[f"param{i}"] = str(parameters[i]) # API: https://www.showdoc.com.cn/262556420217021/6129761750718760 response = self.api.session.post( self.api.get_url("mixSet"), data=request_data ) return self.api.process_response(response.json(), f"writing parameter {parameter_id}") def write_ac_charge_times(self, charge_power, charge_stop_soc, mains_enabled, periods): """ Set AC charge time periods for an SPH inverter. Args: device_sn (str): The serial number of the inverter. charge_power (int): Charging power percentage (0-100). charge_stop_soc (int): Stop charging at this SOC percentage (0-100). mains_enabled (bool): Enable grid charging. periods (list): List of 3 period dicts, each with keys: - start_time (datetime.time): Start time for the period - end_time (datetime.time): End time for the period - enabled (bool): Whether this period is enabled Returns: dict: The server response. Example: from datetime import time api.sph_write_ac_charge_times( device_sn="ABC123", charge_power=100, charge_stop_soc=100, mains_enabled=True, periods=[ {"start_time": time(1, 0), "end_time": time(5, 0), "enabled": True}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, ] ) Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if not 0 <= charge_power <= 100: # noqa: PLR2004 raise GrowattParameterError("charge_power must be between 0 and 100") if not 0 <= charge_stop_soc <= 100: # noqa: PLR2004 raise GrowattParameterError("charge_stop_soc must be between 0 and 100") if len(periods) != 3: # noqa: PLR2004 raise GrowattParameterError("periods must contain exactly 3 period definitions") # Build request data request_data = { "mix_sn": self.device_sn, "type": "mix_ac_charge_time_period", "param1": str(charge_power), "param2": str(charge_stop_soc), "param3": "1" if mains_enabled else "0", } # Add period parameters (param4-18) for i, period in enumerate(periods): base = i * 5 + 4 request_data[f"param{base}"] = str(period["start_time"].hour) request_data[f"param{base + 1}"] = str(period["start_time"].minute) request_data[f"param{base + 2}"] = str(period["end_time"].hour) request_data[f"param{base + 3}"] = str(period["end_time"].minute) request_data[f"param{base + 4}"] = "1" if period["enabled"] else "0" # API: https://www.showdoc.com.cn/262556420217021/6129761750718760 response = self.api.session.post( self.api.get_url("mixSet"), data=request_data ) return self.api.process_response(response.json(), "writing AC charge time periods") def write_ac_discharge_times(self, discharge_power, discharge_stop_soc, periods): """ Set AC discharge time periods for an SPH inverter. Args: device_sn (str): The serial number of the inverter. discharge_power (int): Discharging power percentage (0-100). discharge_stop_soc (int): Stop discharging at this SOC percentage (0-100). periods (list): List of 3 period dicts, each with keys: - start_time (datetime.time): Start time for the period - end_time (datetime.time): End time for the period - enabled (bool): Whether this period is enabled Returns: dict: The server response. Example: from datetime import time api.sph_write_ac_discharge_times( device_sn="ABC123", discharge_power=100, discharge_stop_soc=10, periods=[ {"start_time": time(17, 0), "end_time": time(21, 0), "enabled": True}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, {"start_time": time(0, 0), "end_time": time(0, 0), "enabled": False}, ] ) Raises: GrowattParameterError: If parameters are invalid. GrowattV1ApiError: If the API returns an error response. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if not 0 <= discharge_power <= 100: # noqa: PLR2004 raise GrowattParameterError("discharge_power must be between 0 and 100") if not 0 <= discharge_stop_soc <= 100: # noqa: PLR2004 raise GrowattParameterError("discharge_stop_soc must be between 0 and 100") if len(periods) != 3: # noqa: PLR2004 raise GrowattParameterError("periods must contain exactly 3 period definitions") # Build request data request_data = { "mix_sn": self.device_sn, "type": "mix_ac_discharge_time_period", "param1": str(discharge_power), "param2": str(discharge_stop_soc), } # Add period parameters (param3-17) for i, period in enumerate(periods): base = i * 5 + 3 request_data[f"param{base}"] = str(period["start_time"].hour) request_data[f"param{base + 1}"] = str(period["start_time"].minute) request_data[f"param{base + 2}"] = str(period["end_time"].hour) request_data[f"param{base + 3}"] = str(period["end_time"].minute) request_data[f"param{base + 4}"] = "1" if period["enabled"] else "0" # API: https://www.showdoc.com.cn/262556420217021/6129761750718760 response = self.api.session.post( self.api.get_url("mixSet"), data=request_data ) return self.api.process_response(response.json(), "writing AC discharge time periods") def _parse_time_periods(self, settings_data, time_type): """ Parse time periods from settings data. Internal helper method to extract and format time period data from SPH settings. Args: settings_data (dict): Settings data from sph_detail call. time_type (str): Either "Charge" or "Discharge" to specify which periods to parse. Returns: list: A list of dictionaries, each containing details for one time period: - period_id (int): The period number (1-3) - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the period is enabled """ periods = [] # Process each time period (1-3 for SPH) for i in range(1, 4): # Get raw time values start_time_raw = settings_data.get(f"forced{time_type}TimeStart{i}", "0:0") end_time_raw = settings_data.get(f"forced{time_type}TimeStop{i}", "0:0") enabled_raw = settings_data.get(f"forced{time_type}StopSwitch{i}", 0) # Handle 'null' string values if start_time_raw == "null" or not start_time_raw: start_time_raw = "0:0" if end_time_raw == "null" or not end_time_raw: end_time_raw = "0:0" # Format times with leading zeros (HH:MM) try: start_parts = start_time_raw.split(":") start_hour = int(start_parts[0]) start_min = int(start_parts[1]) start_time = f"{start_hour:02d}:{start_min:02d}" except (ValueError, IndexError): start_time = "00:00" try: end_parts = end_time_raw.split(":") end_hour = int(end_parts[0]) end_min = int(end_parts[1]) end_time = f"{end_hour:02d}:{end_min:02d}" except (ValueError, IndexError): end_time = "00:00" # Get the enabled status if enabled_raw == "null" or enabled_raw is None: enabled = False else: try: enabled = int(enabled_raw) == 1 except (ValueError, TypeError): enabled = False period = { "period_id": i, "start_time": start_time, "end_time": end_time, "enabled": enabled } periods.append(period) return periods def read_ac_charge_times(self, settings_data=None): """ Read AC charge time periods and settings from an SPH inverter. Retrieves all 3 AC charge time periods plus global charge settings (power, stop SOC, mains enabled) from an SPH inverter. Note that this function uses sph_detail() internally to get the settings data. To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from sph_detail(). Args: device_sn (str): The device serial number of the inverter. settings_data (dict, optional): Settings data from sph_detail call to avoid repeated API calls. Returns: dict: A dictionary containing: - charge_power (int): Charging power percentage (0-100) - charge_stop_soc (int): Stop charging at this SOC percentage (0-100) - mains_enabled (bool): Whether grid/mains charging is enabled - periods (list): List of 3 period dicts, each with: - period_id (int): The period number (1-3) - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the period is enabled Example: # Option 1: Fetch settings automatically charge_config = api.sph_read_ac_charge_times(device_sn="DEVICE_SERIAL_NUMBER") print(f"Charge power: {charge_config['charge_power']}%") print(f"Periods: {charge_config['periods']}") # Option 2: Reuse existing settings data settings_response = api.sph_detail("DEVICE_SERIAL_NUMBER") charge_config = api.sph_read_ac_charge_times(device_sn="DEVICE_SERIAL_NUMBER", settings_data=settings_response) Raises: GrowattParameterError: If neither device_sn nor settings_data is provided. GrowattV1ApiError: If the API request fails. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if settings_data is None: settings_data = self.detail() # Extract global charge settings charge_power = settings_data.get("chargePowerCommand", 0) charge_stop_soc = settings_data.get("wchargeSOCLowLimit", 100) mains_enabled_raw = settings_data.get("acChargeEnable", 0) # Handle null/empty values if charge_power == "null" or charge_power is None or charge_power == "": charge_power = 0 if charge_stop_soc == "null" or charge_stop_soc is None or charge_stop_soc == "": charge_stop_soc = 100 if mains_enabled_raw == "null" or mains_enabled_raw is None or mains_enabled_raw == "": mains_enabled = False else: mains_enabled = int(mains_enabled_raw) == 1 return { "charge_power": int(charge_power), "charge_stop_soc": int(charge_stop_soc), "mains_enabled": mains_enabled, "periods": self._parse_time_periods(settings_data, "Charge") } def read_ac_discharge_times(self, settings_data=None): """ Read AC discharge time periods and settings from an SPH inverter. Retrieves all 3 AC discharge time periods plus global discharge settings (power, stop SOC) from an SPH inverter. Note that this function uses sph_detail() internally to get the settings data. To avoid endpoint rate limit, you can pass the settings_data parameter with the data returned from sph_detail(). Args: device_sn (str, optional): The device serial number of the inverter. settings_data (dict, optional): Settings data from sph_detail call to avoid repeated API calls. Returns: dict: A dictionary containing: - discharge_power (int): Discharging power percentage (0-100) - discharge_stop_soc (int): Stop discharging at this SOC percentage (0-100) - periods (list): List of 3 period dicts, each with: - period_id (int): The period number (1-3) - start_time (str): Start time in format "HH:MM" - end_time (str): End time in format "HH:MM" - enabled (bool): Whether the period is enabled Example: # Option 1: Fetch settings automatically discharge_config = api.sph_read_ac_discharge_times(device_sn="DEVICE_SERIAL_NUMBER") print(f"Discharge power: {discharge_config['discharge_power']}%") print(f"Stop SOC: {discharge_config['discharge_stop_soc']}%") # Option 2: Reuse existing settings data settings_response = api.sph_detail("DEVICE_SERIAL_NUMBER") discharge_config = api.sph_read_ac_discharge_times(device_sn="DEVICE_SERIAL_NUMBER", settings_data=settings_response) Raises: GrowattParameterError: If neither device_sn nor settings_data is provided. GrowattV1ApiError: If the API request fails. requests.exceptions.RequestException: If there is an issue with the HTTP request. """ if settings_data is None: settings_data = self.detail() # Extract global discharge settings discharge_power = settings_data.get("disChargePowerCommand", 0) discharge_stop_soc = settings_data.get("wdisChargeSOCLowLimit", 10) # Handle null/empty values if discharge_power == "null" or discharge_power is None or discharge_power == "": discharge_power = 0 if discharge_stop_soc == "null" or discharge_stop_soc is None or discharge_stop_soc == "": discharge_stop_soc = 10 return { "discharge_power": int(discharge_power), "discharge_stop_soc": int(discharge_stop_soc), "periods": self._parse_time_periods(settings_data, "Discharge") } indykoning-PyPi_GrowattServer-0258b4e/setup.py000077500000000000000000000014161514467344200215240ustar00rootroot00000000000000 """Setup metadata for the growattServer package.""" from pathlib import Path import setuptools long_description = Path("README.md").read_text(encoding="utf8") setuptools.setup( name="growattServer", version="2.0.0", author="IndyKoning", author_email="indykoningnl@gmail.com", description="A package to talk to growatt server", license="MIT", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/indykoning/PyPi_GrowattServer", packages=setuptools.find_packages(), classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ], install_requires=[ "requests", ], )