Skip to content

Commit 63b376c

Browse files
indykoningindykoning
committed
Added docs
1 parent a04ff93 commit 63b376c

4 files changed

Lines changed: 114 additions & 2 deletions

File tree

‎docs/openapiv1.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This version of the API follows the newer [OpenAPI V1 API](https://www.showdoc.com.cn/262556420217021/0) Growatt has made available.
44

5-
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.
5+
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.
66

77
## Usage
88

@@ -33,6 +33,36 @@ Methods that work across all device types.
3333
| `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. |
3434
| `api.device_list(plant_id)` | plant_id: String | Get a list of devices in specified plant. |
3535

36+
#### Devices
37+
38+
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.
39+
40+
```python
41+
import growattServer
42+
from growattServer.open_api_v1.devices import Sph, Min
43+
44+
api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
45+
46+
my_inverter = Sph(api, 'YOUR_DEVICE_SERIAL_NUMBER') # or Min(api, 'YOUR_DEVICE_SERIAL_NUMBER')
47+
my_inverter.detail()
48+
my_inverter.energy()
49+
my_inverter.energy_history()
50+
my_inverter.read_parameter()
51+
my_inverter.write_parameter()
52+
```
53+
54+
| Method | Arguments | Description |
55+
|:---|:---|:---|
56+
| `device.energy()` | None | Get current energy data for any inverter, including power and energy values. |
57+
| `device.detail()` | None | Get detailed data for any inverter. |
58+
| `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). |
59+
| `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. |
60+
| `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. |
61+
62+
For more details see: [OpenApiV1 Devices](./openapiv1/devices.md)
63+
64+
The remaining methods below all actually use these device methods.
65+
3666
#### MIN Methods
3767

3868
Methods for MIN devices (type 7).
@@ -73,7 +103,7 @@ Convenience methods that wrap the core SPH methods above for common use cases.
73103

74104
#### Classic methods
75105

76-
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.
106+
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.
77107

78108
### Variables
79109

‎docs/openapiv1/devices.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# OpenAPI V1 - Devices
2+
3+
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.
4+
5+
```python
6+
import growattServer
7+
from growattServer.open_api_v1.devices import Sph, Min
8+
9+
api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
10+
11+
device = Sph(api, 'YOUR_DEVICE_SERIAL_NUMBER') # or Min(api, 'YOUR_DEVICE_SERIAL_NUMBER')
12+
device.detail()
13+
device.energy()
14+
device.energy_history()
15+
device.read_parameter()
16+
device.write_parameter()
17+
```
18+
19+
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
20+
21+
```
22+
import growattServer
23+
24+
api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
25+
device = api.get_device(device_sn, device_type)
26+
if device is not None:
27+
device.detail()
28+
device.energy()
29+
device.energy_history()
30+
device.read_parameter()
31+
device.write_parameter()
32+
```
33+
34+
The basic methods are described here
35+
36+
| Method | Arguments | Description |
37+
|:---|:---|:---|
38+
| `device.energy()` | None | Get current energy data for any inverter, including power and energy values. |
39+
| `device.detail()` | None | Get detailed data for any inverter. |
40+
| `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). |
41+
| `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. |
42+
| `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. |
43+
44+
However some device classes harbor more methods, which will be described in their respective readmes:
45+
- [SPH/MIX](./devices/sph.md)
46+
- [Min/TLX](./devices/min.md)

‎docs/openapiv1/devices/min.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# OpenAPI V1 - Min/TLX Device (device type 7)
2+
3+
The Min device offers the following methods
4+
5+
| Method | Arguments | Description |
6+
|:---|:---|:---|
7+
| `device.energy()` | None | Get current energy data for a min inverter, including power and energy values. |
8+
| `device.detail()` | None | Get detailed data for a min inverter. |
9+
| `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). |
10+
| `device.settings()` | None | Get all settings for a min inverter. |
11+
| `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) |
12+
| `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) |
13+
| `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) |
14+
| `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‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# OpenAPI V1 - SPH/MIX Device (device type 5)
2+
3+
The SPH device offers the following methods
4+
5+
| Method | Arguments | Description |
6+
|:---|:---|:---|
7+
| `device.detail()` | None | Get detailed data and settings for an SPH hybrid inverter. see: [details](../sph_settings.md) |
8+
| `device.energy()` | None | Get current energy data for an SPH inverter, including power and energy values. |
9+
| `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). |
10+
| `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) |
11+
| `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) |
12+
13+
#### SPH Helper Methods
14+
15+
Convenience methods that wrap the core SPH methods above for common use cases.
16+
17+
| Method | Arguments | Description |
18+
|:---|:---|:---|
19+
| `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) |
20+
| `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) |
21+
| `device.read_ac_charge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses charge config from `sph_detail()` response. see: [details](../sph_settings.md) |
22+
| `device.read_ac_discharge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses discharge config from `sph_detail()` response. see: [details](../sph_settings.md) |

0 commit comments

Comments
 (0)