Templates: simplify guided setup (#4698)

cmd/configure/flow.go

@@ -95,7 +95,7 @@ func (c *CmdConfigure) configureDeviceGuidedSetup() {
 // configureLinkedTypes lets the user configure devices that are marked as being linked to a guided device
 // e.g. SMA Inverters, Energy Meter with SMA Home Manager
 func (c *CmdConfigure) configureLinkedTypes(templateItem templates.Template) {
-	linkedTemplates := templateItem.GuidedSetup.Linked
+	linkedTemplates := templateItem.Linked
 
 	deviceOfTemplateAdded := make(map[string]bool)
 

cmd/configure/helper.go

@@ -342,7 +342,7 @@ func (c *CmdConfigure) fetchElements(deviceCategory DeviceCategory) []templates.
 			titleTmpl.SetTitle(title)
 
 			if deviceCategory == DeviceCategoryGuidedSetup {
-				if tmpl.GuidedSetup.Enable {
+				if tmpl.GuidedSetupEnabled() {
 					items = append(items, titleTmpl)
 				}
 			} else {

templates/README.md

@@ -29,19 +29,15 @@ Either `brand`, or `description` need to be set.
 
 ## `group`
 
-`group` contains the reference to a `groups.yaml` entry. This is used to group switchable sockets and generic device support (e.g. SunSpec) templates.
+`group` is used to group switchable sockets and generic device support (e.g. SunSpec) templates.
 
-## `guidedsetup`
+## `guidedsetup` (Obsolete)
 
-`guidedsetup` if the device can be used for a guided setup, which are devices that provide multiple meter usages, or meter devices that are typically installed with specific other devices. Mostly used for meter devices that provided multiple usage data with the same user input. These devices are then sorted at the bottom of the product list.
+`guidedsetup` is enabled when the device has linked templates or >1 usage. It is used with devices that provide multiple meter usages, or meter devices that are typically installed with specific other devices. Mostly used for meter devices that provided multiple usage data with the same user input. These devices are then sorted at the bottom of the product list.
 
-### `enable`
+## `linked`
 
-`enable: true` to define that this device can be used for `guidedsetup`
-
-### `linked`
-
-Allows to define a list of meter devices that are typically installed with this device
+Allows to define a list of meter devices that are typically installed with this device. Enables `guidedsetup` mode.
 
 #### `template`
 

templates/definition/meter/e3dc.yaml

@@ -1,8 +1,6 @@
 template: e3dc
 products:
   - brand: E3DC
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/fronius-gen24.yaml

@@ -6,8 +6,6 @@ products:
   - brand: Fronius
     description:
       generic: Primo GEN24 Plus
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/fronius-solarapi-v1.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Fronius
     description:
       generic: Solar API V1
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/huawei-sun2000-dongle-powersensor.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Huawei
     description:
       generic: SUN2000 with SDongle & Power Sensor
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/kostal-piko-mp-plus.yaml

@@ -3,14 +3,12 @@ products:
   - brand: Kostal
     description:
       generic: Piko MP Plus
-guidedsetup:
-  enable: true
-  linked:
-    - template: kostal-ksem-inverter
-      usage: grid
-    - template: kostal-ksem
-      usage: grid
-      excludetemplate: kostal-ksem-inverter
+linked:
+  - template: kostal-ksem-inverter
+    usage: grid
+  - template: kostal-ksem
+    usage: grid
+    excludetemplate: kostal-ksem-inverter
 params:
   - name: usage
     choice: ["pv"]

templates/definition/meter/kostal-piko.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Kostal
     description:
       generic: Piko, Piko BA
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/kostal-plenticore.yaml

@@ -3,14 +3,12 @@ products:
   - brand: Kostal
     description:
       generic: Plenticore Hybrid
-guidedsetup:
-  enable: true
-  linked:
-    - template: kostal-ksem-inverter
-      usage: grid
-    - template: kostal-ksem
-      usage: grid
-      excludetemplate: kostal-ksem-inverter
+linked:
+  - template: kostal-ksem-inverter
+    usage: grid
+  - template: kostal-ksem
+    usage: grid
+    excludetemplate: kostal-ksem-inverter
 params:
   - name: usage
     choice: ["pv", "battery"]

templates/definition/meter/lg-ess-home-8-10.yaml

@@ -3,8 +3,6 @@ products:
   - brand: LG
     description:
       generic: ESS Home 8/10
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/openems.yaml

@@ -2,8 +2,6 @@ template: openems
 products:
   - brand: OpenEMS
   - brand: FENECON
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/powerdog.yaml

@@ -2,8 +2,6 @@ template: powerdog
 products:
   - description:
       generic: Powerdog
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv"]

templates/definition/meter/rct-power.yaml

@@ -3,8 +3,6 @@ products:
   - brand: RCT
     description:
       generic: Power
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/senec-home.yaml

@@ -3,8 +3,6 @@ products:
   - brand: SENEC
     description:
       generic: .Home
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/sma-datamanager.yaml

@@ -5,8 +5,6 @@ products:
   - brand: SMA
     description:
       generic: Data Manager
-guidedsetup:
-  enable: true
 requirements:
   description:
     de: In der Weboberfläche des SMA Data Manager muss im Bereich "Externe Kommunikation" der Schalter "Modbus Server aktivieren" eingeschaltet sein.

templates/definition/meter/sma-homemanager.yaml

@@ -4,25 +4,23 @@ products:
     description:
       generic: Sunny Home Manager 2.0
 capabilities: ["smahems"]
-guidedsetup:
-  enable: true
-  linked:
-    - template: sma-energy-meter
-      usage: pv
-    - template: sma-hybrid
-      usage: pv
-      multiple: true
-      excludetemplate: sma-energy-meter
-    - template: sma-inverter
-      usage: pv
-      multiple: true
-      excludetemplate: sma-energy-meter
-    - template: sma-hybrid
-      usage: battery
-      multiple: true
-    - template: sma-inverter
-      usage: battery
-      multiple: true
+linked:
+  - template: sma-energy-meter
+    usage: pv
+  - template: sma-hybrid
+    usage: pv
+    multiple: true
+    excludetemplate: sma-energy-meter
+  - template: sma-inverter
+    usage: pv
+    multiple: true
+    excludetemplate: sma-energy-meter
+  - template: sma-hybrid
+    usage: battery
+    multiple: true
+  - template: sma-inverter
+    usage: battery
+    multiple: true
 params:
   - name: usage
     choice: ["grid"]

templates/definition/meter/solaredge-hybrid.yaml

@@ -3,8 +3,6 @@ products:
   - brand: SolarEdge
     description:
       generic: Hybrid Inverter
-guidedsetup:
-  enable: true
 requirements:
   description:
     de: Nur ein System kann auf den Wechselrichter zugreifen!

templates/definition/meter/solaredge-inverter.yaml

@@ -4,8 +4,6 @@ products:
     description:
       de: Wechselrichter
       en: Inverter
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv"]

templates/definition/meter/solarlog.yaml

@@ -2,12 +2,10 @@ template: solarlog
 products:
   - description:
       generic: Solarlog
-guidedsetup:
-  enable: true
 requirements:
   description:
     de: |
-      Wir empfehlen dieses Gerät für den Netzbezug/Einspeisewerte nur zu verwenden, wenn kein anderes Gerät diese Daten liefert. 
+      Wir empfehlen dieses Gerät für den Netzbezug/Einspeisewerte nur zu verwenden, wenn kein anderes Gerät diese Daten liefert.
       Falls eine Hausbatterie angeschlossen ist sollte dieses Gerät auf keinen Fall für die erwähnten Werte verwendet werden!
     en: |
       We recommend to use this device for grid power values only, if no other device is available providing this data.

templates/definition/meter/solarwatt-myreserve-matrix.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Solarwatt
     description:
       generic: MyReserve Matrix (LAN oder PowerGateway)
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]
@@ -24,7 +22,7 @@ render: |
   {{- end }}
   {{- if eq .usage "battery" }}
     jq: .FData.IBat * .FData.VBat
-  soc: 
+  soc:
     source: http
     uri: http://{{ .host }}:{{ .port }}/
     jq: .SData.SoC

templates/definition/meter/solarwatt.yaml

@@ -7,8 +7,6 @@ products:
   - brand: Solarwatt
     description:
       generic: EnergyManager, EnergyManager Pro
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/solax-hybrid-cloud.yaml

@@ -14,8 +14,6 @@ requirements:
       The Solax hybrid inverter has to be registered in the SolaxCloud.
 
       **Attention**: Values can only be fetched every 150s and then also can be 5 minutes old. Charging by PV will not be optimal because of this! Only use as fallback if no local access is available.
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/solax.yaml

@@ -7,8 +7,6 @@ products:
   - brand: Qcells
     description:
       generic: Q.HOME ESS HYB-G3
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/sonnenbatterie.yaml

@@ -4,8 +4,6 @@ products:
   - brand: Sonnen
     description:
       generic: sonnenBatterie
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/sungrow-hybrid.yaml

@@ -4,8 +4,6 @@ products:
   - brand: Sungrow
     description:
       generic: SH Series Hybrid Inverter
-guidedsetup:
-  enable: true
 requirements:
   description:
     de: Die Verbindung ist nur seriell (RS485) oder TCP (mit dem WiNet-S-Dongle) möglich.

templates/definition/meter/sungrow-inverter.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Sungrow
     description:
       generic: SG Series Inverter
-guidedsetup:
-  enable: true
 requirements:
   description:
     de: Die Verbindung ist nur seriell (RS485) oder TCP (mit dem WiNet-S-Dongle) möglich.

templates/definition/meter/tesla-powerwall.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Tesla
     description:
       generic: Powerwall
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/varta-energiespeicher-battery-only.yaml

@@ -4,8 +4,6 @@ products:
     description:
       de: Energiespeicher (kein PV-Sensor)
       en: Energiespeicher (without PV Sensor)
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "battery"]

templates/definition/meter/varta-energiespeicher.yaml

@@ -4,8 +4,6 @@ products:
     description:
       de: Energiespeicher (mit PV-Sensor)
       en: Energiespeicher (with PV Sensor)
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/definition/meter/victron-energy.yaml

@@ -3,8 +3,6 @@ products:
   - brand: Victron
     description:
       generic: Energy
-guidedsetup:
-  enable: true
 params:
   - name: usage
     choice: ["grid", "pv", "battery"]

templates/docs/meter/solarlog_0.yaml

@@ -1,7 +1,7 @@
 product:
   description: Solarlog
 description: |
-  Wir empfehlen dieses Gerät für den Netzbezug/Einspeisewerte nur zu verwenden, wenn kein anderes Gerät diese Daten liefert. 
+  Wir empfehlen dieses Gerät für den Netzbezug/Einspeisewerte nur zu verwenden, wenn kein anderes Gerät diese Daten liefert.
   Falls eine Hausbatterie angeschlossen ist sollte dieses Gerät auf keinen Fall für die erwähnten Werte verwendet werden!
 
 render:

util/templates/template.go

@@ -24,6 +24,12 @@ type Template struct {
 	titles []string
 }
 
+// GuidedSetupEnabled returns true if there are linked templates or >1 usage
+func (t *Template) GuidedSetupEnabled() bool {
+	_, p := t.ParamByName(ParamUsage)
+	return len(t.Linked) > 0 || len(p.Choice) > 1
+}
+
 // UpdateParamWithDefaults adds default values to specific param name entries
 func (t *Template) UpdateParamsWithDefaults() error {
 	for i, p := range t.Params {

util/templates/template_types.go

@@ -169,11 +169,6 @@ type Requirements struct {
 	URI         string       // URI to a webpage with more details about the preparation requirements
 }
 
-type GuidedSetup struct {
-	Enable bool             // if true, guided setup is possible
-	Linked []LinkedTemplate // a list of templates that should be processed as part of the guided setup
-}
-
 // Linked Template
 type LinkedTemplate struct {
 	Template        string
@@ -291,12 +286,12 @@ type Product struct {
 // TemplateDefinition contains properties of a device template
 type TemplateDefinition struct {
 	Template     string
+	Group        string    // the group this template belongs to, references groupList entries
 	Covers       []string  // list of covered outdated template names
 	Products     []Product // list of products this template is compatible with
 	Capabilities []string
 	Requirements Requirements
-	GuidedSetup  GuidedSetup
-	Group        string // the group this template belongs to, references groupList entries
+	Linked       []LinkedTemplate // a list of templates that should be processed as part of the guided setup
 	Params       []Param
 	Render       string // rendering template
 }