iobroker.goodwe-sems 0.1.0

package/admin/i18n/uk/translations.json

@@ -0,0 +1,43 @@
+{
+    "debugRawResponse": "Сохранять сырой JSON-ответ (отладка)",
+    "debugRawResponseHelp": "Записывает последний полный ответ SEMS API в info.rawResponse. По умолчанию выключено.",
+    "hintLoginText": "Войдите с обычной учётной записью портала SEMS (той же, что на semsportal.com или в приложении SEMS). Учётная запись SEMS \"Organization\"/OpenAPI не требуется.",
+    "hintPollingText": "Портал SEMS не документирован для сторонних обращений и может ограничивать частые запросы. 5 минут - безопасное значение по умолчанию; адаптер применяет минимум 60с и автоматически снижает частоту при ошибках.",
+    "hintPushoverText": "Критические события можно отправлять через Pushover в дополнение к логу ioBroker.",
+    "maxConsecutiveErrors": "Ошибок до уведомления \"станция недоступна\"",
+    "maxConsecutiveErrorsHelp": "Количество последовательных неудачных опросов перед уведомлением об отключении.",
+    "notifyHeader": "Надсилати сповіщення при",
+    "notifyOnAdapterError": "Неочікуваній помилці адаптера",
+    "notifyOnLoginFailure": "Помилка входу SEMS",
+    "notifyOnRateLimit": "Досягнуто ліміту запитів SEMS",
+    "notifyOnStationOffline": "Тривалій відмові",
+    "pollInterval": "Інтервал опитування (секунди)",
+    "pollIntervalHelp": "Минимум 60с, рекомендуется 300с (5 мин).",
+    "pollingTab": "Опитування",
+    "powerStationId": "ID электростанции (опционально)",
+    "powerStationIdHelp": "Оставьте пустым для автоматического определения. При нескольких станциях укажите ID вручную (из URL портала SEMS после входа).",
+    "priorityEmergency": "Экстренный",
+    "priorityHigh": "Высокий",
+    "priorityLow": "Низкий (без звука)",
+    "priorityNormal": "Обычный",
+    "pushoverApiToken": "Pushover API/App-токен",
+    "pushoverInstance": "Экземпляр адаптера Pushover",
+    "pushoverInstanceHelp": "например, pushover.0",
+    "pushoverMode": "Доставка Pushover",
+    "pushoverModeBoth": "Оба варианта",
+    "pushoverModeDirect": "Напрямую через API Pushover",
+    "pushoverModeHelp": "Способ отправки уведомлений Pushover.",
+    "pushoverModeInstance": "Через существующий экземпляр ioBroker.pushover",
+    "pushoverModeNone": "Отключено (только лог)",
+    "pushoverPriority": "Приоритет Pushover",
+    "pushoverTab": "Сповіщення Pushover",
+    "pushoverUserKey": "Pushover User-Key",
+    "requestTimeout": "Тайм-аут запроса (секунды)",
+    "requestTimeoutHelp": "На один HTTP-запрос к порталу SEMS.",
+    "semsAccount": "Обліковий запис SEMS (e-mail)",
+    "semsAccountHelp": "Адрес электронной почты для входа на semsportal.com.",
+    "semsPassword": "Пароль SEMS",
+    "semsPasswordHelp": "Хранится в зашифрованном виде.",
+    "stationOfflineMinutes": "Пауза уведомления об отключении (мин)",
+    "stationOfflineMinutesHelp": "Только информативно."
+}

package/admin/i18n/zh-cn/translations.json

@@ -0,0 +1,43 @@
+{
+    "debugRawResponse": "保存原始 JSON 响应（调试）",
+    "debugRawResponseHelp": "将最近一次完整的 SEMS API 响应写入 info.rawResponse，默认关闭。",
+    "hintLoginText": "使用您普通的 SEMS Portal 账户登录（与 semsportal.com 或 SEMS App 相同的账户）。不需要 SEMS \"organization\"/OpenAPI 账户。",
+    "hintPollingText": "SEMS 门户未公开第三方使用文档，频繁请求可能触发限流。默认 5 分钟较为安全；适配器强制最小值为 60 秒，并在出错或被限流后自动退避。",
+    "hintPushoverText": "除始终写入 ioBroker 日志外，关键事件还可通过 Pushover 推送到手机。",
+    "maxConsecutiveErrors": "触发“电站离线”告警前的失败次数",
+    "maxConsecutiveErrorsHelp": "连续失败的轮询次数达到该值后，视为真正的故障。",
+    "notifyHeader": "以下情况发送告警",
+    "notifyOnAdapterError": "适配器发生意外错误",
+    "notifyOnLoginFailure": "SEMS 登录失败",
+    "notifyOnRateLimit": "达到 SEMS 请求限制",
+    "notifyOnStationOffline": "长时间故障",
+    "pollInterval": "轮询间隔（秒）",
+    "pollIntervalHelp": "最小 60 秒，建议 300 秒（5 分钟）。",
+    "pollingTab": "轮询间隔",
+    "powerStationId": "电站 ID（可选）",
+    "powerStationIdHelp": "留空以自动检测。若账户下有多个电站，请手动填写 ID（登录后可在 SEMS 门户网址中找到）。",
+    "priorityEmergency": "紧急",
+    "priorityHigh": "高",
+    "priorityLow": "低（无声音）",
+    "priorityNormal": "普通",
+    "pushoverApiToken": "Pushover API/App 令牌",
+    "pushoverInstance": "Pushover 适配器实例",
+    "pushoverInstanceHelp": "例如 pushover.0",
+    "pushoverMode": "Pushover 发送方式",
+    "pushoverModeBoth": "两者皆用",
+    "pushoverModeDirect": "直接调用 Pushover API",
+    "pushoverModeHelp": "Pushover 通知的发送方式。",
+    "pushoverModeInstance": "通过现有的 ioBroker.pushover 实例",
+    "pushoverModeNone": "禁用（仅记录日志）",
+    "pushoverPriority": "Pushover 优先级",
+    "pushoverTab": "Pushover 通知",
+    "pushoverUserKey": "Pushover User-Key",
+    "requestTimeout": "请求超时（秒）",
+    "requestTimeoutHelp": "每次向 SEMS 门户发起请求的超时时间。",
+    "semsAccount": "SEMS 账户（邮箱）",
+    "semsAccountHelp": "用于登录 semsportal.com 的电子邮件地址。",
+    "semsPassword": "SEMS 密码",
+    "semsPasswordHelp": "以加密方式存储。",
+    "stationOfflineMinutes": "故障告警间隔（分钟）",
+    "stationOfflineMinutesHelp": "仅作说明用途。"
+}

package/admin/jsonConfig.json

@@ -0,0 +1,211 @@
+{
+    "i18n": true,
+    "type": "tabs",
+    "items": {
+        "_login": {
+            "type": "panel",
+            "label": "SEMS-Login",
+            "items": {
+                "_hintLogin": {
+                    "type": "staticText",
+                    "text": "hintLoginText",
+                    "newLine": true
+                },
+                "account": {
+                    "type": "text",
+                    "label": "semsAccount",
+                    "help": "semsAccountHelp",
+                    "newLine": true,
+                    "trim": true,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "password": {
+                    "type": "password",
+                    "label": "semsPassword",
+                    "help": "semsPasswordHelp",
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "powerStationId": {
+                    "type": "text",
+                    "label": "powerStationId",
+                    "help": "powerStationIdHelp",
+                    "newLine": true,
+                    "trim": true,
+                    "xs": 12,
+                    "sm": 8,
+                    "md": 6
+                }
+            }
+        },
+        "_polling": {
+            "type": "panel",
+            "label": "pollingTab",
+            "items": {
+                "_hintPolling": {
+                    "type": "staticText",
+                    "text": "hintPollingText",
+                    "newLine": true
+                },
+                "pollInterval": {
+                    "type": "number",
+                    "label": "pollInterval",
+                    "help": "pollIntervalHelp",
+                    "min": 60,
+                    "max": 3600,
+                    "step": 30,
+                    "newLine": true,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "requestTimeout": {
+                    "type": "number",
+                    "label": "requestTimeout",
+                    "help": "requestTimeoutHelp",
+                    "min": 5,
+                    "max": 60,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "maxConsecutiveErrors": {
+                    "type": "number",
+                    "label": "maxConsecutiveErrors",
+                    "help": "maxConsecutiveErrorsHelp",
+                    "min": 1,
+                    "max": 20,
+                    "newLine": true,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "stationOfflineMinutes": {
+                    "type": "number",
+                    "label": "stationOfflineMinutes",
+                    "help": "stationOfflineMinutesHelp",
+                    "min": 5,
+                    "max": 720,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "debugRawResponse": {
+                    "type": "checkbox",
+                    "label": "debugRawResponse",
+                    "help": "debugRawResponseHelp",
+                    "newLine": true,
+                    "xs": 12,
+                    "sm": 8,
+                    "md": 6
+                }
+            }
+        },
+        "_pushover": {
+            "type": "panel",
+            "label": "pushoverTab",
+            "items": {
+                "_hintPushover": {
+                    "type": "staticText",
+                    "text": "hintPushoverText",
+                    "newLine": true
+                },
+                "pushoverMode": {
+                    "type": "select",
+                    "label": "pushoverMode",
+                    "help": "pushoverModeHelp",
+                    "newLine": true,
+                    "options": [
+                        { "value": "none", "label": "pushoverModeNone" },
+                        { "value": "instance", "label": "pushoverModeInstance" },
+                        { "value": "direct", "label": "pushoverModeDirect" },
+                        { "value": "both", "label": "pushoverModeBoth" }
+                    ],
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "pushoverPriority": {
+                    "type": "select",
+                    "label": "pushoverPriority",
+                    "newLine": true,
+                    "options": [
+                        { "value": -1, "label": "priorityLow" },
+                        { "value": 0, "label": "priorityNormal" },
+                        { "value": 1, "label": "priorityHigh" },
+                        { "value": 2, "label": "priorityEmergency" }
+                    ],
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "pushoverInstance": {
+                    "type": "instance",
+                    "label": "pushoverInstance",
+                    "help": "pushoverInstanceHelp",
+                    "adapter": "pushover",
+                    "newLine": true,
+                    "hidden": "data.pushoverMode !== 'instance' && data.pushoverMode !== 'both'",
+                    "xs": 12,
+                    "sm": 8,
+                    "md": 6
+                },
+                "pushoverUserKey": {
+                    "type": "text",
+                    "label": "pushoverUserKey",
+                    "newLine": true,
+                    "hidden": "data.pushoverMode !== 'direct' && data.pushoverMode !== 'both'",
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "pushoverApiToken": {
+                    "type": "password",
+                    "label": "pushoverApiToken",
+                    "hidden": "data.pushoverMode !== 'direct' && data.pushoverMode !== 'both'",
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 4
+                },
+                "_notifyHeader": {
+                    "type": "header",
+                    "text": "notifyHeader",
+                    "newLine": true
+                },
+                "notifyOnLoginFailure": {
+                    "type": "checkbox",
+                    "label": "notifyOnLoginFailure",
+                    "newLine": true,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "notifyOnRateLimit": {
+                    "type": "checkbox",
+                    "label": "notifyOnRateLimit",
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "notifyOnStationOffline": {
+                    "type": "checkbox",
+                    "label": "notifyOnStationOffline",
+                    "newLine": true,
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                },
+                "notifyOnAdapterError": {
+                    "type": "checkbox",
+                    "label": "notifyOnAdapterError",
+                    "xs": 12,
+                    "sm": 6,
+                    "md": 3
+                }
+            }
+        }
+    }
+}

package/io-package.json

@@ -0,0 +1,207 @@
+{
+  "common": {
+    "name": "goodwe-sems",
+    "version": "0.1.0",
+    "news": {
+      "0.1.0": {
+        "en": "initial release",
+        "de": "Erstveröffentlichung",
+        "ru": "первый выпуск",
+        "pt": "lançamento inicial",
+        "nl": "eerste release",
+        "fr": "version initiale",
+        "it": "versione iniziale",
+        "es": "versión inicial",
+        "pl": "pierwsze wydanie",
+        "uk": "перший випуск",
+        "zh-cn": "首次发布"
+      }
+    },
+    "title": "GoodWe SEMS Portal",
+    "titleLang": {
+      "en": "GoodWe SEMS Portal",
+      "de": "GoodWe SEMS Portal",
+      "ru": "GoodWe SEMS Portal",
+      "pt": "GoodWe SEMS Portal",
+      "nl": "GoodWe SEMS Portal",
+      "fr": "GoodWe SEMS Portal",
+      "it": "GoodWe SEMS Portal",
+      "es": "GoodWe SEMS Portal",
+      "pl": "GoodWe SEMS Portal",
+      "uk": "GoodWe SEMS Portal",
+      "zh-cn": "GoodWe SEMS 门户"
+    },
+    "desc": {
+      "en": "Reads inverter, battery and power-flow data from the GoodWe SEMS Portal cloud for installations that have no local/LAN access to the inverter.",
+      "de": "Liest Wechselrichter-, Batterie- und Energiefluss-Daten aus dem GoodWe-SEMS-Portal (Cloud) für Anlagen ohne lokalen/LAN-Zugriff auf den Wechselrichter.",
+      "ru": "Считывает данные инвертора, батареи и потоков энергии из облачного портала GoodWe SEMS для установок без локального доступа к инвертору.",
+      "pt": "Lê dados do inversor, bateria e fluxo de energia do portal SEMS da GoodWe na nuvem para instalações sem acesso local/LAN ao inversor.",
+      "nl": "Leest omvormer-, batterij- en energiestroomgegevens uit het GoodWe SEMS-portaal (cloud) voor installaties zonder lokale/LAN-toegang tot de omvormer.",
+      "fr": "Lit les données de l'onduleur, de la batterie et des flux d'énergie depuis le portail cloud GoodWe SEMS pour les installations sans accès local/LAN à l'onduleur.",
+      "it": "Legge i dati dell'inverter, della batteria e del flusso di energia dal portale cloud GoodWe SEMS per impianti senza accesso locale/LAN all'inverter.",
+      "es": "Lee datos del inversor, la batería y el flujo de energía desde el portal en la nube GoodWe SEMS para instalaciones sin acceso local/LAN al inversor.",
+      "pl": "Odczytuje dane falownika, baterii i przepływu energii z chmury portalu GoodWe SEMS dla instalacji bez lokalnego dostępu do falownika.",
+      "uk": "Зчитує дані інвертора, батареї та потоків енергії з хмарного порталу GoodWe SEMS для установок без локального доступу до інвертора.",
+      "zh-cn": "为无法本地访问逆变器的装置从 GoodWe SEMS 云端门户读取逆变器、电池和功率流数据。"
+    },
+    "authors": [
+      "bueste <bueste@users.noreply.github.com>"
+    ],
+    "keywords": ["goodwe", "sems", "semsportal", "inverter", "solar", "pv", "photovoltaik", "battery"],
+    "licenseInformation": {
+      "type": "free",
+      "license": "MIT"
+    },
+    "platform": "Javascript/Node.js",
+    "main": "main.js",
+    "icon": "goodwe-sems.png",
+    "enabled": true,
+    "extIcon": "https://raw.githubusercontent.com/bueste/ioBroker.goodwe-sems/main/admin/goodwe-sems.png",
+    "readme": "https://github.com/bueste/ioBroker.goodwe-sems/blob/main/README.md",
+    "loglevel": "info",
+    "mode": "daemon",
+    "type": "energy",
+    "compact": true,
+    "connectionType": "cloud",
+    "dataSource": "poll",
+    "tier": 3,
+    "adminUI": {
+      "config": "json"
+    },
+    "encryptedNative": ["password", "pushoverApiToken"],
+    "protectedNative": ["password", "pushoverApiToken"],
+    "dependencies": [
+      {
+        "js-controller": ">=5.0.19"
+      }
+    ],
+    "globalDependencies": [
+      {
+        "admin": ">=6.13.16"
+      }
+    ]
+  },
+  "native": {
+    "account": "",
+    "password": "",
+    "powerStationId": "",
+    "pollInterval": 300,
+    "requestTimeout": 15,
+    "maxConsecutiveErrors": 3,
+    "pushoverMode": "none",
+    "pushoverInstance": "pushover.0",
+    "pushoverUserKey": "",
+    "pushoverApiToken": "",
+    "pushoverPriority": 0,
+    "notifyOnLoginFailure": true,
+    "notifyOnRateLimit": true,
+    "notifyOnStationOffline": true,
+    "notifyOnAdapterError": true,
+    "stationOfflineMinutes": 30,
+    "debugRawResponse": false
+  },
+  "objects": [],
+  "instanceObjects": [
+    {
+      "_id": "info",
+      "type": "channel",
+      "common": {
+        "name": "Information"
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.connection",
+      "type": "state",
+      "common": {
+        "role": "indicator.connected",
+        "name": "SEMS Portal reachable",
+        "type": "boolean",
+        "read": true,
+        "write": false,
+        "def": false
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.lastSuccess",
+      "type": "state",
+      "common": {
+        "role": "value.time",
+        "name": "Timestamp of last successful poll",
+        "type": "number",
+        "read": true,
+        "write": false,
+        "def": 0
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.lastError",
+      "type": "state",
+      "common": {
+        "role": "text",
+        "name": "Last error message",
+        "type": "string",
+        "read": true,
+        "write": false,
+        "def": ""
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.consecutiveErrors",
+      "type": "state",
+      "common": {
+        "role": "value",
+        "name": "Number of consecutive failed polls",
+        "type": "number",
+        "read": true,
+        "write": false,
+        "def": 0
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.rateLimited",
+      "type": "state",
+      "common": {
+        "role": "indicator",
+        "name": "SEMS Portal is currently rate-limiting this account",
+        "type": "boolean",
+        "read": true,
+        "write": false,
+        "def": false
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.activePollInterval",
+      "type": "state",
+      "common": {
+        "role": "value.interval",
+        "name": "Currently active poll interval (seconds, incl. backoff)",
+        "type": "number",
+        "unit": "s",
+        "read": true,
+        "write": false,
+        "def": 300
+      },
+      "native": {}
+    },
+    {
+      "_id": "info.rawResponse",
+      "type": "state",
+      "common": {
+        "role": "json",
+        "name": "Raw last SEMS API response (debug, disabled by default)",
+        "type": "string",
+        "read": true,
+        "write": false,
+        "def": "",
+        "expert": true
+      },
+      "native": {}
+    }
+  ]
+}

package/lib/errors.js

@@ -0,0 +1,43 @@
+"use strict";
+
+/**
+ * Base class for all errors raised by the SEMS API client.
+ * Keeping a dedicated hierarchy lets main.js react differently
+ * (log level, Pushover severity, retry behaviour) per error type
+ * instead of parsing error message strings.
+ */
+class SemsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+/** Login failed (wrong credentials, portal changed its login contract, ...). */
+class SemsAuthError extends SemsError {}
+
+/** The portal answered with its rate-limit code (observed: GY0429). */
+class SemsRateLimitError extends SemsError {
+    /**
+     * @param {string} message
+     * @param {number} retryAfterSeconds recommended cool-down before the next request
+     */
+    constructor(message, retryAfterSeconds = 300) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+
+/** Network-level failure (timeout, DNS, connection reset, non-2xx, ...). */
+class SemsNetworkError extends SemsError {}
+
+/** The portal answered but the payload did not look like what we expected. */
+class SemsProtocolError extends SemsError {}
+
+module.exports = {
+    SemsError,
+    SemsAuthError,
+    SemsRateLimitError,
+    SemsNetworkError,
+    SemsProtocolError,
+};