Skip to content

Commit d97adf6

Browse files
kellerzakellerza
committed
availability
1 parent ae36c15 commit d97adf6

47 files changed

Lines changed: 1353 additions & 566 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/rules/sunsynk-addons.mdc‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
description: Sunsynk HA add-ons — edit edge only; multi is CI/release; options docs workflow
3+
globs:
4+
- hass-addon-sunsynk-*/**
5+
- src/ha_addon_sunsynk_multi/**
6+
- www/docs/reference/multi-options.md
7+
alwaysApply: true
8+
---
9+
10+
# Sunsynk Home Assistant add-ons
11+
12+
## Editing policy (agents)
13+
14+
**Do not** create, edit, delete, or move files under **`hass-addon-sunsynk-multi/`** unless the user **explicitly** asks for
15+
stable-multi work (e.g. “sync multi”, “release prep”, “fix CI output in multi”, “cherry-pick to stable addon”). Normal
16+
tasks — config, schema, translations, Dockerfile, run scripts, CHANGELOG in the add-on folder — **must only be proposed
17+
under `hass-addon-sunsynk-edge/`**.
18+
19+
If the user has **`hass-addon-sunsynk-multi/**`** open or asks for a change that would touch multi, **redirect**: apply the
20+
same change under **`hass-addon-sunsynk-edge/`** (or `src/` / docs as below) and state that multi is updated by **CI when
21+
a GitHub tag is pushed**.
22+
23+
## Repository layout
24+
25+
- **`hass-addon-sunsynk-edge`** — **Development add-on.** All manual add-on packaging work happens here (`config.yaml`,
26+
`schema`, `translations/`, Docker/run scripts).
27+
28+
- **`hass-addon-sunsynk-multi`** — **Stable / release add-on.** **CI-maintained** for routine changes; do not hand-edit
29+
as part of feature work.
30+
31+
- **`src/ha_addon_sunsynk_multi`** — **Add-on Python** used in the Docker build. Implement behaviour here; it ships with
32+
edge builds immediately and is what the multi image is built from on release (no second code path).
33+
34+
## Supervisor options (documentation workflow)
35+
36+
When you add or change a **Supervisor option**, keep these in sync — **using edge for packaging strings**:
37+
38+
### 1. Home Assistant UI (`translations/en.yaml`)
39+
40+
- Add or update **`hass-addon-sunsynk-edge/translations/en.yaml`** only (short `name` / `description` for the Supervisor
41+
UI).
42+
- **Do not** update `hass-addon-sunsynk-multi/translations/` unless the user explicitly requests stable-multi sync; CI /
43+
release flow is expected to align multi with edge.
44+
45+
### 2. Reference docs (`www/docs/reference/multi-options.md`)
46+
47+
- Document every user-facing option; this page is built into the **VitePress** site. Use the same `OPTION_KEY` as in
48+
`config.yaml` (uppercase with underscores).
49+
50+
**Dev / edge only:** if the option exists **only** in `hass-addon-sunsynk-edge/config.yaml` (not yet in multi’s
51+
`config.yaml`), prefix the bullet in `multi-options.md` with:
52+
53+
```markdown
54+
- <i-mdi-dev-to class="vp-edge-option-icon" /> `YOUR_OPTION` – …
55+
```
56+
57+
**After release:** when CI adds the option to **`hass-addon-sunsynk-multi/config.yaml`**, remove that icon prefix and any
58+
“edge only” wording for that option (edits to **`multi-options.md`** are fine; still avoid hand-editing multi **addon**
59+
files unless the user asked).
60+
61+
### 3. Python (`src/ha_addon_sunsynk_multi/options.py`)
62+
63+
- Add or update `Options` / `InverterOptions` fields so YAML/env loading matches the edge schema (uppercase keys map to
64+
lowercase attributes via `mqtt_entity`).

‎.github/ISSUE_TEMPLATE/addon.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ A clear and concise description of what the bug is.
1818

1919
### Your environment
2020

21-
- Home Assistant version: 2025.1.x
21+
- Home Assistant version: 2026.1.x
2222
- Addon:
2323
- Name: sunsynk-multi
24-
- Version: 2025-01-11
24+
- Version: 2026-01-11
2525
- Inverter:
2626
- Make: Sunsynk/Deye/Sol-Ark/...
2727
- Model: \_\_
@@ -30,18 +30,21 @@ A clear and concise description of what the bug is.
3030
- RS485/RS232/solarman
3131
- RS485/RS232 brand
3232

33-
### You configuration
33+
### Your configuration
3434

35-
```yaml
36-
37-
paste config in the block surrounded by 3x backticks
35+
Paste your add-on YAML **between** the two lines below (replace the placeholder line). Keep the
36+
first line (three backticks and `yaml`) and the last line (three backticks only) so GitHub formats
37+
it as a code block.
3838

39+
```yaml
40+
# replace this line with your full configuration
3941
```
4042

4143
### Logs
4244

43-
```logs
44-
45-
paste logs in 3x backticks...
45+
Same idea for logs: paste between the fences (replace the placeholder). Use the most recent lines
46+
that show the error.
4647

48+
```text
49+
# replace this line with relevant log lines
4750
```

‎.github/ISSUE_TEMPLATE/sensor.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ assignees: ''
88
---
99

1010
Existing sensor definitions can be found
11-
[sunsynk/definitions](https://github.com/kellerza/sunsynk/blob/main/src/sunsynk/definitions/). You can test your own
12-
definitions using [custom sensors](https://kellerza.github.io/sunsynk/reference/mysensors)
11+
[sunsynk/definitions](https://github.com/kellerza/sunsynk/blob/main/src/sunsynk/definitions/). You
12+
can test your own definitions using
13+
[custom sensors](https://kellerza.github.io/sunsynk/reference/mysensors)
1314

1415
## Your environment
1516

‎.vscode/extensions.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
{
22
"recommendations": [
3-
"davidanson.vscode-markdownlint",
4-
"marvhen.reflow-markdown",
5-
"yzhang.markdown-all-in-one"
3+
"charliermarsh.ruff",
4+
"zuban.zubanls",
5+
"biomejs.biome",
6+
"rvben.rumdl"
67
]
78
}

‎.vscode/settings.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@
1010
"umodbus"
1111
],
1212
"cSpell.ignoreRandomStrings": true,
13-
"reflowMarkdown.preferredLineLength": 100,
14-
"reflowMarkdown.wrapLongLinks": "wrap"
13+
"python-envs.defaultEnvManager": "ms-python.python:venv",
14+
"python-envs.pythonProjects": []
1515
}

‎README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Deye/Sunsynk Inverters
22

3-
This repo enables access to Deye Hybrid Inverters & Deye branded inverters like Sunsynk through a Python 3 library. It
4-
also provides an Add-On that can be installed in the Home Assistant OS.
3+
This repo enables access to Deye Hybrid Inverters & Deye branded inverters like Sunsynk through a
4+
Python 3 library. It also provides an Add-On that can be installed in the Home Assistant OS.
55

66
This code was developed on a [Sunsynk](https://www.sunsynk.org/) 5.5 kWh inverter.
77

@@ -13,9 +13,10 @@ Refer to [https://kellerza.github.io/sunsynk/](https://kellerza.github.io/sunsyn
1313

1414
## Home Assistant Sunsynk Add-On
1515

16-
For the Add-On you require Home Assistant OS and a RS-485 adaptor to connect to your Sunsynk inverter. Sensors are read
17-
using the Modbus protocol and sent to a MQTT server. See
18-
[deployment options](https://kellerza.github.io/sunsynk/guide/deployment-options) for examples of tested hardware.
16+
For the Add-On you require Home Assistant OS and a RS-485 adaptor to connect to your Sunsynk
17+
inverter. Sensors are read using the Modbus protocol and sent to a MQTT server. See
18+
[deployment options](https://kellerza.github.io/sunsynk/guide/deployment-options) for examples of
19+
tested hardware.
1920

2021
### Installation
2122

‎hass-addon-mbusd/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Modbus TCP to Modbus RTU Gateway Add-on
22

3-
This Add-on uses the [mbusd](https://github.com/3cky/mbusd) gateway. It provides a TCP-Slave (or server) which acts as a
4-
RTU-master to get data from Modbus RTU-slave devices.
3+
This Add-on uses the [mbusd](https://github.com/3cky/mbusd) gateway. It provides a TCP-Slave (or
4+
server) which acts as a RTU-master to get data from Modbus RTU-slave devices.
55

6-
I use this mainly for testing, but mbusd can also be deployed on a low-spec device (i.e. Raspberry Pi 1b) to convert an
7-
RS-485 connection to TCP.
6+
I use this mainly for testing, but mbusd can also be deployed on a low-spec device (i.e. Raspberry
7+
Pi 1b) to convert an RS-485 connection to TCP.
88

99
## Configuration
1010

‎hass-addon-sunsynk-edge/config.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ options:
3535
MANUFACTURER: Sunsynk
3636
READ_ALLOW_GAP: 2
3737
READ_SENSORS_BATCH_SIZE: 20
38+
STALE_INVERTER_AFTER_SECONDS: 120
39+
STALE_INVERTER_SKIP_SECONDS: 600
3840
SCHEDULES:
3941
- KEY: W
4042
READ_EVERY: 5
@@ -44,6 +46,7 @@ options:
4446
CHANGE_PERCENT: 0
4547
NUMBER_ENTITY_MODE: "auto"
4648
PROG_TIME_INTERVAL: 15
49+
TIMEOUT: 1
4750
schema:
4851
DRIVER: list(pymodbus|umodbus|solarman)
4952
INVERTERS:
@@ -63,6 +66,8 @@ schema:
6366
MANUFACTURER: str
6467
READ_ALLOW_GAP: int(1,50)
6568
READ_SENSORS_BATCH_SIZE: int(1,100)
69+
STALE_INVERTER_AFTER_SECONDS: int(1,1000)?
70+
STALE_INVERTER_SKIP_SECONDS: int(60,86400)?
6671
SCHEDULES:
6772
- KEY: str
6873
READ_EVERY: int(1,3600)
@@ -72,6 +77,7 @@ schema:
7277
CHANGE_PERCENT: int(0,500)?
7378
NUMBER_ENTITY_MODE: list(auto|box|slider)
7479
PROG_TIME_INTERVAL: list(5|10|15|30|45|60)?
80+
TIMEOUT: int(1,10)?
7581
MQTT_CUSTOM: bool?
7682
MQTT_HOST: str?
7783
MQTT_PORT: port?

‎hass-addon-sunsynk-edge/translations/en.yaml‎

Lines changed: 82 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,104 @@
11
configuration:
22
DRIVER:
33
name: Inverter Driver
4-
description: "
4+
description: |
55
The inverter driver to use.
66
77
*pymodbus* is recommended when connected via a RS485/TCP adapter.
88
9-
With *solarman* you have to reduce the frequency that you read (see schedules)"
9+
With *solarman* you have to reduce the frequency that you read (see schedules).
1010
INVERTERS:
1111
name: Inverters
12-
description: '
12+
description: |
1313
Add one item per inverter.
1414
1515
HA_PREFIX should be unique for each inverter.
1616
1717
If PORT is a blank string "" the selected DEBUG_DEVICE will be used.
1818
1919
Only the solarman driver requires the DONGLE_SERIAL_NUMBER.
20-
'
20+
21+
Optional **DRIVER** per inverter overrides the global driver for that inverter.
2122
SENSOR_DEFINITIONS:
2223
name: Sensor definitions
2324
description: ""
24-
25+
SENSOR_OVERRIDES:
26+
name: Sensor overrides
27+
description: |
28+
Override sensor attributes (min, max, factor, trace). Each entry is `key=value`.
29+
See the documentation for examples.
30+
SENSORS:
31+
name: Sensors
32+
description: |
33+
Sensor groups or individual sensor names to poll for all inverters.
34+
SENSORS_FIRST_INVERTER:
35+
name: Sensors (first inverter)
36+
description: |
37+
Extra sensors polled only for the first inverter (typically settings).
38+
MANUFACTURER:
39+
name: Manufacturer
40+
description: Manufacturer name shown on the Home Assistant device.
41+
READ_ALLOW_GAP:
42+
name: Read allow gap
43+
description: |
44+
Maximum register address gap to include in a single Modbus read (fills gaps between requested registers).
45+
READ_SENSORS_BATCH_SIZE:
46+
name: Read batch size
47+
description: Maximum number of registers to read in one Modbus request.
48+
STALE_INVERTER_AFTER_SECONDS:
49+
name: Stale inverter after (seconds)
50+
description: |
51+
After a successful read, if Modbus failures continue past this many seconds, that inverter enters stale quiet so the
52+
bus is not blocked for others. Default 120.
53+
STALE_INVERTER_SKIP_SECONDS:
54+
name: Stale skip (seconds)
55+
description: |
56+
How long to stay in stale quiet before a one-off serial probe and possible recovery. Default 600.
57+
SCHEDULES:
58+
name: Schedules
59+
description: |
60+
When to read sensors and when to publish to MQTT (per key, e.g. power **W**). See the schedules documentation.
61+
NUMBER_ENTITY_MODE:
62+
name: Number entity mode
63+
description: |
64+
How read/write number entities display in Home Assistant — **auto**, **box**, or **slider**.
2565
PROG_TIME_INTERVAL:
2666
name: Program time interval
27-
description: "
28-
Set the program time interval in minutes for the selection list.
67+
description: |
68+
Program time selection list step in minutes.
69+
70+
Warning: 5 minutes produces a very long list to scroll through.
71+
TIMEOUT:
72+
name: Modbus timeout
73+
description: |
74+
Modbus timeout in seconds for connect and register read/write attempts.
2975
30-
Warning: setting this to 5 minutes will result in a very long list to scroll through."
76+
Default **1** second. Increase if you see spurious timeouts on slow links.
77+
MQTT_CUSTOM:
78+
name: Custom MQTT
79+
description: |
80+
When enabled, use MQTT_HOST, MQTT_PORT, MQTT_USERNAME, and MQTT_PASSWORD below instead of Supervisor discovery.
81+
MQTT_HOST:
82+
name: MQTT host
83+
description: MQTT broker hostname (used when custom MQTT is enabled).
84+
MQTT_PORT:
85+
name: MQTT port
86+
description: MQTT broker port (used when custom MQTT is enabled).
87+
MQTT_USERNAME:
88+
name: MQTT username
89+
description: MQTT broker username (used when custom MQTT is enabled).
90+
MQTT_PASSWORD:
91+
name: MQTT password
92+
description: MQTT broker password (used when custom MQTT is enabled).
93+
DEBUG:
94+
name: Debug level
95+
description: |
96+
Log verbosity. 0 = normal, higher values print more detail (see documentation).
97+
DEBUG_DEVICE:
98+
name: Debug device
99+
description: USB serial device used when an inverter PORT is left empty.
100+
MUTE_LOGS:
101+
name: Mute logs (clock times)
102+
description: |
103+
Local times (`hh:mm`) when the add-on temporarily sets logging to critical for 60 seconds to suppress noisy
104+
expected messages. Optional.

‎hass-addon-sunsynk-multi/config.yaml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,6 @@ options:
3535
MANUFACTURER: Sunsynk
3636
READ_ALLOW_GAP: 2
3737
READ_SENSORS_BATCH_SIZE: 20
38-
STALE_INVERTER_AFTER_TIMEOUTS: 10
39-
STALE_INVERTER_SKIP_SECONDS: 600
4038
SCHEDULES:
4139
- KEY: W
4240
READ_EVERY: 5
@@ -64,8 +62,6 @@ schema:
6462
MANUFACTURER: str
6563
READ_ALLOW_GAP: int(1,50)
6664
READ_SENSORS_BATCH_SIZE: int(1,100)
67-
STALE_INVERTER_AFTER_TIMEOUTS: int(0,1000)?
68-
STALE_INVERTER_SKIP_SECONDS: int(60,86400)?
6965
SCHEDULES:
7066
- KEY: str
7167
READ_EVERY: int(1,3600)

0 commit comments

Comments
 (0)