Migrate V1 devices to their own folder (#131)

Co-authored-by: steinmn <46349253+steinmn@users.noreply.github.com>

Author: indykoning

.ruff.toml

@@ -23,6 +23,7 @@ ignore = [
     "T201", # Prints are allowed in examples
     "PLR0913",
     "FBT002",
+    "N999",
 ]
 
 [lint.flake8-pytest-style]

docs/openapiv1.md

@@ -2,7 +2,7 @@
 
 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 functions described in this file where possible.
+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
 
@@ -33,6 +33,36 @@ Methods that work across all device types.
 | `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).
@@ -68,12 +98,12 @@ Convenience methods that wrap the core SPH methods above for common use cases.
 |:---|:---|:---|
 | `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 (optional), 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 (optional), settings_data (optional) | Helper: parses discharge config from `sph_detail()` response. 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 functions described in this section where possible. There is no guarantee that the classic API methods will work, or remain stable through updates.
+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
 

docs/openapiv1/devices.md

@@ -0,0 +1,46 @@
+# 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)

docs/openapiv1/devices/min.md

@@ -0,0 +1,14 @@
+# 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) |

docs/openapiv1/devices/sph.md

@@ -0,0 +1,22 @@
+# 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) |

docs/openapiv1/sph_settings.md

@@ -184,7 +184,7 @@ For SPH (hybrid inverter) systems, the public V1 API provides methods to read an
 ### Read: `api.sph_read_ac_charge_times`
 
 * parameters:
-  * `device_sn`: The device serial number (not used if settings_data is provided)
+  * `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

examples/sph_example.py

@@ -76,6 +76,7 @@
 
             # 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:")
@@ -86,6 +87,7 @@
 
             # 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:")

growattServer/__init__.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """growattServer package exports."""
 
-# ruff: noqa: N999
 from .base_api import GrowattApi, Timespan, hash_password
 from .exceptions import GrowattError, GrowattParameterError, GrowattV1ApiError
 from .open_api_v1 import DeviceType, OpenApiV1